naftiko: 1.0.0-alpha2
info:
  label: Shell Loyalty Program
  description: Unified Shell Go+ loyalty program workflow combining account management, points tracking, rewards catalogue,
    offer assignment, and redemption. Designed for partners integrating Shell loyalty into digital apps and services.
  tags:
  - Energy
  - Loyalty
  - Points
  - Retail
  - Rewards
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SHELL_LOYALTY_TOKEN: SHELL_LOYALTY_TOKEN
capability:
  consumes:
  - type: http
    namespace: shell-loyalty
    baseUri: https://api.shell.com/loyalty/v1
    description: Shell Go+ loyalty program API
    authentication:
      type: bearer
      token: '{{SHELL_LOYALTY_TOKEN}}'
    resources:
    - name: accounts
      path: /accounts
      description: Manage loyalty accounts
      operations:
      - name: enroll-account
        method: POST
        description: Enroll a new loyalty account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            firstName: '{{tools.first_name}}'
            lastName: '{{tools.last_name}}'
            email: '{{tools.email}}'
            countryCode: '{{tools.country_code}}'
      - name: get-account
        method: GET
        description: Get loyalty account details
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Loyalty account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-points-balance
        method: GET
        description: Get loyalty points balance for an account
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Loyalty account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: redeem-points
        method: POST
        description: Redeem loyalty points for a reward
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            rewardId: '{{tools.reward_id}}'
            pointsToRedeem: '{{tools.points_to_redeem}}'
      - name: list-loyalty-transactions
        method: GET
        description: Get loyalty transaction history for an account
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Loyalty account ID
        - name: fromDate
          in: query
          type: string
          required: false
          description: Start date filter
        - name: toDate
          in: query
          type: string
          required: false
          description: End date filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: catalogue
      path: /catalogue
      description: Browse loyalty rewards catalogue
      operations:
      - name: list-catalogue
        method: GET
        description: List available loyalty rewards
        inputParameters:
        - name: category
          in: query
          type: string
          required: false
          description: Filter by reward category
        - name: countryCode
          in: query
          type: string
          required: false
          description: Filter by country
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: offers
      path: /accounts/{accountId}/offers
      description: Manage loyalty offers
      operations:
      - name: list-offers
        method: GET
        description: List available offers for a loyalty account
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Loyalty account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8081
    namespace: shell-loyalty-program-api
    description: Unified REST API for Shell Go+ loyalty program integration.
    resources:
    - path: /v1/loyalty-accounts
      name: loyalty-accounts
      description: Manage Shell Go+ loyalty accounts
      operations:
      - method: POST
        name: enroll-member
        description: Enroll a new loyalty program member
        call: shell-loyalty.enroll-account
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/loyalty-accounts/{id}
      name: loyalty-account
      description: Access specific loyalty account
      operations:
      - method: GET
        name: get-account
        description: Get loyalty account details
        call: shell-loyalty.get-account
        with:
          accountId: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/loyalty-accounts/{id}/balance
      name: points-balance
      description: Access points balance
      operations:
      - method: GET
        name: get-balance
        description: Get current points balance
        call: shell-loyalty.get-points-balance
        with:
          accountId: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/loyalty-accounts/{id}/redeem
      name: redemption
      description: Redeem loyalty points
      operations:
      - method: POST
        name: redeem-points
        description: Redeem points for a reward
        call: shell-loyalty.redeem-points
        with:
          accountId: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/loyalty-accounts/{id}/transactions
      name: loyalty-transactions
      description: Loyalty transaction history
      operations:
      - method: GET
        name: list-transactions
        description: Get loyalty transaction history
        call: shell-loyalty.list-loyalty-transactions
        with:
          accountId: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rewards
      name: rewards
      description: Browse Shell rewards catalogue
      operations:
      - method: GET
        name: list-rewards
        description: List available rewards
        call: shell-loyalty.list-catalogue
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/loyalty-accounts/{id}/offers
      name: offers
      description: Manage loyalty offers
      operations:
      - method: GET
        name: list-offers
        description: List available offers
        call: shell-loyalty.list-offers
        with:
          accountId: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9091
    namespace: shell-loyalty-program-mcp
    transport: http
    description: MCP server for AI-assisted Shell Go+ loyalty program management.
    tools:
    - name: enroll-loyalty-member
      description: Enroll a new customer in Shell Go+ loyalty program
      hints:
        readOnly: false
      call: shell-loyalty.enroll-account
      with:
        first_name: tools.first_name
        last_name: tools.last_name
        email: tools.email
        country_code: tools.country_code
      outputParameters:
      - type: object
        mapping: $.
    - name: get-loyalty-account
      description: Retrieve Shell Go+ loyalty account profile and tier information
      hints:
        readOnly: true
      call: shell-loyalty.get-account
      with:
        accountId: tools.account_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-points-balance
      description: Get current redeemable and pending points balance for a loyalty account
      hints:
        readOnly: true
      call: shell-loyalty.get-points-balance
      with:
        accountId: tools.account_id
      outputParameters:
      - type: object
        mapping: $.
    - name: redeem-loyalty-points
      description: Redeem loyalty points for a reward from the Shell catalogue
      hints:
        readOnly: false
      call: shell-loyalty.redeem-points
      with:
        reward_id: tools.reward_id
        points_to_redeem: tools.points_to_redeem
      outputParameters:
      - type: object
        mapping: $.
    - name: list-rewards-catalogue
      description: Browse available rewards in Shell Go+ loyalty catalogue
      hints:
        readOnly: true
        openWorld: true
      call: shell-loyalty.list-catalogue
      outputParameters:
      - type: object
        mapping: $.
    - name: list-loyalty-transactions
      description: Get loyalty points earn and redeem transaction history
      hints:
        readOnly: true
      call: shell-loyalty.list-loyalty-transactions
      with:
        accountId: tools.account_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-available-offers
      description: List personalized loyalty offers available for a member account
      hints:
        readOnly: true
      call: shell-loyalty.list-offers
      with:
        accountId: tools.account_id
      outputParameters:
      - type: object
        mapping: $.