lib/api-spec/openapi.yaml

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: API specification for FB Group Publisher PRO
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: me
    description: Current user
  - name: subscription
    description: PayPal subscription management
  - name: paypal
    description: PayPal webhook
  - name: savedLists
    description: Saved group lists
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /me:
    get:
      operationId: getMe
      tags: [me]
      summary: Get current user with subscription state
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeResponse"
        "401":
          description: Unauthorized

  /subscription/create:
    post:
      operationId: createSubscription
      tags: [subscription]
      summary: Create PayPal subscription, returns approval URL
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSubscriptionResponse"
        "401":
          description: Unauthorized

  /subscription/activate:
    post:
      operationId: activateSubscription
      tags: [subscription]
      summary: Activate subscription after PayPal approval
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActivateSubscriptionBody"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionState"

  /subscription/cancel:
    post:
      operationId: cancelSubscription
      tags: [subscription]
      summary: Cancel current subscription
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionState"

  /paypal/webhook:
    post:
      operationId: paypalWebhook
      tags: [paypal]
      summary: PayPal webhook receiver
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /saved-lists:
    get:
      operationId: listSavedLists
      tags: [savedLists]
      summary: List saved group lists
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListSavedListsResponse"
        "401":
          description: Unauthorized
    post:
      operationId: createSavedList
      tags: [savedLists]
      summary: Save a group list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSavedListBody"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SavedList"

  /saved-lists/{id}:
    delete:
      operationId: deleteSavedList
      tags: [savedLists]
      summary: Delete a saved list
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Deleted

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

    SubscriptionState:
      type: object
      properties:
        status:
          type: string
          enum: [none, trialing, active, cancelled, suspended, expired]
        trialEnd:
          type: [string, "null"]
          format: date-time
        currentPeriodEnd:
          type: [string, "null"]
          format: date-time
        paypalSubscriptionId:
          type: [string, "null"]
        hasAccess:
          type: boolean
      required:
        - status
        - hasAccess

    MeResponse:
      type: object
      properties:
        userId:
          type: string
        email:
          type: [string, "null"]
        subscription:
          $ref: "#/components/schemas/SubscriptionState"
      required:
        - userId
        - subscription

    CreateSubscriptionResponse:
      type: object
      properties:
        subscriptionId:
          type: string
        approvalUrl:
          type: string
      required:
        - subscriptionId
        - approvalUrl

    ActivateSubscriptionBody:
      type: object
      properties:
        subscriptionId:
          type: string
      required:
        - subscriptionId

    SavedList:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        groupIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - groupIds
        - createdAt

    ListSavedListsResponse:
      type: array
      items:
        $ref: "#/components/schemas/SavedList"

    CreateSavedListBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
        groupIds:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - name
        - groupIds