openapi: 3.0.0
info:
  version: '0.0'
  title: Qomon
  description: |-
    This is Qomon's API definition.

    To get an authorization go to [Qomon's setting page](https://qomon.app/settings/extensions/connect) and create an API key.
servers:
  - description: Qomon local
    url: http://localhost:8080/api
  - description: Qomon integration
    url: https://test.quorumapps.com/api
  - description: Qomon production
    url: https://qomon.app/api

paths:
  /folder/{id}:
    get:
      summary: Get a single folder by ID
      operationId: getFolder
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: ID of the folder to retrieve
      responses:
        "200":
          description: Folder retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: "#/components/schemas/FolderView"
        "400":
          description: Invalid folder ID
        "404":
          description: Folder not found
        "500":
          description: Internal server error
    delete:
      summary: Delete a folder by ID and its associations (templates)
      operationId: deleteFolder
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: ID of the folder to delete
      responses:
        "200":
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FoldersView"
        "404":
          description: Folder not found
        "500":
          description: Internal server error

  /folders:
    get:
      summary: Get all private and public folders
      operationId: getTemplateFolders
      responses:
        "200":
          description: Folders retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FoldersView"
        "500":
          description: Internal server error

  /folder:
    post:
      summary: Create a new folder
      operationId: addFolder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderArgs"
      responses:
        "200":
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FoldersView"
        "400":
          description: Invalid request payload
        "409":
          description: Folder limit reached or duplicate name
        "422":
          description: Folder name contains invalid characters
        "500":
          description: Internal server error
    patch:
      summary: Update a folder
      operationId: updateFolder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderArgs"
      responses:
        "200":
          description: Folder updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: "#/components/schemas/FolderView"
        "400":
          description: Invalid request payload
        "404":
          description: Folder not found
        "500":
          description: Internal server error

  /folder/{id}/insert:
    post:
      summary: Add templates to a folder
      operationId: insertTemplates
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: ID of the folder to add templates to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderTemplatesArgs"
      responses:
        "200":
          description: Templates added to the folder successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: "#/components/schemas/FolderView"
        "400":
          description: Invalid request payload or folder ID
        "403":
          description: Cannot insert templates into a public folder
        "404":
          description: Folder not found or one or more templates do not exist
        "500":
          description: Internal server error

  /folder/{id}/remove:
    post:
      summary: Remove templates from a folder
      operationId: removeTemplates
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: ID of the folder to remove templates from
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderTemplatesArgs"
      responses:
        "200":
          description: Templates removed from the folder successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: "#/components/schemas/FolderView"
        "400":
          description: Invalid request payload or folder ID
        "403":
          description: Cannot remove templates from a public folder
        "404":
          description: Folder not found or one or more templates do not exist
        "500":
          description: Internal server error

  /emailer/template/move:
    post:
      summary: Move an email template to different folders
      operationId: moveEmailTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailerFolderArgs"
      responses:
        "200":
          description: Template successfully moved and updated folder returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  folders:
                    type: array
                    items:
                      $ref: "#/components/schemas/FolderView"
        "400":
          description: Bad request (e.g., missing template ID or folder IDs)
        "404":
          description: Not found (e.g., template or folder does not exist)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Template not found or access denied"
        "409":
          description: Conflict (e.g., template is already associated with one or more destination folders)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Template is already associated with one or more destination folders"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Unexpected error occurred"
    
components:
  schemas:
    FoldersView:
      type: object
      properties:
        folders:
          type: array
          items:
            $ref: "#/components/schemas/FolderView"
        public_folders:
          type: array
          items:
            $ref: "#/components/schemas/PublicFolderView"

    FolderView:
      type: object
      properties:
        id:
          type: integer
          format: uint
        name:
          type: string
        url:
          type: string
        is_favorite:
          type: boolean
        is_default:
          type: boolean
        is_removable:
          type: boolean
        templates:
          type: array
          items:
            $ref: "#/components/schemas/TemplateView"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        count_templates:
          type: integer
        category:
          $ref: "#/components/schemas/FolderCategory"

    PublicFolderView:
      type: object
      properties:
        name:
          type: string
        locale:
          type: string
        templates:
          type: array
          items:
            $ref: "#/components/schemas/PublicTemplateView"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        count_templates:
          type: integer
        category:
          $ref: "#/components/schemas/FolderCategory"

    PublicTemplateView:
      type: object
      properties:
        name:
          type: string
        image_url:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        content_html:
          type: string
        content_json:
          type: string
        category:
          $ref: "#/components/schemas/TemplateCategory"

    TemplateView:
      type: object
      properties:
        id:
          type: integer
          format: uint
        user_id:
          type: integer
        folder_id:
          type: integer
        name:
          type: string
        url:
          type: string
        image_url:
          type: string
        is_favorite:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        category:
          $ref: "#/components/schemas/TemplateCategory"

    FolderArgs:
      type: object
      required:
        - name
        - is_favorite
      properties:
        name:
          type: string
        is_favorite:
          type: boolean
        folder_id:
          type: integer
        category:
          $ref: "#/components/schemas/FolderCategory"

    FolderTemplatesArgs:
      type: object
      properties:
        template_ids:
          type: array
          items:
            type: integer
          description: List of template IDs to be added or removed from the folder

    EmailerFolderArgs:
      type: object
      required:
        - emailer_template_id
      properties:
        dest_folder_id:
          type: integer
        emailer_template_id:
          type: integer
          format: int64
          description: ID of the template to move
        origin_folder_id:
          type: integer
          format: int64
          description: ID of the original folder containing the template (only for return)

    FolderCategory:
      type: string
      enum: [email, campaign, transac, workflow]
      description: Category of the folder
      example: email
      default: email