openapi.yaml

openapi: 3.1.0
info:
  title: Fluxora HTTP API
  version: 0.1.0
  description: |
    Fluxora Backend: Off-chain companion to the streaming contract.

    Presents operator-grade reliability with predictable HTTP semantics, durable views of chain-derived data,
    and explicit failure behavior when dependencies are unhealthy.

    ## Security Header Baseline
    Fluxora applies Helmet at the Express boundary so every HTTP response carries a consistent
    browser-facing security-header baseline, including `Content-Security-Policy`,
    `Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options`, and
    `Referrer-Policy`. The service also suppresses the `X-Powered-By` header.

    These headers are transport invariants for public clients, authenticated partners,
    administrators, and internal workers that traverse the HTTP surface. They do not replace
    authentication, authorization, TLS termination, or proxy hardening.

    ## Trust Boundaries
    - **Public Internet Clients**: Read-only access to stream listings and health checks
    - **Authenticated Partners**: Create and manage streams with idempotency guarantees
    - **Administrators**: Full access including internal indexer endpoints
    - **Internal Workers**: Indexer endpoints for chain state synchronization

    ## Failure Modes & Client-Visible Behavior
    - **Invalid Input (400)**: Malformed addresses, negative amounts, oversized payloads
    - **Unauthorized (401)**: Missing or invalid authentication token
    - **Forbidden (403)**: Insufficient permissions for the requested operation
    - **Conflict (409)**: Duplicate submission detected (idempotency key collision)
    - **Payload Too Large (413)**: Request exceeds 256 KiB limit
    - **Service Unavailable (503)**: Dependency outage (database, Stellar RPC, workers)
    - **Internal Server Error (500)**: Unexpected error; check logs with requestId

  contact:
    name: Fluxora Team
  license:
    name: MIT

servers:
  - url: http://localhost:3000
    description: Local development
  - url: https://api.fluxora.example.com
    description: Production

paths:
  /:
    get:
      summary: API root information
      operationId: getRoot
      tags:
        - System
      responses:
        '200':
          description: API metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootResponse'

  /health:
    get:
      summary: Health check endpoint
      operationId: getHealth
      tags:
        - System
      description: |
        Returns the health status of the service and its dependencies.
        Used by load balancers and monitoring systems.
        Returns 503 during graceful shutdown.
      responses:
        '200':
          description: Service is healthy or degraded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service is shutting down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /health/ready:
    get:
      summary: Readiness probe
      operationId: getHealthReady
      tags:
        - System
      description: |
        Returns 200 if all dependencies are healthy and service is ready to accept traffic.
        Returns 503 if any dependency is unhealthy or service is shutting down.
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
        '503':
          description: Service is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /health/live:
    get:
      summary: Liveness probe
      operationId: getHealthLive
      tags:
        - System
      description: |
        Returns detailed health report for all dependencies.
      responses:
        '200':
          description: Detailed health report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LivenessResponse'
        '500':
          description: Failed to get health report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/admin/status/read-only:
    get:
      summary: Read-only admin feature-flag status
      operationId: getAdminStatusReadOnly
      tags:
        - Admin
      description: |
        Returns non-sensitive operational pause flags without requiring
        admin credentials. This endpoint is read-only and does not expose
        reindex internals or mutation capabilities.
      responses:
        '200':
          description: Current pause-flag state
          content:
            application/json:
              schema:
                type: object
                required:
                  - pauseFlags
                properties:
                  pauseFlags:
                    type: object
                    required:
                      - streamCreation
                      - ingestion
                    properties:
                      streamCreation:
                        type: boolean
                        description: Whether creation of new streams is paused.
                      ingestion:
                        type: boolean
                        description: Whether chain ingestion/indexing is paused.

  /api/auth/session:
    post:
      summary: Create authentication session
      operationId: createSession
      tags:
        - Auth
      description: |
        Issues a JWT token for authenticated access to privileged endpoints.
        In this iteration, any valid Stellar address can obtain a session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
              properties:
                address:
                  type: string
                  description: Stellar public key
                  pattern: '^G[A-Z2-7]{55}$'
                  example: GBBD47UZQ5CYVVEUVRYNQZX3G5KRZTAYF5XSVS2UKMCCWW5LJJLXNVQX
                role:
                  type: string
                  enum: [operator, viewer]
                  default: viewer
                  description: User role for authorization
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/streams:
    post:
      summary: Create a new stream
      operationId: createStream
      tags:
        - Streams
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: |
            Unique key that makes this request idempotent. Clients MUST supply a
            fresh value per logical operation and MUST reuse the same value when
            retrying after a network failure.

            **Format**: 1–128 characters; allowed charset: `[A-Za-z0-9:_-]`.
            UUID v4 is recommended but any value matching the charset is accepted.

            **Behaviour**:
            - Same key + same body → 201 (cached response, `Idempotency-Replayed: true`)
            - Same key + different body → 409 CONFLICT
            - Missing or malformed key → 400 VALIDATION_ERROR

            **Security**: The key value is never echoed in error response bodies
            or server logs to prevent accidental secret leakage.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStreamRequest'
      responses:
        '201':
          description: |
            Stream created (or replayed from cache).
            Check `Idempotency-Replayed` response header and `meta.idempotencyReplayed`
            to distinguish a fresh creation from a cached replay.
          headers:
            Idempotency-Key:
              description: Echoes the key supplied by the client.
              schema:
                type: string
            Idempotency-Replayed:
              description: |
                `true` when the response was served from the idempotency cache;
                `false` on first creation.
              schema:
                type: string
                enum: ['true', 'false']
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamResponse'
        '400':
          description: |
            Invalid request. Common causes:
            - Missing or malformed `Idempotency-Key` header
            - Invalid JSON body
            - Invalid Stellar address format
            - Non-string amount field (must be decimal string)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Idempotency-Key collision — the same key was previously used with a
            different request body. Use a new Idempotency-Key or retry with the
            original body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body exceeds 256 KiB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            Unprocessable entity — one or more Stellar addresses in the request
            body do not exist on-chain. The stream cannot be created because it
            would never match an on-chain event.

            The `details.missingAddresses` array lists every address that was
            not found. Addresses that could not be verified due to an RPC outage
            are omitted (the request is allowed through in that case).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          details:
                            type: object
                            properties:
                              missingAddresses:
                                type: array
                                items:
                                  type: string
                                  pattern: '^G[A-Z2-7]{55}$'
                                example:
                                  - 'GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN'
        '503':
          description: Service unavailable (database, Stellar RPC, or idempotency store down)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      summary: List streams with cursor pagination and indexed filters
      operationId: listStreams
      tags:
        - Streams
      parameters:
        - name: limit
          in: query
          required: false
          description: Number of streams to return (1-100, default 20)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          required: false
          description: |
            Opaque pagination cursor returned in `next_cursor` from a previous
            response. Encodes the last seen stream id (base64url). Omit for
            the first page.
          schema:
            type: string
        - name: include_total
          in: query
          required: false
          description: |
            When true, include a `total` field in the response reflecting the
            current count of matching streams. This is a point-in-time snapshot
            and is not guaranteed to be consistent with the cursor position.
          schema:
            type: boolean
            default: false
        - name: status
          in: query
          required: false
          description: Filter by stream status (uses the status index).
          schema:
            type: string
            enum: [scheduled, active, paused, completed, cancelled]
        - name: sender
          in: query
          required: false
          description: Filter by sender Stellar address (uses the sender_address index).
          schema:
            type: string
        - name: recipient
          in: query
          required: false
          description: Filter by recipient Stellar address (uses the recipient_address index).
          schema:
            type: string
      responses:
        '200':
          description: Cursor-paginated list of streams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamListResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/streams/{streamId}:
    get:
      summary: Get stream details
      operationId: getStream
      tags:
        - Streams
      parameters:
        - name: streamId
          in: path
          required: true
          description: Stream identifier (format: stream-{timestamp}-{random})
          schema:
            type: string
      responses:
        '200':
          description: Stream details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamResponse'
        '404':
          description: Stream not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Cancel a stream
      operationId: cancelStream
      tags:
        - Streams
      security:
        - BearerAuth: []
      parameters:
        - name: streamId
          in: path
          required: true
          description: Stream identifier
          schema:
            type: string
      responses:
        '200':
          description: Stream cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelStreamResponse'
        '401':
          description: Missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Stream not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Stream already cancelled or completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/indexer/sync:
    post:
      summary: Trigger indexer synchronization
      operationId: triggerIndexerSync
      tags:
        - Internal
      security:
        - BearerAuth: []
      description: |
        Internal endpoint for workers to synchronize chain state.
        Requires admin authentication.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ledgerSequence:
                  type: integer
                  description: Stellar ledger sequence number
              required:
                - ledgerSequence
      responses:
        '202':
          description: Sync accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body exceeds 256 KiB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/indexer/events/replay:
    get:
      summary: Cursor-based event replay from the event store
      operationId: replayIndexerEvents
      tags:
        - Internal
      description: |
        Returns a page of stored contract events starting strictly after the
        supplied `afterEventId` cursor, ordered by `(ledger ASC, eventId ASC)`.

        Consumers advance the replay window by passing the returned `nextCursor`
        value as `afterEventId` on the next request. Omit `afterEventId` to
        start from the beginning of the store.

        Amount fields in event payloads follow the decimal-string serialization
        policy — they are never coerced to numbers.

        ## Trust Boundaries
        - Public internet clients may not call this route.
        - Authenticated internal workers may replay events for audit and
          catch-up purposes only.

        ## Failure Modes
        - An unknown `afterEventId` is treated as "cursor past end of store"
          and returns an empty event list (not a 404).
        - `limit` is silently capped at 1000.
      parameters:
        - name: x-indexer-worker-token
          in: header
          required: true
          description: Internal worker authentication token
          schema:
            type: string
        - name: afterEventId
          in: query
          required: false
          description: |
            Exclusive cursor. Only events that come strictly after this
            eventId (in ledger-ascending order) are returned.
            Omit to start from the beginning of the store.
          schema:
            type: string
        - name: fromLedger
          in: query
          required: false
          description: Only return events at or after this ledger (inclusive).
          schema:
            type: integer
            minimum: 0
        - name: toledger
          in: query
          required: false
          description: Only return events at or before this ledger (inclusive).
          schema:
            type: integer
            minimum: 0
        - name: contractId
          in: query
          required: false
          description: Filter by Soroban contract ID.
          schema:
            type: string
        - name: topic
          in: query
          required: false
          description: Filter by event topic (e.g. `stream.created`).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum events per page (default 100, max 1000).
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
      responses:
        '200':
          description: Cursor-paginated event page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventReplayResponse'
        '401':
          description: Missing or invalid internal worker credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ResponseMeta:
      type: object
      required:
        - timestamp
      properties:
        timestamp:
          type: string
          format: date-time
          description: ISO-8601 timestamp of the response
          example: '2024-01-01T12:00:00.000Z'
        requestId:
          type: string
          description: Opaque request identifier for log correlation
          example: 550e8400-e29b-41d4-a716-446655440000

    RootResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            name:
              type: string
              example: Fluxora API
            version:
              type: string
              example: 0.1.0
            docs:
              type: string
              example: Programmable treasury streaming on Stellar.
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    HealthResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            status:
              type: string
              enum: [ok, degraded, shutting_down]
              description: Overall service health
              example: ok
            service:
              type: string
              example: fluxora-backend
            network:
              type: string
              description: Stellar network (testnet, public, etc.)
              example: testnet
            contractAddresses:
              type: object
              description: Deployed contract addresses
              example: {}
            timestamp:
              type: string
              format: date-time
              example: '2024-01-01T12:00:00.000Z'
            indexer:
              type: object
              properties:
                status:
                  type: string
                  enum: [ok, stalled, starting, unknown]
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    ReadinessResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            report:
              type: object
              description: Detailed readiness report
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    LivenessResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            report:
              type: object
              description: Detailed liveness report
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    SessionResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            token:
              type: string
              description: JWT token for authentication
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
            user:
              type: object
              properties:
                address:
                  type: string
                  example: GBBD47UZQ5CYVVEUVRYNQZX3G5KRZTAYF5XSVS2UKMCCWW5LJJLXNVQX
                role:
                  type: string
                  example: operator
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    CreateStreamRequest:
      type: object
      required:
        - sender
        - recipient
        - depositAmount
        - ratePerSecond
        - startTime
      properties:
        sender:
          type: string
          description: |
            Stellar public key of the sender.
            Must start with 'G' followed by exactly 55 base32 characters [A-Z2-7].
            Total length: 56 characters.
          pattern: '^G[A-Z2-7]{55}$'
          example: GBBD47UZQ5CYVVEUVRYNQZX3G5KRZTAYF5XSVS2UKMCCWW5LJJLXNVQX
        recipient:
          type: string
          description: |
            Stellar public key of the recipient.
            Must start with 'G' followed by exactly 55 base32 characters [A-Z2-7].
            Total length: 56 characters.
          pattern: '^G[A-Z2-7]{55}$'
          example: GBRPYHIL2CI3WHZDTOOQFC6EB4KJJGUJJBBX7XNLG5DBNVQWDADUZSQX
        depositAmount:
          type: string
          description: |
            Total amount to deposit in stroops (1 XLM = 10,000,000 stroops).
            Must be a non-negative decimal string.
            Must be >= ratePerSecond (minimum 1 second of streaming).
            Max: 9223372036854775807 stroops (~922 million XLM).
          pattern: '^\d+(\.\d+)?$'
          example: '1000000000'
        ratePerSecond:
          type: string
          description: |
            Streaming rate in stroops per second.
            Must be a positive decimal string.
          pattern: '^\d+(\.\d+)?$'
          example: '100000'
        startTime:
          type: integer
          description: |
            Unix timestamp (seconds) when streaming begins.
            Must be in the future or within the last hour.
          example: 1704067200

    Stream:
      type: object
      description: |
        A durable, PostgreSQL-backed stream record.
        All monetary amounts are decimal strings - never numbers.
      required:
        - id
        - sender
        - recipient
        - depositAmount
        - ratePerSecond
        - startTime
        - endTime
        - status
      properties:
        id:
          type: string
          description: |
            Unique stream identifier derived from SHA-256 of request content.
            Format: stream-{64-char-hex}-{eventIndex}
          example: stream-a3f1c2d...0c-0
        sender:
          type: string
          description: |
            Sender Stellar public key (G + 55 base32 chars).
          pattern: '^G[A-Z2-7]{55}$'
          example: GBBD47UZQ5CYVVEUVRYNQZX3G5KRZTAYF5XSVS2UKMCCWW5LJJLXNVQX
        recipient:
          type: string
          description: |
            Recipient Stellar public key (G + 55 base32 chars).
          pattern: '^G[A-Z2-7]{55}$'
          example: GBRPYHIL2CI3WHZDTOOQFC6EB4KJJGUJJBBX7XNLG5DBNVQWDADUZSQX
        depositAmount:
          type: string
          description: Total deposit as a decimal string (never a number).
          pattern: '^[+-]?[0-9]+(\.[0-9]+)?$'
          example: '1000'
        ratePerSecond:
          type: string
          description: Streaming rate per second as a decimal string.
          pattern: '^[+-]?[0-9]+(\.[0-9]+)?$'
          example: '10'
        startTime:
          type: integer
          description: Stream start time (Unix epoch seconds).
          example: 1700000000
        endTime:
          type: integer
          description: Stream end time (Unix epoch seconds). 0 = indefinite.
          example: 0
        status:
          type: string
          enum:
            - active
            - paused
            - completed
            - cancelled
          description: Current stream status.
          example: active

    StreamResponse:
      type: object
      required:
        - streams
        - has_more
        - next_cursor
      properties:
        streams:
          type: array
          items:
            $ref: '#/components/schemas/Stream'
        has_more:
          type: boolean
          description: Whether more pages are available.
          example: true
        next_cursor:
          type: string
          nullable: true
          description: |
            Opaque cursor for the next page. Always present in the response.
            `null` when `has_more` is false (no further pages).
            Pass as the `cursor` query parameter on the next request.
          example: eyJ2IjoxLCJsYXN0SWQiOiJzdHJlYW0tYWJjLTAifQ
        total:
          type: integer
          nullable: true
          description: Total count (only present when include_total=true).
          example: 42

    StreamListResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          required:
            - streams
            - has_more
            - next_cursor
          properties:
            streams:
              type: array
              items:
                $ref: '#/components/schemas/Stream'
            has_more:
              type: boolean
              description: Whether more streams are available.
              example: false
            next_cursor:
              type: string
              nullable: true
              description: |
                Opaque cursor for the next page. Always present.
                `null` when there are no further pages.
                Encodes the `id` of the last stream on the current page
                using keyset (`WHERE id > $cursor ORDER BY id ASC`) semantics.
              example: null
            total:
              type: integer
              nullable: true
              description: Total number of streams (only if include_total=true).
              example: null
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    CancelStreamResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            message:
              type: string
              example: Stream cancelled
            id:
              type: string
              example: stream-1704067200-abc12
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    AcceptedResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          properties:
            status:
              type: string
              example: queued
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    EventReplayResponse:
      type: object
      required:
        - success
        - data
        - meta
      description: |
        Response envelope for the cursor-based event replay endpoint.
        Amount fields inside `events[].payload` are always decimal strings.
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          required:
            - events
            - total
            - limit
            - offset
          properties:
            events:
              type: array
              description: Ordered list of contract events for this page.
              items:
                $ref: '#/components/schemas/StreamEventRecord'
            total:
              type: integer
              description: Total events matching the filter after the cursor position.
              example: 42
            limit:
              type: integer
              description: Effective page size (capped at 1000).
              example: 100
            offset:
              type: integer
              description: Always 0 when cursor-based pagination is used.
              example: 0
            nextCursor:
              type: string
              nullable: true
              description: |
                Pass as `afterEventId` on the next request to advance the
                replay window. Absent when there are no more events.
              example: evt-abc123
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    StreamEventRecord:
      type: object
      description: |
        An append-only record of a contract event as ingested from the chain.
        Amount fields in `payload` follow the decimal-string serialization policy.
      required:
        - eventId
        - ledger
        - ledgerHash
        - contractId
        - topic
        - txHash
        - txIndex
        - operationIndex
        - eventIndex
        - payload
        - happenedAt
        - ingestedAt
      properties:
        eventId:
          type: string
          description: Stable unique identifier for this event (chain-derived).
          example: evt-abc123
        ledger:
          type: integer
          description: Ledger sequence number.
          example: 512345
        ledgerHash:
          type: string
          description: Ledger hash for reorg detection.
          example: abc123def456
        contractId:
          type: string
          description: Soroban contract ID.
          example: CCONTRACT123
        topic:
          type: string
          description: Event topic.
          example: stream.created
        txHash:
          type: string
          description: Transaction hash.
          example: tx-abc123
        txIndex:
          type: integer
          example: 0
        operationIndex:
          type: integer
          example: 0
        eventIndex:
          type: integer
          example: 0
        payload:
          type: object
          description: |
            Arbitrary event payload. Amount fields (depositAmount, ratePerSecond,
            etc.) are always decimal strings — never numbers.
          additionalProperties: true
          example:
            streamId: stream-abc123
            depositAmount: "100.0000000"
            ratePerSecond: "0.0000001"
        happenedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp when the event occurred on-chain.
          example: '2026-03-26T12:00:00.000Z'
        ingestedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp when the event was ingested into the store.
          example: '2026-03-26T12:00:01.000Z'

    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum: [false]
          description: Always false for error responses
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              enum:
                - VALIDATION_ERROR
                - NOT_FOUND
                - CONFLICT
                - UNAUTHORIZED
                - FORBIDDEN
                - PAYLOAD_TOO_LARGE
                - TOO_MANY_REQUESTS
                - REQUEST_TIMEOUT
                - SERVICE_UNAVAILABLE
                - INTERNAL_ERROR
                - DECIMAL_ERROR
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human-readable error message
              example: Validation failed
            requestId:
              type: string
              description: Correlation ID for log triage
              example: 550e8400-e29b-41d4-a716-446655440000
            details:
              description: Additional error context (field-level validation errors, etc.)
              nullable: true

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token for authentication. Include in Authorization header:
        Authorization: Bearer <token>
    AdminAuth:
      type: http
      scheme: bearer
      description: |
        Admin API key for privileged operations. Include in Authorization header:
        Authorization: Bearer <ADMIN_API_KEY>
        Set via ADMIN_API_KEY environment variable.

tags:
  - name: System
    description: System health and metadata endpoints
  - name: Auth
    description: Authentication and session management
  - name: Streams
    description: Stream creation, retrieval, and listing
  - name: Internal
    description: Internal endpoints for workers and administrators