openapi: 3.0.1
info:
  title: Bitfinex Mock Test Control API
  version: 1.0.0
  description: |
    Test control endpoints for Bitfinex mock service.
    These endpoints allow test automation to retrieve test configuration.

    Note: These endpoints are test-only and not part of the real Bitfinex API.
    They use the `/mock/bitfinex/` prefix to clearly separate from real API endpoints.
paths:
  /mock/bitfinex/test-keys:
    get:
      tags:
        - Bitfinex Test Control
      summary: Get test API keys for Bitfinex mock
      description: |
        Retrieves test API keys for E2E tests. These keys are used by exchange-gateway tests
        to authenticate with the Bitfinex mock service.

        When `unique=false` (default): returns fixed keys from config for the predefined test partner.
        When `unique=true`: generates unique apiKey, apiSecret, and accountId per call.
      operationId: getTestKeys
      parameters:
        - in: query
          name: unique
          description: |
            If true, generates unique apiKey, apiSecret, and accountId for each call.
            Use for partner onboarding tests to avoid conflicts.
            Default: false (returns fixed keys from config).
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Test keys retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestKeysResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /mock/bitfinex/configure:
    post:
      tags:
        - Bitfinex Test Control
      summary: Configure Bitfinex mock behavior
      description: |
        Configures the Bitfinex mock behavior for testing.

        **autoExecuteOrders**: Controls whether orders are executed or cancelled.
        When false, FOK orders are cancelled and other orders set to ACTIVE.

        **apiKey** (optional): Scopes the setting to a specific Bitfinex API key.
        When absent, sets the global default and clears all per-apiKey overrides.
      operationId: configureMock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureMockRequest'
      responses:
        '200':
          description: Mock configured successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /mock/bitfinex/deposits/simulate:
    post:
      tags:
        - Bitfinex Test Control
      summary: Simulate a crypto deposit from Bitfinex
      description: |
        Simulates a crypto deposit from Bitfinex. This creates a movement entry and updates wallet balance,
        which will trigger bitfinex-gateway to detect the deposit via movements sync or WebSocket.

        This endpoint is used for E2E testing to simulate deposits without requiring actual blockchain transactions.
      operationId: simulateDeposit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateDepositRequest'
      responses:
        '200':
          description: Deposit simulated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TestKeysResponse:
      type: object
      properties:
        apiKey:
          type: string
          description: Test API key for Bitfinex mock
          example: test-api-key-mock
        apiSecret:
          type: string
          description: Test API secret for Bitfinex mock
          example: test-api-secret-mock
        accountId:
          type: string
          description: Test account ID for Bitfinex mock
          example: test-account-id-mock
      required:
        - apiKey
        - apiSecret
        - accountId
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful (always false for errors)
          example: false
        message:
          type: string
          description: Error message describing what went wrong
          example: 'Customer not found: 123'
      required:
        - success
        - message
    ConfigureMockRequest:
      type: object
      description: Request to configure Bitfinex mock behavior for testing
      properties:
        autoExecuteOrders:
          type: boolean
          description: |
            Whether orders should be auto-executed (true) or cancelled (false).
            When false, FOK orders will be cancelled, causing exchanges to fail.
            If apiKey is provided, applies only to that key. Otherwise sets global default.
        apiKey:
          type: string
          description: |
            Optional Bitfinex API key to scope the configuration.
            When provided, autoExecuteOrders applies only to orders submitted with this key.
            When absent, sets global default and clears all per-apiKey overrides.
      required: []
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful
          example: true
        message:
          type: string
          description: Human-readable message describing the result
          example: Customer approved
      required:
        - success
        - message
    SimulateDepositRequest:
      type: object
      description: Request to simulate a crypto deposit from Bitfinex
      required:
        - apiKey
        - currency
        - amount
        - depositAddress
      properties:
        apiKey:
          type: string
          description: Bitfinex API key for the account receiving the deposit
          example: test-api-key-mock
        currency:
          type: string
          description: Cryptocurrency code (e.g., "BTC", "ETH")
          example: BTC
        amount:
          type: string
          format: decimal
          description: Deposit amount
          example: '0.1'
        depositAddress:
          type: string
          description: Deposit address that received the funds
          example: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
        transactionHash:
          type: string
          description: Blockchain transaction hash (optional, will be generated if not provided)
          example: abc123def456...
        confirmations:
          type: integer
          description: Number of confirmations (optional, defaults to 10)
          example: 10
          default: 10