zuplo 6.69.8 → 6.69.10

package/docs/articles/monetization/meters.mdx

@@ -43,8 +43,10 @@ Track the total number of API requests:
 }
 ```
 
-Each event contains the `subscription` ID linking it to a subscription and a
-`total` field in `data` with the quantity to record:
+Each event identifies the subscription being metered, the actor that drove the
+consumption, and how much to record. The `subscription` field carries the
+subscription ID, the `subject` field identifies the actor, and `data.total`
+carries the quantity:
 
 ```json
 {
@@ -52,7 +54,7 @@ Each event contains the `subscription` ID linking it to a subscription and a
   "specversion": "1.0",
   "type": "api_requests",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 1
@@ -62,8 +64,13 @@ Each event contains the `subscription` ID linking it to a subscription and a
 
 :::note
 
-Events emitted by the `MonetizationInboundPolicy` always set `subject` and
-`subscription` to the same subscription ULID. See
+`subject` identifies _who_ consumed the subscription's entitlements on this
+request — typically the API key's consumer name, the end-user id, or another
+stable per-actor identifier. It is **not** the subscription id (use the
+`subscription` field for that) and is not used to route billing. Its purpose is
+to let you break down usage within a subscription so you can see which key,
+user, or agent drove the consumption — a single subscription will commonly emit
+events with many different `subject` values. See
 [Monetization Policy](./monetization-policy.md) for how usage is recorded.
 
 :::
@@ -96,7 +103,7 @@ consumed 50 tokens looks like this:
   "specversion": "1.0",
   "type": "tokens",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 50
@@ -126,7 +133,7 @@ Each event reports the number of bytes transferred:
   "specversion": "1.0",
   "type": "data_transfer",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 4096

package/docs/articles/monetization/plans.mdx

@@ -204,8 +204,7 @@ After the trial ends, customers automatically move to the default phase. The $99
 monthly subscription fee is charged in advance at the start of each billing
 period via the `monthly_fee` flat-fee rate card. The plan includes 10,000 API
 requests per period; additional requests are billed at $0.01 each in arrears
-(the soft limit on the metered entitlement allows overage to flow through to the
-next invoice).
+(soft limit allows overage).
 
 ## Plan Properties
 

package/docs/articles/monetization/rate-cards.mdx

@@ -26,7 +26,9 @@ A rate card consists of:
 - **Feature** - Optional link to a feature from your product catalog
 - **Price** - How much to charge (see [Pricing Models](./pricing-models.mdx))
 - **Entitlement** - Optional usage limits or access controls
-- **Billing Cadence** - How often to bill (monthly, one-time, etc.)
+- **Billing Cadence** - How often this rate card produces a charge — distinct
+  from the plan's billing cadence, and constrained to align with it (see
+  [Billing Cadence](#billing-cadence) below)
 
 ## Rate Card Types
 
@@ -53,8 +55,9 @@ recurring fee. Use these for:
 }
 ```
 
-When `billingCadence` is set (e.g., `P1M` for monthly), the fee recurs each
-billing period. When `billingCadence` is `null`, the fee is charged once per
+When `billingCadence` is set (e.g., `P1M`), the flat fee recurs at that cadence
+— see [Billing Cadence](#billing-cadence) for the constraint relative to the
+plan's cadence. When `billingCadence` is `null`, the fee is charged once per
 subscription phase.
 
 The `paymentTerm` field controls when the charge is collected:
@@ -90,6 +93,36 @@ Usage-based rate cards support multiple pricing models. See
 [Pricing Models](./pricing-models.mdx) for details on unit, tiered, package, and
 dynamic pricing.
 
+## Billing Cadence
+
+A rate card's `billingCadence` controls how often this specific rate card
+produces a charge. It's distinct from the **plan's** `billingCadence`, which
+sets the overall invoice schedule for the subscription:
+
+- For **flat-fee** rate cards, the cadence determines how often the flat fee
+  recurs. Set it to `null` to charge once per subscription phase (a setup fee,
+  onboarding charge, or other one-time payment).
+- For **usage-based** rate cards, the cadence is required and determines the
+  period over which metered usage is aggregated and emitted as an invoice line.
+
+### Alignment with the plan
+
+The rate card's cadence must align with the plan's `billingCadence`. Two
+cadences align when:
+
+- They are identical (e.g., plan `P1M` and rate card `P1M`), or
+- The shorter one divides the longer one without remainder (e.g., plan `P1M`
+  with a rate card at `P3M`, or plan `P1Y` with a rate card at `P1M`).
+
+Plans accept these `billingCadence` values: `PT1H`, `P1D`, `P1W`, `P2W`, `P4W`,
+`P1M`, `P3M`, `P6M`, `P12M`, `P1Y`. A rate card with a cadence that doesn't
+align (for example, `P2M` on a `P3M` plan, where neither divides the other) is
+rejected at plan creation.
+
+This rule exists for invoice-generation correctness: it guarantees that every
+rate-card cycle ends on a plan-invoice boundary, so a single charge from this
+rate card lands on exactly one customer invoice rather than straddling two.
+
 ## Rate Cards With Features
 
 When a rate card is linked to a feature via `featureKey`:

package/docs/cli/bucket-list.mdx

@@ -0,0 +1,71 @@
+---
+title: "Zuplo CLI: Bucket List"
+sidebar_label: bucket list
+---
+
+<CliCommand
+  command="bucket list"
+  description="Lists the buckets in your account"
+  options={[
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "project",
+    "type": "string",
+    "description": "Filter buckets by project name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  }
+]}
+  examples={[
+  [
+    "$0 bucket list",
+    "List all buckets in your account"
+  ],
+  [
+    "$0 bucket list --output json",
+    "List all buckets as JSON"
+  ],
+  [
+    "$0 bucket list --account my-account",
+    "Explicitly specify the account"
+  ],
+  [
+    "$0 bucket list --project my-project",
+    "Filter buckets by project name"
+  ]
+]}
+  usage="$0 bucket list [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/cli/logout.mdx

@@ -0,0 +1,25 @@
+---
+title: "Zuplo CLI: Logout"
+sidebar_label: logout
+---
+
+<CliCommand
+  command="logout"
+  description="Logs the current user out if logged in"
+  examples={[
+  [
+    "$0 logout",
+    "Remove locally stored Zuplo credentials"
+  ]
+]}
+  usage="$0 logout"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/policies/api-key-inbound/schema.json

@@ -46,6 +46,11 @@
               "x-show-example": false,
               "description": "The scheme used on the header."
             },
+            "bucketId": {
+              "type": "string",
+              "x-show-example": false,
+              "description": "The ID of the API Key service bucket. Preferred over bucketName. Defaults to the autogenerated bucket ID for your project."
+            },
             "bucketName": {
               "type": "string",
               "x-show-example": false,

package/package.json

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