apiVersion: capability.naftiko.dev/v1alpha1
kind: Capability
metadata:
  name: currency-conversion
  provider: fixer
  description: |
    Convert an arbitrary monetary amount from one currency to another using the
    Fixer real-time exchange rate, with optional fallback to a historical date.
spec:
  uses:
    - sharedCapability: fixer-shared
      operations: [convertCurrency, getLatest, getSymbols]
  preconditions:
    - description: Caller subscription must include the /convert endpoint (Basic plan or above).
  workflow:
    - step: validateSymbols
      operation: getSymbols
      purpose: Confirm both `from` and `to` ISO 4217 codes are recognized.
    - step: convertAmount
      operation: convertCurrency
      parameters:
        from: "{{ input.from }}"
        to: "{{ input.to }}"
        amount: "{{ input.amount }}"
        date: "{{ input.date | optional }}"
    - step: fallbackLatestRate
      when: convertAmount.error
      operation: getLatest
      purpose: |
        If /convert is unavailable (plan downgrade, transient failure), fall back to
        deriving a conversion locally from /latest rates anchored on the source currency.
  outputs:
    rate: "{{ convertAmount.info.rate }}"
    convertedAmount: "{{ convertAmount.result }}"
    rateTimestamp: "{{ convertAmount.info.timestamp }}"
    historical: "{{ convertAmount.historical }}"
  governance:
    minPlan: Basic
    httpsRequired: true