openapi: 3.1.0

info:
  title: Self Bank Agent API
  version: 1.0.0-sandbox
  description: Sandbox-first agent integration contract for selected Self Bank capabilities.

servers:
  - url: https://cube.self.team/api/agent/v1
    description: Self Bank sandbox-first public agent contract

tags:
  - name: Catalog
  - name: Simulations
  - name: Analytics

paths:
  /catalog/products:
    get:
      tags: [Catalog]
      summary: Retrieve Self Bank product and service catalog
      description: Returns product and service categories exposed for sandbox-first agent discovery.
      operationId: getProductCatalog
      security:
        - bearerAuth: [catalog.read]
      parameters:
        - in: query
          name: category
          required: false
          schema:
            type: string
          description: Optional category filter.
        - in: query
          name: clientType
          required: false
          schema:
            type: string
          description: Optional client type filter.
        - in: query
          name: country
          required: false
          schema:
            type: string
          description: Optional country filter.
      responses:
        '200':
          description: Catalog returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalogResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /simulations/onboarding:
    post:
      tags: [Simulations]
      summary: Simulate corporate onboarding flow
      description: Simulates a Self Bank onboarding flow without creating a real customer.
      operationId: simulateOnboarding
      security:
        - bearerAuth: [simulation.onboarding]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingSimulationRequest'
      responses:
        '200':
          description: Onboarding simulation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSimulationResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /simulations/payments:
    post:
      tags: [Simulations]
      summary: Simulate payment validation and routing flow
      description: Validates and simulates a payment flow in Self Bank without moving real funds.
      operationId: simulatePayment
      security:
        - bearerAuth: [simulation.payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentSimulationRequest'
      responses:
        '200':
          description: Payment simulation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSimulationResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /analytics/summary:
    post:
      tags: [Analytics]
      summary: Generate operational analytics summary
      description: Returns an aggregated sandbox analytics summary for selected operational dimensions.
      operationId: generateAnalyticsSummary
      security:
        - bearerAuth: [analytics.summary.read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsSummaryRequest'
      responses:
        '200':
          description: Analytics summary generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummaryResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /simulations/account-opening:
    post:
      tags: [Simulations]
      summary: Simulate account-opening lifecycle
      description: Simulates the lifecycle of an account-opening request in Self Bank without opening a real account.
      operationId: simulateAccountOpening
      security:
        - bearerAuth: [simulation.account_opening]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountOpeningSimulationRequest'
      responses:
        '200':
          description: Account-opening simulation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountOpeningSimulationResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Scope-limited bearer token for sandbox-first Self Bank agent access.

  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    ProductCatalogResponse:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
        status:
          type: string
        clientTypes:
          type: array
          items:
            type: string
        sandboxSupported:
          type: boolean
        requiredInputs:
          type: array
          items:
            type: string
        nextActions:
          type: array
          items:
            type: string

    OnboardingSimulationRequest:
      type: object
      required: [clientType, country, industry, requestedProducts]
      properties:
        clientType:
          type: string
        country:
          type: string
        industry:
          type: string
        requestedProducts:
          type: array
          items:
            type: string

    OnboardingSimulationResponse:
      type: object
      properties:
        simulationId:
          type: string
        status:
          type: string
        recommendedFlow:
          type: array
          items:
            type: string
        requiredDocuments:
          type: array
          items:
            type: string
        estimatedRiskLevel:
          type: string
        humanReviewRequired:
          type: boolean
        environment:
          type: string

    PaymentSimulationRequest:
      type: object
      required: [paymentType, payer, beneficiary, amount, currency, purpose]
      properties:
        paymentType:
          type: string
        payer:
          type: object
          properties:
            organizationId:
              type: string
            debitAccount:
              type: string
        beneficiary:
          type: object
          properties:
            type:
              type: string
            name:
              type: string
            tin:
              type: string
            account:
              type: string
            bic:
              type: string
        amount:
          type: number
        currency:
          type: string
        purpose:
          type: string
        priority:
          type: integer
        sandbox:
          type: boolean

    PaymentSimulationResponse:
      type: object
      properties:
        simulationId:
          type: string
        status:
          type: string
        validationResult:
          type: object
          properties:
            isValid:
              type: boolean
            errors:
              type: array
              items:
                type: string
            warnings:
              type: array
              items:
                type: string
        workflowPreview:
          type: array
          items:
            type: string
        estimatedControls:
          type: array
          items:
            type: string
        environment:
          type: string

    AnalyticsSummaryRequest:
      type: object
      properties:
        period:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
        dimensions:
          type: array
          items:
            type: string
        organizationId:
          type: string
        format:
          type: string
        sandbox:
          type: boolean

    AnalyticsSummaryResponse:
      type: object
      properties:
        summaryId:
          type: string
        status:
          type: string
        metrics:
          type: object
          additionalProperties: true
        highlights:
          type: array
          items:
            type: string
        environment:
          type: string

    AccountOpeningSimulationRequest:
      type: object
      properties:
        organizationType:
          type: string
        residency:
          type: string
        currency:
          type: string
        requestedAccountType:
          type: string
        hasFullDocumentSet:
          type: boolean

    AccountOpeningSimulationResponse:
      type: object
      properties:
        simulationId:
          type: string
        status:
          type: string
        stages:
          type: array
          items:
            type: string
        requiredChecks:
          type: array
          items:
            type: string
        humanReviewRequired:
          type: boolean
        environment:
          type: string

    ResponseMeta:
      type: object
      properties:
        environment:
          type: string
        generatedAt:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
                additionalProperties: true
            requestId:
              type: string
