openapi.yaml

openapi: "3.1.0"

info:
  title: Stellarlend API
  version: "1.0.0"
  description: |
    Server-side API routes for the Stellarlend DeFi lending platform.
    All routes live under `/api/` and are implemented as Next.js App Router
    route handlers (`app/api/*/route.ts`).

    **Authentication**
    Protected routes require a valid session cookie (`session`).
    A session is obtained via `POST /api/auth/session` and is stored as an
    HttpOnly, SameSite=strict cookie.

    **Caching**
    Public read routes use an in-memory SWR cache (lib/cache).
    Responses include an `X-Cache: HIT | MISS | STALE | BYPASS` header.
    Cache is bypassed whenever an `Authorization` header, `session` / `token`
    cookie, or `x-user-id` header is present.

    **Request correlation**
    API clients may send `x-request-id` as a ULID to correlate logs across
    Stellarlend and upstream services. If it is omitted or malformed, the
    middleware generates a fresh ULID, returns it in the `x-request-id`
    response header, and forwards it on outbound service calls.

servers:
  - url: http://localhost:3000
    description: Local development

tags:
  - name: health
    description: Platform health check
  - name: auth
    description: Session management
  - name: account
    description: Account management including deletion
  - name: prices
    description: Real-time asset prices
  - name: markets
    description: Per-asset supply/borrow APR and utilization
  - name: positions
    description: User lending and borrowing positions
  - name: transactions
    description: Transaction history and creation
  - name: quote
    description: Lending / borrowing quote calculations
  - name: notifications
    description: In-app notifications for the authenticated user
  - name: liquidation
    description: Liquidation risk assessment for user positions
  - name: admin
    description: Internal admin-only routes for deployment and maintenance

paths:

  # ---------------------------------------------------------------------------
  # Health
  # ---------------------------------------------------------------------------
  /api/health:
    get:
      operationId: getHealth
      tags: [health]
      summary: Platform health check
      description: |
        Checks internal service status and Stellar Horizon reachability.
        Returns 200 when healthy, 503 when degraded or unhealthy.
      parameters:
        - $ref: "#/components/parameters/XRequestId"
      responses:
        "200":
          description: Platform is healthy
          headers:
            x-request-id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: Platform is degraded or unhealthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  # ---------------------------------------------------------------------------
  # Auth
  # ---------------------------------------------------------------------------
  /api/auth/session:
    post:
      operationId: createSession
      tags: [auth]
      summary: Create a session
      description: Authenticates the user and sets an HttpOnly session cookie.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "200":
          description: Session created
          headers:
            Set-Cookie:
              description: HttpOnly session cookie
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"

    get:
      operationId: getSession
      tags: [auth]
      summary: Check session status
      responses:
        "200":
          description: Session is active
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"

    delete:
      operationId: deleteSession
      tags: [auth]
      summary: Destroy session (logout)
      responses:
        "200":
          description: Session cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /api/auth/logout:
    post:
      operationId: logout
      tags: [auth]
      summary: Logout and revoke session
      description: |
        Revokes the current session server-side and clears the session cookie.
        This endpoint ensures that:
        - The session token is invalidated immediately
        - The cookie is removed from the browser
        - Other devices using the same session cannot replay the token
        - An audit log entry is recorded for security compliance

        Requires an active session cookie. Used by the navbar disconnect action
        in wallet-authenticated flows.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Successfully logged out
          headers:
            Set-Cookie:
              description: Clears the HttpOnly session cookie
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required: [success, message]
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Logged out successfully"
                  walletAddress:
                    type: string
                    description: |
                      The wallet address that was logged out.
                      Included for navbar UI state management.
                    example: "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        "401":
          description: No active session to logout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "No active session"
        "500":
          $ref: "#/components/responses/InternalError"

    delete:
      operationId: logoutDelete
      tags: [auth]
      summary: Logout and revoke session (alternative endpoint)
      description: |
        Same as POST /api/auth/logout.
        Provided for REST semantics preference.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Successfully logged out
          headers:
            Set-Cookie:
              description: Clears the HttpOnly session cookie
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required: [success, message]
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Logged out successfully"
                  walletAddress:
                    type: string
                    example: "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        "401":
          description: No active session to logout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Admin
  # ---------------------------------------------------------------------------
  /api/admin/migrate-status:
    get:
      operationId: getMigrateStatus
      tags: [admin]
      summary: Check migration drift status
      description: |
        Compares applied Drizzle migrations to the repository source manifest.
        Intended for deploy verification and monitoring.
      parameters:
        - name: x-server-token
          in: header
          description: Server token used to authenticate internal admin requests
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Migration status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MigrationStatusResponse"
        "403":
          description: Unauthorized admin request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Prices
  # ---------------------------------------------------------------------------
  /api/prices:
    get:
      operationId: getPrices
      tags: [prices]
      summary: Fetch asset spot prices
      description: |
        Returns current USD prices for supported assets.
        Responses are publicly cached (TTL 5 s, SWR 10 s) unless
        authentication credentials are present.
      parameters:
        - name: assets
          in: query
          description: >
            Comma-separated list of asset symbols to filter
            (e.g. `XLM,USDC`). Omit for all assets.
          required: false
          schema:
            type: string
            example: XLM,USDC
      responses:
        "200":
          description: Asset prices
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            Cache-Control:
              $ref: "#/components/headers/CacheControl"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricesResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Markets
  # ---------------------------------------------------------------------------
  /api/markets:
    get:
      operationId: getMarkets
      tags: [markets]
      summary: Per-asset supply/borrow APR and utilization
      description: |
        Returns live market data for each supported asset sourced from the
        Stellarlend Soroban lending pool contract.
        Responses are publicly cached (TTL 30 s, SWR 60 s) unless
        authentication credentials are present.

        The lending page (`app/lending/page.tsx`) uses this endpoint to
        populate default interest rates instead of hardcoded literals.
      parameters:
        - name: asset
          in: query
          description: >
            Comma-separated list of AssetSymbol values to filter
            (e.g. `?asset=XLM,USDC`). Omit for all assets.
          required: false
          schema:
            type: string
            example: XLM,USDC
      responses:
        "200":
          description: Market data for the requested assets
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            Cache-Control:
              $ref: "#/components/headers/CacheControl"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketsResponse"
        "400":
          description: Unknown asset symbol(s) in the `asset` query param
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Unknown asset(s): FAKE. Supported: XLM, USDC, BTC, ETH"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/internal/cache/invalidate:
    post:
      operationId: invalidateCache
      tags: [auth]
      summary: Invalidate cache namespaces (internal only)
      description: |
        Internal-only endpoint used by deployment tooling to invalidate
        specific cache namespaces (e.g. `prices`, `markets`, `idempotency`).
        This route is protected by an internal server token and should only
        be invoked from trusted CI/CD workflows.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [namespaces]
              properties:
                namespaces:
                  type: array
                  items:
                    type: string
                  example: ["prices", "markets"]
      responses:
        "200":
          description: Number of cache keys deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedCount:
                    type: integer
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Positions
  # ---------------------------------------------------------------------------
  /api/positions:
    get:
      operationId: getPositions
      tags: [positions]
      summary: Fetch user positions
      description: |
        Returns lending/borrowing position data.
        When called without authentication, returns public aggregate data.
        When called with `x-user-id` header or session cookie, returns
        user-specific positions and bypasses the public cache.
      parameters:
        - name: userId
          in: query
          required: false
          schema:
            type: string
        - name: x-user-id
          in: header
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Position data
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PositionsResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/positions/history:
    get:
      operationId: getPositionsHistory
      tags: [positions]
      summary: Fetch historical position snapshots
      description: |
        Returns daily snapshots of user lending/borrowing positions over time,
        including supplied/borrowed balances and effective APY.
        
        Data is bucketed by the specified interval (1h, 1d, 7d, 30d) with the
        first snapshot of each bucket returned. Responses are cached per wallet
        with a 5-minute TTL.
        
        Requires authentication. Returns data only for the authenticated wallet.
      security:
        - session: []
      parameters:
        - name: from
          in: query
          required: false
          description: Start timestamp in milliseconds (default 90 days ago)
          schema:
            type: integer
            format: int64
            minimum: 0
            example: 1700000000000
        - name: to
          in: query
          required: false
          description: End timestamp in milliseconds (default now)
          schema:
            type: integer
            format: int64
            minimum: 0
            example: 1702592000000
        - name: interval
          in: query
          required: false
          description: Time bucketing interval
          schema:
            type: string
            enum: [1h, 1d, 7d, 30d]
            default: 1d
      responses:
        "200":
          description: Historical position snapshots
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            Cache-Control:
              description: Cache-Control header
              schema:
                type: string
                example: "max-age=300, public"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PositionHistoryResponse"
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Bad Request
                message: time range cannot exceed 365 days
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Liquidation
  # ---------------------------------------------------------------------------
  /api/liquidations:
    get:
      operationId: getLiquidations
      tags: [liquidation]
      summary: List user positions ranked by liquidation risk
      description: |
        Returns all borrowing positions for the authenticated user, ranked by
        proximity to liquidation. Each position includes the computed health
        factor, the price level at which the position becomes liquidatable, and
        a normalized risk score between 0 (safe) and 1 (liquidatable).

        Collateral factors are sourced from `lib/markets/registry.ts`.

        **Risk score formula:**
        ```
        riskScore = clamp(1 - (healthFactor - 1) / (SAFE_HF - 1), 0, 1)
        ```
        where SAFE_HF = 2.0. A health factor ≤ 1 yields riskScore = 1;
        a health factor ≥ 2 yields riskScore = 0.

        **Health factor formula:**
        ```
        healthFactor = (collateralAmount × collateralFactor) / borrowedAmount
        ```

        **Liquidation price factor formula:**
        ```
        liquidationPriceFactor = borrowedAmount / (collateralAmount × collateralFactor)
        ```
        This is the fraction of the current price at which the position becomes
        liquidatable. A value of 0.8 means a 20% price decline triggers liquidation.
      security:
        - sessionCookie: []
      parameters:
        - name: wallet
          in: query
          required: false
          description: >
            Override wallet address for admin inspection.
            Must be a valid Stellar public key (max 56 chars).
          schema:
            type: string
            maxLength: 56
            example: GA-test-address
      responses:
        "200":
          description: Liquidation risk assessment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiquidationsResponse"
        "400":
          description: Invalid wallet address parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Invalid wallet address
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Transactions
  # ---------------------------------------------------------------------------
  /api/transactions:
    get:
      operationId: listTransactions
      tags: [transactions]
      summary: List transactions with optional filters
      description: |
        Supports the existing offset pagination (`page` and `pageSize`) and optional cursor pagination (`cursor` and `limit`).

        Offset pagination is convenient for jumping to an approximate page and remains backward compatible, but large offsets can become inefficient and may miss or duplicate rows when new transactions are inserted between requests. Cursor pagination uses a stable `(date, id)` keyset ordered by `sortDir`, so forward and reverse iteration stays efficient and consistent for sequential scans. Cursor pagination is intentionally limited to `sortBy=date`; use offset pagination when sorting by amount.
      parameters:
        - name: asset
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/AssetSymbol"
        - name: type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/TransactionType"
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/TransactionStatus"
        - name: page
          in: query
          required: false
          description: 1-based offset page number used when cursor/limit is omitted.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          required: false
          description: Offset page size, capped at 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 6
        - name: cursor
          in: query
          required: false
          description: Opaque cursor returned as nextCursor or prevCursor. Supplying cursor or limit enables keyset pagination.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Cursor page size, capped at 100. Supplying limit enables keyset pagination from the beginning of the ordered result set.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 6
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [date, amount]
            default: date
        - name: sortDir
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        "200":
          description: Transaction list
          content:
            application/json:
              schema:
                type: object
                required: [transactions, total, nextCursor, prevCursor]
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: "#/components/schemas/Transaction"
                  total:
                    type: integer
                    minimum: 0
                  nextCursor:
                    type: string
                    nullable: true
                    description: Cursor for the next page when cursor pagination has another page.
                  prevCursor:
                    type: string
                    nullable: true
                    description: Cursor for the previous page when cursor pagination has an earlier page.
        "400":
          description: Invalid filter or cursor pagination value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      operationId: createTransaction
      tags: [transactions]
      summary: Create a transaction record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionInput"
      responses:
        "201":
          description: Transaction created
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    $ref: "#/components/schemas/Transaction"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/transactions/{id}:
    get:
      operationId: getTransactionDetail
      tags: [transactions]
      summary: Retrieve detailed transaction records with operations
      description: |
        Returns the normalized transaction record with embedded operation logs, fee, and explorer links.
        Accepts mock transaction IDs (TXN\d+) and 64-character hexadecimal Soroban/Stellar transaction hashes.
      parameters:
        - name: id
          in: path
          required: true
          description: The transaction identifier (either mock TXN\d+ or a 64-character hex hash)
          schema:
            type: string
            pattern: "^(TXN\\d+|[0-9a-fA-F]{64})$"
            example: TXN12345
      responses:
        "200":
          description: Detailed transaction found
          content:
            application/json:
              schema:
                type: object
                required: [transaction]
                properties:
                  transaction:
                    type: object
                    required: [id, asset, type, status, amount, date, time, fee, explorerUrl, operations]
                    properties:
                      id:
                        type: string
                        example: TXN12345
                      asset:
                        $ref: "#/components/schemas/AssetSymbol"
                      type:
                        $ref: "#/components/schemas/TransactionType"
                      status:
                        $ref: "#/components/schemas/TransactionStatus"
                      amount:
                        type: number
                        example: 2000
                      date:
                        type: string
                        format: date
                        example: "2025-04-12"
                      time:
                        type: string
                        example: "09:32AM"
                      fee:
                        type: string
                        example: "0.0001000 XLM"
                      explorerUrl:
                        type: string
                        format: uri
                        example: "https://stellar.expert/explorer/testnet/tx/TXN12345"
                      operations:
                        type: array
                        items:
                          type: object
                          required: [id, type, source, destination, amount, asset]
                          properties:
                            id:
                              type: string
                              example: "op_TXN12345_1"
                            type:
                              type: string
                              example: "payment"
                            source:
                              type: string
                              example: "GA2C5RFPE6GCKMY3AA3H6AOF5Q4G5S4GX6TQCGEAAS624JBZ2G2UQHGD"
                            destination:
                              type: string
                              example: "GBXQ2P5Z5U67G6Z66Z66Z66Z66Z66Z66Z66Z66Z66Z66Z66Z66Z66"
                            amount:
                              type: string
                              example: "2000.0000000"
                            asset:
                              type: string
                              example: "XLM"
        "400":
          description: Invalid transaction ID format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/transactions/export:
    get:
      operationId: exportTransactions
      tags: [transactions]
      summary: Export transactions as CSV
      parameters:
        - name: asset
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/AssetSymbol"
        - name: type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/TransactionType"
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/TransactionStatus"
      responses:
        "200":
          description: CSV file download
          content:
            text/csv:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"

  # ---------------------------------------------------------------------------
  # Quote
  # ---------------------------------------------------------------------------
  /api/quote:
    post:
      operationId: calculateQuote
      tags: [quote]
      summary: Calculate a lending or borrowing quote
      description: |
        Accepts lending parameters and returns projected earnings (lend)
        or repayment schedule (borrow).  Backed by lib/lending/quote.ts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuoteRequest"
      responses:
        "200":
          description: Quote result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuoteResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ---------------------------------------------------------------------------
  # Admin
  # ---------------------------------------------------------------------------
  /api/admin/users:
    get:
      operationId: adminListUsers
      tags: [admin]
      summary: List all platform users (admin only)
      description: |
        Returns a paginated, searchable list of platform users.
        **Requires** an authenticated session JWT that carries a `role: admin` claim.
        Response fields are limited to a safe allow-list; hashed credentials and
        session tokens are never included.
        Every successful call emits a structured audit event.
      security:
        - sessionCookie: []
        - adminBearerToken: []
      parameters:
        - name: page
          in: query
          required: false
          description: 1-based page number (default: 1)
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: pageSize
          in: query
          required: false
          description: Records per page, 1-100 (default: 20)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
        - name: search
          in: query
          required: false
          description: Case-insensitive substring match on email and name (max 100 chars)
          schema:
            type: string
            maxLength: 100
            example: alice
      responses:
        "200":
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUsersResponse"
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Authenticated but does not hold the admin role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Forbidden
        "500":
          $ref: "#/components/responses/InternalError"

  # ---------------------------------------------------------------------------
  # Notifications
  # ---------------------------------------------------------------------------
  /api/notifications:
    get:
      operationId: listNotifications
      tags: [notifications]
      summary: List notifications for the authenticated user
      description: |
        Returns all notifications scoped to the caller's user ID
        along with the current unread count (useful for nav-badge rendering).
        Requires an active session cookie.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Notification list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/notifications/{id}:
    patch:
      operationId: markNotificationRead
      tags: [notifications]
      summary: Mark a notification as read
      description: |
        Sets `read: true` on the specified notification.
        Only affects notifications owned by the authenticated user.
        Requires an active session cookie.
      security:
        - sessionCookie: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Updated notification
          content:
            application/json:
              schema:
                type: object
                properties:
                  notification:
                    $ref: "#/components/schemas/Notification"
        "400":
          description: Missing or blank notification id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Notification not found for this user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/notifications/stream:
    get:
      operationId: streamNotifications
      tags: [notifications]
      summary: Server-Sent Events stream for per-user notifications
      description: |
        Opens a per-session Server-Sent Events (SSE) connection that pushes
        new notifications and unread-count updates for the authenticated user.

        Event types:
        - `notification`: contains a single `Notification` object
        - `unreadCount`: contains `{ unreadCount: number }`

        Clients SHOULD subscribe to this endpoint to receive live updates.
        Polling the `/api/notifications` GET endpoint remains a supported
        fallback for environments that do not support SSE.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: SSE stream (text/event-stream)
          content:
            text/event-stream: {}
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ---------------------------------------------------------------------------
  # Account Deletion (GDPR/CCPA)
  # ---------------------------------------------------------------------------
  /api/account/delete/challenge:
    get:
      operationId: getDeletionChallenge
      tags: [account]
      summary: Get a deletion challenge
      description: |
        Returns a time-limited challenge string that must be submitted
        with the DELETE request to confirm account deletion.
        The challenge expires after 5 minutes and can only be used once.
        Requires an active session cookie.
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Deletion challenge issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletionChallengeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/account/delete:
    delete:
      operationId: deleteAccount
      tags: [account]
      summary: Delete account (GDPR/CCPA)
      description: |
        Initiates account deletion by anonymizing PII, revoking sessions,
        and enqueueing async cleanup of derived data.
        Requires a valid deletion challenge obtained from `GET /api/account/delete/challenge`.

        **Deletion flow:**
        1. `GET /api/account/delete/challenge` to obtain a challenge
        2. `DELETE /api/account/delete` with the challenge in the request body

        **What is deleted immediately:**
        - Profile PII (displayName, bio, website, timezone) is anonymized
        - All user notifications are removed

        **What is scheduled for later deletion (retention-respecting):**
        - Backup anonymization (30-day retention)
        - Derived data removal (7-day retention)
        - Cache entry cleanup (1-day retention)
        - Audit log purge (90-day retention for compliance)
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [challenge]
              properties:
                challenge:
                  type: string
                  description: The deletion challenge string from GET /api/account/delete/challenge
      responses:
        "200":
          description: Account deletion initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountDeletionResponse"
        "400":
          description: Missing or invalid challenge
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid, expired, or mismatched challenge
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

# =============================================================================
# Components
# =============================================================================
components:

  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
    adminBearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT bearing a `role: admin` claim.
        Issued at login; include in `Authorization: Bearer <token>` header.
        Required for all `/api/admin/*` endpoints.

  parameters:
    XRequestId:
      name: x-request-id
      in: header
      required: false
      description: Optional client-provided ULID used for end-to-end request correlation. Malformed values are ignored and replaced.
      schema:
        type: string
        pattern: '^[0-7][0-9A-HJKMNP-TV-Z]{25}$'
        example: '01HZ0000000000000000000000'

  headers:
    XRequestId:
      description: ULID used to correlate this request across middleware, logs, and upstream HTTP calls.
      schema:
        type: string
        pattern: '^[0-7][0-9A-HJKMNP-TV-Z]{25}$'
        example: '01HZ0000000000000000000000'
    XCache:
      description: "Cache resolution status: HIT | MISS | STALE | BYPASS"
      schema:
        type: string
        enum: [HIT, MISS, STALE, BYPASS]
    CacheControl:
      schema:
        type: string

  responses:
    Unauthorized:
      description: No valid session
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Unauthorized
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Failed to fetch market data

  schemas:

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string

    MigrationStatusResponse:
      type: object
      required: [applied, pending, ok]
      properties:
        applied:
          type: array
          items:
            type: string
        pending:
          type: array
          items:
            type: string
        ok:
          type: boolean

    AssetSymbol:
      type: string
      enum: [XLM, USDC, BTC, ETH]
      description: Canonical Stellarlend asset identifier

    TransactionType:
      type: string
      enum: [Deposit, Withdrawal, "Lend Funds", "Loan Payment"]

    TransactionStatus:
      type: string
      enum: [Completed, Processing, Failed]

    Transaction:
      type: object
      required: [id, asset, type, status, amount, date, time]
      properties:
        id:
          type: string
          example: TXN1716800000000
        asset:
          $ref: "#/components/schemas/AssetSymbol"
        type:
          $ref: "#/components/schemas/TransactionType"
        status:
          $ref: "#/components/schemas/TransactionStatus"
        amount:
          type: number
          example: 500.0
        date:
          type: string
          format: date
          example: "2026-05-27"
        time:
          type: string
          example: "14:30"

    TransactionInput:
      type: object
      required: [asset, type, status, amount, date, time]
      properties:
        asset:
          $ref: "#/components/schemas/AssetSymbol"
        type:
          $ref: "#/components/schemas/TransactionType"
        status:
          $ref: "#/components/schemas/TransactionStatus"
        amount:
          type: number
        date:
          type: string
          format: date
        time:
          type: string

    HealthResponse:
      type: object
      required: [status, timestamp, environment, version, checks]
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
        timestamp:
          type: string
          format: date-time
        environment:
          type: string
          enum: [development, staging, production]
        version:
          type: string
        checks:
          type: object
          properties:
            database:
              type: string
            api:
              type: string
            stellar:
              type: string
              enum: [healthy, degraded, unhealthy]

    PricesResponse:
      type: object
      required: [prices, timestamp, source]
      properties:
        prices:
          type: object
          additionalProperties:
            type: number
          example:
            XLM: 0.1245
            USDC: 1.00
            BTC: 67340.50
            ETH: 3480.20
        timestamp:
          type: string
          format: date-time
        source:
          type: string

    AssetMarket:
      type: object
      required: [asset, supplyApr, borrowApr, utilization, totalSupply, totalBorrow]
      properties:
        asset:
          $ref: "#/components/schemas/AssetSymbol"
        supplyApr:
          type: number
          description: Annual percentage rate for lending (e.g. 8.5 = 8.5%)
          example: 8.5
        borrowApr:
          type: number
          description: Annual percentage rate for borrowing
          example: 12.0
        utilization:
          type: number
          description: Ratio of borrowed to supplied capital (0–1)
          minimum: 0
          maximum: 1
          example: 0.71
        totalSupply:
          type: number
          description: Total supplied liquidity in USD
          example: 2500000
        totalBorrow:
          type: number
          description: Total borrowed in USD
          example: 1775000

    MarketsResponse:
      type: object
      required: [markets, timestamp, source]
      properties:
        markets:
          type: array
          items:
            $ref: "#/components/schemas/AssetMarket"
        timestamp:
          type: string
          format: date-time
        source:
          type: string

    PositionsResponse:
      type: object
      properties:
        positions:
          type: array
          items:
            type: object
        userId:
          type: string
        mode:
          type: string
          enum: [public, authenticated]

    PositionSnapshot:
      type: object
      required: [timestamp, supplied, borrowed, effectiveSupplyApy, effectiveBorrowApy]
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
          example: 1700000000000
        supplied:
          type: number
          description: Total supplied balance in USD
          minimum: 0
          example: 5000
        borrowed:
          type: number
          description: Total borrowed balance in USD
          minimum: 0
          example: 2000
        effectiveSupplyApy:
          type: number
          description: Weighted average supply APY (percentage)
          minimum: 0
          example: 2.5
        effectiveBorrowApy:
          type: number
          description: Weighted average borrow APY (percentage)
          minimum: 0
          example: 8.5

    PositionHistoryResponse:
      type: object
      required: [walletAddress, snapshots, interval, bucketCount]
      properties:
        walletAddress:
          type: string
          description: Stellar wallet address
          example: GBTEST123...
        snapshots:
          type: array
          description: Array of position snapshots bucketed by interval
          items:
            $ref: "#/components/schemas/PositionSnapshot"
        interval:
          type: string
          description: Time bucketing interval
          enum: [1h, 1d, 7d, 30d]
          example: 1d
        bucketCount:
          type: integer
          description: Number of snapshot buckets returned
          minimum: 0
          example: 30

    LiquidationPosition:
      type: object
      required: [asset, borrowedAmount, collateralAsset, collateralAmount, collateralFactor, healthFactor, liquidationPriceFactor, riskScore]
      properties:
        asset:
          $ref: "#/components/schemas/AssetSymbol"
          description: The borrowed asset
        borrowedAmount:
          type: number
          description: Amount borrowed in USD
          minimum: 0
          example: 1500
        collateralAsset:
          $ref: "#/components/schemas/AssetSymbol"
          description: The asset posted as collateral
        collateralAmount:
          type: number
          description: Collateral value in USD
          minimum: 0
          example: 5000
        collateralFactor:
          type: number
          description: Collateral factor of the collateral asset (0-1)
          minimum: 0
          maximum: 1
          example: 0.75
        healthFactor:
          type: number
          description: Current health factor (≥1 is safe, <1 is liquidatable)
          example: 2.5
        liquidationPriceFactor:
          type: number
          description: Price multiplier at which liquidation triggers (0 = no borrow)
          minimum: 0
          example: 0.4
        riskScore:
          type: number
          description: Normalized risk score — 0 (safe) to 1 (liquidatable)
          minimum: 0
          maximum: 1
          example: 0.25

    LiquidationsResponse:
      type: object
      required: [positions, totalRiskScore, timestamp]
      properties:
        positions:
          type: array
          description: Positions ranked by risk score (most at risk first)
          items:
            $ref: "#/components/schemas/LiquidationPosition"
        totalRiskScore:
          type: number
          description: Aggregate risk — the maximum risk score across all positions
          minimum: 0
          maximum: 1
          example: 0.83
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the computation

    QuoteRequest:
      type: object
      required: [type, asset, amount, interestRate]
      properties:
        type:
          type: string
          enum: [lend, borrow]
        asset:
          $ref: "#/components/schemas/AssetSymbol"
        amount:
          type: number
        interestRate:
          type: number
          description: Annual percentage rate
        duration:
          type: integer
          description: Duration in days (required for borrow)
        collateral:
          $ref: "#/components/schemas/AssetSymbol"
        collateralAmount:
          type: number

    QuoteResponse:
      type: object
      properties:
        totalEarnings:
          type: number
        dailyEarnings:
          type: number
        totalRepayment:
          type: number
          description: Present only for borrow quotes
        monthlyPayment:
          type: number
          description: Present only for borrow quotes

    NotificationType:
      type: string
      enum: [info, success, warning, error]

    Notification:
      type: object
      required: [id, userId, title, message, read, createdAt, type]
      properties:
        id:
          type: string
          example: notif-1
        userId:
          type: string
        title:
          type: string
          example: Deposit Confirmed
        message:
          type: string
        read:
          type: boolean
        createdAt:
          type: string
          format: date-time
        type:
          $ref: "#/components/schemas/NotificationType"

    NotificationsResponse:
      type: object
      required: [notifications, unreadCount]
      properties:
        notifications:
          type: array
          items:
            $ref: "#/components/schemas/Notification"
        unreadCount:
          type: integer
          minimum: 0
          example: 2

    DeletionChallengeResponse:
      type: object
      required: [challenge, expiresAt, message]
      properties:
        challenge:
          type: string
          description: Hex-encoded challenge string (64 characters)
          example: "a1b2c3d4e5f6..."
        expiresAt:
          type: string
          format: date-time
          description: ISO timestamp when the challenge expires
        message:
          type: string
          example: "Sign this challenge with your wallet to confirm account deletion"

    AccountDeletionResponse:
      type: object
      required: [message, anonymizedAt, notificationsRemoved, cleanupJobsEnqueued]
      properties:
        message:
          type: string
          example: "Account deletion initiated"
        anonymizedAt:
          type: string
          format: date-time
          description: ISO timestamp when PII was anonymized
        notificationsRemoved:
          type: integer
          description: Number of user notifications removed
          example: 5
        cleanupJobsEnqueued:
          type: integer
          description: Number of async cleanup jobs scheduled
          example: 3