naftiko: 1.0.0-alpha2
info:
  label: Runa Rewards Distribution
  description: Workflow capability for digital reward and gift card distribution using the Runa platform. Combines product
    discovery, order management, balance monitoring, and cost estimation for B2C payment, employee incentive, customer loyalty,
    and marketing reward workflows. Serves reward program managers, growth engineers, and operations teams automating digital
    reward delivery at scale.
  tags:
  - Gift Cards
  - Rewards
  - Payments
  - Incentives
  - Payouts
  - B2C
  - Loyalty
  - Runa
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    RUNA_API_KEY: RUNA_API_KEY
capability:
  consumes:
  - type: http
    namespace: payouts-api
    baseUri: https://api.runa.io/v2
    description: Runa Payouts API for digital reward and gift card distribution
    authentication:
      type: apikey
      key: X-Api-Key
      value: '{{RUNA_API_KEY}}'
      placement: header
    resources:
    - name: orders
      path: /order
      description: Digital reward order management
      operations:
      - name: create-order
        method: POST
        description: Create a new digital reward or gift card order
        inputParameters:
        - name: payment_method
          in: body
          type: object
          required: true
          description: Payment method (type, currency)
        - name: items
          in: body
          type: array
          required: true
          description: Order items with face_value, distribution_method, and products
        - name: X-Idempotency-Key
          in: header
          type: string
          required: false
          description: Idempotency key (UUID) to prevent duplicate orders
        - name: X-Execution-Mode
          in: header
          type: string
          required: false
          description: sync or async execution mode
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-orders
        method: GET
        description: List orders for the authenticated account
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-order
        method: GET
        description: Get details for a specific order by ID
        inputParameters:
        - name: orderId
          in: path
          type: string
          required: true
          description: Order identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: estimate-order
        method: POST
        description: Estimate the cost of an order before creating it
        inputParameters:
        - name: payment_method
          in: body
          type: object
          required: true
          description: Payment method for estimation
        - name: items
          in: body
          type: array
          required: true
          description: Items to estimate
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: products
      path: /products
      description: Product catalog browsing
      operations:
      - name: list-products
        method: GET
        description: Browse available gift card and payout products
        inputParameters:
        - name: country
          in: query
          type: string
          required: false
          description: ISO country code filter
        - name: category
          in: query
          type: string
          required: false
          description: Category name filter
        - name: currency
          in: query
          type: string
          required: false
          description: Currency code filter
        - name: query
          in: query
          type: string
          required: false
          description: Search by product name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-product
        method: GET
        description: Get details for a specific product
        inputParameters:
        - name: productId
          in: path
          type: string
          required: true
          description: Product identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-categories
        method: GET
        description: List all product categories in the Runa catalog
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-countries
        method: GET
        description: List all supported countries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: balance
      path: /balance
      description: Account balance management
      operations:
      - name: get-balance
        method: GET
        description: Get account balance by currency
        inputParameters:
        - name: currency
          in: query
          type: string
          required: false
          description: ISO 4217 currency code
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: utilities
      path: /ping
      description: Connectivity and health check
      operations:
      - name: ping
        method: GET
        description: Verify API connectivity and authentication
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: rewards-distribution-api
    description: Unified REST API for Runa digital reward and gift card distribution workflows.
    resources:
    - path: /v1/catalog
      name: catalog
      description: Browse available reward products
      operations:
      - method: GET
        name: browse-catalog
        description: Browse available gift cards and payout products
        call: payouts-api.list-products
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/catalog/categories
      name: categories
      description: Product categories
      operations:
      - method: GET
        name: list-categories
        description: List product categories for catalog filtering
        call: payouts-api.list-categories
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/catalog/countries
      name: countries
      description: Supported countries
      operations:
      - method: GET
        name: list-countries
        description: List countries supported by Runa
        call: payouts-api.list-countries
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/catalog/{productId}
      name: product
      description: Product details
      operations:
      - method: GET
        name: get-product
        description: Get product denominations and redemption info
        call: payouts-api.get-product
        with:
          productId: rest.productId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rewards
      name: rewards
      description: Digital reward orders
      operations:
      - method: POST
        name: send-reward
        description: Create and send a digital reward to a recipient
        call: payouts-api.create-order
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: list-rewards
        description: List all reward orders
        call: payouts-api.list-orders
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rewards/{orderId}
      name: reward
      description: Specific reward order
      operations:
      - method: GET
        name: get-reward-status
        description: Get reward order status and payout URL
        call: payouts-api.get-order
        with:
          orderId: rest.orderId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rewards/estimate
      name: reward-estimate
      description: Estimate reward cost
      operations:
      - method: POST
        name: estimate-reward
        description: Estimate cost before sending a reward
        call: payouts-api.estimate-order
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/account/balance
      name: balance
      description: Account balance
      operations:
      - method: GET
        name: get-balance
        description: Get current account balance
        call: payouts-api.get-balance
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: rewards-distribution-mcp
    transport: http
    description: MCP server for AI-assisted digital reward and gift card distribution using Runa.
    tools:
    - name: browse-catalog
      description: Browse available gift cards and payout products in the Runa catalog
      hints:
        readOnly: true
        openWorld: true
      call: payouts-api.list-products
      with:
        country: tools.country
        category: tools.category
        query: tools.query
      outputParameters:
      - type: object
        mapping: $.
    - name: get-product-details
      description: Get denomination options and redemption instructions for a specific Runa product
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.get-product
      with:
        productId: tools.productId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-product-categories
      description: List all product categories available in the Runa catalog (e.g., Retail, Dining, Gaming)
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.list-categories
      outputParameters:
      - type: object
        mapping: $.
    - name: list-supported-countries
      description: List all countries where Runa can deliver digital rewards
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.list-countries
      outputParameters:
      - type: object
        mapping: $.
    - name: estimate-reward-cost
      description: Estimate the cost of sending a digital reward before placing the order
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.estimate-order
      with:
        payment_method: tools.paymentMethod
        items: tools.items
      outputParameters:
      - type: object
        mapping: $.
    - name: send-reward
      description: Create and send a digital reward or gift card to a recipient via Runa
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payouts-api.create-order
      with:
        payment_method: tools.paymentMethod
        items: tools.items
      outputParameters:
      - type: object
        mapping: $.
    - name: get-reward-status
      description: Check the fulfillment status of a reward order and retrieve the payout URL
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.get-order
      with:
        orderId: tools.orderId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-rewards
      description: List all digital reward orders placed with the Runa account
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.list-orders
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-balance
      description: Get the current Runa account balance to check available funds before sending rewards
      hints:
        readOnly: true
        openWorld: false
      call: payouts-api.get-balance
      with:
        currency: tools.currency
      outputParameters:
      - type: object
        mapping: $.