openapi.yaml

openapi: 3.0.0
info:
  title: CommitLabs API
  description: API for the CommitLabs protocol, managing liquidity commitments on the Stellar network.
  version: 1.0.0

servers:
  - url: /
    description: Local development server

security: []

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    # Standard Success Envelope
    SuccessEnvelope:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        data:
          type: object
        meta:
          type: object
          description: Optional pagination or extra context

    # Standard Error Envelope
    ErrorEnvelope:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g., NOT_FOUND, VALIDATION_ERROR)
            message:
              type: string
              description: Human-readable message safe for UI display
            details:
              type: object
              description: Extra context (only included in development)

  responses:
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            ok: false
            error:
              code: "VALIDATION_ERROR"
              message: "Invalid parameters provided."
    Unauthorized:
      description: Authentication failed or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: The request is understood but refused due to policy or ownership.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Too many requests.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'

paths:
  /api/health:
    get:
      summary: Health Check
      description: Returns the current status and version of the API.
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/metrics:
    get:
      summary: System Metrics
      description: Returns health metrics including uptime and request counts.
      responses:
        '200':
          description: Metrics retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments:
    get:
      summary: List Commitments
      description: Fetch a list of commitments with optional filtering and pagination.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of commitments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

    post:
      summary: Create Commitment
      description: Initializes a new liquidity commitment (Stub).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                asset:
                  type: string
                  example: "XLM"
                amount:
                  type: number
                  example: 100
      responses:
        '201':
          description: Commitment created (stubbed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/commitments/search:
    get:
      summary: Search Commitments
      description: >
        Search and filter commitments by asset, status, and risk type with
        stable sorting and pagination. Mirrors the marketplace filtering contract.
      parameters:
        - name: ownerAddress
          in: query
          required: true
          schema:
            type: string
          description: Stellar address of the commitment owner.
        - name: asset
          in: query
          schema:
            type: string
          description: Filter by asset code (e.g. XLM, USDC). Case-insensitive.
        - name: status
          in: query
          schema:
            type: string
            enum: [ACTIVE, SETTLED, VIOLATED, EARLY_EXIT]
          description: Filter by commitment status.
        - name: riskType
          in: query
          schema:
            type: string
            enum: [Safe, Balanced, Aggressive]
          description: Filter by risk type.
        - name: minCompliance
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Minimum compliance score (0–100).
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt, amount, complianceScore, status, asset]
            default: createdAt
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Filtered and paginated list of commitments.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          data:
                            type: array
                            items:
                              type: object
                              properties:
                                commitmentId: { type: string }
                                ownerAddress: { type: string }
                                asset: { type: string }
                                amount: { type: string }
                                status: { type: string }
                                riskType: { type: string }
                                complianceScore: { type: number }
                                currentValue: { type: string }
                                feeEarned: { type: string }
                                violationCount: { type: integer }
                                createdAt: { type: string }
                                expiresAt: { type: string }
                          meta:
                            type: object
                            properties:
                              page: { type: integer }
                              pageSize: { type: integer }
                              total: { type: integer }
                              totalPages: { type: integer }
                              hasNextPage: { type: boolean }
                              hasPrevPage: { type: boolean }
                          filters:
                            type: object
                            properties:
                              asset: { type: string, nullable: true }
                              status: { type: string, nullable: true }
                              riskType: { type: string, nullable: true }
                              minCompliance: { type: number, nullable: true }
                              sortBy: { type: string }
                              sortOrder: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/commitments/{id}/fund:
    post:
      summary: Fund a Created Commitment
      description: Submit the on-chain `fund_escrow` transaction for a previously created commitment.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Commitment identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callerAddress:
                  type: string
                  example: "GOWNER..."
      responses:
        '200':
          description: Commitment funded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/commitments/{id}/settle:
    post:
      summary: Settle Commitment
      description: Marks a specific commitment as settled (Stub).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                finalValue:
                  type: number
                  example: 105
      responses:
        '200':
          description: Settlement recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/commitments/{id}/settle/preview:
    get:
      summary: Settlement Preview
      description: Returns a preview of whether a commitment is eligible for settlement and an estimated settlement amount.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The commitment ID to preview settlement for.
      responses:
        '200':
          description: Settlement preview result.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          eligible:
                            type: boolean
                          reason:
                            type: string
                            nullable: true
                          estimatedSettlement:
                            type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/commitments/{id}/early-exit:
    post:
      summary: Early Exit
      description: Triggers an early exit for a commitment with potential penalties (Stub).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  example: "user-request"
      responses:
        '200':
          description: Early exit processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/marketplace/listings/{id}/preflight:
    post:
      summary: Purchase Preflight
      description: Checks whether the authenticated buyer is eligible to purchase a listing before committing.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [buyerAddress]
              properties:
                buyerAddress:
                  type: string
                  example: "GBUYERADDRESS..."
      responses:
        '200':
          description: Preflight result.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          eligible:
                            type: boolean
                          reasons:
                            type: array
                            items:
                              type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/marketplace/listings/{id}/purchase:
    post:
      summary: Purchase Listing
      description: |
        Purchases a marketplace listing. Runs preflight eligibility checks,
        authenticates the buyer via session cookie, triggers on-chain ownership
        transfer through the contracts service, and records the event in the
        audit log.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The marketplace listing ID.
      responses:
        '200':
          description: Purchase completed successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          listingId:
                            type: string
                          commitmentId:
                            type: string
                          buyerAddress:
                            type: string
                          price:
                            type: string
                          currencyAsset:
                            type: string
                          txHash:
                            type: string
                            nullable: true
                          reference:
                            type: string
                            nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Purchase not eligible (listing inactive, buyer is seller, etc.).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/attestations:
    get:
      summary: List Attestations
      description: Returns a paginated list of attestations, optionally filtered by commitmentId.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: commitmentId
          in: query
          schema:
            type: string
          description: Filter attestations by a specific commitment ID.
      responses:
        '200':
          description: A paginated list of attestations.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                          meta:
                            type: object
                            properties:
                              totalItems: { type: integer }
                              itemCount: { type: integer }
                              itemsPerPage: { type: integer }
                              totalPages: { type: integer }
                              currentPage: { type: integer }
    post:
      summary: Record Attestation
      description: Logs an attestation event for a commitment (Stub).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                commitmentId:
                  type: string
                status:
                  type: string
                  example: "valid"
      responses:
        '200':
          description: Attestation logged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/admin/audit-events:
    get:
      summary: List audit events
      responses:
        '200':
          description: Audit events retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/analytics/user:
    options:
      summary: Analytics user CORS preflight
      responses:
        '204':
          description: CORS preflight response.

  /api/attestations/recent:
    get:
      summary: Recent attestations
      responses:
        '200':
          description: Recent attestations retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/auth:
    post:
      summary: Authenticate wallet session
      responses:
        '200':
          description: Session established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/auth/csrf:
    get:
      summary: CSRF token
      responses:
        '200':
          description: CSRF token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/auth/logout:
    post:
      summary: End session
      responses:
        '200':
          description: Session ended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/auth/nonce:
    post:
      summary: Request auth nonce
      responses:
        '200':
          description: Nonce issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/auth/verify:
    post:
      summary: Verify wallet signature
      responses:
        '200':
          description: Signature verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/export:
    get:
      summary: Export commitments
      responses:
        '200':
          description: Commitments exported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/validate:
    post:
      summary: Validate commitment draft
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/{id}:
    get:
      summary: Get commitment by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Commitment retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/commitments/{id}/dispute:
    post:
      summary: Dispute commitment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dispute recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/{id}/early-exit/preview:
    get:
      summary: Early exit preview
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Early exit preview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/{id}/events:
    get:
      summary: Commitment events (SSE)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Event stream.
          content:
            text/event-stream:
              schema:
                type: string

  /api/commitments/{id}/history:
    get:
      summary: Commitment lifecycle history
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Paginated lifecycle events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/{id}/resolve:
    post:
      summary: Resolve commitment dispute
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Commitment resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/commitments/{id}/status:
    get:
      summary: Commitment status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current commitment status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/config/supported:
    get:
      summary: Supported configuration
      responses:
        '200':
          description: Supported config values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/login:
    options:
      summary: Login CORS preflight
      responses:
        '204':
          description: CORS preflight response.

  /api/marketplace:
    options:
      summary: Marketplace CORS preflight
      responses:
        '204':
          description: CORS preflight response.

  /api/marketplace/featured:
    get:
      summary: Featured marketplace listings
      responses:
        '200':
          description: Featured listings retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/marketplace/listings:
    get:
      summary: List marketplace listings
      responses:
        '200':
          description: Listings retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
    post:
      summary: Create marketplace listing
      responses:
        '201':
          description: Listing created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/marketplace/listings/{id}:
    delete:
      summary: Delete marketplace listing
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Listing deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/marketplace/stats:
    get:
      summary: Marketplace statistics
      responses:
        '200':
          description: Marketplace stats retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/notifications:
    get:
      summary: User notifications
      responses:
        '200':
          description: Notifications retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/protocol/constants:
    get:
      summary: Protocol constants
      responses:
        '200':
          description: Protocol constants retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/ready:
    get:
      summary: Readiness probe
      responses:
        '200':
          description: Service is ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/seed:
    post:
      summary: Seed mock data
      responses:
        '200':
          description: Data seeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'

  /api/user/preferences:
    get:
      summary: Get user preferences
      responses:
        '200':
          description: Preferences retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
    put:
      summary: Update user preferences
      responses:
        '200':
          description: Preferences updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'