openapi.yaml

openapi: 3.1.0
info:
  title: Ethos-Protocol Backend API
  description: >
    Backend API for Ethos-Protocol, a decentralized "Dead Man's Switch" built on Stellar/Soroban.
    This API provides endpoints for vault management, reminder preferences, notifications, and administrative operations.
  version: 1.0.0
  contact:
    name: Ethos-Protocol Team
    url: https://github.com/Ethos-Protocol/Ethos-Protocol
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://api.ethos-protocol.app
    description: Production server
  - url: https://testnet-api.ethos-protocol.app
    description: Testnet server

tags:
  - name: Health & Status
    description: API health checks and status endpoints
  - name: Reminder Preferences
    description: Vault reminder notification preferences
  - name: Notifications
    description: Push notification and delivery management
  - name: TTL Insurance
    description: TTL insurance policy management
  - name: Vaults
    description: Vault query and analytics
  - name: Vault Sharing
    description: Share vault access with other users
  - name: Vault Backup
    description: Backup and recovery operations
  - name: Release Simulator
    description: Project vault release dates under different check-in behaviour scenarios
  - name: Time-Series
    description: Time-series data ingestion, querying, compression, retention, and benchmarking (#75)
  - name: Bulk Jobs
    description: Async bulk operation queuing, progress tracking, and result retrieval (#74)
  - name: Cost Estimation
    description: Pre-flight Stellar/Soroban operation cost estimation (#72)
  - name: Request Replay
    description: API request replay for debugging and regression testing (#73)

paths:
  /health:
    get:
      summary: Health check
      description: Returns API health status without requiring database connectivity
      operationId: getHealth
      tags:
        - Health & Status
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                  version:
                    type: string
                    description: Semantic version of the API
                required:
                  - status
                  - version
              examples:
                success:
                  value:
                    status: ok
                    version: 1.0.0

  /ready:
    get:
      summary: Readiness check
      description: Returns readiness status including database connectivity
      operationId: getReady
      tags:
        - Health & Status
      responses:
        '200':
          description: API is ready and database is connected
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                  version:
                    type: string
                  database:
                    type: string
                    enum: [connected]
                required:
                  - status
                  - version
                  - database
        '503':
          description: Service unavailable (database not connected)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/reminder-preferences:
    parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the vault
    get:
      summary: Get reminder preferences for a vault
      description: Retrieve the current reminder notification preferences for a specific vault
      operationId: getPreferences
      tags:
        - Reminder Preferences
      responses:
        '200':
          description: Reminder preferences retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReminderPreferences'
        '404':
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      summary: Set reminder preferences for a vault
      description: >
        Update or create reminder notification preferences for a vault.
        Supports idempotent requests via the `idempotency-key` header.
      operationId: setPreferences
      tags:
        - Reminder Preferences
      parameters:
        - name: idempotency-key
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: >
            UUID to ensure idempotent requests. If provided, the same response will be returned
            for identical requests within 24 hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPreferencesRequest'
            examples:
              emailOnly:
                summary: Email-only reminders
                value:
                  channels:
                    - email
                  hours_before_expiry: 24
                  frequency: daily
              multiChannel:
                summary: Multiple notification channels
                value:
                  channels:
                    - email
                    - sms
                    - push
                  hours_before_expiry: 48
                  frequency: weekly
      responses:
        '200':
          description: Preferences set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReminderPreferences'
        '400':
          description: Invalid request (empty channels or invalid hours_before_expiry)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                emptyChannels:
                  value:
                    error: "channels must not be empty"
                invalidHours:
                  value:
                    error: "hours_before_expiry must be > 0"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/notifications/register:
    post:
      summary: Register a device token for push notifications
      description: Register a new device push token to receive vault-related notifications
      operationId: registerDeviceToken
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterTokenRequest'
      responses:
        '201':
          description: Device token registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceToken'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/notifications/preferences:
    put:
      summary: Update notification preferences
      description: Update owner notification preferences (channels, frequency, locale)
      operationId: updateNotificationPreferences
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePreferencesRequest'
      responses:
        '200':
          description: Preferences updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferences'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/notifications/unsubscribe:
    get:
      summary: Unsubscribe from reminder emails
      description: Unsubscribe an owner from all reminder email notifications using an unsubscribe token
      operationId: unsubscribeReminders
      tags:
        - Notifications
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Unsubscribe token (provided in notification emails)
      responses:
        '200':
          description: Successfully unsubscribed
          content:
            text/plain:
              schema:
                type: string
              examples:
                success:
                  value: "You (owner_address) have been unsubscribed from reminder emails."
        '400':
          description: Invalid or expired unsubscribe token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/ttl-insurance/purchase:
    post:
      summary: Purchase TTL insurance policy
      description: >
        Purchase a TTL insurance policy to automatically extend TTL when owner becomes inactive.
        Requires owner authentication.
      operationId: purchaseTtlInsurance
      tags:
        - TTL Insurance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTtlInsuranceRequest'
      responses:
        '201':
          description: TTL insurance policy purchased successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtlInsurancePolicy'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/ttl-insurance/vaults/{vault_id}:
    get:
      summary: Get TTL insurance policy for a vault
      description: Retrieve TTL insurance policy details for a specific vault
      operationId: getTtlInsurancePolicy
      tags:
        - TTL Insurance
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
      responses:
        '200':
          description: Policy retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtlInsurancePolicy'
        '404':
          description: Vault or policy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/search:
    post:
      summary: Search vaults
      description: Search for vaults based on owner, beneficiary, status, and date range with pagination
      operationId: searchVaults
      tags:
        - Vaults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQuery'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/compare:
    post:
      summary: Compare multiple vaults
      description: Retrieve and compare multiple vaults by their IDs
      operationId: compareVaults
      tags:
        - Vaults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vault_ids:
                  type: array
                  items:
                    type: string
                  description: Array of vault IDs to compare
              required:
                - vault_ids
      responses:
        '200':
          description: Comparison results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComparisonResult'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/export:
    get:
      summary: Export vault data
      description: Export vault data, history, and audit log in JSON or CSV format
      operationId: exportVault
      tags:
        - Vaults
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, csv]
            default: json
          description: Export format
      responses:
        '200':
          description: Vault data exported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportData'
            text/csv:
              schema:
                type: string
        '404':
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid format specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/analytics:
    get:
      summary: Get vault analytics
      description: Retrieve analytics data for vault activity, TTL, and release rates
      operationId: getVaultAnalytics
      tags:
        - Vaults
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
      responses:
        '200':
          description: Analytics data retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultAnalytics'
        '404':
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/share:
    post:
      summary: Share vault access
      description: Grant another address access to view or edit vault with specified permissions
      operationId: shareVault
      tags:
        - Vault Sharing
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareRequest'
      responses:
        '201':
          description: Vault shared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultShare'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/backup:
    post:
      summary: Create vault backup
      description: Create an encrypted backup of vault state for disaster recovery
      operationId: createVaultBackup
      tags:
        - Vault Backup
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
      responses:
        '201':
          description: Backup created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultBackup'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      summary: List vault backups
      description: List all backups for a specific vault
      operationId: listVaultBackups
      tags:
        - Vault Backup
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
          description: The vault ID
      responses:
        '200':
          description: Backups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  backups:
                    type: array
                    items:
                      $ref: '#/components/schemas/VaultBackup'
        '404':
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/restore:
    post:
      summary: Restore vault from backup
      description: Restore a vault to a previous state using an encrypted backup and decryption key
      operationId: restoreVaultBackup
      tags:
        - Vault Backup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreRequest'
      responses:
        '200':
          description: Vault restored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        '400':
          description: Invalid request or decryption failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Backup not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/vaults/{vault_id}/simulate-release:
    get:
      summary: Simulate vault release scenarios
      description: >
        Projects when a vault will release to its beneficiary under one or more
        check-in behaviour scenarios. Useful for owners who want to understand
        the impact of their check-in habits on release timing.
      operationId: simulateVaultRelease
      tags:
        - Release Simulator
      parameters:
        - name: vault_id
          in: path
          required: true
          description: The ID of the vault to simulate
          schema:
            type: string
          example: vault-abc-123
        - name: scenarios
          in: query
          required: false
          description: >
            Comma-separated list of scenarios to run. Defaults to all three when
            omitted. Valid values: `no_check_ins`, `consistent_check_ins`,
            `missed_check_in_dates`.
          schema:
            type: string
            example: "no_check_ins,missed_check_in_dates"
        - name: missed_count
          in: query
          required: false
          description: >
            For the `missed_check_in_dates` scenario: number of consecutive
            check-ins the owner misses before stopping entirely. Defaults to 1.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Simulation results for the requested scenarios
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateReleaseResponse'
              example:
                vault_id: "vault-abc-123"
                current_ttl_remaining: 86400
                check_in_interval: 2592000
                last_check_in: "2026-06-29T10:00:00Z"
                simulated_at: "2026-06-30T06:39:00Z"
                scenarios:
                  - scenario: "no_check_ins"
                    description: "Owner performs no further check-ins. Vault releases when the current TTL expires."
                    projected_release_at: "2026-07-01T06:39:00Z"
                    seconds_until_release: 86400
                    confidence: "high"
                    notes: "Current TTL remaining: 86400 seconds (1.0 days)."
                  - scenario: "consistent_check_ins"
                    description: "Owner checks in consistently at the configured interval. Vault does not release."
                    projected_release_at: "2126-06-30T06:39:00Z"
                    seconds_until_release: -1
                    confidence: "high"
                    notes: "With a check-in interval of 2592000 seconds (30.0 days), consistent check-ins prevent vault release indefinitely."
                  - scenario: "missed_check_in_dates"
                    description: "Owner misses 1 consecutive check-in(s), then stops entirely."
                    projected_release_at: "2026-08-01T06:39:00Z"
                    seconds_until_release: 2678400
                    confidence: "medium"
                    notes: "Each missed check-in adds 2592000 seconds (30.0 days) to the release window. 1 missed check-in(s) → 2592000 additional seconds."
        '404':
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid scenario name(s) specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ── Time-Series Data Optimizations (#75) ──────────────────────────────────

  /timeseries/ingest:
    post:
      summary: Ingest a time-series data point
      description: Store a single metric data point in the time-series engine. Data is automatically routed to a monthly partition for the given series.
      operationId: ingestTimeSeriesPoint
      tags:
        - Time-Series
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestRequest'
      responses:
        '204':
          description: Point ingested successfully
        '400':
          description: Invalid request body

  /timeseries/query:
    post:
      summary: Query time-series data
      description: Retrieve data points for a series, optionally downsampled to hourly, daily, or weekly resolution.
      operationId: queryTimeSeries
      tags:
        - Time-Series
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeSeriesQueryRequest'
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesQueryResponse'

  /timeseries/{series}/compress:
    post:
      summary: Compress all partitions for a series
      description: Apply lossy compression (value rounding to 4dp) to all uncompressed partitions. Returns bytes saved.
      operationId: compressTimeSeries
      tags:
        - Time-Series
      parameters:
        - name: series
          in: path
          required: true
          schema:
            type: string
          example: vault.balance
      responses:
        '200':
          description: Compression result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompressResponse'

  /timeseries/{series}/retention:
    post:
      summary: Set retention policy for a series
      description: Configure how long raw, hourly, and daily data is retained before automatic pruning.
      operationId: setRetentionPolicy
      tags:
        - Time-Series
      parameters:
        - name: series
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetRetentionRequest'
      responses:
        '200':
          description: Applied retention policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionPolicy'

  /timeseries/{series}/benchmark:
    post:
      summary: Benchmark storage for a series
      description: Run a full storage benchmark — measures raw bytes, compression savings, and downsampled counts.
      operationId: benchmarkTimeSeries
      tags:
        - Time-Series
      parameters:
        - name: series
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Benchmark result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkResult'

  # ── Bulk Operation Queuing (#74) ───────────────────────────────────────────

  /jobs:
    post:
      summary: Submit a bulk operation job
      description: Enqueue an async bulk operation (e.g., update TTL for multiple vaults, send reminders). Returns immediately with a job ID for status polling.
      operationId: createBulkJob
      tags:
        - Bulk Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '202':
          description: Job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobResponse'
        '400':
          description: Invalid request (empty items list)
    get:
      summary: List all bulk jobs
      description: Returns all jobs ordered by creation time (newest first). Filter by status with the `status` query parameter.
      operationId: listBulkJobs
      tags:
        - Bulk Jobs
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/JobStatus'
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkJob'

  /jobs/{job_id}:
    get:
      summary: Get job status and progress
      description: Returns detailed status, progress percentage, and estimated time remaining for a job.
      operationId: getBulkJob
      tags:
        - Bulk Jobs
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
        '404':
          description: Job not found
    delete:
      summary: Cancel a job
      description: Cancel a queued or running job. Completed or failed jobs cannot be cancelled.
      operationId: cancelBulkJob
      tags:
        - Bulk Jobs
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Job cancelled
        '404':
          description: Job not found or not cancellable

  # ── Request Cost Estimation (#72) ─────────────────────────────────────────

  /estimate-cost:
    post:
      summary: Estimate operation cost
      description: |
        Returns a detailed fee breakdown for a Stellar/Soroban operation before it is submitted.
        Fees are in stroops (1 XLM = 10,000,000 stroops).

        **Cost factors documented at** `/docs/cost-estimation`.
      operationId: estimateCost
      tags:
        - Cost Estimation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateCostRequest'
            examples:
              check_in:
                summary: Estimate a vault check-in
                value:
                  operation: check_in
              bulk_check_in:
                summary: Estimate bulk check-in for 50 vaults with scenarios
                value:
                  operation: bulk_check_in
                  bulk_count: 50
                  include_scenarios: true
      responses:
        '200':
          description: Cost breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateCostResponse'

  # ── API Request Replay Capability (#73) ───────────────────────────────────

  /replay:
    post:
      summary: Replay a logged API request
      description: |
        Re-execute a previously recorded API request. Supports conditional replay (only replay
        if the original had a specific status, path substring, or body value) and optional
        response comparison to detect drift.

        **Admin endpoint** — restrict access in production.
      operationId: replayRequest
      tags:
        - Request Replay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayRequest'
      responses:
        '200':
          description: Replay result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayResult'
        '404':
          description: Log entry not found

  /replay/batch:
    post:
      summary: Batch replay multiple logged requests
      description: Replay up to 50 logged requests in one call. Returns per-request outcomes and a summary (identical/diverged/skipped counts).
      operationId: batchReplay
      tags:
        - Request Replay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReplayRequest'
      responses:
        '200':
          description: Batch replay results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchReplayResponse'
        '400':
          description: Empty list or more than 50 entries

  /replay/logs:
    get:
      summary: List stored request logs
      description: Returns stored request/response logs, newest first. Filterable by path prefix.
      operationId: listRequestLogs
      tags:
        - Request Replay
      parameters:
        - name: path
          in: query
          required: false
          schema:
            type: string
          description: Filter by URL path prefix (e.g. `/api/vaults`)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 200
      responses:
        '200':
          description: List of request logs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestLog'

  /replay/logs/{log_id}:
    get:
      summary: Get a single request log entry
      operationId: getRequestLog
      tags:
        - Request Replay
      parameters:
        - name: log_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Request log entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestLog'
        '404':
          description: Log entry not found

components:
  schemas:
    # ── Time-Series schemas ────────────────────────────────────────────────

    IngestRequest:
      type: object
      properties:
        series:
          type: string
          description: Series name (e.g. vault.balance, check_in.count)
          example: vault.balance
        timestamp:
          type: string
          format: date-time
          description: ISO-8601 timestamp (defaults to now)
        value:
          type: number
          format: double
        tags:
          type: object
          additionalProperties:
            type: string
      required:
        - series
        - value

    TimeSeriesQueryRequest:
      type: object
      properties:
        series:
          type: string
        resolution:
          type: string
          enum: [raw, hourly, daily, weekly]
          default: raw
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
      required:
        - series

    TimeSeriesQueryResponse:
      type: object
      properties:
        series:
          type: string
        resolution:
          type: string
          enum: [raw, hourly, daily, weekly]
        points:
          type: array
          items:
            $ref: '#/components/schemas/TSPoint'
        count:
          type: integer
      required:
        - series
        - resolution
        - points
        - count

    TSPoint:
      type: object
      properties:
        series:
          type: string
        timestamp:
          type: string
          format: date-time
        value:
          type: number
          format: double
        tags:
          type: object
          additionalProperties:
            type: string
      required:
        - series
        - timestamp
        - value

    CompressResponse:
      type: object
      properties:
        series:
          type: string
        bytes_saved:
          type: integer
        partitions_compressed:
          type: integer
      required:
        - series
        - bytes_saved
        - partitions_compressed

    SetRetentionRequest:
      type: object
      properties:
        raw_retention_days:
          type: integer
          minimum: 1
          description: Days to keep raw data
        hourly_retention_days:
          type: integer
          description: Days to keep hourly downsampled data (0 = disabled)
        daily_retention_days:
          type: integer
          description: Days to keep daily downsampled data (0 = disabled)
      required:
        - raw_retention_days

    RetentionPolicy:
      type: object
      properties:
        series:
          type: string
        raw_retention_days:
          type: integer
        hourly_retention_days:
          type: integer
        daily_retention_days:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - series
        - raw_retention_days
        - hourly_retention_days
        - daily_retention_days

    BenchmarkResult:
      type: object
      properties:
        series:
          type: string
        raw_point_count:
          type: integer
        raw_bytes:
          type: integer
        compressed_bytes:
          type: integer
        compression_ratio:
          type: number
          format: double
        downsampled_hourly_count:
          type: integer
        downsampled_daily_count:
          type: integer
        partitions_created:
          type: integer
        points_pruned_by_retention:
          type: integer
        benchmark_ran_at:
          type: string
          format: date-time
      required:
        - series
        - raw_point_count
        - compression_ratio

    # ── Bulk Job schemas ───────────────────────────────────────────────────

    BulkOperationType:
      type: string
      enum: [update_ttl, send_reminders, export_vaults, retention_sweep, custom]

    JobStatus:
      type: string
      enum: [queued, running, completed, failed, cancelled]

    BulkJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
        operation:
          $ref: '#/components/schemas/BulkOperationType'
        payload:
          description: Input data supplied at job creation
        status:
          $ref: '#/components/schemas/JobStatus'
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Completion percentage
        total_items:
          type: integer
        processed_items:
          type: integer
        failed_items:
          type: integer
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        result:
          nullable: true
          description: Structured result (available when completed)
        error:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
      required:
        - id
        - operation
        - status
        - progress
        - total_items

    CreateJobRequest:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/BulkOperationType'
        items:
          description: Array of items to process (e.g. vault IDs for update_ttl)
          example: ["vault-1", "vault-2", "vault-3"]
        label:
          type: string
          description: Optional human-readable label for this job
      required:
        - operation
        - items

    CreateJobResponse:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatus'
        message:
          type: string
      required:
        - job_id
        - status
        - message

    JobStatusResponse:
      type: object
      properties:
        job:
          $ref: '#/components/schemas/BulkJob'
        estimated_seconds_remaining:
          type: integer
          nullable: true
          description: Linear extrapolation of seconds until completion
      required:
        - job

    # ── Cost Estimation schemas ────────────────────────────────────────────

    EstimateCostRequest:
      type: object
      properties:
        operation:
          type: string
          enum: [create_vault, check_in, deposit, withdraw, trigger_release, update_beneficiary, bulk_check_in, custom]
        vault_id:
          type: string
          nullable: true
          description: Optional vault ID for vault-specific estimation
        amount_stroops:
          type: integer
          format: int64
          nullable: true
          description: Amount in stroops for deposit/withdraw operations
        bulk_count:
          type: integer
          format: int64
          nullable: true
          description: Number of vaults for bulk_check_in
        payload_bytes:
          type: integer
          format: int64
          nullable: true
          description: Payload size in bytes for custom operations
        include_scenarios:
          type: boolean
          default: false
          description: Include scenario variants in the response
      required:
        - operation

    CostBreakdown:
      type: object
      properties:
        base_fee_stroops:
          type: integer
          format: int64
        instruction_fee_stroops:
          type: integer
          format: int64
        write_entries_fee_stroops:
          type: integer
          format: int64
        read_entries_fee_stroops:
          type: integer
          format: int64
        rent_fee_stroops:
          type: integer
          format: int64
        total_stroops:
          type: integer
          format: int64
        total_xlm:
          type: number
          format: double
          description: Total cost in XLM (total_stroops / 10,000,000)
        notes:
          type: array
          items:
            type: string
          description: Human-readable explanation of cost drivers
      required:
        - total_stroops
        - total_xlm

    EstimateCostResponse:
      type: object
      properties:
        operation:
          type: string
        breakdown:
          $ref: '#/components/schemas/CostBreakdown'
        scenarios:
          type: array
          items:
            $ref: '#/components/schemas/CostScenario'
          description: Scenario variants (populated when include_scenarios=true)
        estimated_at:
          type: string
          format: date-time
        docs_url:
          type: string
          description: Link to cost factor documentation
      required:
        - operation
        - breakdown
        - estimated_at
        - docs_url

    CostScenario:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        parameters:
          type: object
          additionalProperties: true
        breakdown:
          $ref: '#/components/schemas/CostBreakdown'
      required:
        - name
        - description
        - breakdown

    # ── Request Replay schemas ─────────────────────────────────────────────

    RequestLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        method:
          type: string
          enum: [GET, POST, PUT, DELETE, PATCH, OPTIONS]
        path:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
          description: Request headers (Authorization stripped)
        request_body:
          nullable: true
          description: Original request body
        response_status:
          type: integer
        response_body:
          description: Original response body
        duration_ms:
          type: integer
          description: Original processing time in milliseconds
        recorded_at:
          type: string
          format: date-time
        tag:
          type: string
          nullable: true
      required:
        - id
        - method
        - path
        - response_status
        - recorded_at

    ReplayCondition:
      type: object
      description: |
        A condition that must be met before the replay executes.
        Exactly one of the condition variants must be specified.
      properties:
        original_status_equals:
          type: integer
          description: Only replay if original status equals this code
        path_contains:
          type: string
          description: Only replay if request path contains this substring
        body_key_equals:
          type: object
          properties:
            key:
              type: string
            value:
              description: JSON value to match against
          description: Only replay if request body has this key=value
        always:
          type: boolean
          description: Always replay (default)

    ReplayRequest:
      type: object
      properties:
        log_id:
          type: string
          format: uuid
          description: ID of the log entry to replay
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ReplayCondition'
          description: Optional conditions — all must pass for the replay to proceed
        validate:
          type: boolean
          default: true
          description: Compare replayed response to original and report differences
      required:
        - log_id

    ReplayOutcome:
      type: string
      enum: [identical, diverged, skipped, unvalidated]

    ReplayResult:
      type: object
      properties:
        log_id:
          type: string
          format: uuid
        method:
          type: string
        path:
          type: string
        original_status:
          type: integer
        replayed_status:
          type: integer
        replayed_body:
          description: Response body from the replay
        outcome:
          $ref: '#/components/schemas/ReplayOutcome'
        diff_notes:
          type: array
          items:
            type: string
          description: Human-readable diff summary (populated when outcome is diverged)
        replayed_at:
          type: string
          format: date-time
      required:
        - log_id
        - outcome
        - replayed_at

    BatchReplayRequest:
      type: object
      properties:
        log_ids:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 50
          description: IDs of log entries to replay
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ReplayCondition'
        validate:
          type: boolean
          default: true
      required:
        - log_ids

    BatchReplayResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ReplayResult'
        total:
          type: integer
        identical:
          type: integer
        diverged:
          type: integer
        skipped:
          type: integer
      required:
        - results
        - total
        - identical
        - diverged
        - skipped

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        status_code:
          type: integer
          description: HTTP status code
      required:
        - error

    Locale:
      type: string
      enum: [en, es, fr, de]
      description: Supported locales

    Channel:
      type: string
      enum: [email, sms, push]
      description: Notification delivery channel

    Frequency:
      type: string
      enum: [once, daily, weekly, hourly, monthly]
      description: Reminder frequency

    ReminderPreferences:
      type: object
      properties:
        vault_id:
          type: string
          format: uuid
          description: Vault ID
        channels:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
          description: Notification channels enabled
        hours_before_expiry:
          type: integer
          minimum: 1
          description: Hours before expiry to send reminder
        frequency:
          $ref: '#/components/schemas/Frequency'
      required:
        - vault_id
        - channels
        - hours_before_expiry
        - frequency

    SetPreferencesRequest:
      type: object
      properties:
        channels:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
          minItems: 1
          description: Notification channels to enable
        hours_before_expiry:
          type: integer
          minimum: 1
          description: Hours before expiry to send reminder
        frequency:
          $ref: '#/components/schemas/Frequency'
      required:
        - channels
        - hours_before_expiry
        - frequency

    RegisterTokenRequest:
      type: object
      properties:
        owner:
          type: string
          description: Owner address
        token:
          type: string
          description: Device push token
        platform:
          type: string
          enum: [ios, android, web]
          description: Device platform
      required:
        - owner
        - token
        - platform

    DeviceToken:
      type: object
      properties:
        owner:
          type: string
          description: Owner address
        token:
          type: string
          description: Device push token
        platform:
          type: string
          enum: [ios, android, web]
        registered_at:
          type: string
          format: date-time
          description: Registration timestamp (RFC3339)
      required:
        - owner
        - token
        - platform
        - registered_at

    NotificationPreferences:
      type: object
      properties:
        owner:
          type: string
          description: Owner address
        expiry_warning_enabled:
          type: boolean
          default: true
        check_in_reminder_enabled:
          type: boolean
          default: true
        vault_released_enabled:
          type: boolean
          default: true
        warning_hours_before:
          type: integer
          default: 24
          description: Hours before expiry to warn
        locale:
          $ref: '#/components/schemas/Locale'
      required:
        - owner

    UpdatePreferencesRequest:
      type: object
      properties:
        owner:
          type: string
          description: Owner address
        expiry_warning_enabled:
          type: boolean
        check_in_reminder_enabled:
          type: boolean
        vault_released_enabled:
          type: boolean
        warning_hours_before:
          type: integer
        locale:
          $ref: '#/components/schemas/Locale'

    TtlInsurancePolicy:
      type: object
      properties:
        vault_id:
          type: string
          description: Associated vault ID
        extension_seconds:
          type: integer
          description: Seconds to extend TTL when triggered
        inactivity_threshold_seconds:
          type: integer
          description: Inactivity duration before triggering
        enabled:
          type: boolean
        purchased_at:
          type: string
          format: date-time
        last_extended_at:
          type: string
          format: date-time
          nullable: true
      required:
        - vault_id
        - extension_seconds
        - inactivity_threshold_seconds
        - enabled
        - purchased_at

    PurchaseTtlInsuranceRequest:
      type: object
      properties:
        extension_seconds:
          type: integer
          minimum: 1
          description: Seconds to extend TTL
        inactivity_threshold_seconds:
          type: integer
          minimum: 1
          description: Inactivity threshold in seconds
      required:
        - extension_seconds
        - inactivity_threshold_seconds

    VaultStatus:
      type: string
      enum: [active, expired, released, paused]
      description: Current vault status

    Vault:
      type: object
      properties:
        id:
          type: string
          description: Vault ID
        owner:
          type: string
          description: Vault owner address
        beneficiary:
          type: string
          description: Beneficiary address
        balance:
          type: integer
          format: int64
          description: Vault balance in stroops
        check_in_interval:
          type: integer
          description: Check-in interval in seconds
        last_check_in:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/VaultStatus'
        ttl_remaining:
          type: integer
          nullable: true
          description: Remaining TTL in seconds
      required:
        - id
        - owner
        - beneficiary
        - balance
        - check_in_interval
        - created_at
        - status

    SearchQuery:
      type: object
      properties:
        owner:
          type: string
          description: Filter by owner address
        beneficiary:
          type: string
          description: Filter by beneficiary address
        status:
          $ref: '#/components/schemas/VaultStatus'
        created_after:
          type: string
          format: date-time
          description: Filter vaults created after this date
        created_before:
          type: string
          format: date-time
          description: Filter vaults created before this date
        page:
          type: integer
          minimum: 1
          default: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20

    SearchResult:
      type: object
      properties:
        vaults:
          type: array
          items:
            $ref: '#/components/schemas/Vault'
        total:
          type: integer
          description: Total matching vaults
        page:
          type: integer
        limit:
          type: integer
      required:
        - vaults
        - total
        - page
        - limit

    ComparisonResult:
      type: object
      properties:
        vaults:
          type: array
          items:
            $ref: '#/components/schemas/Vault'
      required:
        - vaults

    EventType:
      type: string
      enum: [check_in, ttl_update, status_change, deposit, withdrawal, release]

    VaultEvent:
      type: object
      properties:
        vault_id:
          type: string
        event_type:
          $ref: '#/components/schemas/EventType'
        timestamp:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true
      required:
        - vault_id
        - event_type
        - timestamp

    AuditEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        action:
          type: string
        actor:
          type: string
        details:
          type: object
          additionalProperties: true
      required:
        - timestamp
        - action
        - actor

    ExportData:
      type: object
      properties:
        vault:
          $ref: '#/components/schemas/Vault'
        history:
          type: array
          items:
            $ref: '#/components/schemas/VaultEvent'
        audit_log:
          type: array
          items:
            $ref: '#/components/schemas/AuditEntry'
      required:
        - vault
        - history
        - audit_log

    TimeSeriesPoint:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Date in ISO-8601 format (YYYY-MM-DD)
        vaults_created:
          type: integer
        vaults_released:
          type: integer
      required:
        - date
        - vaults_created
        - vaults_released

    VaultAnalytics:
      type: object
      properties:
        total_vaults:
          type: integer
        active_vaults:
          type: integer
        average_ttl_seconds:
          type: number
          format: double
        release_rate:
          type: number
          format: double
          description: Fraction of vaults that are released
        time_series:
          type: array
          items:
            $ref: '#/components/schemas/TimeSeriesPoint'
      required:
        - total_vaults
        - active_vaults
        - average_ttl_seconds
        - release_rate
        - time_series

    SharePermission:
      type: string
      enum: [view_only, edit, admin]

    VaultShare:
      type: object
      properties:
        share_id:
          type: string
          format: uuid
        vault_id:
          type: string
        shared_with:
          type: string
          description: Address or email vault is shared with
        permission:
          $ref: '#/components/schemas/SharePermission'
        created_at:
          type: string
          format: date-time
      required:
        - share_id
        - vault_id
        - shared_with
        - permission
        - created_at

    ShareRequest:
      type: object
      properties:
        shared_with:
          type: string
          description: Address or email to share with
        permission:
          $ref: '#/components/schemas/SharePermission'
      required:
        - shared_with
        - permission

    VaultBackup:
      type: object
      properties:
        backup_id:
          type: string
          format: uuid
        vault_id:
          type: string
        created_at:
          type: string
          format: date-time
        encrypted_payload:
          type: string
          description: Base64-encoded AES-GCM encrypted vault state JSON
      required:
        - backup_id
        - vault_id
        - created_at
        - encrypted_payload

    RestoreRequest:
      type: object
      properties:
        backup_id:
          type: string
          format: uuid
        encryption_key:
          type: string
          description: Base64-encoded 32-byte AES key used during backup
      required:
        - backup_id
        - encryption_key

    ScenarioType:
      type: string
      enum:
        - no_check_ins
        - consistent_check_ins
        - missed_check_in_dates
      description: >
        The check-in behaviour scenario to simulate.

        - `no_check_ins` — owner never checks in again; vault releases when current TTL expires.
        - `consistent_check_ins` — owner checks in at every interval indefinitely; vault never releases.
        - `missed_check_in_dates` — owner misses N consecutive check-ins, then stops.

    ScenarioResult:
      type: object
      description: Projected release outcome for a single scenario
      properties:
        scenario:
          $ref: '#/components/schemas/ScenarioType'
        description:
          type: string
          description: Human-readable description of the scenario assumptions
        projected_release_at:
          type: string
          format: date-time
          description: >
            Projected UTC timestamp when the vault will release under this scenario.
            For `consistent_check_ins`, this is a far-future sentinel value.
        seconds_until_release:
          type: integer
          format: int64
          description: >
            Seconds from simulation time until projected release.
            -1 means the vault will never release under this scenario.
        confidence:
          type: string
          enum: [high, medium, low]
          description: >
            Confidence in the projection.
            `high` — deterministic given vault state.
            `medium` — 1–2 missed check-ins assumed.
            `low` — 3+ missed check-ins assumed (higher uncertainty).
        notes:
          type: string
          description: Additional context about the scenario's assumptions and calculations
      required:
        - scenario
        - description
        - projected_release_at
        - seconds_until_release
        - confidence
        - notes

    SimulateReleaseResponse:
      type: object
      description: Response containing simulation results for one or more release scenarios
      properties:
        vault_id:
          type: string
          description: The ID of the vault that was simulated
        current_ttl_remaining:
          type: integer
          format: int64
          nullable: true
          description: Current TTL remaining in seconds; null if not known or already expired
        check_in_interval:
          type: integer
          format: int64
          description: The vault's configured check-in interval in seconds
        last_check_in:
          type: string
          format: date-time
          description: Timestamp of the last recorded check-in
        scenarios:
          type: array
          items:
            $ref: '#/components/schemas/ScenarioResult'
          description: Simulation results, one per requested scenario
        simulated_at:
          type: string
          format: date-time
          description: Timestamp when this simulation was generated
      required:
        - vault_id
        - check_in_interval
        - last_check_in
        - scenarios
        - simulated_at

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication for passkey-authenticated requests

security:
  - ApiKeyAuth: []
  - BearerAuth: []