naftiko: 1.0.0-alpha2
info:
  label: Shopper Approved Review Management
  description: Workflow capability for managing customer reviews and ratings through Shopper Approved. Covers review collection
    via order submission, review retrieval for display, product review management, site statistics for reporting, and review
    follow-up scheduling for merchants and developers integrating Shopper Approved into their e-commerce platforms.
  tags:
  - Reviews
  - Ratings
  - Ecommerce
  - Customer Feedback
  - Social Proof
  - Google Seller Ratings
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SHOPPER_APPROVED_SITE_ID: SHOPPER_APPROVED_SITE_ID
    SHOPPER_APPROVED_TOKEN: SHOPPER_APPROVED_TOKEN
capability:
  consumes:
  - type: http
    namespace: shopper-approved
    baseUri: https://api.shopperapproved.com
    description: Shopper Approved Review Management API
    authentication:
      type: apikey
      key: token
      value: '{{env.SHOPPER_APPROVED_TOKEN}}'
      placement: query
    resources:
    - name: site-stats
      path: /aggregates/{{env.SHOPPER_APPROVED_SITE_ID}}
      description: Site review statistics and aggregate ratings
      operations:
      - name: get-site-stats
        method: GET
        description: Retrieve aggregated review statistics for the site
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: reviews
      path: /reviews/{{env.SHOPPER_APPROVED_SITE_ID}}
      description: Customer site reviews
      operations:
      - name: list-reviews
        method: GET
        description: Retrieve a list of customer reviews
        inputParameters:
        - name: from
          in: query
          type: string
          required: false
          description: Start date for reviews (YYYY-MM-DD)
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of reviews to return
        - name: page
          in: query
          type: integer
          required: false
          description: Page number for pagination
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: review-detail
      path: /reviews/{{env.SHOPPER_APPROVED_SITE_ID}}/{review_id}
      description: Specific customer review by ID
      operations:
      - name: get-review
        method: GET
        description: Retrieve a specific review by order ID
        inputParameters:
        - name: review_id
          in: path
          type: string
          required: true
          description: The order ID of the review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: review-update
      path: /reviews/{{env.SHOPPER_APPROVED_SITE_ID}}/{review_id}/update
      description: Update review follow-up details
      operations:
      - name: update-review
        method: PUT
        description: Update a review's follow-up date or cancellation status
        inputParameters:
        - name: review_id
          in: path
          type: string
          required: true
          description: The order ID of the review to update
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            followup: '{{tools.followup}}'
            cancelled: '{{tools.cancelled}}'
    - name: orders
      path: /orders/{{env.SHOPPER_APPROVED_SITE_ID}}
      description: Submit orders for review collection
      operations:
      - name: submit-order
        method: POST
        description: Submit an order to trigger a review request email
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            orderid: '{{tools.orderid}}'
            email: '{{tools.email}}'
            name: '{{tools.name}}'
            date: '{{tools.date}}'
            followup: '{{tools.followup}}'
            products: '{{tools.products}}'
    - name: product-reviews
      path: /products/{{env.SHOPPER_APPROVED_SITE_ID}}
      description: Product-specific reviews
      operations:
      - name: list-product-reviews
        method: GET
        description: Retrieve product reviews for the site
        inputParameters:
        - name: from
          in: query
          type: string
          required: false
          description: Start date for product reviews
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of reviews to return
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: shopper-approved-review-management-api
    description: Unified REST API for Shopper Approved review management workflows.
    resources:
    - path: /v1/stats
      name: stats
      description: Site review statistics for dashboards and reporting
      operations:
      - method: GET
        name: get-site-stats
        description: Get overall site rating, review count, and star distribution
        call: shopper-approved.get-site-stats
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews
      name: reviews
      description: Customer site reviews for display and analysis
      operations:
      - method: GET
        name: list-reviews
        description: List customer reviews with date range and pagination
        call: shopper-approved.list-reviews
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}
      name: review-detail
      description: Individual review management
      operations:
      - method: GET
        name: get-review
        description: Retrieve a specific customer review
        call: shopper-approved.get-review
        with:
          review_id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: update-review
        description: Reschedule or cancel a review follow-up
        call: shopper-approved.update-review
        with:
          review_id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/product-reviews
      name: product-reviews
      description: Product-specific reviews for PDP display
      operations:
      - method: GET
        name: list-product-reviews
        description: List product reviews across the catalog
        call: shopper-approved.list-product-reviews
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orders
      name: orders
      description: Order submission for review collection
      operations:
      - method: POST
        name: submit-order
        description: Submit a completed order to trigger review request
        call: shopper-approved.submit-order
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: shopper-approved-review-management-mcp
    transport: http
    description: MCP server for AI-assisted Shopper Approved review management.
    tools:
    - name: get-site-stats
      description: Get overall site review statistics including average rating and count by star level
      hints:
        readOnly: true
        openWorld: true
      call: shopper-approved.get-site-stats
      outputParameters:
      - type: object
        mapping: $.
    - name: list-reviews
      description: List customer site reviews with optional date range filtering and page navigation
      hints:
        readOnly: true
        openWorld: true
      call: shopper-approved.list-reviews
      outputParameters:
      - type: object
        mapping: $.
    - name: get-review
      description: Retrieve a specific customer review by its order ID
      hints:
        readOnly: true
        openWorld: true
      call: shopper-approved.get-review
      with:
        review_id: tools.review_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-product-reviews
      description: List product-level reviews for display on product detail pages
      hints:
        readOnly: true
        openWorld: true
      call: shopper-approved.list-product-reviews
      outputParameters:
      - type: object
        mapping: $.
    - name: submit-order
      description: Submit a completed order to trigger a review collection email at a specified follow-up date
      hints:
        readOnly: false
        destructive: false
      call: shopper-approved.submit-order
      with:
        orderid: tools.orderid
        email: tools.email
        name: tools.name
        date: tools.date
        followup: tools.followup
        products: tools.products
      outputParameters:
      - type: object
        mapping: $.
    - name: update-review
      description: Update a review's follow-up date or cancel the review request
      hints:
        readOnly: false
        idempotent: true
      call: shopper-approved.update-review
      with:
        review_id: tools.review_id
        followup: tools.followup
        cancelled: tools.cancelled
      outputParameters:
      - type: object
        mapping: $.