openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: LinkedIn Bot API specification
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: posts
    description: Post generation and publishing
  - name: queue
    description: Post queue management
  - name: schedule
    description: Scheduling management
  - name: persona
    description: Persona/bio management
  - name: config
    description: Configuration and status
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /posts/generate:
    post:
      operationId: generatePost
      tags: [posts]
      summary: Generate a LinkedIn post using AI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeneratePostRequest"
      responses:
        "200":
          description: Generated post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedPost"
        "500":
          description: Generation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /posts/publish:
    post:
      operationId: publishPost
      tags: [posts]
      summary: Publish a post to LinkedIn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishPostRequest"
      responses:
        "200":
          description: Post published
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishResult"
        "500":
          description: Publish failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /posts/image:
    post:
      operationId: generatePostImage
      tags: [posts]
      summary: Generate an image for a LinkedIn post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeneratePostImageRequest"
      responses:
        "200":
          description: Generated image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedPostImage"
        "400":
          description: Image generation request failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /posts/history:
    get:
      operationId: getPostHistory
      tags: [posts]
      summary: Get post history
      responses:
        "200":
          description: Post history
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostHistoryResponse"
    delete:
      operationId: clearPostHistory
      tags: [posts]
      summary: Clear post history
      responses:
        "200":
          description: History cleared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"

  /queue:
    get:
      operationId: getQueue
      tags: [queue]
      summary: Get the post queue
      responses:
        "200":
          description: Current queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueResponse"
    post:
      operationId: addToQueue
      tags: [queue]
      summary: Add a topic to the queue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddToQueueRequest"
      responses:
        "200":
          description: Added to queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Queue full
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      operationId: clearQueue
      tags: [queue]
      summary: Clear the entire queue
      responses:
        "200":
          description: Queue cleared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"

  /queue/{index}:
    delete:
      operationId: removeFromQueue
      tags: [queue]
      summary: Remove a specific item from the queue
      parameters:
        - name: index
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Item removed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /schedule:
    get:
      operationId: getSchedule
      tags: [schedule]
      summary: Get current schedule
      responses:
        "200":
          description: Current schedule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleResponse"
    post:
      operationId: setSchedule
      tags: [schedule]
      summary: Set auto-posting schedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetScheduleRequest"
      responses:
        "200":
          description: Schedule set
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
    delete:
      operationId: deleteSchedule
      tags: [schedule]
      summary: Delete the schedule
      responses:
        "200":
          description: Schedule deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"

  /persona:
    get:
      operationId: getPersona
      tags: [persona]
      summary: Get current persona/bio
      responses:
        "200":
          description: Current persona
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonaResponse"
    put:
      operationId: updatePersona
      tags: [persona]
      summary: Update persona/bio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePersonaRequest"
      responses:
        "200":
          description: Persona updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
    delete:
      operationId: deletePersona
      tags: [persona]
      summary: Clear the persona
      responses:
        "200":
          description: Persona cleared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"

  /config:
    get:
      operationId: getConfig
      tags: [config]
      summary: Get configuration status (which tokens are set)
      responses:
        "200":
          description: Configuration status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"

  /stats:
    get:
      operationId: getStats
      tags: [posts]
      summary: Get posting stats summary
      responses:
        "200":
          description: Stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsResponse"

components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
        - error

    SuccessResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message

    GeneratePostRequest:
      type: object
      properties:
        topic:
          type: string
        tone:
          type: string
          enum: [formal, casual, humorous, professional]
        length:
          type: string
          enum: [short, long]

    GeneratedPost:
      type: object
      properties:
        text:
          type: string
      required:
        - text

    PublishPostRequest:
      type: object
      properties:
        text:
          type: string
        topic:
          type: string
        imageUrl:
          type: string
        sourceImageUrl:
          type: string
      required:
        - text

    GeneratePostImageRequest:
      type: object
      properties:
        text:
          type: string
        topic:
          type: string
      required:
        - text

    GeneratedPostImage:
      type: object
      properties:
        imageUrl:
          type: string
        sourceImageUrl:
          type: string
        prompt:
          type: string
      required:
        - imageUrl
        - sourceImageUrl
        - prompt

    PublishResult:
      type: object
      properties:
        postId:
          type: string
        message:
          type: string
      required:
        - postId
        - message

    PostHistoryItem:
      type: object
      properties:
        date:
          type: string
        topic:
          type: string
        text:
          type: string
      required:
        - date
        - topic
        - text

    PostHistoryResponse:
      type: object
      properties:
        history:
          type: array
          items:
            $ref: "#/components/schemas/PostHistoryItem"
      required:
        - history

    QueueItem:
      type: object
      properties:
        topic:
          type: string
        added:
          type: string
      required:
        - topic
        - added

    QueueResponse:
      type: object
      properties:
        queue:
          type: array
          items:
            $ref: "#/components/schemas/QueueItem"
        maxSize:
          type: integer
      required:
        - queue
        - maxSize

    AddToQueueRequest:
      type: object
      properties:
        topic:
          type: string
      required:
        - topic

    ScheduleResponse:
      type: object
      properties:
        schedule:
          type: object
          nullable: true
          properties:
            hour:
              type: integer
            minute:
              type: integer
            timezone:
              type: string
            scheduledDate:
              type: string
              nullable: true
          required:
            - hour
            - minute
            - timezone
      required:
        - schedule

    SetScheduleRequest:
      type: object
      properties:
        hour:
          type: integer
          minimum: 0
          maximum: 23
        minute:
          type: integer
          minimum: 0
          maximum: 59
        timezone:
          type: string
        scheduledDate:
          type: string
      required:
        - hour
        - minute

    PersonaResponse:
      type: object
      properties:
        bio:
          type: string
      required:
        - bio

    UpdatePersonaRequest:
      type: object
      properties:
        bio:
          type: string
      required:
        - bio

    ConfigResponse:
      type: object
      properties:
        linkedinConfigured:
          type: boolean
        groqConfigured:
          type: boolean
      required:
        - linkedinConfigured
        - groqConfigured

    StatsResponse:
      type: object
      properties:
        totalPosts:
          type: integer
        postsThisWeek:
          type: integer
        postsThisMonth:
          type: integer
        queueSize:
          type: integer
        scheduleActive:
          type: boolean
        topTopics:
          type: array
          items:
            type: object
            properties:
              topic:
                type: string
              count:
                type: integer
            required:
              - topic
              - count
      required:
        - totalPosts
        - postsThisWeek
        - postsThisMonth
        - queueSize
        - scheduleActive
        - topTopics
