zuplo 6.69.0 → 6.69.2

package/docs/articles/environment-variables.mdx

@@ -64,11 +64,26 @@ variable named `MY_VAR` can't be set on say the **Production** environments.
 
 ## Reserved Environment Variables
 
-Environment variables can't start with `ZUPLO` or `__ZUPLO`.
+Environment variables can't start with `ZUPLO_` or `__ZUPLO`. The same
+restriction applies to names beginning with `ZUDOKU_`.
+
+If you need a variable that's exposed to the
+[Developer Portal](../dev-portal/introduction.mdx) build, prefix it with
+`ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`). Public-prefixed variables are bundled
+into the portal's static output and **must not contain secrets**, as they're
+visible to anyone who loads the page.
 
 ## Using Environment Variables
 
-Environment variables can be used in several places within your Zuplo project:
+Environment variables can be used in several places in your Zuplo project. Each
+location has its own syntax:
+
+| Location                                              | Syntax                 | Resolved              |
+| ----------------------------------------------------- | ---------------------- | --------------------- |
+| Custom code (handlers, policies, hooks)               | `environment.VAR_NAME` | Runtime               |
+| Configuration files (`policies.json`, OpenAPI routes) | `$env(VAR_NAME)`       | Build time            |
+| URL Rewrite, URL Forward, and WebSocket handlers      | `${env.VAR_NAME}`      | Runtime (per request) |
+| Developer Portal config (`zudoku.config.ts`)          | `process.env.VAR_NAME` | Portal build time     |
 
 ### In Code
 
@@ -77,13 +92,44 @@ See the
 [Environment Variables API Reference](../programmable-api/environment.mdx) for
 detailed usage examples and patterns.
 
+```ts
+import { environment } from "@zuplo/runtime";
+
+const apiKey = environment.API_KEY; // string | undefined
+```
+
 ### In Configuration Files
 
-Inside some configuration files, environment variables can be referenced with
-the pattern `$env(MY_VAR)`.
+Inside policy options, route handler options, and CORS policy options,
+environment variables can be referenced with the `$env(VAR_NAME)` pattern.
+Substitutions happen at build time — the build replaces each `$env()` expression
+with a reference to the runtime `environment` object before the project is
+deployed.
+
+#### Where `$env()` is allowed
+
+- `config/policies.json` — any property under `policies[].handler.options`,
+  including nested objects and array elements
+- `config/policies.json` — any direct property of a `corsPolicies[]` entry, such
+  as `allowedOrigins`, `allowedHeaders`, `allowedMethods`, `exposeHeaders`, and
+  `maxAge`
+- `config/routes.oas.json` (and other OpenAPI route files) — any property under
+  a route's `x-zuplo-route.handler.options`, including nested objects and array
+  elements
+
+`$env()` is **not** allowed in other locations such as policy `name`,
+`policyType`, `module`, route paths, or top-level OpenAPI fields. Using it
+elsewhere produces a build error:
+
+```text
+An $env() statement is not expected at this location.
+```
+
+#### Standalone substitution
 
-For example, in the `policies.json` file, an environment variable could be set
-on a policy option.
+When the value is _only_ an `$env()` expression, the variable's value is
+inserted directly. The runtime type matches the type of the environment variable
+(always a string when set, `undefined` when not).
 
 ```json
 {
@@ -93,23 +139,130 @@ on a policy option.
     "export": "default",
     "module": "$import(./modules/YOUR_MODULE)",
     "options": {
-      "config1": "$env(MY_CONFIG_VAR)",
+      "apiKey": "$env(BACKEND_API_KEY)",
       "config2": true
     }
   }
 }
 ```
 
-### Rewrite & Forwarding Handler
+#### String interpolation
+
+You can mix `$env()` with literal text to compose a value. The build wraps the
+result in a JavaScript template literal that's evaluated at runtime, so each
+request gets the current value of the variable.
+
+```json
+{
+  "options": {
+    "endpoint": "https://$env(API_HOST)/v1",
+    "userAgent": "MyGateway/$env(APP_VERSION) ($env(ENVIRONMENT_NAME))"
+  }
+}
+```
+
+:::note
+
+If the variable isn't set, the interpolated portion resolves to an empty string.
+For example, with `API_HOST` unset, `"https://$env(API_HOST)/v1"` becomes
+`"https:///v1"`. Use a standalone `$env()` (no surrounding text) if you need to
+detect an unset variable in your handler or policy code.
+
+:::
+
+#### In arrays
+
+`$env()` works inside string array elements, including mixed arrays where some
+elements are static and others are interpolated:
+
+```json
+{
+  "options": {
+    "allowedKeys": ["$env(PRIMARY_KEY)", "$env(SECONDARY_KEY)"],
+    "tags": ["public", "$env(REGION)", "tier-$env(SERVICE_TIER)"]
+  }
+}
+```
+
+#### In nested objects
+
+`$env()` works at any depth within a handler or policy `options` object:
+
+```json
+{
+  "options": {
+    "database": {
+      "host": "$env(DB_HOST)",
+      "credentials": {
+        "username": "$env(DB_USER)",
+        "password": "$env(DB_PASSWORD)"
+      }
+    }
+  }
+}
+```
+
+#### Variable name rules
+
+The name inside `$env(...)` is matched literally up to the first closing
+parenthesis. Use only letters, digits, and underscores in the name — matching
+what the [Zuplo Portal](#environment-variable-editor) accepts when you create
+the variable.
+
+### Rewrite, Forwarding, and WebSocket Handlers
+
+The URL Rewrite handler's `rewritePattern`, the URL Forward handler's `baseUrl`,
+and the WebSocket handler's `rewritePattern` use a different syntax. These
+options are evaluated as JavaScript template literals at request time, so you
+reference variables with `${env.VAR_NAME}`:
+
+```json
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "https://${env.BACKEND_HOST}"
+    }
+  }
+}
+```
+
+Because `rewritePattern` and `baseUrl` run as code, they also have access to the
+request, URL parts, route params, and query string. See the
+[URL Rewrite Handler](../handlers/url-rewrite.mdx) docs for the full list of
+available variables.
 
-When referencing environment variables inside of the URL Rewrite handler and the
-URL Forward handler, variables are substituted using JavaScript style string
-interpolation.
+:::caution
 
-```txt
-https://${env.API_URL}/path/to/call
+Using `$env(VAR_NAME)` inside `rewritePattern` or `baseUrl` is the most common
+mistake. The build will warn you when it detects this, but the value will be
+passed through to the handler as a literal string and the rewrite will fail at
+runtime. Always use `${env.VAR_NAME}` in these two options.
+
+:::
+
+### In the Developer Portal
+
+The Developer Portal's `zudoku.config.ts` runs in Node-like build tooling and
+uses `process.env` rather than `$env()`:
+
+```ts title="zudoku.config.ts"
+const config: ZudokuConfig = {
+  authentication: {
+    type: "auth0",
+    domain: process.env.ZUPLO_PUBLIC_AUTH0_DOMAIN,
+    clientId: process.env.ZUPLO_PUBLIC_AUTH0_CLIENT_ID,
+  },
+};
+
+export default config;
 ```
 
+Only variables prefixed with `ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`) are available
+in the portal build, and their values are embedded into the client-side bundle.
+Don't use this prefix for any value that should remain private.
+
 ## System Environment Variables
 
 The following variables are automatically set by the system and are available to

package/docs/articles/monetization/meters.mdx

@@ -35,9 +35,9 @@ Track the total number of API requests:
 
 ```json
 {
-  "slug": "requests",
+  "slug": "api_requests",
   "name": "API Requests",
-  "eventType": "requests",
+  "eventType": "api_requests",
   "aggregation": "SUM",
   "valueProperty": "$.total"
 }
@@ -50,7 +50,7 @@ Each event contains the `subscription` ID linking it to a subscription and a
 {
   "id": "5c10fade-1c9e-4d6c-8275-c52c36731d3c",
   "specversion": "1.0",
-  "type": "requests",
+  "type": "api_requests",
   "source": "monetization-policy",
   "subject": "customer-id",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
@@ -142,9 +142,9 @@ curl \
   --header "Content-Type: application/json" \
   --data @- << EOF
 {
-  "slug": "requests",
+  "slug": "api_requests",
   "name": "API Requests",
-  "eventType": "requests",
+  "eventType": "api_requests",
   "aggregation": "SUM",
   "valueProperty": "$.total"
 }

package/docs/articles/monetization/quickstart.md

@@ -84,7 +84,8 @@ Add the monetization plugin to your Developer Portal configuration.
 ## Step 3: Configure the Monetization Service
 
 1. Navigate to the **Services** tab in your project.
-2. Select the environment you want to configure (e.g., **Working Copy**).
+2. Select the environment you want to configure. We will use **Working Copy**
+   for this quickstart.
 3. Click **Configure** on the **Monetization Service** card.
 
 ## Step 4: Create a meter
@@ -93,11 +94,11 @@ Meters track what you want to measure — API calls, tokens processed, data
 transferred, etc.
 
 1. In the Monetization Service, click the **Meters** tab.
-2. Click **Add Meter** and select **Blank Meter**.
-3. Fill in the meter details:
-   - **Name**: `Requests`
-   - **Event**: `requests` — the type of event this meter listens for.
-   - **Description**: `API Requests`
+2. Click **Add Meter** and select **API Requests** from the template list.
+3. Verify the pre-filled meter details:
+   - **Name**: `API Requests`
+   - **Event**: `api_requests` — the type of event this meter listens for.
+   - **Description**: `Counts all incoming API requests`
    - **Aggregation**: `SUM` — how values are combined (other options include
      `COUNT`, `MAX`, etc.).
    - **Value Property**: `$.total` — a JSONPath expression that extracts the
@@ -115,15 +116,18 @@ Feature** for each of the following:
 
 | Name             | Key                | Linked Meter | Purpose                       |
 | ---------------- | ------------------ | ------------ | ----------------------------- |
-| API Requests     | `requests`         | Requests     | Usage-based (linked to meter) |
+| API Requests     | `api_requests`     | API Requests | Usage-based (linked to meter) |
 | Monthly Fee      | `monthly_fee`      | —            | Flat-rate billing             |
 | Metadata Support | `metadata_support` | —            | Boolean on/off feature        |
 
 :::tip{title="Key Naming Conventions"}
 
-When creating features that are metered, the key must match the key you set for
-the associated meter. For example, if your Requests meter key is `requests`,
-then your Requests feature key must also be `requests`.
+The meter key, the feature key, and the key in the monetization policy's
+`meters` configuration must all match. For example, the API Requests meter key
+is `api_requests`, the feature key must also be `api_requests`, and the policy
+must use `"meters": { "api_requests": 1 }`.
+
+See [Naming Consistency](./meters.mdx#naming-consistency) for the full rule.
 
 :::
 
@@ -243,10 +247,13 @@ charges.
 
 :::warning
 
-Always use your Stripe **test** key (`sk_test_...`) while following this guide.
-This creates a sandbox environment where you can safely test subscriptions and
-payments without processing real transactions. When you're ready for production,
-update to your live key (`sk_live_...`).
+Always use your Stripe **test** key (`sk_test_...`) in the **Working Copy**
+environment while following this guide. Stripe test keys run in a sandbox
+environment where you can safely test subscriptions and payments without
+processing real transactions. When you're ready for production, configure the
+**Production** environment with a live key (`sk_live_...`). Do not replace a
+test key with a live key in the same environment — use one key type per
+environment.
 
 :::
 
@@ -265,9 +272,9 @@ directory.
 
 ![Monetization policy in the policy picker list](../../../public/media/monetization/monetization-policy.png)
 
-3. In the **Meters** configuration field, you can keep the default value of
-   `requests` set `1` to match the meter you created in _Step 4_. This field
-   maps the meter slug to the number of units each request consumes.
+3. In the **Meters** configuration field, set the key to `api_requests` with a
+   value of `1` to match the meter you created in _Step 4_. This field maps the
+   meter slug to the number of units each request consumes.
 
 ```json
 {
@@ -276,7 +283,7 @@ directory.
   "options": {
     "cacheTtlSeconds": 60,
     "meters": {
-      "requests": 1
+      "api_requests": 1
     }
   }
 }

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

@@ -54,13 +54,15 @@ Connect with a Stripe **test** key (`sk_test_...`) first to validate your
 configuration end-to-end. Test mode uses Stripe's test card numbers (e.g.,
 `4242 4242 4242 4242`) and never charges real money.
 
-When you're ready to go live, update to your live key (`sk_live_...`).
+When you're ready to go live, configure a separate Zuplo environment (e.g.,
+**Production**) with your live key (`sk_live_...`).
 
 :::caution
 
-Always use your Stripe **test** key while developing. Test mode and live mode
-are separate environments in Stripe. Products, customers, and subscriptions
-don't transfer between them.
+Use one Stripe key type per Zuplo environment — do not replace a test key with a
+live key in the same environment. Test mode and live mode are separate
+environments in Stripe. Products, customers, and subscriptions created in test
+mode don't transfer to live mode and vice versa.
 
 :::
 

package/docs/articles/tunnel-setup.mdx

@@ -22,6 +22,26 @@ A tunnel is a way to expose your _internal services_ to the Zuplo gateway
 without exposing it to the public internet. Your Zuplo Gateway accesses those
 services through the `service://` protocol.
 
+## Create the tunnel
+
+Before you deploy the tunnel container, create the tunnel in Zuplo using the
+CLI. This gives you the tunnel record in your account and the token that you
+will later provide to the container as `TUNNEL_TOKEN`.
+
+```bash
+zuplo tunnel create --tunnel-name <your-tunnel-name>
+zuplo tunnel list
+zuplo tunnel describe --tunnel-id <your-tunnel-id>
+```
+
+Use these commands as follows:
+
+1. Run `zuplo tunnel create` to create the tunnel.
+1. Run `zuplo tunnel list` to see the tunnels in your account and identify the
+   tunnel ID if you need it.
+1. Run `zuplo tunnel describe` with the tunnel ID to retrieve the tunnel details
+   and copy the token value you will use for `TUNNEL_TOKEN`.
+
 The easiest way to deploy your tunnel is using a Docker container. The three
 basic requirements for deploying a secure tunnel with Docker are:
 

package/docs/cli/whoami.mdx

@@ -0,0 +1,25 @@
+---
+title: "Zuplo CLI: Whoami"
+sidebar_label: whoami
+---
+
+<CliCommand
+  command="whoami"
+  description="Displays the currently authenticated user"
+  examples={[
+  [
+    "$0 whoami",
+    "Display the currently authenticated user"
+  ]
+]}
+  usage="$0 whoami [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/package.json

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