zuplo 6.71.6 → 6.71.8

package/docs/articles/graphql.mdx

@@ -119,16 +119,14 @@ per API.
 
 Import `graphqlPlugin` and add an instance per API. The `path` is where the docs
 mount, and `schema` points at your GraphQL API — either a live endpoint URL or a
-path to a schema definition language (SDL) file. Define the `path` once with
-`createPath` (a helper exported from `zudoku`) and reference the same value from
-both the plugin and the navigation link, so the link can never point at a path
-the plugin isn't mounted at:
+path to a schema definition language (SDL) file. Define the `path` once as a
+const and reference the same value from both the plugin and the navigation link,
+so the link can never point at a path the plugin isn't mounted at:
 
 ```tsx title="zudoku.config.tsx"
 import { graphqlPlugin } from "@zudoku/plugin-graphql";
-import { createPath } from "zudoku";
 
-const graphqlPath = createPath("/graphql");
+const graphqlPath = "/graphql";
 
 const config = {
   navigation: [

package/docs/articles/local-development-troubleshooting.mdx

@@ -36,6 +36,16 @@ certificates, you can add the following script:
 }
 ```
 
+## "unknown format ... ignored" warnings
+
+When the development server prints warnings like
+`unknown format "date-time" ignored in schema at path "…"`, your OpenAPI schema
+uses a `format` keyword that the validator does not actively check. These
+warnings are safe to ignore — they do not stop the server or change validation
+behavior. See
+[OpenAPI Format Validation Warnings](./openapi-string-format-validation-warnings.mdx)
+for details.
+
 ## Updating the Zuplo CLI
 
 To update the CLI, run the following command in your project directory.

package/docs/articles/monetization/dynamic-metering.md

@@ -0,0 +1,105 @@
+---
+title: Dynamic Metering
+sidebar_label: Dynamic Metering
+---
+
+Most routes meter a fixed amount per request through the policy's
+[`meters`](./monetization-policy.md#meters) option. For variable-cost endpoints
+— an AI endpoint billed by tokens returned, a search billed by records matched —
+the amount isn't known until the backend responds. Set meter values from code at
+runtime with the `MonetizationInboundPolicy` static methods.
+
+## The runtime metering methods
+
+| Method                       | What it does                                                            |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `setMeters(context, meters)` | Replaces the runtime meter map, overriding matching static keys         |
+| `addMeters(context, meters)` | Adds to the runtime meter map, accumulating with static and prior calls |
+| `getMeters(context)`         | Returns the current runtime meter map                                   |
+
+Call them from a custom policy or handler. Because the values usually come from
+the response, the most common place is a custom outbound policy.
+
+```ts
+import {
+  MonetizationInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+// In a custom outbound policy, set meters based on the response
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  if (!response.ok) {
+    return response;
+  }
+
+  // Reading the body consumes it, so rebuild the response afterward
+  const body = (await response.json()) as {
+    usage?: { total_tokens?: number };
+  };
+  const tokens = body.usage?.total_tokens ?? 0;
+
+  MonetizationInboundPolicy.setMeters(context, { tokens_used: tokens });
+
+  return new Response(JSON.stringify(body), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+```
+
+Use `addMeters` to add to existing meter values rather than replacing them:
+
+```ts
+MonetizationInboundPolicy.addMeters(context, {
+  api_credits: creditsConsumed,
+});
+```
+
+Read the current runtime meter values at any point:
+
+```ts
+const meters = MonetizationInboundPolicy.getMeters(context);
+// { tokens_used: 150 }
+```
+
+## How meter values are merged
+
+The final metering hook combines static and runtime values before sending usage:
+
+- `options.meters` provides the static base values.
+- `setMeters` replaces the runtime meter map, overriding matching static keys.
+- `addMeters` accumulates into the runtime meter map, then combines additively
+  with static values.
+- When both the static and runtime maps are empty, the policy skips metering.
+
+For a meter key like `api` with `options.meters.api = 1`:
+
+- `setMeters(context, { api: 50 })` sends `api: 50` (replaces the static value).
+- `addMeters(context, { api: 50 })` sends `api: 51` (adds to the static value).
+
+The policy reports usage only for the status codes set by
+[`meterOnStatusCodes`](./monetization-policy.md#meteronstatuscodes), so a failed
+backend response costs the caller nothing.
+
+## Enforcing quotas on runtime meters
+
+Runtime meters set from an outbound policy run _after_ the response, so they
+can't block the current request on their own. To enforce a quota on a value you
+meter at runtime, declare the meter statically with a value of `0` — the policy
+checks the entitlement up front without double-counting. See
+[Block on a response-derived meter](./programmatic-monetization.md#block-on-a-response-derived-meter).
+
+## Next steps
+
+- [Programmatic Monetization](./programmatic-monetization.md) — gate operations
+  by plan and enforce quotas on runtime meters.
+- [Reading Subscription Data](./subscription-data.md) — inspect the plan and
+  entitlements in code.
+- [Monetization Policy Reference](./monetization-policy.md) — every policy
+  configuration option.
+- [Meters](./meters.mdx) — defining the meters you increment.

package/docs/articles/monetization/index.mdx

@@ -85,22 +85,25 @@ pricing, wire up Stripe, and configure your gateway to enforce quotas.
 
 ## Documentation map
 
-| Document                                                               | What it covers                                                                        |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| [Quickstart](./monetization/quickstart.md)                             | End-to-end setup in 30 minutes                                                        |
-| [Meters](./monetization/meters.mdx)                                    | How meters track usage dimensions                                                     |
-| [Features](./monetization/features.mdx)                                | Connecting meters to your product catalog                                             |
-| [Plans](./monetization/plans.mdx)                                      | Plan structure, phases, lifecycle, and publishing                                     |
-| [Rate Cards](./monetization/rate-cards.mdx)                            | Pricing and entitlements within plans                                                 |
-| [Pricing Models](./monetization/pricing-models.mdx)                    | Flat, per-unit, tiered, volume, and package pricing                                   |
-| [Billing Models Guide](./monetization/billing-models.md)               | Choosing the right pricing strategy for your business                                 |
-| [Stripe Integration](./monetization/stripe-integration.md)             | Connecting Stripe and managing payments                                               |
-| [Developer Portal Setup](./monetization/developer-portal.md)           | Configuring the self-serve portal for your customers                                  |
-| [Monetization Policy Reference](./monetization/monetization-policy.md) | Configuring the `MonetizationInboundPolicy` per-route                                 |
-| [API Access](./monetization/api-access.mdx)                            | Authentication, buckets, bucket configuration, Stripe setup APIs, and reference links |
-| [Subscription Lifecycle](./monetization/subscription-lifecycle.md)     | Managing trials, upgrades, downgrades, and cancellations                              |
-| [Private Plans](./monetization/private-plans.md)                       | Invite-only plans for specific users                                                  |
-| [Tax Collection](./monetization/tax-collection.md)                     | Enabling VAT, sales tax, or GST via Stripe Tax                                        |
-| [Going to Production](./monetization/going-to-production.mdx)          | Pre-launch checklist, Stripe live mode, and known limitations                         |
-| [Plan Examples](./monetization/plan-examples.mdx)                      | Real-world plan configurations                                                        |
-| [Troubleshooting](./monetization/troubleshooting.md)                   | Common issues, debugging, and FAQ                                                     |
+| Document                                                                 | What it covers                                                                        |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [Quickstart](./monetization/quickstart.md)                               | End-to-end setup in 30 minutes                                                        |
+| [Meters](./monetization/meters.mdx)                                      | How meters track usage dimensions                                                     |
+| [Features](./monetization/features.mdx)                                  | Connecting meters to your product catalog                                             |
+| [Plans](./monetization/plans.mdx)                                        | Plan structure, phases, lifecycle, and publishing                                     |
+| [Rate Cards](./monetization/rate-cards.mdx)                              | Pricing and entitlements within plans                                                 |
+| [Pricing Models](./monetization/pricing-models.mdx)                      | Flat, per-unit, tiered, volume, and package pricing                                   |
+| [Billing Models Guide](./monetization/billing-models.md)                 | Choosing the right pricing strategy for your business                                 |
+| [Stripe Integration](./monetization/stripe-integration.md)               | Connecting Stripe and managing payments                                               |
+| [Developer Portal Setup](./monetization/developer-portal.md)             | Configuring the self-serve portal for your customers                                  |
+| [Monetization Policy Reference](./monetization/monetization-policy.md)   | Configuring the `MonetizationInboundPolicy` per-route                                 |
+| [Subscription Data](./monetization/subscription-data.md)                 | Reading the active subscription — plan, entitlements, payment status — in code        |
+| [Dynamic Metering](./monetization/dynamic-metering.md)                   | Setting meter values at runtime with `setMeters`, `addMeters`, and `getMeters`        |
+| [Programmatic Monetization](./monetization/programmatic-monetization.md) | Gating operations by plan and metering from the response in code                      |
+| [API Access](./monetization/api-access.mdx)                              | Authentication, buckets, bucket configuration, Stripe setup APIs, and reference links |
+| [Subscription Lifecycle](./monetization/subscription-lifecycle.md)       | Managing trials, upgrades, downgrades, and cancellations                              |
+| [Private Plans](./monetization/private-plans.md)                         | Invite-only plans for specific users                                                  |
+| [Tax Collection](./monetization/tax-collection.md)                       | Enabling VAT, sales tax, or GST via Stripe Tax                                        |
+| [Going to Production](./monetization/going-to-production.mdx)            | Pre-launch checklist, Stripe live mode, and known limitations                         |
+| [Plan Examples](./monetization/plan-examples.mdx)                        | Real-world plan configurations                                                        |
+| [Troubleshooting](./monetization/troubleshooting.md)                     | Common issues, debugging, and FAQ                                                     |

package/docs/articles/monetization/meters.mdx

@@ -83,10 +83,10 @@ Track token consumption for AI applications:
 The meter aggregates events from the gateway; the per-request quantity comes
 from the `MonetizationInboundPolicy`. Set a fixed cost per request in the
 policy's `meters` option, or call
-[`MonetizationInboundPolicy.setMeters`](./monetization-policy.md#dynamic-metering)
-from a custom outbound policy to report a value derived from the response — for
-example, the actual token count an LLM returned. An event for a request that
-consumed 50 tokens looks like this:
+[`MonetizationInboundPolicy.setMeters`](./dynamic-metering.md) from a custom
+outbound policy to report a value derived from the response — for example, the
+actual token count an LLM returned. An event for a request that consumed 50
+tokens looks like this:
 
 ```json
 {

package/docs/articles/monetization/monetization-policy.md

@@ -8,6 +8,16 @@ every request to a protected route, authenticates the API key, checks the
 customer's subscription and payment status, enforces quota, meters the request,
 and allows or blocks access.
 
+:::tip
+
+Working with monetization in code? See
+[Reading Subscription Data](./subscription-data.md) to inspect the plan and
+entitlements, [Dynamic Metering](./dynamic-metering.md) to set meter values at
+runtime, and [Programmatic Monetization](./programmatic-monetization.md) to gate
+operations by plan.
+
+:::
+
 ## Basic configuration
 
 Add the policy to your `policies.json`:
@@ -68,7 +78,7 @@ If `meters` is omitted, the policy still authenticates the API key and validates
 the subscription's payment status, but no usage is recorded. If `meters` is
 provided, it must contain at least one entry — an empty object throws a
 configuration error. To track usage at runtime instead of from static config,
-see [Dynamic metering](#dynamic-metering).
+see the [Dynamic Metering](./dynamic-metering.md) guide.
 
 ```json
 // Increment the api_requests meter by 1 per request
@@ -152,6 +162,13 @@ below it:
 
 Set the value to `0` to block requests immediately when payment is overdue.
 
+:::tip
+
+Read the subscription's plan, entitlements, and payment status in your own code
+with [`getSubscriptionData`](./subscription-data.md).
+
+:::
+
 ## Multiple policies for different routes
 
 Different routes can have different metering configurations. Define multiple
@@ -210,60 +227,12 @@ Apply each to the appropriate routes:
 
 ## Dynamic metering
 
-For AI APIs and other variable-cost endpoints, you may need to meter based on
-the response — for example, counting the number of tokens returned by an LLM.
-
-Use the `setMeters` and `addMeters` static methods to set meter values
-programmatically at runtime from a custom policy or handler:
-
-```typescript
-import { MonetizationInboundPolicy } from "@zuplo/runtime";
-
-// In a custom outbound policy, set meters based on the response
-export default async function meterTokens(response, request, context) {
-  if (response.ok) {
-    const body = await response.json();
-    const tokens = body.usage?.total_tokens ?? 0;
-
-    MonetizationInboundPolicy.setMeters(context, {
-      tokens_used: tokens,
-    });
-  }
-  return response;
-}
-```
-
-You can also use `addMeters` to add to existing meter values rather than
-replacing them:
-
-```typescript
-MonetizationInboundPolicy.addMeters(context, {
-  api_credits: creditsConsumed,
-});
-```
-
-You can also read the current runtime meter values at any point:
-
-```typescript
-const meters = MonetizationInboundPolicy.getMeters(context);
-// { tokens_used: 150 }
-```
-
-### How meter values are merged
-
-The final metering hook combines static and runtime values before usage is sent:
-
-- `options.meters` provides the static base values
-- `setMeters` replaces the current runtime meter map, overriding matching static
-  keys
-- `addMeters` accumulates into the runtime meter map, then combines additively
-  with static values
-- If both static and runtime maps are empty, metering is skipped
-
-For a meter key like `api` with `options.meters.api = 1`:
-
-- `setMeters(context, { api: 50 })` sends `api: 50` (replaces static value)
-- `addMeters(context, { api: 50 })` sends `api: 51` (adds to static value)
+For variable-cost endpoints — billing by tokens returned, records processed, or
+any value computed at runtime — set meter values from code with `setMeters`,
+`addMeters`, and `getMeters` instead of static config. See the
+[Dynamic Metering](./dynamic-metering.md) guide for the full API and merge
+rules, and [Programmatic Monetization](./programmatic-monetization.md) for
+gating operations and enforcing quotas on runtime meters.
 
 ## Error responses
 
@@ -320,3 +289,12 @@ If you still want per-second or per-minute rate limiting on top of monthly
 quotas, add a standalone rate-limiting policy after the monetization policy.
 These serve different purposes: monetization enforces billing quotas, while rate
 limiting protects against traffic spikes.
+
+## Related guides
+
+- [Reading Subscription Data](./subscription-data.md) — inspect the plan,
+  entitlements, and payment status in code.
+- [Dynamic Metering](./dynamic-metering.md) — set meter values at runtime with
+  `setMeters`, `addMeters`, and `getMeters`.
+- [Programmatic Monetization](./programmatic-monetization.md) — gate operations
+  by plan and enforce quotas on response-derived meters.

package/docs/articles/monetization/programmatic-monetization.md

@@ -0,0 +1,254 @@
+---
+title: Programmatic Monetization
+sidebar_label: Programmatic Monetization
+---
+
+Pricing rules often depend on _who's_ calling or _what_ your API returns. A few
+examples:
+
+- Restrict bulk export to the Enterprise plan.
+- Offer advanced search only to plans that include it.
+- Bill an AI endpoint by the tokens it returns, and a search endpoint by the
+  rows it matches — not a flat amount per call.
+
+You can enforce rules and meter usage declaratively with
+[features and entitlements](./features.mdx) on your plans, in code with custom
+policies, or both together. This guide covers the code path, for decisions that
+need runtime logic. It shows two techniques, then combines them:
+
+- **[Gate operations by plan](#gate-operations-by-plan)** — read the caller's
+  subscription and allow or block the request based on their plan or
+  entitlements.
+- **[Meter from the response](#meter-from-the-response)** — compute usage from
+  the response body, report it, and enforce a quota on it.
+
+Both build on the [`MonetizationInboundPolicy`](./monetization-policy.md): the
+[subscription data](./subscription-data.md) it exposes and its
+[dynamic metering](./dynamic-metering.md) methods. Add that policy to your
+monetized routes first.
+
+## Gate operations by plan
+
+To make an operation available on some plans but not others, read the
+subscription in a custom code inbound policy and block the request when the plan
+doesn't qualify. Place the policy _after_ `monetization-inbound` so the
+subscription data exists on the context.
+
+```ts
+// modules/plan-gate.ts
+import {
+  MonetizationInboundPolicy,
+  HttpProblems,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+  if (!subscription) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "No active subscription",
+    });
+  }
+
+  // Bulk export is an Enterprise-only operation
+  if (subscription.plan.key !== "enterprise") {
+    return HttpProblems.forbidden(request, context, {
+      detail: "Bulk export requires the Enterprise plan",
+    });
+  }
+
+  return request;
+}
+```
+
+To gate on a specific feature instead of the whole plan, check its entitlement:
+
+```ts
+const advancedSearch = subscription.entitlements["advanced_search"];
+if (!advancedSearch?.hasAccess) {
+  return HttpProblems.forbidden(request, context, {
+    detail: "Your plan does not include advanced search",
+  });
+}
+```
+
+Register the policy and apply it after `monetization-inbound` on the routes you
+want to protect:
+
+```json
+// config/policies.json
+{
+  "name": "plan-gate",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/plan-gate)"
+  }
+}
+```
+
+```json
+// On the route
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monetization-inbound", "plan-gate"]
+    }
+  }
+}
+```
+
+## Meter from the response
+
+For variable-cost endpoints, meter a request by something you only know once the
+backend responds — the number of records returned, items processed, or tokens
+generated. Compute the value in a custom code outbound policy and report it with
+`MonetizationInboundPolicy.addMeters`.
+
+```ts
+// modules/count-records.ts
+import {
+  MonetizationInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  if (!response.ok) {
+    return response;
+  }
+
+  // Reading the body consumes it, so rebuild the response afterward
+  const data = (await response.json()) as { records: unknown[] };
+  const recordCount = data.records?.length ?? 0;
+
+  MonetizationInboundPolicy.addMeters(context, { records: recordCount });
+
+  return new Response(JSON.stringify(data), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+```
+
+`addMeters` accumulates with any static `meters` and earlier calls; use
+`setMeters` to replace the runtime value instead. The policy sends the combined
+total once the response goes out, and only for the configured status codes. See
+[Dynamic Metering](./dynamic-metering.md) for the full API and merge rules.
+
+## Block on a response-derived meter
+
+`addMeters` runs in an outbound policy — it sees the response only after the
+handler returns. By then it's too late to block the current request, and because
+the meter never appeared in the policy's static config, the inbound quota check
+never ran for it. A caller who is already over their limit still gets through.
+
+To enforce the quota, declare the meter in the policy's `meters` option with a
+value of **`0`**:
+
+```json
+// config/policies.json
+{
+  "name": "monetization-inbound",
+  "policyType": "monetization-inbound",
+  "handler": {
+    "export": "MonetizationInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "meters": { "records": 0 }
+    }
+  }
+}
+```
+
+This does two things:
+
+1. **Enforces the quota up front.** At request time the policy checks the
+   `records` entitlement and returns `403 Forbidden` when the balance has run
+   out — before the request reaches your backend.
+2. **Avoids double-counting.** The static `0` contributes nothing to the total.
+   Runtime values add to the static base (`0 + n = n`), so `addMeters` reports
+   the exact amount to bill.
+
+:::note
+
+The quota check runs at the start of each request and lets through any caller
+who still has balance; the policy charges usage after the response. So a request
+whose cost exceeds the remaining balance still completes, the balance goes
+negative, and the policy blocks the next request. An increment of `1` enforces
+the quota exactly — a caller overshoots only when a single request meters more
+than `1` against a partial balance.
+
+:::
+
+## Putting it together
+
+A complete setup for a metered, plan-gated, response-counted route:
+
+```json
+// config/policies.json
+{
+  "policies": [
+    {
+      "name": "monetization-inbound",
+      "policyType": "monetization-inbound",
+      "handler": {
+        "export": "MonetizationInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "meters": { "records": 0 }
+        }
+      }
+    },
+    {
+      "name": "plan-gate",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/plan-gate)"
+      }
+    },
+    {
+      "name": "count-records",
+      "policyType": "custom-code-outbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/count-records)"
+      }
+    }
+  ]
+}
+```
+
+```json
+// On the route
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monetization-inbound", "plan-gate"],
+      "outbound": ["count-records"]
+    }
+  }
+}
+```
+
+The request flows through the monetization policy (authenticates, checks the
+`records` quota, blocks if the quota has run out), then the plan gate (allows
+the operation only on qualifying plans), then your handler, then the outbound
+policy (counts the records and reports them with `addMeters`).
+
+## Next steps
+
+- [Reading Subscription Data](./subscription-data.md) — the full subscription
+  object you can read in code.
+- [Dynamic Metering](./dynamic-metering.md) — the full `setMeters` / `addMeters`
+  / `getMeters` API and how static and runtime values merge.
+- [Monetization Policy Reference](./monetization-policy.md) — every
+  configuration option.
+- [Meters](./meters.mdx) — defining the meters your policies increment.