Reloadly Digital Rewards

naftiko: "1.0.0-alpha1"

info:
  label: Reloadly Digital Rewards
  description: >-
    Unified workflow capability combining Reloadly Gift Cards and Airtime APIs
    for building digital rewards, loyalty programs, and employee incentive
    platforms. Enables program managers and marketing teams to discover
    reward options, check costs, place orders, and track fulfillment across
    both gift cards and mobile top-ups from a single integration.
  tags:
    - Reloadly
    - Digital Rewards
    - Gift Cards
    - Airtime
    - Loyalty
    - Incentives
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      RELOADLY_CLIENT_ID: RELOADLY_CLIENT_ID
      RELOADLY_CLIENT_SECRET: RELOADLY_CLIENT_SECRET

capability:
  consumes:
    - import: reloadly-gift-cards
      location: ./shared/gift-cards.yaml
    - import: reloadly-airtime
      location: ./shared/airtime.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: reloadly-rewards-api
      description: "Unified REST API for digital rewards program management."
      resources:
        - path: /v1/gift-cards
          name: gift-cards
          description: Gift card product catalog
          operations:
            - method: GET
              name: list-gift-cards
              description: List available gift card products
              call: "reloadly-gift-cards.list-products"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/gift-cards/{productId}
          name: gift-card
          description: Individual gift card product
          operations:
            - method: GET
              name: get-gift-card
              description: Get gift card product details
              call: "reloadly-gift-cards.get-product"
              with:
                productId: "rest.productId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/discounts
          name: discounts
          description: Available discount rates on gift cards
          operations:
            - method: GET
              name: list-discounts
              description: List gift card discount rates
              call: "reloadly-gift-cards.list-discounts"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders
          name: orders
          description: Gift card orders
          operations:
            - method: POST
              name: place-gift-card-order
              description: Place a gift card reward order
              call: "reloadly-gift-cards.place-order"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders/{orderId}
          name: order
          description: Individual gift card order
          operations:
            - method: GET
              name: get-order
              description: Get gift card order and codes
              call: "reloadly-gift-cards.get-order"
              with:
                orderId: "rest.orderId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/operators
          name: operators
          description: Mobile network operators for airtime
          operations:
            - method: GET
              name: list-operators
              description: List mobile network operators
              call: "reloadly-airtime.list-operators"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/topups
          name: topups
          description: Airtime top-up orders
          operations:
            - method: POST
              name: send-topup
              description: Send airtime top-up reward
              call: "reloadly-airtime.send-topup"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/transactions
          name: transactions
          description: All reward transactions
          operations:
            - method: GET
              name: list-gift-card-transactions
              description: List gift card transactions
              call: "reloadly-gift-cards.list-transactions"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/airtime-transactions
          name: airtime-transactions
          description: Airtime top-up transactions
          operations:
            - method: GET
              name: list-airtime-transactions
              description: List airtime transactions
              call: "reloadly-airtime.list-topup-transactions"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/balance
          name: balance
          description: Account balances
          operations:
            - method: GET
              name: get-gift-card-balance
              description: Get gift card account balance
              call: "reloadly-gift-cards.get-balance"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: reloadly-rewards-mcp
      transport: http
      description: "MCP server for AI-assisted digital rewards program management."
      tools:
        - name: list-gift-card-products
          description: Browse the gift card product catalog filtered by country and currency
          hints:
            readOnly: true
            openWorld: true
          call: "reloadly-gift-cards.list-products"
          with:
            countryCode: "tools.countryCode"
            currencyCode: "tools.currencyCode"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-gift-card-product
          description: Get details for a specific gift card product including denominations
          hints:
            readOnly: true
            openWorld: true
          call: "reloadly-gift-cards.get-product"
          with:
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-gift-card-discounts
          description: List discount rates available on gift card products
          hints:
            readOnly: true
            openWorld: true
          call: "reloadly-gift-cards.list-discounts"
          outputParameters:
            - type: object
              mapping: "$."
        - name: place-gift-card-order
          description: Order a digital gift card reward for a recipient
          hints:
            readOnly: false
            destructive: false
          call: "reloadly-gift-cards.place-order"
          with:
            productId: "tools.productId"
            quantity: "tools.quantity"
            unitPrice: "tools.unitPrice"
            senderName: "tools.senderName"
            recipientEmail: "tools.recipientEmail"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-gift-card-order
          description: Retrieve gift card order details and redemption codes
          hints:
            readOnly: true
            openWorld: false
          call: "reloadly-gift-cards.get-order"
          with:
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-operators
          description: Browse mobile network operators for airtime top-ups by country
          hints:
            readOnly: true
            openWorld: true
          call: "reloadly-airtime.list-operators"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."
        - name: auto-detect-operator
          description: Automatically identify the mobile operator for a phone number
          hints:
            readOnly: true
            openWorld: true
          call: "reloadly-airtime.auto-detect-operator"
          with:
            phone: "tools.phone"
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."
        - name: send-airtime-topup
          description: Send a mobile airtime top-up reward to a phone number
          hints:
            readOnly: false
            destructive: false
          call: "reloadly-airtime.send-topup"
          with:
            operatorId: "tools.operatorId"
            amount: "tools.amount"
            useLocalAmount: "tools.useLocalAmount"
            customIdentifier: "tools.customIdentifier"
            recipientPhone: "tools.recipientPhone"
            senderPhone: "tools.senderPhone"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-gift-card-transactions
          description: List gift card order transaction history
          hints:
            readOnly: true
            openWorld: false
          call: "reloadly-gift-cards.list-transactions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-airtime-transactions
          description: List airtime top-up transaction history
          hints:
            readOnly: true
            openWorld: false
          call: "reloadly-airtime.list-topup-transactions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-account-balance
          description: Check the current account balance for gift card purchases
          hints:
            readOnly: true
            openWorld: false
          call: "reloadly-gift-cards.get-balance"
          outputParameters:
            - type: object
              mapping: "$."