Stigg Pricing and Entitlements

naftiko: "1.0.0-alpha1"

info:
  label: Stigg Pricing and Entitlements
  description: >-
    Unified pricing, subscription, and entitlement management workflow for SaaS
    products. Enables engineering teams to provision customers, manage subscription
    lifecycles, enforce feature access gates, and track usage for metered billing —
    all through a single integration that allows product managers to iterate on
    pricing without additional engineering effort.
  tags:
    - FinOps
    - Pricing
    - Billing
    - Entitlements
    - Usage-Based Billing
    - SaaS
    - Subscription Management
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      STIGG_API_KEY: STIGG_API_KEY

capability:
  consumes:
    - import: stigg
      location: ./shared/stigg.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: pricing-entitlements-api
      description: >-
        Unified REST API for customer provisioning, subscription management,
        and feature entitlement enforcement.
      resources:
        - path: /v1/customers
          name: customers
          description: Customer provisioning and retrieval.
          operations:
            - method: POST
              name: provision-customer
              description: Provision a new customer in Stigg.
              call: "stigg.provision-customer"
              with:
                customerId: "rest.customerId"
                name: "rest.name"
                email: "rest.email"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/customers/{customerId}
          name: customer
          description: Individual customer operations.
          operations:
            - method: GET
              name: get-customer
              description: Retrieve customer details and active subscriptions.
              call: "stigg.get-customer"
              with:
                customerId: "rest.customerId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/subscriptions
          name: subscriptions
          description: Subscription lifecycle management.
          operations:
            - method: POST
              name: create-subscription
              description: Create a new subscription for a customer.
              call: "stigg.create-subscription"
              with:
                customerId: "rest.customerId"
                planId: "rest.planId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/subscriptions/{subscriptionId}/cancel
          name: cancel-subscription
          description: Cancel an active subscription.
          operations:
            - method: POST
              name: cancel-subscription
              description: Cancel an active subscription.
              call: "stigg.cancel-subscription"
              with:
                subscriptionId: "rest.subscriptionId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/entitlements
          name: entitlements
          description: Feature entitlement checks.
          operations:
            - method: GET
              name: check-entitlement
              description: Check if a customer can access a specific feature.
              call: "stigg.check-entitlement"
              with:
                customerId: "rest.customerId"
                featureId: "rest.featureId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/customers/{customerId}/entitlements
          name: customer-entitlements
          description: All entitlements for a customer.
          operations:
            - method: GET
              name: get-entitlements
              description: Get all feature entitlements for a customer.
              call: "stigg.get-entitlements"
              with:
                customerId: "rest.customerId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/usage
          name: usage
          description: Feature usage reporting.
          operations:
            - method: POST
              name: report-usage
              description: Report feature usage for metered billing.
              call: "stigg.report-usage"
              with:
                customerId: "rest.customerId"
                featureId: "rest.featureId"
                value: "rest.value"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: pricing-entitlements-mcp
      transport: http
      description: >-
        MCP server for AI-assisted pricing management, entitlement enforcement,
        and subscription lifecycle operations.
      tools:
        - name: provision-customer
          description: >-
            Provision a new customer in Stigg. Use when onboarding a new tenant
            or user to the SaaS product.
          hints:
            readOnly: false
          call: "stigg.provision-customer"
          with:
            customerId: "tools.customerId"
            name: "tools.name"
            email: "tools.email"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-customer
          description: >-
            Get customer details including active subscriptions and plan information.
          hints:
            readOnly: true
            idempotent: true
          call: "stigg.get-customer"
          with:
            customerId: "tools.customerId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-subscription
          description: >-
            Enroll a customer in a pricing plan by creating a subscription.
          hints:
            readOnly: false
          call: "stigg.create-subscription"
          with:
            customerId: "tools.customerId"
            planId: "tools.planId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: cancel-subscription
          description: >-
            Cancel an active customer subscription. Use for churn, downgrades,
            or account closures.
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "stigg.cancel-subscription"
          with:
            subscriptionId: "tools.subscriptionId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: check-entitlement
          description: >-
            Check whether a customer has access to a specific feature and what
            their usage limits are. Use as a feature gate before executing
            protected functionality.
          hints:
            readOnly: true
            idempotent: true
          call: "stigg.check-entitlement"
          with:
            customerId: "tools.customerId"
            featureId: "tools.featureId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-entitlements
          description: >-
            Get all feature entitlements for a customer to understand their
            full access profile across all plan features.
          hints:
            readOnly: true
            idempotent: true
          call: "stigg.get-entitlements"
          with:
            customerId: "tools.customerId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: report-usage
          description: >-
            Report measured feature usage for a customer for metered billing
            calculations. Use after each metered API call or event.
          hints:
            readOnly: false
          call: "stigg.report-usage"
          with:
            customerId: "tools.customerId"
            featureId: "tools.featureId"
            value: "tools.value"
          outputParameters:
            - type: object
              mapping: "$."