zuplo 6.67.32 → 6.68.0

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

@@ -0,0 +1,314 @@
+---
+title: Monetization Policy Reference
+sidebar_label: Monetization Policy
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+The `MonetizationInboundPolicy` is the gateway enforcement mechanism. It runs on
+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.
+
+## Basic configuration
+
+Add the policy to your `policies.json`:
+
+```json
+{
+  "name": "monetization-inbound",
+  "policyType": "monetization-inbound",
+  "handler": {
+    "export": "MonetizationInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "meters": {
+        "api_requests": 1
+      }
+    }
+  }
+}
+```
+
+Then reference it in your route's inbound policy pipeline:
+
+```json
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monetization-inbound"]
+    }
+  }
+}
+```
+
+:::note
+
+The `MonetizationInboundPolicy` handles API key authentication internally. It
+reads the API key from the `Authorization` header, validates it, and sets
+`request.user`. You do not need a separate `api-key-auth` policy on monetized
+routes — the monetization policy replaces it.
+
+:::
+
+## Configuration options
+
+| Option               | Type               | Default           | Description                                       |
+| -------------------- | ------------------ | ----------------- | ------------------------------------------------- |
+| `meters`             | object             | (required)        | Map of meter keys to increment values             |
+| `meterOnStatusCodes` | string or number[] | `"200-299"`       | Status code range to meter                        |
+| `authHeader`         | string             | `"authorization"` | Header to read the API key from                   |
+| `authScheme`         | string             | `"Bearer"`        | Expected auth scheme prefix                       |
+| `cacheTtlSeconds`    | number             | `60`              | How long to cache subscription data (minimum 60s) |
+
+### `meters`
+
+The `meters` option defines which meters to increment and by how much when a
+request is processed. Values must be positive numbers.
+
+```json
+// Increment the api_requests meter by 1 per request
+{ "meters": { "api_requests": 1 } }
+
+// Increment multiple meters simultaneously
+{ "meters": { "api_requests": 1, "api_credits": 5 } }
+
+// Increment by a fixed amount per request (expensive endpoint)
+{ "meters": { "api_credits": 10 } }
+```
+
+### `meterOnStatusCodes`
+
+Controls which responses count toward metering. By default, only successful
+responses (2xx) are metered.
+
+```json
+// Only meter successful responses (default)
+{ "meterOnStatusCodes": "200-299" }
+
+// Only meter 200 OK
+{ "meterOnStatusCodes": "200" }
+
+// Meter success and redirects
+{ "meterOnStatusCodes": "200-399" }
+
+// Comma-separated ranges
+{ "meterOnStatusCodes": "200, 201, 300-304" }
+
+// Array of specific status codes
+{ "meterOnStatusCodes": [200, 201, 202] }
+```
+
+:::caution
+
+The wildcard `"*"` is not a valid value for `meterOnStatusCodes` and throws a
+configuration error. Use a specific range like `"200-599"` if you want to meter
+most responses.
+
+:::
+
+This is important for fairness: if your backend returns a 500 error, you
+probably don't want to charge the customer for that request.
+
+### `authHeader`
+
+The header to read the API key from. Defaults to `"authorization"`.
+
+### `authScheme`
+
+The expected auth scheme prefix. Defaults to `"Bearer"`. The policy expects the
+header value in the format `{authScheme} {apiKey}`.
+
+### `cacheTtlSeconds`
+
+How long to cache subscription and entitlement data, in seconds. Defaults to
+`60` with a minimum of `60`. Increasing this value reduces calls to the gateway
+service but means entitlement changes take longer to propagate.
+
+## Subscription and payment validation
+
+The policy checks payment status on every request. Access is granted when:
+
+- The subscription is active and not expired
+- Payment status is `paid` or `not_required` (free plans)
+
+When payment fails, a configurable grace period (default 3 days) allows
+continued access while retries are attempted. After the grace period, access is
+blocked until payment succeeds.
+
+The grace period is configurable via metadata on the plan or customer:
+
+- Plan metadata key: `zuplo_max_payment_overdue_days`
+- Customer metadata key: `zuplo_max_payment_overdue_days`
+- Default: `3` (days)
+
+## Multiple policies for different routes
+
+Different routes can have different metering configurations. Define multiple
+policy instances:
+
+```json
+[
+  {
+    "name": "monetization-standard",
+    "policyType": "monetization-inbound",
+    "handler": {
+      "export": "MonetizationInboundPolicy",
+      "module": "$import(@zuplo/runtime)",
+      "options": {
+        "meters": { "api_requests": 1 }
+      }
+    }
+  },
+  {
+    "name": "monetization-ai",
+    "policyType": "monetization-inbound",
+    "handler": {
+      "export": "MonetizationInboundPolicy",
+      "module": "$import(@zuplo/runtime)",
+      "options": {
+        "meters": { "api_requests": 1, "tokens": 1 }
+      }
+    }
+  },
+  {
+    "name": "monetization-premium",
+    "policyType": "monetization-inbound",
+    "handler": {
+      "export": "MonetizationInboundPolicy",
+      "module": "$import(@zuplo/runtime)",
+      "options": {
+        "meters": { "api_credits": 10 }
+      }
+    }
+  }
+]
+```
+
+Apply each to the appropriate routes:
+
+```json
+// Simple lookup -> 1 request meter
+"/api/v1/search": { "inbound": ["monetization-standard"] }
+
+// AI endpoint -> 1 request + token metering
+"/api/v1/analyze": { "inbound": ["monetization-ai"] }
+
+// Premium endpoint -> 10 credits
+"/api/v1/bulk-export": { "inbound": ["monetization-premium"] }
+```
+
+## 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)
+
+## Error responses
+
+The policy returns `403 Forbidden` for all error conditions. Responses follow
+the RFC 7807 Problem Details format:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/403",
+  "title": "Forbidden",
+  "status": 403,
+  "detail": "API Key has exceeded the allowed limit for \"api_requests\" meter.",
+  "instance": "/api/v1/resource",
+  "trace": {
+    "timestamp": "2026-01-15T10:00:00Z",
+    "requestId": "req_abc123",
+    "buildId": "build_xyz"
+  }
+}
+```
+
+Common error details:
+
+| Condition                 | `detail` message                                                    |
+| ------------------------- | ------------------------------------------------------------------- |
+| No auth header            | `"No Authorization Header"`                                         |
+| Wrong auth scheme         | `"Invalid Authorization Scheme"`                                    |
+| Invalid API key           | `"API Key is invalid or does not have access to the API"`           |
+| Expired API key           | `"API Key has expired."`                                            |
+| Expired subscription      | `"API Key has an expired subscription."`                            |
+| Payment not made          | `"Payment has not been made."`                                      |
+| Payment overdue           | `"Payment is overdue. Please update your payment method."`          |
+| Quota exhausted           | `"API Key has exceeded the allowed limit for \"X\" meter."`         |
+| Meter not in subscription | `"API Key does not have \"X\" meter provided by the subscription."` |
+
+## Pipeline ordering
+
+The monetization policy should be the first policy in the inbound pipeline since
+it handles authentication:
+
+```
+1. monetization-inbound  → Authenticates, checks subscription, enforces quota, meters usage
+2. rate-limiting         → (Optional) Per-second/per-minute spike protection
+3. caching               → (Optional) Response caching
+4. → Route handler       → Your API logic
+```
+
+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.

package/docs/articles/monetization/plan-examples.mdx

@@ -0,0 +1,366 @@
+---
+title: Plan Examples
+sidebar_label: Plan Examples
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+This guide walks through progressively building a plan, starting simple and
+adding complexity. All examples assume you have already created:
+
+- A meter called `api_requests` that tracks API calls
+- A feature called `api_requests` linked to that meter
+
+## 1. Basic Fixed Monthly Plan
+
+A simple plan with a flat $9.99/month fee and 1,000 API requests included.
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/plans \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "starter",
+  "name": "Starter Plan",
+  "description": "1,000 API requests per month",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Default",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "API Requests",
+          "featureKey": "api_requests",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "flat",
+            "amount": "9.99"
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false,
+            "usagePeriod": "P1M"
+          }
+        }
+      ]
+    }
+  ]
+}
+EOF
+```
+
+**What this does:**
+
+- Charges $9.99 at the start of each month
+- Grants 1,000 API requests per month
+- Hard limit (`isSoftLimit: false`) - requests are blocked after 1,000
+
+## 2. Add a Free Trial
+
+Building on the previous example, add a 2-week free trial with 1,000 requests.
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/plans \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "starter",
+  "name": "Starter Plan",
+  "description": "1,000 API requests per month with 2-week free trial",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "trial",
+      "name": "Free Trial",
+      "duration": "P2W",
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "API Requests (Trial)",
+          "featureKey": "api_requests",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false,
+            "usagePeriod": "P2W"
+          }
+        }
+      ]
+    },
+    {
+      "key": "default",
+      "name": "Default",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "API Requests",
+          "featureKey": "api_requests",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "flat",
+            "amount": "9.99"
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false,
+            "usagePeriod": "P1M"
+          }
+        }
+      ]
+    }
+  ]
+}
+EOF
+```
+
+**What changed:**
+
+- Added a `trial` phase with `duration: "P2W"` (2 weeks)
+- Trial phase has `price: null` and `billingCadence: null` - it's free
+- After 2 weeks, customer automatically moves to the `default` phase
+
+## 3. Add Overage Charges
+
+Now allow customers to exceed their quota and charge $0.01 per additional
+request after the first 1,000.
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/plans \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "starter",
+  "name": "Starter Plan",
+  "description": "1,000 API requests per month with 2-week free trial and overages",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "trial",
+      "name": "Free Trial",
+      "duration": "P2W",
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "API Requests (Trial)",
+          "featureKey": "api_requests",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false,
+            "usagePeriod": "P2W"
+          }
+        }
+      ]
+    },
+    {
+      "key": "default",
+      "name": "Default",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_requests",
+          "name": "API Requests",
+          "featureKey": "api_requests",
+          "billingCadence": "P1M",
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": true,
+            "usagePeriod": "P1M"
+          },
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "1000",
+                "flatPrice": { "type": "flat", "amount": "9.99" },
+                "unitPrice": null
+              },
+              {
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.01" }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+EOF
+```
+
+**What changed:**
+
+- Changed the rate card from `flat_fee` to `usage_based`
+- Changed `isSoftLimit` to `true` - requests continue after 1,000
+- Combined base fee and overage into tiered pricing: first 1,000 cost $9.99
+  flat, then $0.01 per additional request
+
+**Example billing:**
+
+| Usage | Base Fee | Overage             | Total  |
+| ----- | -------- | ------------------- | ------ |
+| 500   | $9.99    | $0                  | $9.99  |
+| 1,000 | $9.99    | $0                  | $9.99  |
+| 1,500 | $9.99    | 500 × $0.01 = $5    | $14.99 |
+| 5,000 | $9.99    | 4,000 × $0.01 = $40 | $49.99 |
+
+## 4. Add Static Entitlements
+
+Finally, add a static entitlement for "large payloads" that grants premium
+features without metering.
+
+:::note
+
+Before adding the `large_payloads` rate card, you must first create a feature
+with `key: "large_payloads"`.
+
+:::
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/plans \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "starter",
+  "name": "Starter Plan",
+  "description": "1,000 API requests per month with 2-week free trial and overages",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "trial",
+      "name": "Free Trial",
+      "duration": "P2W",
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "API Requests (Trial)",
+          "featureKey": "api_requests",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false,
+            "usagePeriod": "P2W"
+          }
+        },
+        {
+          "type": "flat_fee",
+          "key": "large_payloads",
+          "name": "Large Payloads (Trial)",
+          "featureKey": "large_payloads",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "boolean",
+            "config": true
+          }
+        }
+      ]
+    },
+    {
+      "key": "default",
+      "name": "Default",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_requests",
+          "name": "API Requests",
+          "featureKey": "api_requests",
+          "billingCadence": "P1M",
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": true,
+            "usagePeriod": "P1M"
+          },
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "1000",
+                "flatPrice": { "type": "flat", "amount": "9.99" },
+                "unitPrice": null
+              },
+              {
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.01" }
+              }
+            ]
+          }
+        },
+        {
+          "type": "flat_fee",
+          "key": "large_payloads",
+          "name": "Large Payloads",
+          "featureKey": "large_payloads",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "boolean",
+            "config": true
+          }
+        }
+      ]
+    }
+  ]
+}
+EOF
+```
+
+**What changed:**
+
+- Added `large_payloads` rate card to both phases
+- Uses `type: "boolean"` with `config: true` to grant the feature
+- No meter required - this is a static on/off entitlement
+
+**Final plan summary:**
+
+| Phase   | Duration | API Requests       | Large Payloads | Cost        |
+| ------- | -------- | ------------------ | -------------- | ----------- |
+| Trial   | 2 weeks  | 1,000 (hard limit) | Enabled        | Free        |
+| Default | Ongoing  | 1,000 + overages   | Enabled        | $9.99/month |