zuplo 6.70.70 → 6.70.71

package/docs/articles/monetization/api-access.mdx

@@ -52,6 +52,190 @@ curl \
   --header "Authorization: Bearer $ZAPI_KEY"
 ```
 
+## Bucket monetization configuration
+
+Each bucket has an optional `MonetizationConfiguration` that holds bucket-wide
+behavior — multi-subscription support, plan display order, plan-level overrides,
+and the default payment grace period. The configuration is read by the runtime
+and the Developer Portal; it is not stored in OpenMeter.
+
+### Read
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+When no configuration row exists for the bucket, the endpoint returns a default
+body with `multipleSubscriptionsEnabled: false`, an empty `planOrder`, empty
+`planSettings`, and `maxPaymentOverdueDays: 3`.
+
+### Upsert
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "multipleSubscriptionsEnabled": false,
+  "planOrder": ["free", "starter", "pro", "enterprise"],
+  "planSettings": {
+    "pro": { "visiblePhases": ["default"] }
+  },
+  "maxPaymentOverdueDays": 7
+}
+EOF
+```
+
+| Field                          | Type       | Description                                                                                                                                                                                         |
+| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `multipleSubscriptionsEnabled` | `boolean`  | Stored on the bucket. Reserved for future multi-subscription rules; today the Developer Portal create-subscription path enforces a single active subscription per customer regardless of this flag. |
+| `planOrder`                    | `string[]` | Ordered list of plan keys; drives pricing-page sort and upgrade/downgrade direction during plan changes                                                                                             |
+| `planSettings`                 | `object`   | Per-plan overrides keyed by plan key. The supported sub-key today is `visiblePhases` — an array of phase keys that should appear on the pricing page                                                |
+| `maxPaymentOverdueDays`        | `integer`  | Bucket-default payment grace period. Must be ≥ 0. Defaults to `3` when not set                                                                                                                      |
+
+The request body must include at least one of these fields. All four fields are
+optional in the request — the upsert preserves any field you don't send.
+
+`planOrder` is consumed when a customer changes plans through the Developer
+Portal: a target plan whose index is greater than or equal to the current plan's
+index is treated as an upgrade (immediate timing); a lower index is treated as a
+downgrade (next-billing-cycle timing). Plans not listed in `planOrder` default
+to upgrade timing.
+
+`maxPaymentOverdueDays` is the lowest-precedence default for the payment grace
+period. See
+[Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation)
+for the full precedence chain (customer metadata → plan metadata → bucket
+configuration → built-in default).
+
+### Delete
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request DELETE \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+After deletion, GET returns the default body again.
+
+## Stripe setup and billing readiness
+
+Most users connect Stripe through the
+[Zuplo Portal](./stripe-integration.md#connecting-your-stripe-account). For
+automated provisioning — CI scripts, infrastructure-as-code, or self-hosted
+control planes — the same flow is available via these API endpoints.
+
+### Install the Stripe app
+
+Connect a Stripe account to a bucket and create the default billing profile in
+one call:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "apiKey": "rk_test_...",
+  "name": "Stripe Billing Profile",
+  "taxEnabled": false,
+  "taxEnforced": false,
+  "country": "US"
+}
+EOF
+```
+
+The endpoint validates the Stripe key prefix against the bucket's environment:
+
+- Working-copy and preview buckets accept `sk_test_*` or `rk_test_*`
+- Production buckets accept `sk_live_*` or `rk_live_*`
+
+The response returns the installed `appId`. The endpoint fails with a
+`409 Conflict` if a Stripe app is already installed for the bucket.
+
+### Read the current Stripe setup
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Returns the connected Stripe app summary and the billing profiles linked to it.
+
+### Create an additional billing profile
+
+To attach more billing profiles to the same Stripe app:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe/$STRIPE_APP_ID/billing-profile \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "name": "EU Billing Profile",
+  "taxEnabled": true,
+  "taxEnforced": false,
+  "country": "DE"
+}
+EOF
+```
+
+### Check billing readiness
+
+A lightweight check for tooling that gates deploys on Stripe being connected:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/billing-readiness \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Response:
+
+```json
+{
+  "hasStripeApp": true,
+  "stripeAppId": "app_01H...",
+  "hasDefaultBillingProfile": true,
+  "defaultBillingProfileId": "bp_01H..."
+}
+```
+
+Use this in setup wizards to gate the UI on whether Stripe is connected.
+
+### Update a connected app
+
+Rotate the Stripe key on an existing app, or update its name and metadata:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/apps/$APP_ID \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "type": "stripe",
+  "name": "Stripe Billing Profile",
+  "secretAPIKey": "rk_test_..."
+}
+EOF
+```
+
+The same key-prefix validation applies — a live key is rejected on a
+non-production bucket and vice versa.
+
 ## API Reference
 
 For complete API operations, see the API Reference documentation:

package/docs/articles/monetization/meters.mdx

@@ -58,10 +58,10 @@ carries the quantity:
 `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
+`subscription` field for that) and does not 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.
 
 :::

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

@@ -145,7 +145,10 @@ below it:
 
 1. **Customer metadata** — `zuplo_max_payment_overdue_days` on the customer
 2. **Plan metadata** — `zuplo_max_payment_overdue_days` on the plan
-3. **Default** — `3` days
+3. **Bucket configuration** —
+   [`maxPaymentOverdueDays`](./api-access.mdx#bucket-monetization-configuration)
+   on the bucket's monetization configuration
+4. **Default** — `3` days
 
 Set the value to `0` to block requests immediately when payment is overdue.
 

package/docs/articles/monetization/private-plans.md

@@ -99,10 +99,9 @@ Save the returned `id` — you need it to publish and invite users.
 
 :::note
 
-The plan `id` is a 26-character ULID (regex
-`^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$`), separate from the human-friendly
-`key` you set on creation. The publish, invite, and other plan-scoped endpoints
-require the `id`, not the `key`.
+The plan `id` is a 26-character ULID. It's distinct from the human-friendly
+`key` field. Use the `id` (not the `key`) when calling `/publish` and
+`/plan-invites`.
 
 :::
 

package/docs/articles/monetization/stripe-integration.md

@@ -45,6 +45,15 @@ specifically Customers, Checkout Sessions, Customer Portal Sessions, Invoices,
 and Tax Calculations. See
 [What Zuplo creates in Stripe](#what-zuplo-creates-in-stripe) for the full list.
 
+:::tip
+
+To script the connection — for CI, infrastructure-as-code, or self-hosted
+control planes — use the
+[Stripe setup API endpoints](./api-access.mdx#stripe-setup-and-billing-readiness)
+instead of the Portal flow.
+
+:::
+
 ### Test mode vs. live mode
 
 Connect with a Stripe **test** key (`sk_test_...`) first to validate your

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

@@ -67,8 +67,9 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "plan": { "key": "pro" },
-    "customerId": "01J9ZX2A8R0K8H6VG2C1A0K3WP"
+    "plan": { "key": "pro", "version": 1 },
+    "customerKey": "user_external_id",
+    "timing": "immediate"
   }'
 ```
 
@@ -216,14 +217,15 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
   -H "Content-Type: application/json" \
   -d '{
     "timing": "immediate",
-    "plan": { "key": "enterprise" }
+    "plan": { "key": "enterprise", "version": 1 }
   }'
 ```
 
 `timing` accepts `"immediate"`, `"next_billing_cycle"`, or an RFC 3339
 timestamp. Optional fields include `startingPhase`, `name`, `description`,
-`metadata`, `alignment`, and `billingAnchor`. To preview the proration credit
-before committing, call
+`metadata`, `alignment`, and `billingAnchor`. The response includes both the
+closed-out (`current`) and newly-started (`next`) subscriptions. To preview the
+proration credit before committing, call
 `POST /v3/metering/{bucketId}/subscriptions/{subscriptionId}/change/estimate-credit`
 with the same body.
 
@@ -310,9 +312,7 @@ behavior does not apply.
 curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/cancel \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
-  -d '{
-    "timing": "next_billing_cycle"
-  }'
+  -d '{ "timing": "next_billing_cycle" }'
 ```
 
 `timing` controls when the cancellation takes effect:
@@ -341,9 +341,10 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
   -H "Authorization: Bearer {API_KEY}"
 ```
 
-This removes the pending cancellation. The subscription continues as normal. For
-a subscription whose period has already ended, create a new subscription on the
-same plan instead.
+This removes the pending cancellation. The subscription continues as normal.
+
+If the subscription has already ended, create a new subscription rather than
+restoring the old one.
 
 ## Subscriptions per customer
 

package/docs/articles/monorepo-deployment.mdx

@@ -114,7 +114,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
         env:
           ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
 ```
@@ -171,8 +173,12 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # The PR's source branch — not the pull/<number>/merge ref that
+          # pull_request events check out
+          ENVIRONMENT: ${{ github.head_ref }}
         run: |
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
           DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
           echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
@@ -230,6 +236,18 @@ jobs:
             --wait
 ```
 
+:::caution
+
+The deploy step passes `--environment` with the PR's source branch name
+(`github.head_ref`). Workflows triggered by `pull_request` check out the PR
+merge ref (`refs/pull/<number>/merge`), so without `--environment` the CLI names
+the environment after that ref instead of your branch — and any other deploy of
+the same branch creates a second environment with a different URL. See
+[PR Preview Environments](./ci-cd-github/pr-preview-environments.mdx) for
+details.
+
+:::
+
 ### Secrets and environment variables
 
 Store your Zuplo API key as a GitHub Actions secret:

package/docs/cli/deploy.mdx

@@ -122,6 +122,38 @@ zuplo deploy --project my-project
 zuplo deploy --project my-project --environment my-env-name
 ```
 
+### Deploying from CI/CD
+
+Without `--environment`, the CLI names the environment after the current git
+branch. CI systems usually check out a detached HEAD, in which case the CLI
+resolves the branch from the remote branches that contain the checked-out
+commit. Two cases break this inference:
+
+- On GitHub Actions `pull_request` events, the checkout is the pull request
+  merge ref (`refs/pull/<number>/merge`) — a commit that doesn't exist on any
+  branch — so the environment is named after that ref instead of your branch.
+- When the checked-out commit exists on more than one branch, the first match
+  wins, which may not be the branch that triggered the build.
+
+Always pass `--environment` explicitly in CI so that every trigger deploys the
+same, predictably named environment:
+
+```bash
+# GitHub Actions: github.head_ref is the source branch on pull_request
+# events; github.ref_name is the branch on push events
+zuplo deploy --project my-project --environment "$BRANCH_NAME"
+```
+
+Deploying the same environment name always updates the same environment and
+keeps its URL stable across deploys. This matters whenever an external system
+must match the URL exactly — an OIDC token audience, a webhook registration, or
+an allowlist. Capture the URL from the deploy output (`Deployed to
+https://...`) rather than constructing it from the branch name: the URL
+hostname uses a normalized, truncated form of the environment name plus a
+unique identifier. See
+[Branch-Based Deployments](../articles/branch-based-deployments.mdx) for the
+naming rules.
+
 ## Polling timeout
 
 By default, the deploy command polls the status of the deployment every second

package/docs/cli/deploy.partial.mdx

@@ -25,6 +25,38 @@ zuplo deploy --project my-project
 zuplo deploy --project my-project --environment my-env-name
 ```
 
+### Deploying from CI/CD
+
+Without `--environment`, the CLI names the environment after the current git
+branch. CI systems usually check out a detached HEAD, in which case the CLI
+resolves the branch from the remote branches that contain the checked-out
+commit. Two cases break this inference:
+
+- On GitHub Actions `pull_request` events, the checkout is the pull request
+  merge ref (`refs/pull/<number>/merge`) — a commit that doesn't exist on any
+  branch — so the environment is named after that ref instead of your branch.
+- When the checked-out commit exists on more than one branch, the first match
+  wins, which may not be the branch that triggered the build.
+
+Always pass `--environment` explicitly in CI so that every trigger deploys the
+same, predictably named environment:
+
+```bash
+# GitHub Actions: github.head_ref is the source branch on pull_request
+# events; github.ref_name is the branch on push events
+zuplo deploy --project my-project --environment "$BRANCH_NAME"
+```
+
+Deploying the same environment name always updates the same environment and
+keeps its URL stable across deploys. This matters whenever an external system
+must match the URL exactly — an OIDC token audience, a webhook registration, or
+an allowlist. Capture the URL from the deploy output (`Deployed to
+https://...`) rather than constructing it from the branch name: the URL
+hostname uses a normalized, truncated form of the environment name plus a
+unique identifier. See
+[Branch-Based Deployments](../articles/branch-based-deployments.mdx) for the
+naming rules.
+
 ## Polling timeout
 
 By default, the deploy command polls the status of the deployment every second

package/docs/concepts/api-keys.md

@@ -50,8 +50,8 @@ After successful validation, the policy populates `request.user`:
 - `request.user.data` contains the consumer's metadata (plan, customerId, etc.)
 
 This lets downstream policies and handlers make authorization decisions, apply
-per-consumer [rate limits](./rate-limiting.md), or forward identity to your
-backend.
+per-consumer [rate limits](../rate-limiting/how-it-works.md), or forward
+identity to your backend.
 
 :::note
 

package/docs/dev-portal/zudoku/components/callout.mdx

@@ -193,24 +193,17 @@ Or pass any React node as the `icon` to override the default for the chosen `typ
 ## Customize colors
 
 Each callout type is driven by a single CSS variable that determines the icon, border tint, and
-background tint via `color-mix`. Override any of them in your theme's `customCss` to recolor a type
-globally:
-
-```ts title="zudoku.config.ts"
-export default {
-  theme: {
-    customCss: `
-      :root {
-        --callout-tip: oklch(0.65 0.18 160);
-        --callout-sparkles: oklch(0.6 0.22 320);
-      }
-      .dark {
-        --callout-tip: oklch(0.78 0.18 160);
-        --callout-sparkles: oklch(0.75 0.2 320);
-      }
-    `,
-  },
-};
+background tint via `color-mix`. Override any of them in your stylesheet to recolor a type globally:
+
+```css title=styles.css
+:root {
+  --callout-tip: oklch(0.65 0.18 160);
+  --callout-sparkles: oklch(0.6 0.22 320);
+}
+.dark {
+  --callout-tip: oklch(0.78 0.18 160);
+  --callout-sparkles: oklch(0.75 0.2 320);
+}
 ```
 
 All available variables:

package/docs/dev-portal/zudoku/configuration/search.md

@@ -167,3 +167,39 @@ your [Dev Portal Configuration](./overview.md):
   // ...
 }
 ```
+
+### Customizing Inkeep
+
+Any other [base settings](https://docs.inkeep.com/cloud/ui-components/common-settings/base) can be
+set alongside the required fields, for example `filters` to scope results or `transformSource` to
+customize how sources are displayed.
+
+You can also pass
+[`searchSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/search),
+[`aiChatSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/ai-chat), and
+`modalSettings` to customize the respective parts of the search experience. They are merged with
+Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used —
+including ones added after this Dev Portal version was released.
+
+For example, to categorize results into tabs based on their URL:
+
+```typescript
+{
+  // ...
+  search: {
+    type: "inkeep",
+    // ...required fields from above
+    transformSource: (source) => {
+      if (!source.url.includes("/blog/")) return source;
+      return { ...source, tabs: [...(source.tabs ?? []), "Blog"] };
+    },
+    searchSettings: {
+      tabs: [["All", { isAlwaysVisible: true }], "Blog"],
+    },
+    aiChatSettings: {
+      aiAssistantName: "My Assistant",
+    },
+  },
+  // ...
+}
+```

package/docs/dev-portal/zudoku/configuration/site.md

@@ -127,6 +127,44 @@ export const NotFound = () => (
 
 ## Layout
 
+### Collapsible Sidebar
+
+The navigation sidebar is collapsible by default. A small toggle button on the sidebar's right
+border lets users hide and reveal it. Configure the behavior under `site.sidebar`:
+
+```tsx title=zudoku.config.tsx
+{
+  site: {
+    sidebar: {
+      collapsible: true, // default: true. Set to false to disable the toggle entirely.
+      toggleVisibility: "always", // "always" (default) or "hover" — show button only when hovering the sidebar's right edge
+      togglePosition: "bottom", // "top", "center", or "bottom" (default)
+    },
+  }
+}
+```
+
+For finer vertical placement, override the `--sidebar-toggle-y` CSS variable in your stylesheet:
+
+```css
+:root {
+  --sidebar-toggle-y: 30%;
+}
+```
+
+The toggle button carries `aria-expanded="true"` when the sidebar is open and `"false"` when
+collapsed. Combine it with the `[data-sidebar-toggle]` selector to position the button differently
+per state:
+
+```css
+[data-sidebar-toggle][aria-expanded="true"] {
+  --sidebar-toggle-y: 20%;
+}
+[data-sidebar-toggle][aria-expanded="false"] {
+  --sidebar-toggle-y: 80%;
+}
+```
+
 ### Banner
 
 Add a banner message to the top of the page: