zuplo 6.67.32 → 6.68.0

package/docs/articles/monetization/developer-portal.md

@@ -0,0 +1,167 @@
+---
+title: Developer Portal Setup
+sidebar_label: Developer Portal
+---
+
+:::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 Developer Portal is the self-serve storefront for your monetized API.
+Customers browse plans, subscribe, manage their API keys, and monitor usage —
+all without contacting your team. The portal is built on
+[Zudoku](https://zudoku.dev), Zuplo's open-source API documentation framework.
+
+## What the portal provides
+
+Once monetization is enabled, the Developer Portal gains these pages:
+
+**Pricing page** — Displays all published plans with feature comparisons,
+pricing details, and subscribe buttons. Unauthenticated visitors see plans and
+pricing. Authenticated users see which plan they're currently on and get
+upgrade/downgrade options.
+
+**Subscription management** — Lists all of a customer's subscriptions (current
+and past), shows the current billing period, and provides
+cancel/upgrade/downgrade actions.
+
+**Usage dashboard** — Real-time view of quota consumption for the current
+billing period. Shows each metered feature's usage against its entitlement, with
+visual progress indicators.
+
+**API key management** — API keys are displayed within the context of their
+subscription. Each subscription has its own key, making it clear which key
+corresponds to which plan. Customers can regenerate keys from this page.
+
+## Prerequisites
+
+Before setting up monetization in the portal, ensure:
+
+1. **Authentication is configured** — The Developer Portal requires
+   authentication so it can identify customers. Auth0, Clerk, or custom OpenID
+   Connect providers are supported.
+2. **Meters, features, and plans are created** — At least one plan must be
+   published.
+3. **Stripe is connected** — The billing provider must be linked for payment
+   processing.
+
+## Enabling monetization in the portal
+
+Add the monetization plugin to your Developer Portal configuration. Open
+`docs/zudoku.config.tsx` in your project and add the plugin:
+
+```tsx
+import { zuploMonetizationPlugin } from "@zuplo/zudoku-plugin-monetization";
+
+const config: ZudokuConfig = {
+  // ... your existing config
+  plugins: [
+    zuploMonetizationPlugin(),
+    // ... any other plugins you have
+  ],
+};
+```
+
+Save and deploy. Once the plugin is enabled, ensure:
+
+1. Stripe is connected (see [Stripe Integration](./stripe-integration.md))
+2. At least one plan is published
+
+## Configuring the pricing page
+
+### Plan display order
+
+Control plan display order in the Zuplo Portal under **Services →
+Monetization**. Plans can be reordered using drag-and-drop.
+
+### Feature comparison matrix
+
+The pricing page automatically generates a feature comparison table from your
+plans' rate cards and features. Each plan column shows:
+
+- Monthly price (or "Free" / "Custom" for special tiers)
+- Included entitlements for each metered feature (e.g., "50,000 API Calls")
+- Static feature availability (checkmark/cross)
+- Overage pricing where applicable
+
+### Highlighted plans
+
+To highlight a plan as popular, set `popular` to `true` in the plan's metadata.
+The pricing page displays a "Popular" badge on highlighted plans.
+
+### Custom plan descriptions
+
+Plans display their `name` and `description` fields on the pricing page. Set
+these when creating or updating a plan via the API.
+
+### Handling free plans
+
+Free plans that don't require a payment method skip the Stripe Checkout flow
+entirely. Whether a plan requires a payment method is controlled by the
+`paymentMethodRequired` property on the plan itself.
+
+## Usage dashboard
+
+The usage dashboard shows real-time quota consumption for each metered feature
+on the customer's active subscription.
+
+Each meter displays:
+
+- Current usage count
+- Entitlement (quota limit)
+- Usage percentage as a progress bar
+- Billing period start and end dates
+- Overage amount (if applicable)
+
+The usage dashboard updates on each page load, showing current consumption
+against entitlements for all metered features.
+
+## Subscription management
+
+The subscriptions page shows:
+
+- **Active subscriptions** with plan name, status, current period, and API key
+- **API keys** nested under their subscription for clarity
+- **Quick actions**: Upgrade, Downgrade, Cancel, Manage Billing (opens Stripe
+  Customer Portal)
+- **Past subscriptions** with their final status and date range
+
+### API key display
+
+API keys are displayed within the context of their subscription. This is a
+deliberate design choice — in the previous version, keys and subscriptions were
+shown separately, causing confusion about which key was associated with which
+plan.
+
+Each subscription shows:
+
+- The API key value (click to reveal/copy)
+- Key creation date
+- Key status (active/revoked)
+- A "Regenerate" button
+
+When a customer regenerates a key, the old key is immediately revoked and a new
+one is issued. The new key inherits the same plan entitlements.
+
+## Theming and branding
+
+The Developer Portal inherits your project's Zudoku theme. Monetization pages
+use the same fonts, colors, and layout as the rest of your portal.
+
+## Custom domain
+
+The Developer Portal runs at `https://your-project.zuplo.dev/docs` by default.
+For production, configure a custom domain:
+
+1. Navigate to **Settings → Custom Domains** in the Zuplo Portal
+2. Add your domain (e.g., `developers.your-company.com`)
+3. Configure the DNS records as instructed
+4. SSL is provisioned automatically
+
+Your monetization pages, including the Stripe Checkout redirect flow, work
+seamlessly with custom domains.

package/docs/articles/monetization/features.mdx

@@ -0,0 +1,98 @@
+---
+title: Features
+sidebar_label: Features
+---
+
+:::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.
+
+:::
+
+Features describe what your API offers to customers. They represent the
+capabilities in your API product - access to specific endpoints, usage
+allowances, premium functionality, or any other aspect you want to track or
+gate.
+
+## Metered vs Static Features
+
+Features come in two types:
+
+- **Metered features** are linked to a meter and track consumption. Use these
+  for usage-based capabilities like API calls, tokens, or data transfer.
+- **Static features** have no meter attached. Use these for boolean capabilities
+  like "access to premium endpoints" or "priority support".
+
+## Feature Properties
+
+| Property    | Required | Description                                                            |
+| ----------- | -------- | ---------------------------------------------------------------------- |
+| `key`       | Yes      | Unique identifier (lowercase alphanumeric and underscores, 1-64 chars) |
+| `name`      | Yes      | Human-readable display name                                            |
+| `meterSlug` | No       | Links this feature to a meter for usage tracking                       |
+| `metadata`  | No       | Custom key-value pairs for your own use                                |
+
+:::note
+
+Features cannot be updated after creation - they can only be archived. Plan your
+feature structure carefully before creating them.
+
+:::
+
+## Creating a Feature
+
+Create a metered feature linked to an API requests meter:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/features \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "api_calls",
+  "name": "API Calls",
+  "meterSlug": "api_requests"
+}
+EOF
+```
+
+The response includes the created feature:
+
+```json
+{
+  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+  "key": "api_calls",
+  "name": "API Calls",
+  "meterSlug": "api_requests",
+  "createdAt": "2024-01-01T01:01:01.001Z",
+  "updatedAt": "2024-01-01T01:01:01.001Z"
+}
+```
+
+### Creating a Static Feature
+
+For features without usage tracking, omit the `meterSlug`:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/features \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "priority_support",
+  "name": "Priority Support"
+}
+EOF
+```
+
+## API Reference
+
+For complete API operations (list, get, archive), see the
+[Features API Reference](../../api/metering-features).

package/docs/articles/monetization/index.mdx

@@ -0,0 +1,113 @@
+---
+title: API Monetization with Zuplo
+sidebar_label: Overview
+---
+
+:::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.
+
+:::
+
+Zuplo's API Monetization lets you charge for your API directly from your gateway
+— no external metering services, no webhook spaghetti, no state sync headaches.
+Define your pricing, connect Stripe, and start billing. Zuplo handles metering,
+quota enforcement, and subscription management as a single integrated system.
+
+## Why monetize at the gateway?
+
+Most teams attempting API monetization cobble together three separate systems: a
+metering service to count usage, a billing platform to charge customers, and
+custom gateway logic to enforce limits. These systems inevitably drift apart. A
+customer exceeds their quota but metering hasn't synced yet. A subscription
+cancels in Stripe but the gateway still grants access. A webhook fails silently
+and invoices come out wrong.
+
+Zuplo eliminates this by making the gateway the single source of truth. Every
+request that hits your API is metered, enforced, and billed through one system.
+When a customer's quota runs out, they get a `429` immediately — not five
+minutes later when a batch job catches up.
+
+## Core concepts
+
+Zuplo Monetization is built on four primitives:
+
+**[Meters](./monetization/meters.mdx)** count things. Every API call, every
+token consumed, every byte transferred. You define what to count and how to
+aggregate it (count events or sum a value from the response).
+
+**[Features](./monetization/features.mdx)** connect meters to your product
+catalog. A metered feature like "API Calls" links to a meter and enables quota
+tracking. A static feature like "Priority Support" is a simple on/off toggle —
+the customer either has it or doesn't.
+
+**[Plans](./monetization/plans.mdx)** are subscription tiers your customers
+purchase. Each plan contains one or more phases with rate cards that define
+pricing and entitlements. Plans support versioning, multiple currencies, and
+configurable billing cadences (monthly, quarterly, annual).
+
+**[Rate cards](./monetization/rate-cards.mdx)** are the pricing atoms within a
+plan phase. Each rate card ties a feature to a price and specifies the
+entitlement: how much the customer gets, whether the limit is hard (blocked at
+quota) or soft (overage billing), and what
+[pricing model](./monetization/pricing-models.mdx) applies (flat fee, per-unit,
+tiered, volume, or package).
+
+## Supported billing models
+
+| Model                    | How it works                                                                    | Example                                       |
+| ------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------- |
+| **Fixed monthly quotas** | Flat monthly price with included allowance. Hard limit at quota.                | $99/mo for 10,000 requests                    |
+| **Pay-as-you-go**        | No upfront cost. Bill in arrears for actual usage.                              | $0.01 per request, billed monthly             |
+| **Quotas with overages** | Monthly price for base allowance. Overage billed per-unit in arrears.           | $99/mo for 10K requests + $0.005/request over |
+| **Credits / tokens**     | Prepaid credit bundles that burn down with usage. Service stops when exhausted. | Buy 50,000 credits for $49                    |
+
+Plans can combine multiple billing models and support free tiers, free trials
+with automatic conversion to paid, and multiple subscriptions per customer.
+
+## What you get
+
+- **Built-in metering** — Count requests, tokens, bytes, or any custom
+  dimension. No external metering service required.
+- **Real-time quota enforcement** — Customers hitting their limit get a
+  `429 Too Many Requests` response instantly, not after a batch sync.
+- **Stripe billing integration** — Subscriptions, invoicing, and payment
+  collection handled by Stripe. Zuplo keeps access state synchronized
+  automatically.
+- **Self-serve Developer Portal** — Pricing page, plan selection, checkout,
+  subscription management, usage dashboards, and API key management built into
+  the Zudoku-powered portal.
+- **Programmable everything** — Custom policies, webhooks, and the Zuplo
+  Developer API give you full control when the defaults aren't enough.
+- **Trial and phase support** — Model free trials that auto-convert to paid
+  plans without writing transition logic.
+
+## Getting started
+
+Follow the [Quickstart Guide](./monetization/quickstart.md) to go from zero to a
+monetized API in under 30 minutes. You'll create meters, define a plan with
+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, and API 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           |
+| [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

@@ -0,0 +1,135 @@
+---
+title: Meters
+sidebar_label: Meters
+---
+
+:::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.
+
+:::
+
+Meters aggregate usage data from your API. They watch for specific event types,
+extract numeric values, and sum them over configurable time windows.
+
+## How Meters Work
+
+A meter is configured with:
+
+- **Event type** - Which events to process (e.g., `requests`, `tokens`)
+- **Value property** - JSONPath to extract the numeric value from event data.
+  Events use `$.total` as the standard value property.
+- **Aggregation** - How to combine values (typically `SUM`)
+
+When events are ingested, the meter matches events by type, extracts the
+specified value, and aggregates it per customer over time.
+
+## Common Examples
+
+### API Request Counting
+
+Track the total number of API requests:
+
+```json
+{
+  "slug": "requests",
+  "name": "API Requests",
+  "eventType": "requests",
+  "aggregation": "SUM",
+  "valueProperty": "$.total"
+}
+```
+
+Each event contains the subscription ID as the `subject` and a `total` field
+with the quantity to record:
+
+```json
+{
+  "type": "requests",
+  "subject": "sub_xxxxxxxx",
+  "source": "monetization-policy",
+  "data": {
+    "total": 1
+  }
+}
+```
+
+### Token Usage
+
+Track token consumption for AI applications:
+
+```json
+{
+  "slug": "tokens",
+  "name": "Token Usage",
+  "eventType": "tokens",
+  "aggregation": "SUM",
+  "valueProperty": "$.total"
+}
+```
+
+Each event reports a fixed quantity per request. For example, if a meter is
+configured to report 50 tokens per request:
+
+```json
+{
+  "type": "tokens",
+  "subject": "sub_xxxxxxxx",
+  "source": "monetization-policy",
+  "data": {
+    "total": 50
+  }
+}
+```
+
+### Data Transfer
+
+Track bytes transferred:
+
+```json
+{
+  "slug": "data_transfer",
+  "name": "Data Transfer (bytes)",
+  "eventType": "data_transfer",
+  "aggregation": "SUM",
+  "valueProperty": "$.total"
+}
+```
+
+## Naming Consistency
+
+The meter `eventType` must match the key used in three places:
+
+1. The meter's `slug` and `eventType`
+2. The key in the monetization policy's `meters` configuration
+3. The `featureKey` on the plan's entitlement
+
+If these don't match, usage is not tracked correctly against the subscription's
+entitlements.
+
+## Creating a Meter
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/meters \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "slug": "requests",
+  "name": "API Requests",
+  "eventType": "requests",
+  "aggregation": "SUM",
+  "valueProperty": "$.total"
+}
+EOF
+```
+
+## API Reference
+
+For complete API operations (list, get, update, delete), see the
+[Meters API Reference](../../api/metering-meters).