delete:
  x-eov-operation-id: deleteFolder
  x-eov-operation-handler: v1/handlers/folders/folders.handler
  tags:
    - Folders
  summary: Delete a folder
  description: Delete a folder within a project. When `transferToFolderId` is provided, workflows and sub-folders are moved to the target folder before deletion. When omitted, workflows are moved to the project root and archived, and child folders are deleted.
  parameters:
    - name: projectId
      in: path
      description: The ID of the project.
      required: true
      schema:
        type: string
    - name: folderId
      in: path
      description: The ID of the folder.
      required: true
      schema:
        type: string
    - name: transferToFolderId
      in: query
      description: Optional target folder ID to move workflows and sub-folders into before deleting.
      required: false
      schema:
        type: string
  responses:
    '204':
      description: Operation successful.
    '400':
      $ref: '../../../../shared/spec/responses/badRequest.yml'
    '401':
      $ref: '../../../../shared/spec/responses/unauthorized.yml'
    '403':
      $ref: '../../../../shared/spec/responses/forbidden.yml'
    '404':
      $ref: '../../../../shared/spec/responses/notFound.yml'
get:
  x-eov-operation-id: getFolder
  x-eov-operation-handler: v1/handlers/folders/folders.handler
  tags:
    - Folders
  summary: Get folder details
  description: Get folder details including sub-folder and workflow counts.
  parameters:
    - name: projectId
      in: path
      description: The ID of the project.
      required: true
      schema:
        type: string
    - name: folderId
      in: path
      description: The ID of the folder.
      required: true
      schema:
        type: string
  responses:
    '200':
      description: Operation successful.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
                readOnly: true
              name:
                type: string
              parentFolderId:
                type: string
                nullable: true
              createdAt:
                type: string
                format: date-time
                readOnly: true
              updatedAt:
                type: string
                format: date-time
                readOnly: true
              totalSubFolders:
                type: integer
                description: Total number of sub-folders (recursive).
              totalWorkflows:
                type: integer
                description: Total number of workflows (recursive).
    '401':
      $ref: '../../../../shared/spec/responses/unauthorized.yml'
    '403':
      $ref: '../../../../shared/spec/responses/forbidden.yml'
    '404':
      $ref: '../../../../shared/spec/responses/notFound.yml'
patch:
  x-eov-operation-id: updateFolder
  x-eov-operation-handler: v1/handlers/folders/folders.handler
  tags:
    - Folders
  summary: Update a folder
  description: Update folder name or parent folder.
  parameters:
    - name: projectId
      in: path
      description: The ID of the project.
      required: true
      schema:
        type: string
    - name: folderId
      in: path
      description: The ID of the folder.
      required: true
      schema:
        type: string
  requestBody:
    description: Payload for folder update.
    content:
      application/json:
        schema:
          $ref: '../schemas/folder.update.yml'
    required: true
  responses:
    '200':
      description: Operation successful.
      content:
        application/json:
          schema:
            $ref: '../schemas/folder.yml'
    '400':
      $ref: '../../../../shared/spec/responses/badRequest.yml'
    '401':
      $ref: '../../../../shared/spec/responses/unauthorized.yml'
    '403':
      $ref: '../../../../shared/spec/responses/forbidden.yml'
    '404':
      $ref: '../../../../shared/spec/responses/notFound.yml'
