zuplo 6.69.6 → 6.69.9

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

@@ -12,9 +12,9 @@ announced.
 
 :::
 
-Zuplo uses Stripe to handle payment processing, subscription billing, and
-invoicing. Zuplo handles metering, quota enforcement, and subscription state —
-Stripe handles money.
+Zuplo uses Stripe to collect payments. Zuplo is the system of record for plans,
+subscriptions, features, entitlements, and metered usage; Stripe is the system
+of record for **money** — customers, invoices, and payment collection.
 
 ## How it works
 
@@ -22,19 +22,21 @@ The integration flow:
 
 1. You define plans, features, and meters in Zuplo
 2. You connect your Stripe account via the Zuplo Portal
-3. When you publish plans, corresponding Stripe Products and Prices are created
-   automatically
+3. Plans, features, and rate cards stay in Zuplo's catalog — Stripe is used only
+   at billing time
 4. Customers subscribe through your Developer Portal via Stripe Checkout
-5. Stripe processes the payment and creates the subscription
-6. A Zuplo subscription is created with an API key scoped to the plan's
-   entitlements
-7. As the customer uses the API, the monetization policy meters usage in real
+5. Stripe collects the payment method and Zuplo creates the subscription with an
+   API key scoped to the plan's entitlements
+6. As the customer uses the API, the monetization policy meters usage in real
    time
-8. For usage-based billing, usage is tracked continuously and billed through
-   Stripe automatically
+7. At the end of each billing period, Zuplo issues a Stripe Invoice for fixed
+   fees and usage-based charges
 
-Throughout this flow, Zuplo is the source of truth for access control and
-metering. Stripe is the source of truth for payment state.
+Throughout this flow, Zuplo is the source of truth for access control,
+plans/rate cards, and metered usage. Stripe is the source of truth for payment
+state and tax. **Stripe Subscriptions, Products, Prices, and Billing Meters are
+not used** — Zuplo manages those concepts internally and only materializes them
+in Stripe at the moment a charge is needed (as invoice line items).
 
 ## Connecting your Stripe account
 
@@ -45,8 +47,19 @@ metering. Stripe is the source of truth for payment state.
 3. Enter a **Name** and paste your **Stripe API Key**
 4. Click **Save**
 
-The connection authorizes Zuplo to manage Stripe objects on your behalf,
-including products, prices, customers, and subscriptions.
+:::tip
+
+To script the same flow (CI, infrastructure-as-code, etc.) use the
+[Stripe setup API](./api-access.mdx#stripe-setup-and-billing-readiness) — it
+exposes `POST /setup/stripe`, `GET /billing-readiness`, and key-rotation
+endpoints with the same prefix validation as the UI.
+
+:::
+
+The connection authorizes Zuplo to manage Stripe objects on your behalf —
+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.
 
 ### Test mode vs. live mode
 
@@ -143,20 +156,23 @@ new key must:
 
 ## What Zuplo creates in Stripe
 
-When you publish a plan, corresponding objects are created in Stripe
-automatically:
+Zuplo's catalog — plans, features, rate cards, and entitlements — is stored in
+Zuplo. Stripe is used only at the points where money or payment state is
+involved.
+
+The objects that Zuplo creates or manages in your Stripe account:
 
-| Zuplo concept        | Stripe object created            |
-| -------------------- | -------------------------------- |
-| Plan                 | Product                          |
-| Rate card (flat fee) | Price (recurring, fixed amount)  |
-| Rate card (per-unit) | Price (recurring, metered usage) |
-| Rate card (tiered)   | Price (recurring, tiered)        |
-| Feature entitlement  | Metadata on the Product          |
+| Object                          | When it's created                                                          |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| Stripe Customer                 | When a developer first subscribes — one Stripe Customer per Zuplo customer |
+| Stripe Checkout Session         | When a developer subscribes to a plan that requires a payment method       |
+| Stripe Customer Portal Session  | When a developer opens **Manage Billing** in the Developer Portal          |
+| Stripe Invoice and Invoice Item | At the end of each billing period for fixed and usage-based charges        |
+| Stripe Tax Calculation          | At invoice time when [tax collection](./tax-collection.md) is enabled      |
+| Stripe Webhook Endpoint         | Once on connection, so Zuplo can react to payment events                   |
 
-You can see these in your Stripe Dashboard under **Products**. These objects are
-managed automatically — don't edit them directly in Stripe, as your changes may
-be overwritten on the next plan publish.
+To see what Zuplo has created, look under **Customers** and **Invoices** in your
+Stripe dashboard.
 
 ## Subscription flow
 
@@ -164,7 +180,8 @@ be overwritten on the next plan publish.
 
 When a customer clicks "Subscribe" in your Developer Portal:
 
-1. A Stripe Checkout Session is created with the selected plan's prices
+1. A Stripe Checkout Session is created so the customer can enter a payment
+   method
 2. The customer is redirected to Stripe Checkout to enter payment details
 3. On successful payment, the subscription is created
 4. An API key is generated scoped to the subscription's plan entitlements
@@ -175,22 +192,38 @@ When a customer clicks "Subscribe" in your Developer Portal:
 
 When a customer changes their plan through the Developer Portal:
 
-1. The Stripe Subscription is updated with the new plan's prices
-2. Charges are prorated automatically
+1. Zuplo records the plan change and recalculates the customer's entitlements
+2. Any prorated amount is reflected on the customer's next Stripe Invoice
 3. The customer's entitlements update immediately
 4. The API key remains the same; its associated quota changes in real time
 
-Upgrades take effect immediately. Downgrades take effect at the next billing
-cycle.
+Zuplo uses **max_consumption_based proration** so customers can't game
+mid-period upgrades and downgrades — see
+[Subscription Lifecycle → Proration behavior](./subscription-lifecycle.md#proration-behavior)
+for the detailed model and examples.
 
 ### Cancellation
 
-When a customer cancels:
-
-1. The subscription is set to cancel at the end of the current billing period
-   (by default)
-2. The customer retains access until their current billing period ends
-3. At period end, access is revoked and the API key stops working
+When a customer cancels through the Developer Portal, the timing of the
+cancellation depends on whether the current phase has billable items:
+
+- **Paid phases** — the portal sends `timing: "next_billing_cycle"`. The
+  subscription is scheduled to cancel at the end of the current billing
+  period, the customer retains access until then, and the API key stops
+  working at period end.
+- **Free phases** — the portal sends `timing: "immediate"`. With nothing to
+  invoice at period end, there's no billing period to wait out, so the
+  subscription cancels and access is revoked right away. Two situations fall
+  into this branch:
+  - The customer is on a **free trial phase** (the first phase of a plan
+    with a later paid phase) and cancels before the trial converts.
+  - The customer is on a **free plan** — a plan whose only phase has no
+    billable rate cards (every rate card's `price` is `null`).
+
+For programmatic cancellation, see
+[Cancellation](./subscription-lifecycle.md#cancellation) in the Subscription
+Lifecycle guide — the API endpoint accepts a `timing` parameter to control
+this same behavior explicitly.
 
 ## Proration
 
@@ -203,10 +236,13 @@ invoice.
 
 For plans with usage-based pricing (per-unit, tiered, pay-as-you-go), usage is
 tracked in real time by the `MonetizationInboundPolicy`. Each API request
-increments the meter immediately. At the end of the billing period, usage is
-billed through Stripe automatically.
+increments the meter immediately. At the end of the billing period, Zuplo
+generates a Stripe Invoice with line items for the period's fixed fees and
+metered usage, and Stripe collects payment.
 
-You don't need to implement usage reporting or run any batch jobs.
+You don't need to implement usage reporting or run any batch jobs — and Zuplo
+does **not** call Stripe Billing Meters; metered usage is materialized as
+invoice line items directly.
 
 ## Handling failed payments
 
@@ -222,8 +258,11 @@ Stripe retries the payment.
 | `failed`        | Access blocked after grace period (configurable) |
 | `uncollectible` | Access blocked                                   |
 
-The grace period is configurable via `zuplo_max_payment_overdue_days` metadata
-on the plan or customer (default: 3 days).
+The grace period is configurable, with customer metadata overriding plan
+metadata, which overrides the bucket-level `maxPaymentOverdueDays`. Default is 3
+days. See
+[Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation)
+for the full resolution order.
 
 ## Customer portal
 
@@ -260,13 +299,19 @@ After connecting Stripe and publishing plans:
 1. Open your Developer Portal
 2. Subscribe to a plan using test card `4242 4242 4242 4242`
 3. Verify in Stripe Dashboard:
-   - Customer created
-   - Subscription active
-   - Product and Price match your plan
+   - **Customers** — a customer was created with correct metadata and test card
+     attached
+   - **Developers → Webhooks** — the Zuplo-managed webhook endpoint is
+     registered and recent events show `200` responses
 4. Make API requests and verify:
    - Requests succeed within quota
-   - `403 Forbidden` returned when quota exceeded (hard limit plans)
+   - `403 Forbidden` returned when quota exceeded (hard-limit plans)
    - Usage visible in the Developer Portal dashboard
-5. Cancel the subscription and verify:
-   - Access revoked after billing period
-   - Stripe subscription shows canceled
+5. Wait for the next billing cycle (or trigger a manual invoice in test mode)
+   and verify:
+   - **Invoices** — a Stripe Invoice was created with line items matching your
+     plan's fixed fees and metered usage
+6. Cancel the subscription in the Developer Portal and verify:
+   - Access is revoked after the billing period ends
+   - The Zuplo subscription shows `canceled` in the API and Developer Portal
+     (Stripe doesn't track this — there is no Stripe Subscription to look at)

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

@@ -27,8 +27,9 @@ trials, upgrades, downgrades, cancellation, and reactivation.
 :::note
 
 Access is also governed by payment status. If a payment is overdue beyond the
-grace period (default 3 days, configurable via `zuplo_max_payment_overdue_days`
-metadata), access is blocked even for active subscriptions.
+grace period (default 3 days), access is blocked even for active subscriptions.
+The grace period is configurable per-customer, per-plan, or per-bucket — see
+[Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation).
 
 :::
 
@@ -56,14 +57,17 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "customerId": "cus_abc123",
-    "planKey": "pro",
-    "stripeCustomerId": "cus_stripe_xyz"
+    "plan": { "key": "pro" },
+    "customerId": "01J9ZX2A8R0K8H6VG2C1A0K3WP"
   }'
 ```
 
-The `customerId` is the user's identifier in your auth system (Auth0 user ID,
-etc.). The `stripeCustomerId` is the customer's ID in Stripe.
+`plan` references the target plan by its `key` (and optionally `version`).
+Provide either `customerId` (the OpenMeter customer ULID, format
+`^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$`) or `customerKey` (your own
+identifier). Optional fields include `timing` (`"immediate"` by default,
+`"next_billing_cycle"`, or an RFC 3339 timestamp), `startingPhase`, `name`,
+`description`, `metadata`, `alignment`, and `billingAnchor`.
 
 ## Free trials
 
@@ -185,15 +189,24 @@ Customers can change plans from the Subscriptions page in the Developer Portal:
 
 ### Programmatic (API)
 
+Plan changes go through the dedicated `change` endpoint, which closes the
+current subscription and starts a new one on the target plan:
+
 ```bash
-curl -X PATCH https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId} \
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/change \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "planKey": "enterprise"
+    "timing": "immediate",
+    "plan": { "key": "enterprise" }
   }'
 ```
 
+`timing` accepts `"immediate"`, `"next_billing_cycle"`, or an RFC 3339
+timestamp. To preview the proration credit before committing, call
+`POST /v3/metering/{bucketId}/subscriptions/{subscriptionId}/change/estimate-credit`
+with the same body.
+
 ### Proration behavior
 
 When a customer changes plans mid-billing-period, Zuplo uses
@@ -255,9 +268,21 @@ Customers can cancel from the Developer Portal subscriptions page:
 
 ```bash
 curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/cancel \
-  -H "Authorization: Bearer {API_KEY}"
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "timing": "next_billing_cycle"
+  }'
 ```
 
+`timing` controls when the cancellation takes effect:
+
+- Omitted (or `"immediate"`) — the subscription is canceled immediately and
+  access stops right away. Use this for refund-style flows.
+- `"next_billing_cycle"` — access continues until the end of the current billing
+  period, then is revoked. This matches the Developer Portal default.
+- An RFC 3339 timestamp — schedule cancellation at a specific time.
+
 ### Cancellation behavior
 
 | Scenario                     | Default behavior                           |
@@ -276,14 +301,9 @@ 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.
-
-A fully canceled subscription (past the period end) can be restored:
-
-```bash
-curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/restore \
-  -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.
 
 ## Multiple subscriptions
 

package/docs/articles/monetization/troubleshooting.md

@@ -30,8 +30,11 @@ announced.
      -H "Authorization: Bearer {API_KEY}"
    ```
 
-   Fix: Either resolve the payment issue in Stripe, or adjust the grace period
-   via `zuplo_max_payment_overdue_days` metadata on the plan or customer.
+   Fix: Either resolve the payment issue in Stripe, or adjust the grace period.
+   The window resolves customer metadata → plan metadata → bucket configuration
+   → 3-day default. See
+   [Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation)
+   for details.
 
 2. **Customer is using the wrong API key.** Each subscription generates its own
    key. If the customer has multiple subscriptions or regenerated their key,

package/docs/dev-portal/zudoku/configuration/authentication-auth0.md

@@ -154,6 +154,28 @@ When the prompt parameter is omitted (empty string), Auth0 will:
 - Silently authenticate the user if they have a valid session
 - Redirect to the login page if no valid session exists
 
+### Customizing Sign-up
+
+By default Auth0 already adds `screen_hint=signup` when a user clicks Register. To send users to a
+different page (or hide Register entirely):
+
+```typescript
+authentication: {
+  type: "auth0",
+  domain: "your-domain.us.auth0.com",
+  clientId: "<your-auth0-client-id>",
+
+  // Send Register to a separate URL (absolute → external, relative → in-app)
+  signUp: { url: "/register" },
+
+  // Or pass extra params to the Auth0 authorize URL on sign-up
+  signUp: { authorizationParams: { connection: "your-signup-connection" } },
+
+  // Hide Register UI entirely. Visual only — configure Auth0 to actually block sign-ups.
+  disableSignUp: true,
+}
+```
+
 ## Troubleshooting
 
 ### Common Issues

package/docs/dev-portal/zudoku/configuration/authentication-azure-ad.md

@@ -178,6 +178,24 @@ To allow external partners access:
 3. Invite guest users to your directory
 4. Grant appropriate permissions to your application
 
+### Customizing Sign-up
+
+Azure AD B2C usually handles sign-up via a separate user flow. To send users there, point Register
+at the URL of that flow (or any other page):
+
+```typescript
+authentication: {
+  type: "azureb2c",
+  // ...
+
+  // Absolute URL → external redirect, relative path → in-app navigate
+  signUp: { url: "https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1_SignUp/oauth2/v2.0/authorize?..." },
+
+  // Hide Register entirely. Visual only — sign-ups are still controlled by your B2C policy.
+  disableSignUp: true,
+}
+```
+
 ## User Data
 
 Azure AD provides rich user profile data through OpenID Connect:

package/docs/dev-portal/zudoku/configuration/authentication-clerk.md

@@ -84,6 +84,23 @@ that provides 10,000 monthly active users.
 
    You should also ensure your site's domain is added as an allowed origin in the Clerk dashboard.
 
+5. **Customizing Sign-up (Optional)**
+
+   To send Register to a different page, or hide it entirely:
+
+   ```typescript
+   authentication: {
+     type: "clerk",
+     clerkPubKey: "<your-clerk-publishable-key>",
+
+     // Absolute URL → external redirect, relative path → in-app navigate
+     signUp: { url: "/register" },
+
+     // Hide Register UI. Visual only — configure Clerk to actually block sign-ups.
+     disableSignUp: true,
+   },
+   ```
+
 </Stepper>
 
 ## Troubleshooting

package/docs/dev-portal/zudoku/configuration/authentication-firebase.md

@@ -52,6 +52,13 @@ export default {
     // "microsoft", "apple", "yahoo", "password", "emailLink"
     // If not specified, all enabled providers in Firebase will be available
     providers: ["google", "github", "password"],
+    // Optional: disable the sign-up UI for invite-only setups. Defaults to false.
+    // When true, the Register button and "Sign up" link are hidden, and /signup shows a message.
+    // Visual only — also disable sign-ups in your Firebase project for real enforcement.
+    disableSignUp: true,
+    // Optional: send Register to a separate URL instead of /signup
+    // (absolute URL → external redirect, relative path → in-app navigate)
+    signUp: { url: "/register" },
     // Optional: configure redirect URLs after authentication
     redirectToAfterSignIn: "/docs",
     redirectToAfterSignUp: "/getting-started",

package/docs/dev-portal/zudoku/configuration/authentication-openid.md

@@ -92,6 +92,33 @@ You can confirm your issuer URL is correct by opening `<issuer>/.well-known/open
 a browser. It should return a JSON document listing `authorization_endpoint`, `token_endpoint`,
 `userinfo_endpoint`, and `jwks_uri`.
 
+## Customizing Sign-up
+
+By default Register and Sign in both call the OIDC authorize endpoint, so users land on the same
+login page. Two options change that:
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "<the-issuer-url>",
+
+    // Send Register to a separate URL (absolute → external redirect, relative → in-app navigate)
+    signUp: { url: "/register" },
+
+    // Or pass extra params to the authorize URL on sign-up only (e.g. Keycloak)
+    signUp: { authorizationParams: { kc_action: "register" } },
+
+    // Hide Register UI entirely. Visual only — still configure your IdP to block sign-ups.
+    disableSignUp: true,
+  },
+}
+```
+
+When `disableSignUp` is `true`, the Register button on the protected-route login dialog is hidden
+and `/signup` shows an "Invitation required" page.
+
 ## User Profile
 
 After sign-in Dev Portal calls the provider's

package/docs/dev-portal/zudoku/configuration/authentication-supabase.md

@@ -247,6 +247,16 @@ authentication: {
   // Optional: When true, sign-in and sign-up pages show only OAuth buttons (no email/password)
   onlyThirdPartyProviders: true,
 
+  // Optional: When true, the sign-up UI is disabled (for invite-only setups).
+  // Must also be disabled in the Supabase dashboard under
+  // Authentication → Configuration → Sign In / Providers → Allow new users to sign up.
+  // Defaults to false.
+  disableSignUp: true,
+
+  // Optional: send Register to a separate URL instead of /signup
+  // (absolute URL → external redirect, relative path → in-app navigate)
+  signUp: { url: "/register" },
+
   // Optional: Redirect URLs after authentication events
   redirectToAfterSignUp: "/welcome",
   redirectToAfterSignIn: "/dashboard",
@@ -311,6 +321,31 @@ CREATE TRIGGER on_auth_user_created
   FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();
 ```
 
+## Invite-only sign-ups
+
+To launch an invite-only portal where new users can only be created by an admin, set
+`disableSignUp: true` in your Dev Portal config **and** disable new sign-ups in the Supabase dashboard
+(**Authentication** → **Configuration** → **Sign In / Providers** → clear **Allow new users to sign
+up**). When `disableSignUp` is `true`:
+
+- The "Don't have an account? Sign up." link is hidden on the sign-in page.
+- The Register button is hidden on the protected-route login dialog.
+- Navigating to `/signup` shows an "Invitation required" message instead of a form.
+
+```ts title="zudoku.config.ts"
+export default {
+  authentication: {
+    type: "supabase",
+    supabaseUrl: "https://your-project.supabase.co",
+    supabaseKey: "<your-publishable-key>",
+    disableSignUp: true,
+  },
+};
+```
+
+Create users directly from the Supabase dashboard (**Authentication** → **Users** → **Add user**) or
+via the Supabase admin API.
+
 ## Troubleshooting
 
 ### Common Issues

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

@@ -183,6 +183,22 @@ The `url` should be a template where the file path will be appended. For example
 in a `docs/pages/` directory, the URL might be
 `https://github.com/your-org/your-repo/edit/main/docs/pages`.
 
+#### `fullWidth`
+
+**Type:** `boolean` **Default:** `false`
+
+Whether pages should use the full available width (hiding the table of contents sidebar) by default.
+When enabled, the table of contents is accessible via an "On this page" toggle in the page header.
+Combine with `toc: false` to hide the table of contents entirely.
+
+```tsx title="zudoku.config.tsx"
+docs: {
+  defaultOptions: {
+    fullWidth: true, // Use full-width layout for all pages by default
+  }
+}
+```
+
 #### `copyPage`
 
 **Type:** `boolean` **Default:** `undefined`