paths:
  /admin/exchange-rates:
    get:
      summary: List all Exchange Rate Rules
      description: |
        Returns all configured exchange rate rules. For each rule, the response includes:
        - `storedRate` — The rate saved in the database
        - `liveRate` — The real-time rate fetched from the configured provider (WeWire, Graph, etc.)
        - `effectiveRate` — The final rate merchants see after the admin's margin is applied
        
        **SuperAdmin only.**
      tags: [Admin]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of exchange rate rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExchangeRateResponse'
        '403':
          description: Forbidden - SuperAdmin only

    post:
      summary: Create an Exchange Rate Rule
      description: |
        Creates a new exchange rate rule for a currency pair.
        
        **Rate Sources:**
        - `manual` — Admin sets a fixed rate directly. The `rate` field is required.
        - `wewire` — System fetches the live rate from the WeWire API and applies the margin.
        - `graph` — System fetches the live rate from the Graph API and applies the margin.
        - `nine_psb` — Uses 9PSB as source (falls back to `rate` value as 9PSB has no public FX API).
        
        **Margin Operation:**
        - `add` — `effectiveRate = liveRate + margin` (e.g. rate=1650, margin=10 → 1660)
        - `subtract` — `effectiveRate = liveRate - margin` (e.g. rate=1650, margin=10 → 1640)
        
        **SuperAdmin only.**
      tags: [Admin]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRateCreate'
            examples:
              manual:
                summary: Manual rate (admin sets the rate)
                value:
                  baseCurrency: "NGN"
                  targetCurrency: "USD"
                  rateSource: "manual"
                  rate: 1650
                  margin: 20
                  marginOperation: "add"
              wewire_live:
                summary: Live rate from WeWire with margin
                value:
                  baseCurrency: "NGN"
                  targetCurrency: "USD"
                  rateSource: "wewire"
                  rate: 1650
                  margin: 15
                  marginOperation: "add"
      responses:
        '201':
          description: Exchange rate created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Exchange rate created successfully"
                  data:
                    $ref: '#/components/schemas/ExchangeRateResponse'
        '400':
          description: Missing required fields or duplicate currency pair
        '403':
          description: Forbidden - SuperAdmin only

  /admin/exchange-rates/preview:
    get:
      summary: Preview Live Rate from a Provider
      description: |
        Fetches and shows the current live exchange rate from a third-party provider
        **without saving anything**. Useful for the admin to check what the live market
        rate is before creating or updating a rule.
        
        **SuperAdmin only.**
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: baseCurrency
          required: true
          schema:
            type: string
            example: "NGN"
          description: The base/local currency (e.g. NGN)
        - in: query
          name: targetCurrency
          required: true
          schema:
            type: string
            example: "USD"
          description: The foreign/target currency (e.g. USD)
        - in: query
          name: rateSource
          required: true
          schema:
            type: string
            enum: [wewire, graph, nine_psb]
            example: "wewire"
          description: The third-party provider to fetch the rate from
      responses:
        '200':
          description: Live rate preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      baseCurrency:
                        type: string
                        example: "NGN"
                      targetCurrency:
                        type: string
                        example: "USD"
                      rateSource:
                        type: string
                        example: "wewire"
                      liveRate:
                        type: number
                        example: 1648.5
                      fetchedAt:
                        type: string
                        format: date-time
        '400':
          description: Missing query params or invalid rateSource (cannot preview 'manual')
        '403':
          description: Forbidden - SuperAdmin only

  /admin/exchange-rates/{id}:
    patch:
      summary: Update an Exchange Rate Rule
      description: |
        Update any field of an existing exchange rate rule. All fields are optional — only send what you want to change.
        
        If you switch to a live rateSource (wewire, graph), the system will immediately fetch
        and store the current live rate.
        
        **SuperAdmin only.**
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "e1f2a3b4-c5d6-7890-efab-cd1234567890"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRateUpdate'
            examples:
              change_margin:
                summary: Just update the margin
                value:
                  margin: 30
                  marginOperation: "add"
              switch_to_wewire:
                summary: Switch from manual to WeWire live rate
                value:
                  rateSource: "wewire"
                  margin: 10
                  marginOperation: "subtract"
              switch_to_manual:
                summary: Switch back to manual and set a new rate
                value:
                  rateSource: "manual"
                  rate: 1700
                  margin: 0
                  marginOperation: "add"
      responses:
        '200':
          description: Exchange rate updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Exchange rate updated successfully"
                  data:
                    $ref: '#/components/schemas/ExchangeRateResponse'
        '404':
          description: Exchange rate not found
        '403':
          description: Forbidden - SuperAdmin only

    delete:
      summary: Delete an Exchange Rate Rule
      description: Permanently removes an exchange rate rule. SuperAdmin only.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "e1f2a3b4-c5d6-7890-efab-cd1234567890"
      responses:
        '200':
          description: Exchange rate deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Exchange rate NGN/USD deleted successfully"
        '404':
          description: Exchange rate not found
        '403':
          description: Forbidden - SuperAdmin only

components:
  schemas:
    ExchangeRateCreate:
      type: object
      required: [baseCurrency, targetCurrency, margin, marginOperation]
      properties:
        baseCurrency:
          type: string
          example: "NGN"
          description: The base/local currency code
        targetCurrency:
          type: string
          example: "USD"
          description: The foreign/target currency code
        rateSource:
          type: string
          enum: [manual, wewire, graph, nine_psb]
          default: manual
          example: "wewire"
          description: Where the system gets the base rate from
        rate:
          type: number
          example: 1650
          description: Manual/fallback rate. Required when rateSource is "manual"
        margin:
          type: number
          example: 20
          description: The margin value to add/subtract on top of the base rate
        marginOperation:
          type: string
          enum: [add, subtract]
          example: "add"
          description: Whether to add or subtract the margin from the live/manual rate

    ExchangeRateUpdate:
      type: object
      properties:
        rateSource:
          type: string
          enum: [manual, wewire, graph, nine_psb]
          example: "wewire"
        rate:
          type: number
          example: 1700
        margin:
          type: number
          example: 15
        marginOperation:
          type: string
          enum: [add, subtract]
          example: "add"

    ExchangeRateResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "e1f2a3b4-c5d6-7890-efab-cd1234567890"
        baseCurrency:
          type: string
          example: "NGN"
        targetCurrency:
          type: string
          example: "USD"
        rateSource:
          type: string
          enum: [manual, wewire, graph, nine_psb]
          example: "wewire"
        storedRate:
          type: number
          example: 1648.5
          description: The rate last saved to the database
        liveRate:
          type: number
          example: 1651.0
          description: The real-time rate fetched from the provider (same as storedRate if source is manual)
        margin:
          type: number
          example: 20
        marginOperation:
          type: string
          enum: [add, subtract]
          example: "add"
        effectiveRate:
          type: number
          example: 1671.0
          description: The final rate merchants see (liveRate ± margin)
        updatedAt:
          type: string
          format: date-time
