openapi.yaml

openapi: 3.1.0
info:
  title: C++ REST API Template
  description: |
    Infrastructure endpoints for the C++ REST API template: health probes
    and a background-job API. Authentication is opt-in (auth.mode=jwt|bearer|none).
    Rate-limiting and idempotency are driven by headers.
  version: 1.0.0
  contact:
    name: Platform team
servers:
  - url: http://localhost:8080
    description: Local dev
  - url: https://api.example.com
    description: Production

# Global security — attached per-operation below where needed.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    # Browser-SPA session: the access JWT travels in an HttpOnly
    # __Host- cookie set by POST /api/auth/login (auth.cookies.* in
    # config/config.json). Same-origin only — the SPA never reads it
    # from JS; fetch sends it via credentials: 'include'.
    cookieAuth:
      type: apiKey
      in: cookie
      name: __Host-access

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Opaque client-generated key. First request with this key + body hash
        is executed and its response cached; subsequent requests replay it.
        Conflicting body with the same key returns 422.
      schema:
        type: string
        maxLength: 256
    Traceparent:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context header.
      schema:
        type: string
        pattern: '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$'

  schemas:
    # Mirrors ErrorResponse::make in src/utils/ErrorResponse.cpp — every
    # error body carries `error` AND the numeric `status` (message/extras
    # optional). The schema used to omit `status`; the e2e schema validation
    # surfaced the drift.
    Error:
      type: object
      required: [error, status]
      properties:
        error: { type: string }
        status: { type: integer, description: "HTTP status code, duplicated into the body" }
        message: { type: string }
        code: { type: string }

    ValidationError:
      type: object
      required: [error, status, errors]
      properties:
        error:
          type: string
          enum: [validation_failed]
        status: { type: integer }
        errors:
          type: array
          items:
            type: object
            required: [field, code, message]
            properties:
              field: { type: string }
              code: { type: string }
              message: { type: string }

    # Mirrors Jobs::Job::to_json() in src/jobs/Jobs.hpp.
    Job:
      type: object
      required: [id, type, status, created_at]
      properties:
        id:          { type: string, format: uuid }
        type:        { type: string }
        payload:     { type: object, additionalProperties: true }
        status:
          type: string
          enum: [pending, processing, completed, failed, dead]
        result:      { nullable: true }
        error:       { type: string }
        worker_id:   { type: string }
        trace_id:    { type: string, description: W3C trace id of the submitting request — deep-link into Jaeger }
        retry_count: { type: integer }
        max_retries: { type: integer }
        created_at:  { type: integer, format: int64, description: Epoch seconds }
        updated_at:  { type: integer, format: int64, description: Epoch seconds }

    # Mirrors Domain::to_json(Role) in src/domain/Role.hpp.
    Role:
      type: object
      required: [id, name, permissions, is_default]
      properties:
        id:          { type: integer }
        name:        { type: string }
        permissions: { type: integer, description: Bitmask — Domain::Permission::k* }
        is_default:  { type: boolean }

    # Mirrors Domain::to_json(User) in src/domain/User.hpp.
    # `role` is only present when the row was loaded with its role joined.
    User:
      type: object
      required: [id, email, full_name, confirmed, role_id, created_at, updated_at]
      properties:
        id:         { type: string, format: uuid }
        email:      { type: string, format: email }
        first_name: { type: ['string', 'null'] }
        last_name:  { type: ['string', 'null'] }
        full_name:  { type: string }
        confirmed:  { type: boolean }
        role_id:    { type: integer }
        role:       { $ref: '#/components/schemas/Role' }
        created_at: { type: string }
        updated_at: { type: string }

    UserListResponse:
      type: object
      required: [data, total, limit, offset]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/User' }
        total:  { type: integer }
        limit:  { type: integer }
        offset: { type: integer }

    JobListResponse:
      type: object
      required: [data, total, limit, offset]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Job' }
        total:  { type: integer }
        limit:  { type: integer }
        offset: { type: integer }

    DlqListResponse:
      type: object
      required: [data, count, depth]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Job' }
        count: { type: integer, description: Number of jobs returned (after type filter + limit) }
        depth: { type: integer, description: Total DLQ depth (unfiltered) }

    AuditEntry:
      type: object
      required: [id, action, target_type, details, created_at]
      properties:
        id:          { type: integer, format: int64 }
        actor_id:    { type: string, nullable: true, description: Acting principal subject (uuid), or null for a system action }
        action:      { type: string, description: 'Dotted verb, e.g. user.create' }
        target_type: { type: string, description: 'Affected entity kind, e.g. user / role' }
        target_id:   { type: string, nullable: true, description: Affected entity id (uuid or int as text) }
        details:     { type: object, additionalProperties: true, description: Action-specific context }
        created_at:  { type: string, format: date-time }

    AuditListResponse:
      type: object
      required: [data, total, limit, offset]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AuditEntry' }
        total:  { type: integer }
        limit:  { type: integer }
        offset: { type: integer }

    JobCreate:
      type: object
      required: [type]
      properties:
        type:        { type: string, minLength: 1 }
        payload:     { type: object, additionalProperties: true }
        max_retries: { type: integer, minimum: 0, maximum: 20 }

    # GET /api/auth/me, POST /api/auth/login, POST /api/auth/refresh.
    # Mirrors AuthController::me/login/refresh — Response::ok({{"user", user}}).
    MeResponse:
      type: object
      required: [user]
      properties:
        user: { $ref: '#/components/schemas/User' }

    # GET/PATCH /api/admin/users/{id}, POST /api/admin/users.
    # Mirrors AdminController::getUser/updateUser/createUser —
    # Response::ok/created({{"data", user}}).
    UserDetailResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/User' }

    # POST /api/admin/invite. Mirrors AdminController::inviteUser —
    # Response::created({{"data", user}, {"message", "Invitation sent"}}).
    InviteResponse:
      type: object
      required: [data]
      properties:
        data:    { $ref: '#/components/schemas/User' }
        message: { type: string }

    # GET /api/admin/roles. Mirrors AdminController::listRoles —
    # Response::list({{"data", [...roles]}}).
    RolesResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Role' }

    # POST/PATCH /api/admin/roles[/{id}]. Mirrors AdminController::createRole/
    # updateRole — Response::ok({{"data", role}}).
    RoleDetailResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/Role' }

    # Generic "{message: ...}" envelope: logout, delete user/role, etc.
    MessageResponse:
      type: object
      properties:
        message: { type: string }

    # POST /api/v1/auth/register. Mirrors AuthController::registerUser —
    # Response::created({{"user", user}, {"message", ...}}).
    RegisterResponse:
      type: object
      required: [user, message]
      properties:
        user:    { $ref: '#/components/schemas/User' }
        message: { type: string }

    # Mirrors Domain::to_json(Post) in src/domain/Post.hpp — the full admin
    # shape (includes the raw Markdown body). The public index serves the
    # lighter PostCard projection documented inline on /api/v1/public/posts.
    Post:
      type: object
      required: [id, slug, title, summary, body, status, topic, tags, published_at, created_at, updated_at]
      properties:
        id:           { type: string, format: uuid }
        slug:         { type: string }
        title:        { type: string }
        summary:      { type: string }
        body:         { type: string }
        status:       { type: string, enum: [draft, published] }
        topic:        { type: string }
        tags:         { type: array, items: { type: string } }
        published_at: { type: ['string', 'null'], format: date-time }
        created_at:   { type: string }
        updated_at:   { type: string }

    # GET/POST/PATCH /api/v1/posts[/{id}]. Mirrors PostsController —
    # Response::ok/created({{"data", post}}).
    PostDetailResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/Post' }

    # Mirrors Domain::to_json(Package) in src/domain/Billing.hpp.
    BillingPackage:
      type: object
      required: [id, title, amount_cents, credits, active, sort, created_at, updated_at]
      properties:
        id:           { type: string, format: uuid }
        title:        { type: string }
        amount_cents: { type: integer, format: int64 }
        credits:      { type: integer, format: int64 }
        active:       { type: boolean }
        sort:         { type: integer }
        created_at:   { type: string }
        updated_at:   { type: string }

    # GET /api/v1/billing/packages also surfaces the current per-unit rate and
    # the custom-amount bounds — a custom-amount input validates
    # against these client-side, and a package's own price/credits ratio can
    # legitimately differ from the generic rate (a bonus/discount package),
    # so they aren't derivable from the package list alone.
    BillingPackageListResponse:
      type: object
      required: [data, credits_per_unit, min_amount_cents, max_amount_cents]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/BillingPackage' }
        credits_per_unit: { type: integer, format: int64, description: "billing.credits_per_unit — credits per 100 cents" }
        min_amount_cents: { type: integer, format: int64, description: Minimum accepted amount_cents for a custom top-up }
        max_amount_cents: { type: integer, format: int64, description: Maximum accepted amount_cents for a custom top-up }

    # Mirrors Domain::to_json(WalletEntry) in src/domain/Billing.hpp — the
    # full internal/admin shape, INCLUDING created_by. Not used by the
    # user-facing GET /api/v1/billing/wallet response — see PublicWalletEntry.
    WalletEntry:
      type: object
      required: [id, user_id, delta_credits, kind, reference, note, created_at]
      properties:
        id:            { type: string, format: uuid }
        user_id:       { type: string, format: uuid }
        delta_credits: { type: integer, format: int64 }
        kind:          { type: string, enum: [topup, spend, adjustment, refund] }
        reference:     { type: string }
        note:          { type: string }
        created_by:    { type: ['string', 'null'], format: uuid }
        created_at:    { type: string }

    # GET /api/v1/billing/wallet's ledger rows. Deliberately OMITS
    # created_by (an admin's raw UUID on adjustment rows) — that's
    # internal/admin-only information, not something an end user's own
    # wallet view should ever leak. See BillingController::public_wallet_entry.
    PublicWalletEntry:
      type: object
      required: [id, user_id, delta_credits, kind, reference, note, created_at]
      properties:
        id:            { type: string, format: uuid }
        user_id:       { type: string, format: uuid }
        delta_credits: { type: integer, format: int64 }
        kind:          { type: string, enum: [topup, spend, adjustment, refund] }
        reference:     { type: string }
        note:          { type: string }
        created_at:    { type: string }

    # GET /api/v1/billing/wallet. Mirrors BillingController::getWallet.
    WalletResponse:
      type: object
      required: [data, limit, offset]
      properties:
        data:
          type: object
          required: [balance, history]
          properties:
            balance: { type: integer, format: int64 }
            history:
              type: array
              items: { $ref: '#/components/schemas/PublicWalletEntry' }
        limit:  { type: integer }
        offset: { type: integer }

    # POST /api/v1/billing/topup. Mirrors BillingController::topup — the
    # approve URL only; no credit count is ever present here.
    TopupResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [order_id, approve_url]
          properties:
            order_id:    { type: string, description: PayPal order id — pass back to POST .../capture }
            approve_url: { type: string, format: uri, description: Redirect the buyer here to approve the order on PayPal }

    # POST /api/v1/billing/capture. Mirrors BillingController::capture.
    CaptureResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [credited, balance, status]
          properties:
            credited: { type: boolean, description: "false on an idempotent replay, or when PayPal has not yet COMPLETED the capture" }
            balance:  { type: integer, format: int64, description: Wallet balance AFTER this call (unchanged if not credited) }
            status:
              type: string
              description: >
                "captured" once this or an earlier call credited the wallet;
                otherwise PayPal's own capture status verbatim (e.g.
                "PENDING", "DECLINED") — PayPal answers 2xx for both, so this
                is how a caller tells a settled capture from one still in
                flight.
            pending:
              type: boolean
              description: Present (true) only when PayPal's capture has not reached COMPLETED yet — the payment is left uncaptured for the webhook to resolve.

    # POST /api/v1/billing/paypal/webhook. `handled` distinguishes "this event
    # type applies real ledger logic" (PAYMENT.CAPTURE.COMPLETED/REFUNDED/
    # REVERSED — see BillingController::handleCaptureRefunded's doc comment
    # for why REVERSED shares REFUNDED's handling) from "acknowledged but
    # deliberately not acted on" (an unrelated event type) — both answer 200
    # either way, since PayPal retries any non-2xx for days.
    WebhookAckResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [handled]
          properties:
            handled: { type: boolean, description: "true if this event type drives real crediting/refund logic (whether or not it was a no-op replay); false for an ignored/unrecognized event type" }

    # GET/POST/PATCH /api/v1/admin/billing/packages[/{id}]. Same shape as the
    # user-facing BillingPackage — the admin view just isn't filtered to
    # active=true.
    AdminPackageResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/BillingPackage' }

    AdminPackageListResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/BillingPackage' }

    # GET /api/v1/admin/billing/payments. Mirrors Domain::to_json(Payment).
    AdminPaymentListResponse:
      type: object
      required: [data, total, limit, offset]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Payment' }
        total:  { type: integer }
        limit:  { type: integer }
        offset: { type: integer }

    Payment:
      type: object
      required:
        - id
        - user_id
        - provider
        - provider_order_id
        - amount_cents
        - currency
        - credits_expected
        - rate_snapshot
        - status
        - created_at
        - updated_at
      properties:
        id:                  { type: string, format: uuid }
        user_id:             { type: string, format: uuid }
        provider:             { type: string }
        provider_order_id:    { type: string }
        provider_capture_id:  { type: ['string', 'null'] }
        amount_cents:         { type: integer, format: int64 }
        currency:             { type: string }
        credits_expected:     { type: integer, format: int64 }
        rate_snapshot:        { type: integer, format: int64 }
        package_id:           { type: ['string', 'null'], format: uuid }
        status:               { type: string, enum: [created, approved, captured, failed, refunded] }
        failure_reason:       { type: ['string', 'null'] }
        created_at:           { type: string }
        updated_at:           { type: string }

    # GET/PUT /api/v1/admin/billing/settings. Mirrors Domain::to_json(BillingSettings).
    BillingSettings:
      type: object
      required: [credits_per_unit, min_amount_cents, max_amount_cents, updated_at]
      properties:
        credits_per_unit: { type: integer, format: int64, description: Credits granted per 100 cents on a custom-amount top-up }
        min_amount_cents: { type: integer, format: int64 }
        max_amount_cents: { type: integer, format: int64 }
        updated_at:       { type: string }

    BillingSettingsResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/BillingSettings' }

    # POST /api/v1/admin/billing/users/{id}/adjust. Mirrors
    # AdminBillingController::adjustWallet — deliberately does NOT echo the
    # ledger row's full shape (no reference/kind/note round-trip needed by a
    # caller that already knows what it just sent).
    AdjustResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [balance, credited]
          properties:
            balance:  { type: integer, format: int64, description: Wallet balance AFTER this adjustment }
            credited: { type: boolean, description: "false only if this exact adjustment somehow no-op'd (not expected in normal use — adjust() has no idempotency key)" }

    # GET /api/v1/admin/billing/metrics. Mirrors AdminBillingController::metrics
    # / BillingMetricsRepository::get. All money in integer cents, all credits
    # integers — no floating point except conversion.rate.
    BillingMetricsResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required:
            - period
            - revenue_cents
            - payments_count
            - avg_payment_cents
            - conversion
            - refunds_cents
            - refunds_count
            - outstanding_credits
            - outstanding_value_cents
            - series
            - top_packages
            - top_users
          properties:
            period:                   { type: string, enum: [day, week, month] }
            revenue_cents:            { type: integer, format: int64, description: "Sum of amount_cents over captured payments in-window" }
            payments_count:           { type: integer, format: int64, description: "Count of captured payments in-window" }
            avg_payment_cents:        { type: integer, format: int64, description: "revenue_cents / payments_count (integer division; 0 if payments_count is 0)" }
            conversion:
              type: object
              required: [created, captured, rate]
              properties:
                created:  { type: integer, format: int64, description: Every payment (any status) created in-window }
                captured: { type: integer, format: int64, description: Of those, how many reached captured }
                rate:     { type: number, format: double, description: "captured / created as a float ratio; 0 if created is 0" }
            refunds_cents:            { type: integer, format: int64, description: "Sum of billing_refunds.amount_cents in-window, outcome='applied' only" }
            refunds_count:            { type: integer, format: int64, description: "Count of billing_refunds rows in-window, outcome='applied' only" }
            outstanding_credits:      { type: integer, format: int64, description: "SUM(wallet_balances.credits) — all-time liability, NOT windowed" }
            outstanding_value_cents:  { type: integer, format: int64, description: "outstanding_credits * 100 / credits_per_unit (integer math, current billing_settings rate)" }
            series:
              type: array
              description: "Calendar-bucketed (hourly for period=day, daily otherwise); every bucket in range is present, zero-filled if no captured payments landed in it"
              items:
                type: object
                required: [bucket_start, revenue_cents, payments_count]
                properties:
                  bucket_start:    { type: string, description: ISO-8601 UTC bucket start }
                  revenue_cents:   { type: integer, format: int64 }
                  payments_count:  { type: integer, format: int64 }
            top_packages:
              type: array
              description: "Top 5 packages by revenue among captured payments in-window"
              items:
                type: object
                required: [package_id, title, revenue_cents, payments_count]
                properties:
                  package_id:      { type: string, format: uuid }
                  title:           { type: string }
                  revenue_cents:   { type: integer, format: int64 }
                  payments_count:  { type: integer, format: int64 }
            top_users:
              type: array
              description: "Top 5 users by top-up credits among captured payments in-window"
              items:
                type: object
                required: [user_id, email, topup_credits, revenue_cents]
                properties:
                  user_id:         { type: string, format: uuid }
                  email:           { type: string, format: email }
                  topup_credits:   { type: integer, format: int64 }
                  revenue_cents:   { type: integer, format: int64 }

# -----------------------------------------------------------------------------
paths:
  /:
    get:
      summary: Endpoint discovery — list every registered route
      tags: [health]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  version: { type: string }
                  endpoints:
                    type: array
                    items:
                      type: object
                      required: [method, path, description]
                      properties:
                        method: { type: string }
                        path: { type: string }
                        description: { type: string }
  /healthz:
    get:
      summary: Liveness probe
      tags: [health]
      responses:
        '200':
          description: Process is alive
          content:
            application/json:
              schema:
                type: object
                required: [status, timestamp]
                properties:
                  status:    { type: string, enum: [alive] }
                  timestamp: { type: integer, format: int64, description: Epoch seconds }
  /ready:
    get:
      summary: Readiness probe
      tags: [health]
      responses:
        '200': { description: Ready }
        '503': { description: Draining or dependency unhealthy }
  /health:
    get:
      summary: Detailed component health
      tags: [health]
      responses:
        '200': { description: All components healthy }
        '503': { description: One or more components unhealthy }

  # ── Auth ───────────────────────────────────────────────────────────────────
  /api/v1/auth/register:
    post:
      summary: Register a new user
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:      { type: string, format: email }
                password:   { type: string, minLength: 8, maxLength: 128 }
                first_name: { type: string }
                last_name:  { type: string }
      responses:
        '201':
          description: User created — confirmation email queued
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RegisterResponse' }
        '400': { description: Validation failed }
        '409': { description: Email already registered }
        '422':
          description: Idempotency-Key conflict — same key, different body (idempotency middleware)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /api/v1/auth/login:
    post:
      summary: Log in
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:    { type: string, format: email }
                password: { type: string }
      responses:
        '200':
          description: Logged in — Set-Cookie access + refresh
          headers:
            Set-Cookie:
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MeResponse' }
        '401':
          description: Invalid email or password
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '415':
          description: Body content type is not application/json (content-type middleware — applies to every JSON API endpoint)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /api/v1/auth/logout:
    post:
      summary: Log out (clears cookies + revokes refresh token)
      tags: [auth]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Logged out
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageResponse' }
  /api/v1/auth/refresh:
    post:
      summary: Rotate access + refresh tokens
      tags: [auth]
      responses:
        '200':
          description: New cookies issued
          headers:
            Set-Cookie:
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MeResponse' }
        '401':
          description: Refresh token missing / expired / revoked
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /api/v1/auth/me:
    get:
      summary: Get the authenticated user
      tags: [auth]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Current user
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MeResponse' }
        '401': { description: Not authenticated }

  # ── Account self-service ───────────────────────────────────────────────────
  /api/v1/account/confirm-resend:
    post:
      summary: Resend the email-confirmation link to the current user
      tags: [account]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: Confirmation email queued }
        '401': { description: Not authenticated }
  /api/v1/account/confirm/{token}:
    post:
      summary: Confirm an account from an email link
      tags: [account]
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Account confirmed }
        '400': { description: Invalid or expired token }
        '404': { description: User not found }
  /api/v1/account/reset-password-request:
    post:
      summary: Start a password reset (email-based)
      tags: [account]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        '200': { description: "If the email is registered, a reset link is on its way" }
  /api/v1/account/reset-password/{token}:
    post:
      summary: Apply a password reset using an email-link token
      tags: [account]
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [new_password]
              properties:
                new_password: { type: string, minLength: 8, maxLength: 128 }
      responses:
        '200': { description: Password updated }
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /api/v1/account/change-email-request:
    post:
      summary: Start an email-change flow (verifies password, mails a link to new address)
      tags: [account]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [new_email, password]
              properties:
                new_email: { type: string, format: email }
                password:  { type: string }
      responses:
        '200': { description: Confirmation email sent to the new address }
        '401': { description: Wrong password or not authenticated }
  /api/v1/account/change-email/{token}:
    post:
      summary: Apply a pending email change from token
      tags: [account]
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Email updated }
        '400': { description: Invalid or expired token }
        '409': { description: Email already in use }
  /api/v1/account/join-from-invite/{token}:
    post:
      summary: Set password and confirm account from an invite token
      tags: [account]
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [new_password]
              properties:
                new_password: { type: string, minLength: 8, maxLength: 128 }
      responses:
        '200': { description: Account ready — the invitee can now sign in }
        '400': { description: Invalid or expired invitation token }
  /api/v1/account/change-password:
    post:
      summary: Change password while logged in (verifies old password)
      tags: [account]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [old_password, new_password]
              properties:
                old_password: { type: string }
                new_password: { type: string, minLength: 8, maxLength: 128 }
      responses:
        '200': { description: Password updated }
        '401': { description: Wrong current password or not authenticated }

  /api/v1/account/api-keys:
    get:
      summary: List your API keys (metadata only; never the secret)
      tags: [account]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: "Array of API key metadata under data[]" }
        '401': { description: Not authenticated }
    post:
      summary: Create an API key — the secret is returned ONCE in this response
      tags: [account]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        '201': { description: Key created; `key` field holds the one-time secret }
        '401': { description: Not authenticated }

  /api/v1/account/api-keys/{id}:
    delete:
      summary: Revoke one of your API keys
      tags: [account]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200': { description: Key revoked }
        '401': { description: Not authenticated }
        '404': { description: No such key (or not yours) }

  # ── Admin (require Permission::ADMINISTER) ────────────────────────────────
  /api/v1/admin/users:
    get:
      summary: List users (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: User page
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserListResponse' }
        '403':
          description: Not an admin
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
    post:
      summary: Create a confirmed user (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:      { type: string, format: email }
                password:   { type: string, minLength: 8, maxLength: 128 }
                first_name: { type: string }
                last_name:  { type: string }
                role_id:    { type: integer }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserDetailResponse' }
        '400': { description: Validation failed }
        '403': { description: Not an admin }
        '409': { description: Email already registered }
  /api/v1/admin/invite:
    post:
      summary: Invite a user via email (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:      { type: string, format: email }
                first_name: { type: string }
                last_name:  { type: string }
                role_id:    { type: integer }
      responses:
        '201':
          description: Invited
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InviteResponse' }
        '403': { description: Not an admin }
        '409': { description: Email already registered }
  /api/v1/admin/users/{id}:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: User detail (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: User row with role
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserDetailResponse' }
        '403': { description: Not an admin }
        '404': { description: User not found }
    patch:
      summary: Update user — email / role_id / first_name / last_name (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email:      { type: string, format: email }
                role_id:    { type: integer }
                first_name: { type: string }
                last_name:  { type: string }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserDetailResponse' }
        '400': { description: Self role-change refused or validation failed }
        '403': { description: Not an admin }
        '404': { description: User not found }
        '409': { description: Email already taken }
    delete:
      summary: Delete user (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageResponse' }
        '400': { description: Self-delete refused }
        '403': { description: Not an admin }
        '404': { description: User not found }
  /api/v1/admin/roles:
    get:
      summary: List roles (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Roles
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RolesResponse' }
        '403': { description: Not an admin }
    post:
      summary: Create a role (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, permissions]
              properties:
                name:        { type: string, minLength: 1, maxLength: 64 }
                permissions: { type: integer, description: Bitmask — see Domain::Permission::k* in src/domain/Role.hpp }
                is_default:  { type: boolean, default: false }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoleDetailResponse' }
        '400': { description: Validation failed }
        '403': { description: Not an admin }
        '409': { description: Role name already exists }
  /api/v1/admin/roles/{id}:
    parameters:
      - { name: id, in: path, required: true, schema: { type: integer } }
    patch:
      summary: Update role (admin) — partial; pass any of name / permissions / is_default
      tags: [admin]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:        { type: string, minLength: 1, maxLength: 64 }
                permissions: { type: integer }
                is_default:  { type: boolean }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoleDetailResponse' }
        '400': { description: Empty patch or invalid id }
        '403': { description: Not an admin }
        '404': { description: Role not found }
        '409': { description: Role name already exists }
    delete:
      summary: Delete role (admin)
      tags: [admin]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageResponse' }
        '400': { description: Default role cannot be deleted }
        '403': { description: Not an admin }
        '404': { description: Role not found }
        '409': { description: Role is referenced by users — reassign first }

  /api/v1/admin/audit:
    get:
      summary: List the audit trail (admin)
      description: Requires the audit-read permission bit (Domain::Permission::kAuditRead); full admins hold it.
      tags: [admin]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: limit,       in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: offset,      in: query, schema: { type: integer, minimum: 0, default: 0 } }
        - { name: action,      in: query, schema: { type: string }, description: "Exact action filter, e.g. user.create" }
        - { name: actor_id,    in: query, schema: { type: string }, description: Filter by acting principal subject }
        - { name: target_type, in: query, schema: { type: string }, description: "Filter by target kind, e.g. user / role" }
        - { name: from,        in: query, schema: { type: string, format: date-time }, description: created_at lower bound }
        - { name: to,          in: query, schema: { type: string, format: date-time }, description: created_at upper bound }
      responses:
        '200':
          description: Audit page (newest first)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AuditListResponse' }
        '403': { description: Missing the audit-read permission }

  /api/v1/jobs:
    get:
      summary: List jobs (admin; newest first, offset-paginated)
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: type,   in: query, schema: { type: string } }
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: "Job page: { data, total, limit, offset }"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/JobListResponse' }
        '401':
          description: Not authenticated (auth middleware — the route is not in api.public_paths)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403': { description: Not an admin }
    post:
      summary: Submit a background job
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/JobCreate' }
      responses:
        '201': { description: Submitted }
        '400': { description: Validation failed }

  /api/v1/jobs/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      summary: Get job status
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: OK }
        '404': { description: Not found }
    delete:
      summary: Cancel a pending/processing job
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: Cancelled }
        '404': { description: Not found or already finished }

  /api/v1/jobs/dlq:
    get:
      summary: List dead-letter queue jobs
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: type,  in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DlqListResponse' }

  /api/v1/jobs/dlq/{id}/requeue:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      summary: Requeue a DLQ job (resets retry_count, pushes to live queue)
      tags: [jobs]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: Requeued }
        '404': { description: Not found or not in DLQ }

  /api/v1/posts:
    get:
      summary: List posts (admin; offset-paginated, filterable)
      tags: [posts]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
        - { name: q,      in: query, schema: { type: string }, description: Case-insensitive search over title+slug+summary }
        - { name: status, in: query, schema: { type: string, enum: [draft, published] } }
        - { name: topic,  in: query, schema: { type: string } }
        - { name: tag,    in: query, schema: { type: string } }
      responses:
        '200': { description: "{ data, total, limit, offset }" }
        '403': { description: Not an admin }
    post:
      summary: Create post (admin)
      tags: [posts]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug, title]
              properties:
                slug:    { type: string, minLength: 1, maxLength: 160 }
                title:   { type: string, minLength: 1, maxLength: 255 }
                summary: { type: string }
                body:    { type: string }
                status:  { type: string, enum: [draft, published], default: draft }
                topic:   { type: string, maxLength: 80, description: "Section label (e.g. Kubernetes)" }
                tags:
                  type: array
                  description: "Keyword tags driving the index tag cloud. No commas or line breaks per tag."
                  items: { type: string, maxLength: 40 }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PostDetailResponse' }
        '400': { description: Validation failed }
        '403': { description: Not an admin }
        '409': { description: Slug already exists }
  /api/v1/posts/{id}:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: Get post (admin)
      tags: [posts]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: OK }
        '404': { description: Not found }
    patch:
      summary: Update post (admin) — partial; omitted fields keep their current value
      description: >
        Partial update. Only the fields present in the body are changed;
        omitted fields (including status) keep their current value, so a
        title-only PATCH does not unpublish the post or clear published_at.
        Send status=draft explicitly to unpublish.
      tags: [posts]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              # No `required` list: this is a partial update, so any subset of
              # the properties below is a valid body. `minProperties: 1` only
              # rejects the no-op empty object.
              minProperties: 1
              properties:
                slug:    { type: string, minLength: 1, maxLength: 160 }
                title:   { type: string, minLength: 1, maxLength: 255 }
                summary: { type: string }
                body:    { type: string }
                status:  { type: string, enum: [draft, published] }
                topic:   { type: string, maxLength: 80, description: "Section label (e.g. Kubernetes)" }
                tags:
                  type: array
                  description: "Keyword tags driving the index tag cloud. No commas or line breaks per tag."
                  items: { type: string, maxLength: 40 }
      responses:
        '200': { description: Updated }
        '400': { description: Validation failed }
        '403': { description: Not an admin }
        '404': { description: Not found }
        '409': { description: Slug already exists }
    delete:
      summary: Delete post (admin)
      tags: [posts]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: Deleted }
        '404': { description: Not found }
  /api/v1/posts/{id}/preview-token:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: "Admin: issue a draft preview link (stateless HMAC token, 1h TTL)"
      tags: [posts]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: "{ data: { url: '/posts/<slug>?preview=<token>', expires_at } }" }
        '400': { description: Invalid UUID }
        '403': { description: Not an admin }
        '404': { description: Not found }
  /api/v1/public/posts:
    get:
      summary: List published posts (public, no auth) — server-filtered, paged, optional facets
      tags: [posts]
      parameters:
        - { name: page,    in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: limit,   in: query, schema: { type: integer, minimum: 1, maximum: 50, default: 10 } }
        - { name: topic,   in: query, schema: { type: string }, description: "Exact topic; 'Other' also matches blank topics" }
        - { name: tag,     in: query, schema: { type: string }, description: Exact tag membership }
        - { name: q,       in: query, schema: { type: string }, description: Case-insensitive search over title+summary }
        - { name: include, in: query, schema: { type: string, enum: [facets] }, description: Embed facets computed over the current filter }
      responses:
        '200':
          description: Published posts, newest first
          content:
            application/json:
              schema:
                type: object
                description: >
                  The template's standard paginated list envelope
                  ({data, total, limit, offset} — see Response::paginated).
                  offset is the 0-based equivalent of the request's 1-based
                  ?page= query param (offset = (page - 1) * limit).
                required: [data, total, limit, offset]
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required: [slug, title, summary, topic, tags, published_at, read_mins]
                      properties:
                        slug:         { type: string }
                        title:        { type: string }
                        summary:      { type: string }
                        topic:        { type: string }
                        tags:         { type: array, items: { type: string } }
                        published_at: { type: string, format: date-time, nullable: true }
                        read_mins:    { type: integer }
                  total:  { type: integer }
                  limit:  { type: integer }
                  offset: { type: integer }
                  facets:
                    type: object
                    properties:
                      topics:
                        type: array
                        items:
                          type: object
                          properties: { name: { type: string }, count: { type: integer } }
                      tags:
                        type: array
                        items:
                          type: object
                          properties: { name: { type: string }, count: { type: integer } }
  /api/v1/public/posts/{slug}:
    parameters:
      - { name: slug, in: path, required: true, schema: { type: string } }
    get:
      summary: Get a published post by slug (public, no auth)
      tags: [posts]
      parameters:
        - { name: include, in: query, schema: { type: string, enum: [adjacent] }, description: "Embed prev/next published neighbours: { adjacent: { prev, next } } (null at feed edges)" }
        - { name: preview, in: query, schema: { type: string }, description: "Draft preview token (issued via /api/v1/posts/{id}/preview-token); invalid/expired behaves like 404" }
      responses:
        '200': { description: "OK — { data } (+ data.adjacent with include=adjacent)" }
        '404': { description: Not found or not published }
  /posts/{slug}:
    parameters:
      - { name: slug, in: path, required: true, schema: { type: string } }
    get:
      summary: Published post body as raw Markdown (public, no auth)
      tags: [posts]
      parameters:
        - { name: preview, in: query, schema: { type: string }, description: "Draft preview token (issued via /api/v1/posts/{id}/preview-token); reveals that draft's Markdown when valid; invalid/expired/mismatched behaves like 404" }
      responses:
        '200':
          description: "Markdown body: a `# {title}` heading line, a blank line, then the post's raw body"
          content:
            text/markdown:
              schema: { type: string }
        '404':
          description: Content module disabled, unknown slug, or a draft with no (valid, matching) preview token — all render the same Markdown 404 body
          content:
            text/markdown:
              schema: { type: string }
  /sitemap.xml:
    get:
      summary: Dynamic sitemap over published posts (public, no auth)
      tags: [posts]
      responses:
        '200':
          description: "`<urlset>` with the site root plus one `<url>` per published post"
          content:
            application/xml:
              schema: { type: string }
  /uploads/{key}:
    get:
      summary: Serve a stored upload (public, no auth, local storage backend only)
      description: >
        Same-origin read path for the objects written by POST /api/v1/admin/uploads.
        With no CDN origin configured Storage::url() returns /uploads/<key>, which is
        what the editor embeds in post bodies, and it must be same-origin because the
        public-site CSP is "img-src 'self' data:". The key spans path segments
        (posts/<hex>.<ext>), so the route is registered by regex. Content type comes
        from the extension allowlist, never from the request. When
        storage.public_base_url IS set the URLs are absolute and this route answers 404.
      tags: [uploads]
      parameters:
        - { name: key, in: path, required: true, schema: { type: string }, description: "Full storage key, e.g. posts/9f2c0a....png" }
      responses:
        '200': { description: "The stored object, with Cache-Control: public, max-age=31536000, immutable" }
        '404': { description: "Content module disabled, unsafe key, extension outside the raster allowlist, no such object, or a CDN origin is configured" }
        '503': { description: Storage read failed }
  /api/v1/admin/uploads:
    post:
      summary: Upload an image (admin) → { key, url }
      tags: [uploads]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file: { type: string, format: binary }
      responses:
        '201': { description: "Stored — { data: { key, url } }" }
        '400': { description: "no_file | unsupported_type (raster only — SVG is rejected) | bad_size (1 byte – 5 MB) | bad_content (magic bytes do not match the extension)" }
        '401':
          description: Not authenticated (auth middleware — multipart passes the content-type gate but still needs a session)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403': { description: Not an admin }
        '404': { description: Content module disabled }
        '503': { description: Storage backend not configured }
    get:
      summary: "Admin: list uploaded images (media library)"
      tags: [uploads]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200': { description: "{ data: [ { key, name, url, size_bytes, content_type, created_at } ], total, limit, offset } — newest first" }
        '403': { description: Not an admin }
        '404': { description: Content module disabled }
        '503': { description: Storage backend not configured }
  /api/v1/admin/uploads/{name}:
    parameters:
      - { name: name, in: path, required: true, schema: { type: string }, description: Single-segment basename of an upload key (posts/<name>) }
    delete:
      summary: "Admin: delete an uploaded image"
      tags: [uploads]
      security: [{ BearerAuth: [] }]
      responses:
        '200': { description: Deleted }
        '400': { description: Name is not a single URL-safe segment }
        '403': { description: Not an admin }
        '404': { description: "Content module disabled, or no such upload" }
        '503': { description: Storage backend not configured }

  # ── Billing (user-facing wallet/PayPal top-up; require billing.enabled) ────
  /api/v1/billing/packages:
    get:
      summary: List active top-up packages
      description: >
        Also returns the current per-unit rate (credits_per_unit) and the
        custom-amount bounds (min_amount_cents/max_amount_cents) alongside
        the package list — see BillingPackageListResponse.
      tags: [billing]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Active packages (catalogue order) + the current rate/bounds
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BillingPackageListResponse' }
        '401': { description: Not authenticated }
        '404': { description: Billing module disabled }
  /api/v1/billing/wallet:
    get:
      summary: Get your own wallet balance + ledger history
      description: >
        Always the authenticated caller's own wallet — no user-id parameter
        of any kind is accepted, by design (see BillingController::getWallet).
      tags: [billing]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: Balance + ledger page, newest first
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WalletResponse' }
        '401': { description: Not authenticated }
        '404': { description: Billing module disabled }
  /api/v1/billing/topup:
    post:
      summary: Start a PayPal top-up (package or custom amount)
      description: >
        Provide exactly one of package_id or amount_cents. Credits are always
        computed server-side (package.credits, or amount_cents *
        billing.credits_per_unit / 100) — any "credits" field in the body is
        ignored entirely. The resulting amount_cents (a custom amount, OR a
        package's own price) is bounded by billing.min_amount_cents /
        billing.max_amount_cents in both cases.
      tags: [billing]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                package_id:   { type: string, format: uuid, description: "Mutually exclusive with amount_cents" }
                amount_cents: { type: integer, format: int64, minimum: 1, description: "Mutually exclusive with package_id" }
      responses:
        '201':
          description: PayPal order created — redirect the buyer to data.approve_url
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TopupResponse' }
        '400': { description: "Neither/both of package_id+amount_cents given, the resulting amount out of [min,max] (amount_out_of_range or package_price_out_of_range), or malformed input" }
        '401': { description: Not authenticated }
        '404': { description: "Billing module disabled, or package_id does not name an active package" }
        '409': { description: provider_order_id already recorded (PayPal order id collision) }
  /api/v1/billing/capture:
    post:
      summary: Capture an approved PayPal order and credit your wallet
      description: >
        order_id must belong to the authenticated caller — verified via
        PaymentRepository::find_owned before any capture is attempted, so one
        user can never capture (and collect credits for) another user's
        order. Idempotent: capturing an already-captured order returns
        credited=false with the unchanged balance instead of calling PayPal
        again. PayPal answers 2xx even for a PENDING or DECLINED capture —
        the wallet is only ever credited when PayPal's own capture status is
        COMPLETED; otherwise the payment is left uncaptured (for the webhook
        to resolve later) and the response reports credited=false with the
        real status.
      tags: [billing]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [order_id]
              properties:
                order_id: { type: string, description: PayPal order id, as returned by POST .../topup }
      responses:
        '200':
          description: >
            Captured, replayed idempotently, or still pending/declined on
            PayPal's side — see CaptureResponse.status/pending to tell them apart.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CaptureResponse' }
        '400': { description: order_id missing or not a string }
        '401': { description: Not authenticated }
        '404': { description: "Billing module disabled, or no such order for this caller" }
        '409': { description: "This payment is failed/refunded and cannot be captured (payment_not_capturable), or PayPal reports the order hasn't been approved yet (order_not_approved)" }
  /api/v1/billing/paypal/webhook:
    post:
      summary: PayPal webhook — capture/refund notifications
      description: >
        PayPal-to-server only, not a browser request: public (no session) and
        CSRF-exempt (PayPal never presents the session cookie the CSRF check
        keys off), but every request is verified against PayPal's own
        verify-webhook-signature API BEFORE the body is trusted, using the
        paypal-auth-algo / paypal-cert-url / paypal-transmission-id /
        paypal-transmission-sig / paypal-transmission-time headers PayPal
        sends. Response codes intentionally do NOT follow the usual REST
        mapping — PayPal retries any non-2xx delivery for days:
          * PAYMENT.CAPTURE.COMPLETED credits the wallet (idempotent — a
            capture already credited via POST .../capture, including one
            that resolves a PENDING return-flow capture, is a 200 no-op).
          * PAYMENT.CAPTURE.REFUNDED (merchant refund) and
            PAYMENT.CAPTURE.REVERSED (PayPal claws back a capture —
            chargeback/dispute/risk) both DEBIT the wallet via the same
            Billing::refund_capture logic, keyed on the event's own id as
            the idempotency marker — see BillingController::
            handleCaptureRefunded's doc comment for why both event types
            share one handler.
          * Any other event type is acknowledged with 200 and NOT acted on.
        200 is returned for every signature-valid event that was either
        applied or safely no-op'd; a signature-valid event this handler
        FAILED to process (a malformed body, or a refund/reversal it
        couldn't resolve/apply) answers 5xx so PayPal retries instead of the
        event being silently dropped.
      tags: [billing]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: PayPal webhook event envelope (id, event_type, resource, ...) — verbatim as PayPal sends it.
      responses:
        '200':
          description: Signature verified — event handled or deliberately acknowledged-not-acted-on (see WebhookAckResponse.data.handled)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookAckResponse' }
        '401': { description: "Signature verification failed (malformed body, missing paypal-* headers, or PayPal reported the signature invalid) — nothing credited/refunded" }
        '404': { description: Billing module disabled }
        '500': { description: "PayPal's own verify-webhook-signature API was unreachable/non-2xx, OR a signature-valid event could not be processed (malformed shape, or a refund/reversal that couldn't be resolved/applied) — retry later; nothing was silently dropped" }

  # ── Billing admin API (require billing.enabled + full admin) ──────────────
  /api/v1/admin/billing/payments:
    get:
      summary: List payments (admin)
      description: Paged, newest first. Optional ?status= and ?user_id= filters (AND'd together when both are given).
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: status,  in: query, schema: { type: string, enum: [created, approved, captured, failed, refunded] } }
        - { name: user_id, in: query, schema: { type: string, format: uuid } }
        - { name: limit,   in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: offset,  in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: Payment page
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminPaymentListResponse' }
        '400': { description: user_id filter is not a valid UUID }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }
  /api/v1/admin/billing/packages:
    get:
      summary: List every top-up package, active and inactive (admin)
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Full package catalogue
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminPackageListResponse' }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }
    post:
      summary: Create a top-up package (admin)
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, amount_cents, credits]
              properties:
                title:        { type: string, minLength: 1, maxLength: 200 }
                amount_cents: { type: integer, format: int64, minimum: 1 }
                credits:      { type: integer, format: int64, minimum: 1 }
                active:       { type: boolean, default: true }
                sort:         { type: integer, default: 0 }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminPackageResponse' }
        '400': { description: Validation failed }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }
  /api/v1/admin/billing/packages/{id}:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    patch:
      summary: Update a top-up package — partial; any of title/amount_cents/credits/active/sort (admin)
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:        { type: string, minLength: 1, maxLength: 200 }
                amount_cents: { type: integer, format: int64, minimum: 1 }
                credits:      { type: integer, format: int64, minimum: 1 }
                active:       { type: boolean }
                sort:         { type: integer }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminPackageResponse' }
        '400': { description: "Empty patch, invalid id, or validation failed" }
        '403': { description: Not an admin }
        '404': { description: "Billing module disabled, or no such package" }
    delete:
      summary: Delete a top-up package (admin)
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageResponse' }
        '400': { description: Invalid id }
        '403': { description: Not an admin }
        '404': { description: "Billing module disabled, or no such package" }
  /api/v1/admin/billing/settings:
    get:
      summary: Read the billing rate/bounds settings (admin)
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Current settings
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BillingSettingsResponse' }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }
    put:
      summary: Replace the billing rate/bounds settings (admin)
      description: >
        A full replace — all three fields are required. Takes effect for the
        NEXT top-up computed after this call; an in-flight or already-created
        payment keeps the rate_snapshot/credits_expected it was created with
        (see Billing::credit_capture — unaffected by this endpoint).
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [credits_per_unit, min_amount_cents, max_amount_cents]
              properties:
                credits_per_unit: { type: integer, format: int64, minimum: 1 }
                min_amount_cents: { type: integer, format: int64, minimum: 1 }
                max_amount_cents: { type: integer, format: int64, minimum: 1 }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BillingSettingsResponse' }
        '400': { description: "Missing/invalid field, or max_amount_cents < min_amount_cents" }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }
  /api/v1/admin/billing/users/{id}/adjust:
    post:
      summary: Manually adjust a user's wallet balance (admin)
      description: >
        Routes through Billing::adjust — the only code allowed to write
        wallet_entries/wallet_balances. note is mandatory (non-empty);
        created_by on the resulting ledger row is always the authenticated
        admin's own id, never a client-supplied value. Writes an audit_log row.
        With notify=true, the target user receives a best-effort
        wallet-adjustment email (note is reused verbatim as the reason) after
        the adjustment and its audit row have both committed — email delivery
        never affects the money path or the response.
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid }, description: Target user id }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [delta_credits, note]
              properties:
                delta_credits: { type: integer, format: int64, description: "Signed; positive credits, negative debits. Zero is refused (400)." }
                note:          { type: string, minLength: 1, maxLength: 2000 }
                notify:        { type: boolean, default: false, description: "When true, sends the target user a best-effort wallet-adjustment email after the adjustment succeeds. Non-boolean values are silently ignored." }
      responses:
        '200':
          description: Adjusted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdjustResponse' }
        '400': { description: "Empty/missing note, zero delta_credits, malformed user/admin id, or invalid id path param" }
        '403': { description: Not an admin }
        '404': { description: "Billing module disabled, or no such user" }
        '409': { description: A negative delta_credits would drive the balance below zero }
  /api/v1/admin/billing/metrics:
    get:
      summary: Business metrics — revenue, conversion, refunds, outstanding liability, top lists (admin)
      description: >
        revenue/count/avg and conversion are computed over a rolling window
        (now() - interval); refunds counts only billing_refunds rows with
        outcome='applied'; outstanding_credits/outstanding_value_cents are an
        all-time snapshot of wallet_balances, NOT windowed; series is
        calendar-bucketed (hourly for period=day, daily for week/month) with
        every bucket present (zero-filled, no gaps).
      tags: [admin, billing]
      security: [{ BearerAuth: [] }]
      parameters:
        - { name: period, in: query, schema: { type: string, enum: [day, week, month], default: week }, description: "day = last 24h (hourly buckets), week = last 7d (daily buckets), month = last 30d (daily buckets)" }
      responses:
        '200':
          description: Metrics snapshot
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BillingMetricsResponse' }
        '400': { description: "period is not one of day, week, month" }
        '403': { description: Not an admin }
        '404': { description: Billing module disabled }