Togai Usage-Based Billing

naftiko: "1.0.0-alpha1"

info:
  label: "Togai Usage-Based Billing"
  description: >-
    Unified capability for managing the full usage-based billing lifecycle with Togai.
    Covers customer onboarding, account management, usage event ingestion, price plan
    configuration, invoice generation, and credit management for SaaS and cloud products.
  tags:
    - Togai
    - Billing
    - Metering
    - Usage-Based Pricing
    - Revenue Management
    - SaaS
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TOGAI_API_TOKEN: TOGAI_API_TOKEN

capability:
  consumes:
    - import: togai
      location: ./shared/togai-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: togai-billing-api
      description: "Unified REST API for Togai usage-based billing operations."
      resources:
        - path: /v1/customers
          name: customers
          description: "Customer lifecycle management"
          operations:
            - method: GET
              name: list-customers
              description: "List all billing customers"
              call: "togai.list-customers"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-customer
              description: "Create a new billing customer"
              call: "togai.create-customer"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/customers/{customerId}
          name: customer
          description: "Individual customer operations"
          operations:
            - method: GET
              name: get-customer
              description: "Get customer details"
              call: "togai.get-customer"
              with:
                customerId: "rest.customerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/customers/{customerId}/accounts
          name: accounts
          description: "Account management"
          operations:
            - method: GET
              name: list-accounts
              description: "List accounts for a customer"
              call: "togai.list-accounts"
              with:
                customerId: "rest.customerId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-account
              description: "Create a new account"
              call: "togai.create-account"
              with:
                customerId: "rest.customerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/events
          name: events
          description: "Usage event ingestion"
          operations:
            - method: POST
              name: ingest-events
              description: "Ingest usage events for metering"
              call: "togai.ingest-events"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/price-plans
          name: price-plans
          description: "Price plan management"
          operations:
            - method: GET
              name: list-price-plans
              description: "List all price plans"
              call: "togai.list-price-plans"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-price-plan
              description: "Create a new price plan"
              call: "togai.create-price-plan"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/accounts/{accountId}/invoices
          name: invoices
          description: "Invoice management"
          operations:
            - method: GET
              name: list-invoices
              description: "List invoices for an account"
              call: "togai.list-invoices"
              with:
                accountId: "rest.accountId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/accounts/{accountId}/credits
          name: credits
          description: "Credit management"
          operations:
            - method: GET
              name: list-credits
              description: "List credits for an account"
              call: "togai.list-credits"
              with:
                accountId: "rest.accountId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: grant-credit
              description: "Grant credit to an account"
              call: "togai.grant-credit"
              with:
                accountId: "rest.accountId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: togai-billing-mcp
      transport: http
      description: "MCP server for AI-assisted usage-based billing operations with Togai."
      tools:
        - name: list-customers
          description: "List all billing customers in Togai"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.list-customers"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-customer
          description: "Create a new customer in Togai billing system"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "togai.create-customer"
          with:
            name: "tools.name"
            id: "tools.id"
            primaryEmail: "tools.primaryEmail"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-customer
          description: "Get details of a specific Togai customer"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.get-customer"
          with:
            customerId: "tools.customerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-accounts
          description: "List accounts for a Togai customer"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.list-accounts"
          with:
            customerId: "tools.customerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: ingest-events
          description: "Ingest usage events into Togai for metering and billing"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "togai.ingest-events"
          with:
            events: "tools.events"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-price-plans
          description: "List all Togai price plans"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.list-price-plans"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-price-plan
          description: "Create a new usage-based price plan in Togai"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "togai.create-price-plan"
          with:
            name: "tools.name"
            type: "tools.type"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-invoices
          description: "List invoices for a Togai account"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.list-invoices"
          with:
            accountId: "tools.accountId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: grant-credit
          description: "Grant billing credits to a Togai account"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "togai.grant-credit"
          with:
            accountId: "tools.accountId"
            creditAmount: "tools.creditAmount"
            effectiveFrom: "tools.effectiveFrom"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-usage-meters
          description: "List usage meters for a Togai event schema"
          hints:
            readOnly: true
            openWorld: false
          call: "togai.list-usage-meters"
          with:
            eventSchemaName: "tools.eventSchemaName"
          outputParameters:
            - type: object
              mapping: "$."