zuplo 6.71.7 → 6.71.9

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.

package/docs/articles/monetization/subscription-data.md

@@ -0,0 +1,153 @@
+---
+title: Reading Subscription Data
+sidebar_label: Subscription Data
+---
+
+When the `MonetizationInboundPolicy` authenticates a request, it looks up the
+caller's subscription — their plan, entitlements, payment status, and billing
+dates — and stores it on the request context. Read that data from your own code
+with the static `MonetizationInboundPolicy.getSubscriptionData` method to make
+decisions, personalize responses, or log which plan a request ran on.
+
+## Where you can call it
+
+`getSubscriptionData` returns data that the monetization policy puts on the
+context, so it only returns a value **after** the `monetization-inbound` policy
+has run. Call it from:
+
+- A **custom code inbound policy** placed _after_ `monetization-inbound` in the
+  route's inbound pipeline.
+- The **route handler**, which always runs after inbound policies.
+
+On a route without the monetization policy — or in a policy that runs before it
+— the method returns `undefined`. Always handle that case.
+
+:::note
+
+The `monetization-inbound` policy must come before any policy that reads the
+subscription. If your policy runs first, the subscription data isn't on the
+context yet. See
+[pipeline ordering](./monetization-policy.md#pipeline-ordering).
+
+:::
+
+## Basic usage
+
+```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",
+    });
+  }
+
+  context.log.info(`Request on plan: ${subscription.plan.key}`);
+  return request;
+}
+```
+
+## The subscription object
+
+`getSubscriptionData` returns a `MonetizationSubscription`. The fields you reach
+for most are the plan and the entitlements map:
+
+```ts
+interface MonetizationSubscription {
+  id: string;
+  customerId: string;
+  name: string;
+  status: string;
+  currency: string;
+
+  plan: {
+    id: string;
+    name: string;
+    key: string; // Stable identifier — switch on this in code
+    version: number;
+    description?: string;
+  };
+
+  // Keyed by meter or feature key
+  entitlements: Record<
+    string,
+    {
+      balance: number; // Remaining allowance this period
+      hasAccess: boolean; // false when no access or quota spent
+      overage: number; // Usage beyond the included allowance
+      usage: number; // Consumed this period
+    }
+  >;
+
+  paymentStatus?: {
+    status: "paid" | "not_required" | "pending" | "failed" | "uncollectible";
+    isFirstPayment: boolean;
+    lastPaymentFailedAt?: string;
+    lastPaymentSucceededAt?: string;
+  };
+
+  billingCadence: string; // ISO 8601 duration, e.g. "P1M" for monthly
+  billingAnchor: string;
+  nextBillingDate: string;
+  activeFrom: string;
+  activeTo?: string;
+
+  maxPaymentOverdueDays: number;
+  accessBlocked?: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+Switch on `plan.key` rather than `plan.name` in your logic — the key is a stable
+identifier, while the name is a display label that can change.
+
+## Reading entitlements
+
+Each entry in `entitlements` describes one metered feature or static feature on
+the subscription. The key is the meter or feature key; the value reports the
+caller's standing against it:
+
+```ts
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+const apiCalls = subscription?.entitlements["api_requests"];
+if (apiCalls) {
+  context.log.info(
+    `api_requests — used ${apiCalls.usage}, ${apiCalls.balance} remaining`,
+  );
+}
+```
+
+- `hasAccess` is the quickest check for "can this caller use this feature" —
+  it's `false` when the plan doesn't include the feature or the quota has run
+  out.
+- `balance` is the remaining allowance. A balance of `0` or less means no
+  allowance remains.
+- `usage` and `overage` report consumption this billing period.
+
+## Caveats
+
+- **Returns `undefined`** when the monetization policy hasn't run. Guard every
+  call.
+- **The policy caches the data.** Subscription and entitlement data is cached
+  for up to `cacheTtlSeconds` (60 seconds minimum), so `balance`, `usage`, and
+  `overage` can lag real-time consumption by the length of the cache window.
+  Treat them as recent, not exact.
+
+## Next steps
+
+- [Programmatic Monetization](./programmatic-monetization.md) — gate operations
+  by plan and meter requests based on the response.
+- [Dynamic Metering](./dynamic-metering.md) — set meter values at runtime from
+  code.
+- [Monetization Policy Reference](./monetization-policy.md) — every policy
+  configuration option.

package/docs/articles/openapi-string-format-validation-warnings.mdx

@@ -0,0 +1,142 @@
+---
+title: OpenAPI Format Validation Warnings in Local Development
+sidebar_label: Format Validation Warnings
+description:
+  Understand the "unknown format ... ignored" warnings the Zuplo CLI prints
+  during local development, why they appear, and why they are safe to ignore.
+tags:
+  - openapi
+  - local-development
+  - validation
+---
+
+When you run a Zuplo project locally with `npm run dev` (or `zuplo dev`), the
+console may print one or more warnings like this:
+
+```text
+unknown format "date-time" ignored in schema at path "#/properties/createdAt"
+```
+
+These warnings are informational. They do not stop the development server, fail
+schema validation, or change how your gateway behaves once deployed. This page
+explains what the warning means and what, if anything, to do about it.
+
+:::tip
+
+**Short answer: the warnings are safe to ignore.** They report that a `format`
+keyword in your OpenAPI document is not being actively checked — the field is
+still validated against its `type` and every other constraint you defined.
+
+:::
+
+## What the warning means
+
+Zuplo validates requests against your OpenAPI schema using
+[Ajv](https://ajv.js.org/), a standard JSON Schema validator. In JSON Schema and
+OpenAPI, the
+[`format` keyword](https://json-schema.org/understanding-json-schema/reference/string#format)
+(for example `date-time`, `email`, or `uuid`) is an _annotation_. A validator
+only enforces a format if it has a validator registered for that specific
+format. For any format it does not recognize, the standard behavior is to skip
+the format check and log a message like the one above.
+
+When you see `unknown format "date-time" ignored in schema at path "…"`, it
+means:
+
+- The validator found a `format: "date-time"` (or similar) in your schema.
+- It has no registered check for that format in local development, so it
+  **ignores the format** and moves on.
+- The field is **still validated** against its `type` and any other keywords you
+  set, such as `pattern`, `enum`, `minimum`, `maxLength`, or `required`.
+
+The `path` in the message (for example `#/properties/createdAt`, or a path or
+query parameter location) points to where the format appears in the schema, so
+you can locate it.
+
+## Are the warnings safe to ignore?
+
+Yes. The warning is purely informational. It does **not**:
+
+- Stop or crash the local development server.
+- Cause a build or deployment to fail.
+- Reject any request, or change the response your API returns.
+- Change validation behavior in deployed environments.
+
+Type checking and every other constraint in your schema continue to work exactly
+as written. An enforced `format` validates the _shape_ of a value — for example,
+that a string looks like an RFC 3339 date-time. When a format is ignored, you
+lose only that one extra check; the field's `type` and all other constraints are
+unaffected.
+
+## Why some formats warn and others don't
+
+You may notice the warning for some formats but not others, and on some fields
+but not others. A few things drive this:
+
+- **`format` is advisory in JSON Schema.** Validators are free to enforce only
+  the formats they choose to register. Which formats are actively checked is an
+  internal detail of the validator and can differ between CLI versions, so treat
+  the set as subject to change rather than a fixed contract.
+- **Path and query parameters are validated separately from request bodies.**
+  Parameter schemas and body schemas are generally compiled independently, so
+  the same `format` can produce a warning in one place but not the other.
+
+Because the warning is harmless, you do not need to determine exactly which
+formats are checked. The guidance below applies to any format that warns.
+
+## How to remove the warnings
+
+You have two options, depending on whether you rely on that format for
+validation.
+
+**Option 1 — Leave the `format` keyword in place (recommended).** Keeping
+`format` annotations is good practice: they document intent, drive code
+generation and the developer portal, and are useful to consumers of your API
+even when the gateway does not enforce them. The warning is the only cost, and
+it is cosmetic.
+
+**Option 2 — Enforce the value with a constraint that _is_ checked.** If you
+want the gateway to actively reject malformed values, replace or supplement the
+`format` with explicit constraints that the validator always enforces, such as
+`pattern`, `enum`, `minLength`/`maxLength`, or `minimum`/`maximum`. For example,
+to enforce a date-time-like string with a regular expression instead of relying
+on `format`:
+
+```json
+{
+  "createdAt": {
+    "type": "string",
+    "format": "date-time",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+  }
+}
+```
+
+Here `format` stays for documentation, and `pattern` does the actual
+enforcement. The regular expression above is an illustrative RFC 3339-style
+example, not a Zuplo-mandated pattern — adjust it to match the values you
+expect. The warning may still appear for the ignored `format`, but the value is
+now strictly validated.
+
+:::caution
+
+The [Request Validation policy](../policies/request-validation-inbound.mdx)
+options control _what_ is validated (`validateBody`, `validateQueryParameters`,
+`validatePathParameters`, `validateHeaders`) and how failures are handled, but
+they do not let you register additional formats or silence individual format
+warnings. To guarantee a value's shape, use enforced constraints like `pattern`
+as shown above.
+
+:::
+
+## Related
+
+- [Request Validation Policy](../policies/request-validation-inbound.mdx) —
+  validate request bodies, query parameters, path parameters, and headers
+  against your OpenAPI schema.
+- [Schema Validation Failed (SCHEMA_VALIDATION_FAILED)](../errors/schema-validation-failed.mdx)
+  — the runtime error returned when a request does not pass schema validation.
+- [OpenAPI Support in Zuplo](./openapi.mdx) — how Zuplo uses your OpenAPI
+  document to configure the gateway.
+- [Local Development](./local-development.mdx) — run and test your gateway
+  locally with the Zuplo CLI.

package/docs/articles/troubleshooting-deployments-and-git-sync.mdx

@@ -0,0 +1,222 @@
+---
+title: Troubleshooting Stuck Deployments and Git Sync Errors
+sidebar_label: Troubleshooting Deployments
+description:
+  Diagnose Zuplo deployments that hang at "Deploying api" or "Building Developer
+  Portal" and fix Git source-control sync errors such as Bitbucket 410 Gone
+  responses on branch retrieval.
+---
+
+When a deploy seems to hang at `Deploying api…` or `Building Developer Portal…`,
+or your Git provider stops returning branches with a `Bad Request` or `410 Gone`
+error, the cause is usually one of a few known issues. This guide helps you tell
+a genuinely stuck deploy from a slow-but-progressing one, fix Git source-control
+sync failures, and gather the right details before contacting support.
+
+## How a Zuplo deploy progresses
+
+Every deploy, whether triggered by a Git push, the Zuplo CLI, or a save in the
+Portal, runs through two stages in order:
+
+1. **`Deploying api…`**: Zuplo builds your gateway configuration (routes,
+   policies, and modules) and rolls it out to the edge.
+2. **`Building Developer Portal…`**: Zuplo builds the Developer Portal site from
+   your OpenAPI document and portal configuration.
+
+Each stage produces its own build logs. Zuplo separates logs by stage: `api` for
+the gateway build and `dev-portal` for the Developer Portal build. Knowing which
+stage a deploy stalled in tells you where to look.
+
+:::note
+
+A deploy can finish the `api` stage successfully and still be working on the
+`dev-portal` stage. If your gateway is already serving traffic but the deploy
+status hasn't flipped to complete, the Developer Portal build is the most likely
+place it's still working. See
+[The Developer Portal build never finishes](#the-developer-portal-build-never-finishes).
+
+:::
+
+## Is the deploy stuck, or still working?
+
+A deploy that looks frozen in the terminal is often still running on Zuplo's
+side. The Zuplo CLI doesn't run the build itself. It starts the deploy and then
+_polls_ for the result. The build continues on the server even if the CLI stops
+waiting.
+
+### Confirm the server-side status first
+
+Before assuming a deploy failed, check whether it actually completed:
+
+1. Open your [project](https://portal.zuplo.com/+/account/project/) in the Zuplo
+   Portal.
+2. Check the environment you deployed to. If the build finished, the environment
+   shows the new deployment and its URL responds to requests.
+3. Send a request to the environment URL (or its
+   [health check route](./health-checks.mdx), if you have one) to confirm the
+   gateway is live.
+
+If the environment is updated and serving traffic, the deploy succeeded. The CLI
+simply stopped waiting before the build reported back.
+
+:::tip
+
+The CLI prints `Deployed to https://...` on success. If you never saw that line
+but the Portal shows the environment updated, the deploy completed after the CLI
+timed out. Capture the URL from the Portal rather than constructing it from the
+branch name. The hostname uses a normalized, truncated form of the environment
+name plus a unique identifier.
+
+:::
+
+### Extend the CLI polling timeout
+
+By default the CLI polls every second for up to 250 attempts, a little over four
+minutes. Large projects can take longer to build, and when the CLI's poll budget
+runs out it stops waiting even though the deploy keeps running on the server.
+
+Increase the timeout with the `POLL_INTERVAL` and `MAX_POLL_RETRIES` environment
+variables:
+
+```bash
+# Poll every 5 seconds for up to 300 attempts (25 minutes)
+POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy
+```
+
+- **`POLL_INTERVAL`**: Milliseconds between polls. Default `1000` (1 second).
+- **`MAX_POLL_RETRIES`**: Maximum number of polls before the CLI times out.
+  Default `250`.
+
+For the full command reference, see [CLI: deploy](../cli/deploy.mdx).
+
+:::caution
+
+Raising the polling timeout only changes how long the CLI _waits_. It does not
+make the build faster, and it does not fix a build that is genuinely failing. If
+the deploy never completes server-side no matter how long you wait, treat it as
+a failed build and read the logs for the stage that stalled.
+
+:::
+
+## The Developer Portal build never finishes
+
+If the gateway (`api` stage) deploys but the overall deploy hangs at
+`Building Developer Portal…`, the problem is in the Developer Portal build, not
+your routes or policies.
+
+Common causes:
+
+- **Invalid OpenAPI document**: The portal is generated from your OpenAPI
+  document. A malformed `routes.oas.json`, an unresolved `$ref`, or invalid
+  schema can stall or fail the portal build. Validate your OpenAPI document and
+  fix any errors.
+- **A legacy `config/dev-portal.json` file**: Projects migrated from the old
+  Developer Portal can carry a stale `config/dev-portal.json` that breaks the
+  build. See the [Dev Portal Migration Guide](../dev-portal/migration.mdx) for
+  the exact cleanup steps.
+- **Custom portal configuration errors**: Errors in your `zudoku.config.tsx` (or
+  other portal configuration) can prevent the site from building.
+
+Read the `dev-portal` stage build logs to see the specific error, then redeploy
+after fixing it.
+
+## Git source-control sync errors
+
+Zuplo connects to GitHub, GitLab, Bitbucket, and Azure DevOps for source
+control. The integration pushes and pulls code between the Portal and your
+repository, and it lists branches so you can map them to environments. When that
+authorization breaks, branch retrieval fails, often with a `Bad Request` or
+`410 Gone` error.
+
+### Why branch retrieval returns `Bad Request` or `410 Gone`
+
+These errors come from the Git provider, not from Zuplo, and they almost always
+mean the connection is no longer authorized:
+
+- The OAuth authorization Zuplo uses to reach the provider has **expired or been
+  revoked**.
+- The repository was **renamed or moved**, which breaks the existing connection.
+- The Git app was **uninstalled** or lost access to the repository in the
+  provider's settings.
+
+`410 Gone` in particular signals that the resource Zuplo asked for (the branch
+list) is no longer available at that location, typically because the
+authorization or repository link behind it is stale.
+
+### Reconnect the integration
+
+To restore branch sync, re-authorize the connection:
+
+1. Open your
+   [project settings](https://portal.zuplo.com/+/account/project/settings/general)
+   in the Zuplo Portal and select **Source Control**.
+2. Disconnect the current repository connection.
+3. Reconnect and complete the provider's authorization flow again, granting
+   access to the repository that holds your Zuplo project.
+
+After reconnecting, retrieving branches should succeed again.
+
+:::caution
+
+Renaming a repository breaks the Zuplo connection. If you renamed or moved the
+repository, disconnect and reconnect to restore the link. See
+[Rename or Move Project](./rename-or-move-project.mdx) for details.
+
+:::
+
+### Bitbucket-specific notes
+
+Bitbucket integration is available on
+[enterprise plans](https://zuplo.com/pricing) and provides push/pull source
+control without automatic deployments. You deploy with the Zuplo CLI through
+[Bitbucket Pipelines](./custom-ci-cd-bitbucket.mdx).
+
+If reconnecting from the Portal doesn't clear the sync error:
+
+- **Confirm Bitbucket is still enabled for your account.** For
+  [bitbucket.org](https://bitbucket.org), Zuplo support enables the integration.
+  Contact [support@zuplo.com](mailto:support@zuplo.com) with your Bitbucket
+  Workspace ID (found on your Workspace Settings page).
+- **For self-hosted Bitbucket, check the OAuth app.** If the OAuth app's client
+  secret was rotated or its callback URL or permissions changed, branch
+  retrieval fails until the app is reconfigured. The callback URL must be
+  `https://portal.zuplo.com` and the app must grant the `repo`, `user`, and
+  `read:org` permissions. See
+  [Bitbucket Setup](./source-control-setup-bitbucket.mdx).
+
+## Decision tree
+
+Use this to route yourself to the right fix:
+
+| Symptom                                              | Most likely cause                               | First action                                                                                   |
+| ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| CLI hangs at `Deploying api…` then times out         | Build took longer than the CLI's poll budget    | Check the environment in the Portal; raise `MAX_POLL_RETRIES`                                  |
+| CLI reported timeout, but the environment is updated | Deploy completed after the CLI stopped waiting  | None; capture the URL from the Portal                                                          |
+| Deploy hangs at `Building Developer Portal…`         | Developer Portal build error                    | Read the `dev-portal` build logs; validate OpenAPI; check for a stale `config/dev-portal.json` |
+| Branch list fails with `Bad Request` or `410 Gone`   | Git authorization expired, revoked, or stale    | Reconnect the integration in **Source Control** settings                                       |
+| Bitbucket still fails after reconnecting             | Account not enabled, or OAuth app misconfigured | Contact support with your Workspace ID; check the self-hosted OAuth app                        |
+
+## When to contact support
+
+If you've worked through the relevant section above and the deploy or sync still
+fails, contact [support@zuplo.com](mailto:support@zuplo.com). Include these
+details so support can investigate without a round-trip:
+
+- Your **account** and **project** names.
+- The **environment** (branch) you're deploying to.
+- The **stage** where it stalls (`api` or `dev-portal`) and the exact message
+  you see.
+- For sync errors: your **Git provider**, the **repository**, and the exact
+  error text (for example, `410 Gone` on branch retrieval).
+- The **approximate time** of the failed deploy, in UTC.
+
+## Next steps
+
+- [Source Control & Deployments](./source-control.mdx): how source control and
+  deployments fit together across providers.
+- [Branch-Based Deployments](./branch-based-deployments.mdx): how branches map
+  to environments and how environment URLs are named.
+- [Deploying Zuplo from a Monorepo](./monorepo-deployment.mdx): CI/CD
+  configuration, schema validation, and health-check timeouts.
+- [Troubleshooting (local development)](./local-development-troubleshooting.mdx):
+  local dev server, ports, and certificate issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.7",
+  "version": "6.71.9",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.7",
-    "@zuplo/core": "6.71.7",
-    "@zuplo/runtime": "6.71.7",
+    "@zuplo/cli": "6.71.9",
+    "@zuplo/core": "6.71.9",
+    "@zuplo/runtime": "6.71.9",
     "@zuplo/test": "1.4.0"
   }
 }