openapi: 3.0.3

info:
  title: Insforge Schedules API
  version: 1.0.0
  description: Schedule management endpoints

paths:
  /api/schedules:
    get:
      summary: List schedules
      description: Returns all schedules configured in the system.
      tags:
        - Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      summary: Create schedule
      description: Creates a new scheduled job.
      tags:
        - Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleRequest'
      responses:
        '201':
          description: Schedule created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  cronJobId:
                    type: string
                    nullable: true
                  message:
                    type: string

        '404':
          description: Referenced secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/schedules/config:
    get:
      summary: Get schedules configuration
      description: Returns schedule retention configuration.
      tags:
        - Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Schedules configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulesConfig'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    patch:
      summary: Update schedules configuration
      description: Updates schedule retention configuration.
      tags:
        - Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSchedulesConfigRequest'
      responses:
        '200':
          description: Configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/schedules/{id}:
    get:
      summary: Get schedule by ID
      description: Returns a single schedule by identifier.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid

      responses:
        '200':
          description: Schedule found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'

        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    patch:
      summary: Update schedule
      description: Updates an existing schedule.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'

      responses:
        '200':
          description: Schedule updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  cronJobId:
                    type: string
                    nullable: true
                  message:
                    type: string

        '404':
          description: Schedule not found or referenced secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete schedule
      description: Deletes a schedule.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid

      responses:
        '200':
          description: Schedule deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/schedules/{id}/logs:
    get:
      summary: Get execution logs for a schedule
      description: Returns execution history for a schedule with pagination support.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid

        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50

        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0

      responses:
        '200':
          description: Schedule execution logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduleLog'
                  totalCount:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer

        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - statusCode
      properties:
        error:
          type: string
        message:
          type: string
        statusCode:
          type: integer
        nextActions:
          type: string

    Schedule:
      type: object
      required:
        - id
        - name
        - cronSchedule
        - functionUrl
        - httpMethod
        - isActive
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        cronSchedule:
          type: string
        functionUrl:
          type: string
          format: uri
        httpMethod:
          type: string
          enum: [GET, POST, PUT, PATCH, DELETE]
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
        body:
          nullable: true
          oneOf:
            - type: string
            - type: object
        cronJobId:
          type: string
          nullable: true
        lastExecutedAt:
          type: string
          format: date-time
          nullable: true
        isActive:
          type: boolean
        nextRun:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ScheduleLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        scheduleId:
          type: string
          format: uuid
        executedAt:
          type: string
          format: date-time
        statusCode:
          type: integer
        success:
          type: boolean
        durationMs:
          type: integer
        message:
          type: string
          nullable: true

    SchedulesConfig:
      type: object
      properties:
        retentionDays:
          type: integer
          minimum: 1
          nullable: true

    UpdateSchedulesConfigRequest:
      type: object
      required:
        - retentionDays
      properties:
        retentionDays:
          type: integer
          minimum: 1
          nullable: true

    CreateScheduleRequest:
      type: object
      required:
        - name
        - cronSchedule
        - functionUrl
        - httpMethod
      properties:
        name:
          type: string
          minLength: 3
        cronSchedule:
          type: string
          description: 5-field cron expression or interval form (1-59 seconds)
        functionUrl:
          type: string
          format: uri
        httpMethod:
          type: string
          enum: [GET, POST, PUT, PATCH, DELETE]
        headers:
          type: object
          additionalProperties:
            type: string
        body:
          type: object

    UpdateScheduleRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 3
        cronSchedule:
          type: string
        functionUrl:
          type: string
          format: uri
        httpMethod:
          type: string
          enum: [GET, POST, PUT, PATCH, DELETE]
        headers:
          type: object
          additionalProperties:
            type: string
        body:
          type: object
        isActive:
          type: boolean