openapi: 3.1.0
info:
  title: Wpix Public API
  version: "1.0.0"
  description: >
    API pública de leitura de doações da Wpix. Autenticação via API key
    (Bearer). Webhooks (donation.created) são configurados pelo streamer no
    dashboard (app/dashboard/api) — não fazem parte desta API v1.
servers:
  - url: https://SEU_DOMINIO/api/v1

security:
  - bearerApiKey: []

paths:
  /me:
    get:
      summary: Confirma a API key e retorna o streamer dono dela
      operationId: getMe
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  streamer:
                    $ref: "#/components/schemas/Streamer"
                  scopes:
                    type: array
                    items:
                      type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"

  /donations:
    get:
      summary: Lista as doações do streamer dono da API key
      operationId: listDonations
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: before
          in: query
          description: >
            Cursor opaco (base64url de {"created_at","id"}) da última doação
            da página anterior. Estável mesmo com timestamps iguais.
          schema: { type: string }
        - name: since
          in: query
          description: Retorna apenas doações criadas a partir desta data (ISO 8601)
          schema: { type: string, format: date-time }
        - name: status
          in: query
          description: Nesta versão apenas RECEIVED é aceito (padrão implícito).
          schema:
            type: string
            enum: [RECEIVED]
            default: RECEIVED
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  donations:
                    type: array
                    items: { $ref: "#/components/schemas/Donation" }
                  next_cursor:
                    type: string
                    nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/RateLimited"

  /donations/{id}:
    get:
      summary: Detalhe de uma doação específica
      operationId: getDonation
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  donation: { $ref: "#/components/schemas/Donation" }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: >
            Doação não encontrada, ou pertence a outro streamer (nunca 403 —
            evitamos revelar a existência do id de outro streamer).
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      description: >
        API key gerada no dashboard (Configurações > API), formato
        `ak_live_<hex>`. Enviar como `Authorization: Bearer ak_live_...`.

  schemas:
    Streamer:
      type: object
      properties:
        id: { type: string, format: uuid }
        display_name: { type: string }
        slug: { type: string }

    Donation:
      type: object
      description: >
        Nunca inclui donor_email, dados de pagamento (provider_charge_id,
        qr_payload) nem qualquer campo interno/PII.
      properties:
        id: { type: string, format: uuid }
        donor_name: { type: string }
        message: { type: string, nullable: true }
        amount_cents: { type: integer }
        status:
          type: string
          enum: [PENDING, RECEIVED, OVERDUE, REFUNDED, CANCELLED, FAILED]
        paid_at: { type: string, format: date-time, nullable: true }
        created_at: { type: string, format: date-time }

  responses:
    Unauthorized:
      description: API key ausente, inválida ou revogada
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
    Forbidden:
      description: "API key sem o escopo necessário (ex.: falta donations:read)"
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
    UnprocessableEntity:
      description: Parâmetro de filtro inválido (status ou since malformado)
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
    RateLimited:
      description: Rate limit excedido (padrão 100 req/min por API key)
      headers:
        Retry-After:
          schema: { type: integer }
          description: Segundos até a janela liberar
        X-RateLimit-Limit: { schema: { type: integer } }
        X-RateLimit-Remaining: { schema: { type: integer } }
        X-RateLimit-Reset: { schema: { type: integer } }
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
