zuplo 6.68.9 → 6.68.15

package/docs/articles/monetization/meters.mdx

@@ -43,14 +43,17 @@ Track the total number of API requests:
 }
 ```
 
-Each event contains the subscription ID as the `subject` and a `total` field
-with the quantity to record:
+Each event contains the `subscription` ID linking it to a subscription and a
+`total` field in `data` with the quantity to record:
 
 ```json
 {
+  "id": "5c10fade-1c9e-4d6c-8275-c52c36731d3c",
+  "specversion": "1.0",
   "type": "requests",
-  "subject": "sub_xxxxxxxx",
   "source": "monetization-policy",
+  "subject": "customer-id",
+  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 1
   }
@@ -76,9 +79,12 @@ configured to report 50 tokens per request:
 
 ```json
 {
+  "id": "a1b2c3d4-5678-4abc-8def-1234567890ab",
+  "specversion": "1.0",
   "type": "tokens",
-  "subject": "sub_xxxxxxxx",
   "source": "monetization-policy",
+  "subject": "customer-id",
+  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 50
   }
@@ -99,6 +105,22 @@ Track bytes transferred:
 }
 ```
 
+Each event reports the number of bytes transferred:
+
+```json
+{
+  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "specversion": "1.0",
+  "type": "data_transfer",
+  "source": "monetization-policy",
+  "subject": "customer-id",
+  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
+  "data": {
+    "total": 4096
+  }
+}
+```
+
 ## Naming Consistency
 
 The meter `eventType` must match the key used in three places:

package/docs/articles/monetization/troubleshooting.md

@@ -155,7 +155,7 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/meters/{meterIdOrSlug}
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "subject": "{SUBSCRIPTION_ID}",
+    "filterSubscription": ["{SUBSCRIPTION_ID}"],
     "from": "2026-03-01T00:00:00Z",
     "to": "2026-03-31T23:59:59Z",
     "windowSize": "DAY"

package/docs/articles/troubleshooting-slow-responses.mdx

@@ -234,6 +234,76 @@ performance. Use it to:
 - Spot error rate spikes that may correlate with latency issues
 - Track request volume trends that may indicate capacity-related slowness
 
+### OpenTelemetry Tracing
+
+For the most detailed view of where time is spent in your request pipeline,
+enable [OpenTelemetry tracing](./opentelemetry.mdx). The OpenTelemetry plugin
+automatically instruments your API and provides span-level timing for each stage
+of the request lifecycle — including inbound policies, the handler, outbound
+policies, and any subrequests made via `fetch` in custom code.
+
+<EnterpriseFeature name="OpenTelemetry" />
+
+With tracing enabled, you can see exactly how long each policy and handler takes
+to execute, making it straightforward to identify which component is adding
+latency. The plugin also supports W3C trace propagation, so you can follow a
+request all the way from the client through Zuplo to your backend.
+
+To get started, add the `OpenTelemetryPlugin` in your `zuplo.runtime.ts` file
+and configure it to export trace data to any OpenTelemetry-compatible service
+such as [Honeycomb](https://honeycomb.io), [Dynatrace](https://dynatrace.com),
+[Jaeger](https://www.jaegertracing.io/), or an
+[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/):
+
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      exporter: {
+        url: "https://otel-collector.example.com/v1/traces",
+        headers: {
+          "api-key": environment.OTEL_API_KEY,
+        },
+      },
+      service: {
+        name: "my-api",
+        version: "1.0.0",
+      },
+    }),
+  );
+}
+```
+
+You can also add custom spans within your policies to trace specific operations:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { trace } from "@opentelemetry/api";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const tracer = trace.getTracer("my-tracer");
+  return tracer.startActiveSpan("my-custom-operation", async (span) => {
+    span.setAttribute("endpoint", request.url);
+
+    try {
+      // ... policy logic with external calls ...
+      return request;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+For the full configuration reference, including sampling, post-processing, and
+logging, see the [OpenTelemetry documentation](./opentelemetry.mdx).
+
 ### Logging Integrations
 
 For deeper analysis, configure one of Zuplo's
@@ -290,6 +360,8 @@ back-and-forth diagnostic questions.
 
 ## Related Resources
 
+- [OpenTelemetry](./opentelemetry.mdx) — Distributed tracing and logging for
+  detailed request lifecycle visibility
 - [Performance Testing Your API Gateway](./performance-testing.mdx) — How to
   benchmark and compare gateway performance accurately
 - [Proactive Monitoring](./monitoring-your-gateway.mdx) — Setting up health

package/docs/cli/custom-domain-create.mdx

@@ -0,0 +1,91 @@
+---
+title: "Zuplo CLI: Custom Domain Create"
+sidebar_label: custom-domain create
+---
+
+<CliCommand
+  command="custom-domain create"
+  description="Creates a custom domain in your account"
+  options={[
+  {
+    "name": "hostname",
+    "type": "string",
+    "description": "The hostname for the custom domain",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "deployment-name",
+    "type": "string",
+    "description": "The deployment name to assign the custom domain to",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "custom-domain-type",
+    "type": "string",
+    "description": "The type of custom domain to create. Defaults to api server-side.",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "choices": [
+      "api",
+      "dev-portal"
+    ]
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account 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 custom-domain create --hostname api.example.com",
+    "Create an unassigned custom domain"
+  ],
+  [
+    "$0 custom-domain create --hostname api.example.com --output json",
+    "Create a custom domain and output the result as JSON"
+  ],
+  [
+    "$0 custom-domain create \\\n  --hostname api.example.com \\\n  --deployment-name production-deployment",
+    "Create and assign a custom domain to a deployment"
+  ],
+  [
+    "$0 custom-domain create \\\n  --hostname docs.example.com \\\n  --deployment-name production-deployment \\\n  --custom-domain-type dev-portal \\\n  --account my-account",
+    "Create a dev portal custom domain on a specific account"
+  ]
+]}
+  usage="$0 custom-domain create --hostname <hostname> [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/custom-domain-delete.mdx

@@ -0,0 +1,79 @@
+---
+title: "Zuplo CLI: Custom Domain Delete"
+sidebar_label: custom-domain delete
+---
+
+<CliCommand
+  command="custom-domain delete"
+  description="Deletes a custom domain in your account"
+  options={[
+  {
+    "name": "hostname",
+    "type": "string",
+    "description": "The hostname for the custom domain",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "deployment-name",
+    "type": "string",
+    "description": "The deployment name for assigned domains. Required when the hostname is assigned to multiple deployments.",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account 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 custom-domain delete --hostname api.example.com",
+    "Delete an unassigned custom domain or auto-resolve a single deployment assignment"
+  ],
+  [
+    "$0 custom-domain delete --hostname api.example.com --output json",
+    "Delete a custom domain and output the result as JSON"
+  ],
+  [
+    "$0 custom-domain delete \\\n  --hostname api.example.com \\\n  --deployment-name production-deployment",
+    "Delete a deployment-assigned custom domain explicitly"
+  ],
+  [
+    "$0 custom-domain delete \\\n  --hostname docs.example.com \\\n  --deployment-name portal-deployment \\\n  --account my-account",
+    "Delete a custom domain from a specific account"
+  ]
+]}
+  usage="$0 custom-domain delete --hostname <hostname> [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/custom-domain-list.mdx

@@ -0,0 +1,59 @@
+---
+title: "Zuplo CLI: Custom Domain List"
+sidebar_label: custom-domain list
+---
+
+<CliCommand
+  command="custom-domain list"
+  description="Lists the custom domains in your account"
+  options={[
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account 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 custom-domain list",
+    "List all custom domains"
+  ],
+  [
+    "$0 custom-domain list --output json",
+    "List all custom domains as JSON"
+  ],
+  [
+    "$0 custom-domain list --account my-account",
+    "Explicitly specify the account"
+  ]
+]}
+  usage="$0 custom-domain 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/custom-domain-update.mdx

@@ -0,0 +1,79 @@
+---
+title: "Zuplo CLI: Custom Domain Update"
+sidebar_label: custom-domain update
+---
+
+<CliCommand
+  command="custom-domain update"
+  description="Updates the deployment assignment for a custom domain"
+  options={[
+  {
+    "name": "hostname",
+    "type": "string",
+    "description": "The hostname for the custom domain",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "deployment-name",
+    "type": "string",
+    "description": "The deployment name to assign the custom domain to. Omit to detach the current assignment.",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account 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 custom-domain update \\\n  --hostname api.example.com \\\n  --deployment-name production-deployment",
+    "Reassign a custom domain to a deployment"
+  ],
+  [
+    "$0 custom-domain update --hostname api.example.com --output json",
+    "Update a custom domain and output the result as JSON"
+  ],
+  [
+    "$0 custom-domain update --hostname api.example.com",
+    "Detach the current deployment assignment while preserving the stage"
+  ],
+  [
+    "$0 custom-domain update \\\n  --hostname docs.example.com \\\n  --deployment-name portal-deployment \\\n  --account my-account",
+    "Update a custom domain on a specific account"
+  ]
+]}
+  usage="$0 custom-domain update --hostname <hostname> [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/dev-portal/zudoku/configuration/api-catalog.md

@@ -99,8 +99,8 @@ const config = {
   catalogs: {
     path: "/catalog",
     label: "API Catalog",
-    filterItems: (items, { auth: AuthState }) => {
-      return items.filter((items) => items.tags.includes(auth));
+    filterItems: (items, { auth }) => {
+      return items.filter((item) => item.tags.includes("public"));
     },
   },
   // ...

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

@@ -201,11 +201,12 @@ const config = {
     options: {
       examplesLanguage: "shell", // Default language for code examples
       supportedLanguages: [
-        { label: "cURL", language: "shell" },
-        { label: "JavaScript", language: "javascript" },
+        { value: "shell", label: "cURL" },
+        { value: "javascript", label: "JavaScript" },
       ],
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
+      disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: true, // Control initial expanded state of tag categories
       showInfoPage: true, // Show API information page as the index route
@@ -220,10 +221,13 @@ const config = {
 Available options:
 
 - `examplesLanguage`: Set default language for code examples
-- `supportedLanguages`: Array of language options for code examples. Each option has `label`
-  (display name) and `language` (code identifier)
+- `supportedLanguages`: Array of language options for code examples. Each option has `value` (code
+  identifier) and `label` (display name)
 - `disablePlayground`: Disable the interactive API playground globally
 - `disableSidecar`: Disable the sidecar panel completely
+- `disableSecurity`: Disable OpenAPI security scheme display (auth badges on operations, security
+  schemes section on the info page, and the Authorize dialog in the playground). Disabled by default
+  (`true`). Set to `false` to enable security scheme support
 - `showVersionSelect`: Control version selector visibility
   - `"if-available"`: Show version selector only when multiple versions exist (default)
   - `"always"`: Always show version selector (disabled if only one version)
@@ -251,6 +255,7 @@ const config = {
       examplesLanguage: "shell", // Default language for code examples
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
+      disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: false, // Control initial expanded state of tag categories
       showInfoPage: true, // Show API information page as the index route

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

@@ -160,8 +160,8 @@ When the prompt parameter is omitted (empty string), Auth0 will:
 
 2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
 
-3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
-   trailing slash.
+3. **Authentication Loop**: Check that your Auth0 domain is a plain hostname only (e.g.,
+   `your-domain.us.auth0.com`) without a protocol prefix (`https://`) or trailing slash.
 
 4. **Token Validation Errors**: Ensure the audience in your Dev Portal configuration matches the
    identifier of the Auth0 API you created.

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

@@ -44,9 +44,8 @@ to integrate Azure AD with your Dev Portal documentation site.
      - Production: `https://your-site.com/oauth/callback`
      - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
      - Local Development: `http://localhost:3000/oauth/callback`
-   - Under **Implicit grant and hybrid flows**:
-     - Enable **ID tokens**
-     - Enable **Access tokens**
+   - **Implicit grant and hybrid flows** should remain **disabled** — Dev Portal uses the more secure
+     Authorization Code flow with PKCE
    - Configure **Supported account types** if needed
    - Save your changes
 
@@ -82,14 +81,6 @@ to integrate Azure AD with your Dev Portal documentation site.
    };
    ```
 
-5. **Install Azure AD Dependencies**
-
-   Add `@azure/msal-browser` to your project dependencies:
-
-   ```bash
-   npm install @azure/msal-browser
-   ```
-
 </Stepper>
 
 ## Configuration Options
@@ -217,8 +208,8 @@ Azure AD provides rich user profile data through OpenID Connect:
 5. **Token Validation Errors**: Ensure your issuer URL is correct and includes the `/v2.0` endpoint
    for the Microsoft identity platform.
 
-6. **Authentication Not Working**: Make sure you have installed `@azure/msal-browser` to your
-   project.
+6. **Authentication Not Working**: Verify your issuer URL and client ID are correct, and that your
+   app registration is configured as a Single-page application (SPA) with the correct redirect URIs.
 
 ## Security Best Practices
 

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

@@ -68,23 +68,23 @@ that provides 10,000 monthly active users.
 
 4. **Configure Redirect URLs (Optional)**
 
-   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
-   - Go to **Paths** in your Clerk dashboard
-   - Add your production, preview, and local development URLs to the allowed redirect URLs
-   - Common patterns:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
+   If you need custom redirect behavior after sign-in or sign-up, you can configure this in your
+   Dev Portal config:
 
-5. **Install Clerk Dependencies**
-
-   Add `@clerk/clerk-js` to your project dependencies:
-
-   ```bash
-   npm install @clerk/clerk-js
+   ```typescript
+   authentication: {
+     type: "clerk",
+     clerkPubKey: "<your-clerk-publishable-key>",
+     jwtTemplateName: "<your-clerk-jwt-template-name>",
+     redirectToAfterSignIn: "/docs",
+     redirectToAfterSignUp: "/getting-started",
+     redirectToAfterSignOut: "/",
+   },
    ```
 
-   </Stepper>
+   You should also ensure your site's domain is added as an allowed origin in the Clerk dashboard.
+
+</Stepper>
 
 ## Troubleshooting
 
@@ -99,8 +99,9 @@ that provides 10,000 monthly active users.
 3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
    using custom redirects.
 
-4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
-   have installed Clerk to your project.
+4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: This can happen
+   if the Clerk CDN script fails to load. Check your network connectivity and ensure your
+   publishable key is valid.
 
 ## Next Steps
 

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

@@ -49,7 +49,7 @@ export default {
     measurementId: "G-12W6TTNR75",
     // Optional: specify which providers to show in the sign-in UI
     // Available providers: "google", "github", "facebook", "twitter",
-    // "microsoft", "apple", "yahoo", "password", "phone"
+    // "microsoft", "apple", "yahoo", "password", "emailLink"
     // If not specified, all enabled providers in Firebase will be available
     providers: ["google", "github", "password"],
     // Optional: configure redirect URLs after authentication