@1claw/openapi-spec 0.16.1 → 0.16.3

package/README.md

@@ -42,8 +42,9 @@ import spec from "@1claw/openapi-spec/openapi.json";
 
 ## What's in the spec (v0.16.x)
 
+- **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings.
 - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
-- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing`, `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
+- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
 - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag

package/openapi.json

@@ -153,6 +153,7 @@
           "Authentication"
         ],
         "summary": "Exchange agent credentials for JWT",
+        "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n",
         "operationId": "agentToken",
         "security": [],
         "requestBody": {
@@ -2893,7 +2894,7 @@
         ],
         "summary": "Get LLM token billing status",
         "operationId": "getLlmTokenBilling",
-        "description": "Returns whether LLM token billing is enabled for the caller's org.",
+        "description": "Returns whether LLM token billing is enabled, optional Stripe billing credit balance (metered scope), and estimated cycle usage from the upcoming invoice—including per-line metered rows when Stripe returns them (amounts; quantities such as tokens when present).\n",
         "responses": {
           "200": {
             "description": "LLM token billing status",
@@ -6777,8 +6778,83 @@
           }
         }
       },
+      "LlmMeteredInvoiceLine": {
+        "type": "object",
+        "description": "Metered line from Stripe upcoming invoice (usage detail when available).",
+        "properties": {
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "amount_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "quantity": {
+            "type": "number",
+            "nullable": true,
+            "description": "Billed usage units when Stripe returns quantity (e.g. tokens)."
+          },
+          "price_nickname": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "LlmBillingCycleUsage": {
+        "type": "object",
+        "description": "Accrued LLM charges for the current Stripe subscription period (upcoming invoice).",
+        "properties": {
+          "period_start": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "period_end": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "accrued_usage_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "metered_lines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/LlmMeteredInvoiceLine"
+            }
+          }
+        }
+      },
+      "LlmCreditBalance": {
+        "type": "object",
+        "properties": {
+          "available_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "ledger_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "used_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          }
+        }
+      },
       "LlmTokenBillingStatus": {
         "type": "object",
+        "required": [
+          "enabled"
+        ],
         "properties": {
           "enabled": {
             "type": "boolean"
@@ -6789,6 +6865,12 @@
               "active",
               "inactive"
             ]
+          },
+          "credit_balance": {
+            "$ref": "#/components/schemas/LlmCreditBalance"
+          },
+          "billing_cycle_usage": {
+            "$ref": "#/components/schemas/LlmBillingCycleUsage"
           }
         }
       },

package/openapi.yaml

@@ -105,6 +105,19 @@ paths:
         post:
             tags: [Authentication]
             summary: Exchange agent credentials for JWT
+            description: |
+                Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`
+                (`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional
+                `shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.
+
+                When **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object
+                mirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).
+                **Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the
+                global inspection pipeline so per-agent limits and threat **block** actions apply without a
+                separate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT
+                is fresh.
+
+                User JWTs from password, API key, or device flow do **not** include `shroud_config`.
             operationId: agentToken
             security: []
             requestBody:
@@ -1854,7 +1867,10 @@ paths:
             tags: [Billing]
             summary: Get LLM token billing status
             operationId: getLlmTokenBilling
-            description: Returns whether LLM token billing is enabled for the caller's org.
+            description: >
+                Returns whether LLM token billing is enabled, optional Stripe billing credit balance
+                (metered scope), and estimated cycle usage from the upcoming invoice—including per-line
+                metered rows when Stripe returns them (amounts; quantities such as tokens when present).
             responses:
                 "200":
                     description: LLM token billing status
@@ -4487,14 +4503,74 @@ components:
                 limit:
                     type: integer
 
+        LlmMeteredInvoiceLine:
+            type: object
+            description: Metered line from Stripe upcoming invoice (usage detail when available).
+            properties:
+                description:
+                    type: string
+                    nullable: true
+                amount_cents:
+                    type: integer
+                    format: int64
+                quantity:
+                    type: number
+                    nullable: true
+                    description: Billed usage units when Stripe returns quantity (e.g. tokens).
+                price_nickname:
+                    type: string
+                    nullable: true
+
+        LlmBillingCycleUsage:
+            type: object
+            description: Accrued LLM charges for the current Stripe subscription period (upcoming invoice).
+            properties:
+                period_start:
+                    type: string
+                    format: date-time
+                    nullable: true
+                period_end:
+                    type: string
+                    format: date-time
+                    nullable: true
+                accrued_usage_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+                metered_lines:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/LlmMeteredInvoiceLine"
+
+        LlmCreditBalance:
+            type: object
+            properties:
+                available_cents:
+                    type: integer
+                    format: int64
+                ledger_cents:
+                    type: integer
+                    format: int64
+                used_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+
         LlmTokenBillingStatus:
             type: object
+            required: [enabled]
             properties:
                 enabled:
                     type: boolean
                 subscription_status:
                     type: string
                     enum: [active, inactive]
+                credit_balance:
+                    $ref: "#/components/schemas/LlmCreditBalance"
+                billing_cycle_usage:
+                    $ref: "#/components/schemas/LlmBillingCycleUsage"
 
         LlmCheckoutResponse:
             type: object

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@1claw/openapi-spec",
-    "version": "0.16.1",
+    "version": "0.16.3",
     "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
     "license": "MIT",
     "repository": {