zuplo 6.71.25 → 6.71.27

package/docs/articles/accounts/audit-logs.mdx

@@ -10,13 +10,6 @@ account, helping you track changes and maintain compliance requirements. Every
 change performed in your account is logged with detailed information about who
 performed the change, when it occurred, and what resources were affected.
 
-:::note{title="Beta Feature"}
-
-Audit logs are currently in beta. During the beta period not all events may be
-captured. Full coverage is in progress.
-
-:::
-
 ## Overview
 
 Audit logs capture critical events across your Zuplo infrastructure, including:

package/docs/dedicated/federated-gateways.mdx

@@ -3,13 +3,6 @@ title: "Managed Dedicated: Federated Gateways"
 sidebar_label: Federated Gateways
 ---
 
-:::note{title="Beta Feature"}
-
-This feature is in Beta - please use with care and provide feedback to the team
-if you encounter any issues.
-
-:::
-
 <EnterpriseFeature name="Federated Gateways" />
 
 With a managed dedicated Zuplo instance you can create a federated gateway that
@@ -30,7 +23,7 @@ Federated gateways are useful for several reasons:
 - **Versioning**: You can use federated gateways to manage different versions of
   your API. For example, if you wanted to run a new version of your API
   alongside the old one and route requests to specific versions based on user or
-  other context you can keep different versions in separate Zuplo projects.
+  other context, you can keep different versions in separate Zuplo projects.
 - **Risk Minimization**: By separating different parts of your API into
   different Zuplo projects, you can reduce the risk of causing inadvertent
   changes to other parts of the API. This can be especially useful if your API

package/docs/mcp-gateway/cross-app-access/overview.mdx

@@ -8,13 +8,6 @@ description: |
   have to.
 ---
 
-:::note{title="Beta"}
-
-Cross App Access support is in beta. The configuration model and policy options
-may change before general availability.
-
-:::
-
 Cross App Access (XAA) lets one application reach another application's API on a
 user's behalf **through the identity provider both apps already trust** —
 instead of running a separate, point-to-point OAuth connection between them. For

package/docs/mcp-server/openai-apps-sdk.mdx

@@ -21,13 +21,6 @@ emits the UI.
 
 :::
 
-:::warning
-
-The OpenAI Apps SDK and support for it in Zuplo's `mcpServerHandler` is in beta
-and subject to change!
-
-:::
-
 ## `tools`
 
 MCP tools define the functionality of your app. Zuplo MCP servers support tools

package/docs/policies/_index.md

@@ -17,7 +17,7 @@
 | archive-request-gcp-storage-inbound | Archive Request to GCP Storage | Archive the incoming request to Google Cloud Storage. | api-gateway |
 | archive-response-aws-s3-outbound | Archive Response to AWS S3 | Archive the outgoing response body to AWS S3 storage | api-gateway |
 | archive-response-azure-storage-outbound | Archive Response to Azure Storage | Archive the outgoing response to Azure blob storage. | api-gateway |
-| audit-log-inbound | Audit Logs | Capture detailed logs of requests for auditing purposes. | api-gateway |
+| audit-log-inbound | Audit Logs | Capture detailed logs of requests for auditing purposes. The policy emits one structured CloudEvent per request, and user code can emit additional events via the static `log()` method. | api-gateway |
 | auth0-jwt-auth-inbound | Auth0 JWT Auth | Authenticate users using Auth0 issued JWT tokens. | api-gateway |
 | authzen-inbound | AuthZEN Authorization | Authorize requests using an AuthZEN compatible PDP | api-gateway |
 | cognito-jwt-auth-inbound | AWS Cognito JWT Auth | Authenticate requests with JWT tokens issued by AWS Cognito. | api-gateway |

package/docs/policies/audit-log-inbound/doc.md

@@ -1,78 +1,137 @@
-## Adding Custom Metadata
+## Automatic Request Auditing
 
-You can add any additional data to the audit logs with a custom function.
+Once the Audit Logs policy is added to a route, it automatically records one
+structured audit event for every request that passes through it — no extra code
+required. Each event captures who made the request, what they called, and the
+outcome.
 
-:::note
+The automatic event uses the type `com.zuplo.api.request` and includes the
+actor, the HTTP method and path, the response status, and the geolocation of the
+caller.
 
-Custom metadata functions cannot be asynchronous. Due to the frequency of their
-calls, asynchronous functions will add significant latency to your API.
+For very high-volume routes you can record only a fraction of requests by
+setting the `samplingRate` option (for example `0.1` to capture 10% of
+requests).
 
-:::
+## Controlling What's Logged
 
-```ts
-//module - ./modules/audit-logs.ts
+Audit events can contain personal or sensitive data. To keep audit logging
+compliant with your own data-handling and PII policies, use the `include`
+option to turn individual fields off. Everything is captured by default; set a
+flag to `false` to omit it:
 
-import { ZuploRequest } from "@zuplo/runtime";
+- `queryParams` — the request's query-string parameters (in the logged URL).
+- `user` — the authenticated user / actor identity (subject, email,
+  connection). The `user` vs `anonymous` classification is always kept, but the
+  identifying values are omitted when disabled.
+- `ipAddress` — the caller's IP address.
+- `geolocation` — the caller's country, region, and city.
 
-export function auditLogMetadata(request: ZuploRequest): any {
-  const metadata = {
-    accountId: request.user.data.account,
-    customTraceId: request.headers.get("custom-trace-id"),
-  };
-  return metadata;
+```json
+{
+  "name": "audit-logs-inbound",
+  "policyType": "audit-logs",
+  "handler": {
+    "export": "AuditLogInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "include": {
+        "queryParams": false,
+        "ipAddress": false
+      }
+    }
+  }
 }
 ```
 
-## Log Data
+These settings also apply to the geolocation automatically added to custom
+events emitted via `log()`.
 
-The structure of an audit log is shown below.
+## Emitting Custom Events
 
-```json
-{
-  "route": "/customers/:customerId",
-  "method": "GET",
-  "query": {
-    "a": 1,
-    "b": 2
-  },
-  "params": {
-    "customerId": "12345"
-  },
-  "headers": {
-    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36"
-  },
-  "user": {
-    "sub": "user|12356"
-  },
-  "geolocation": {
-    "country": "US",
-    "city": "Seattle",
-    "continent": "NA",
-    "latitude": "1.123",
-    "longitude": "4.567",
-    "postalCode": "29700",
-    "metroCode": "100",
-    "region": "Washington",
-    "timezone": "America/LosAngeles"
-  },
-  "metadata": {
-    // Custom data
-  }
+Beyond the automatic per-request event, you can record your own domain events —
+for example "account deleted" or "API key rotated" — from a handler or custom
+policy using the static `AuditLogInboundPolicy.log()` method. Any fields you
+don't supply are filled in automatically from the request context (event id,
+time, actor, request id, IP address, user agent, and so on).
+
+```ts
+// module - ./modules/audit.ts
+
+import {
+  AuditLogInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export async function deleteAccount(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  const accountId = request.params.accountId;
+
+  // ...perform the delete...
+
+  AuditLogInboundPolicy.log(context, {
+    type: "com.acme.account.deleted",
+    subject: `account|${accountId}`,
+    resources: [{ type: "account", id: accountId }],
+    success: true,
+    data: { reason: "user-initiated" },
+  });
+
+  return new Response(null, { status: 204 });
 }
 ```
 
-## Audit Logs in the Portal
+The event object passed to `log()` supports the following fields. Only `type` is
+required.
 
-Audit logs are not currently surfaced in the Zuplo portal, but the feature is
-planned soon.
+- `type` — the event type, in reverse-DNS form (e.g. `com.acme.account.deleted`).
+- `subject` — the primary entity the event is about.
+- `resources` — an array of `{ type, id, metadata? }` describing the resources
+  the event affected.
+- `success` — whether the operation succeeded.
+- `data` — any additional structured data to attach to the event.
+- `actor` — override the automatically-derived actor
+  (`{ sub, type, email, connection }`).
+- `country`, `region`, `city` — override the caller's geolocation. These
+  default to the current request's location, so you normally don't need to set
+  them.
 
-## Audit Log API
+Audit logging is best-effort: `log()` never throws and never blocks or fails the
+request, even if an event cannot be recorded.
 
-Audit logs can be retrieved using the Zuplo Management API. Logs can be
-retrieved by time span and can be filtered by `tenant`.
+## Audit Log Event Shape
 
-```http
-GET /deployments/:deploymentId/auditlogs?tenant=TENANT
-content-type: application/json
-authorization: Bearer YOUR_TOKEN
+Every audit event follows the [CloudEvents](https://cloudevents.io/) 1.0
+envelope. An automatically-emitted request event looks like this:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "e6c8b1f2-2c3d-4a5b-9e10-1f2a3b4c5d6e",
+  "type": "com.zuplo.api.request",
+  "time": "2026-07-05T18:12:04.123Z",
+  "actorsub": "user|12356",
+  "actortype": "user",
+  "requestid": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
+  "httpmethod": "GET",
+  "httpurl": "/customers/12345?expand=orders",
+  "httpstatus": 200,
+  "success": true,
+  "ipaddress": "203.0.113.7",
+  "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
+  "country": "US",
+  "region": "Washington",
+  "city": "Seattle"
+}
 ```
+
+Custom events emitted via `log()` share the same envelope; the `type`,
+`subject`, `resources`, `success`, and `data` fields come from the event you
+pass, and the remaining fields are populated from the request context.
+
+## Viewing Audit Logs
+
+In-portal viewing and retrieval of audit logs is coming soon.

package/docs/policies/audit-log-inbound/schema.json

@@ -4,14 +4,14 @@
   "type": "object",
   "title": "Audit Logs",
   "isDeprecated": false,
-  "isPaidAddOn": true,
-  "isEnterprise": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
   "isInternal": false,
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],
-  "description": "Capture detailed logs of requests for auditing purposes.",
+  "description": "Capture detailed logs of requests for auditing purposes. The policy emits one structured CloudEvent per request, and user code can emit additional events via the static `log()` method.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -21,7 +21,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "AuditLogsInboundPolicy",
+          "const": "AuditLogInboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -29,51 +29,71 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "title": "AuditLogsInboundPolicyOptions",
+          "title": "AuditLogInboundPolicyOptions",
           "type": "object",
-          "description": "The options for this policy.",
+          "description": "The options for the Audit Log Inbound policy.",
           "additionalProperties": false,
-          "required": ["blockScoresBelow"],
+          "required": [],
           "properties": {
-            "logIpAddress": {
-              "default": true,
-              "description": "if the IP address should be logged."
+            "eventTypeBase": {
+              "type": "string",
+              "description": "Reverse-DNS prefix used for the auto-emitted request event type. Defaults to 'com.zuplo.api'.",
+              "default": "com.zuplo.api"
             },
-            "logUser": {
-              "default": true,
-              "description": "if the user's `sub` should be logged."
+            "bucketId": {
+              "type": "string",
+              "description": "Override the bucket id this policy emits events for. Defaults to the bucket id from the runtime environment."
             },
-            "logGeolocation": {
-              "default": true,
-              "description": "if the geolocation information should be logged (i.e. state, country, longitude, latitude, etc.)."
+            "samplingRate": {
+              "type": "number",
+              "description": "Fraction of requests to capture, between 0 (none) and 1 (all). Defaults to 1.",
+              "default": 1,
+              "minimum": 0,
+              "maximum": 1
             },
-            "logQueryParameters": {
-              "default": true,
-              "description": "log the values of query parameters."
-            },
-            "logRouteParameters": {
-              "default": true,
-              "description": "The parameters in the route to log."
-            },
-            "tenant": {
-              "description": "if the route parameters should be logged (i.e. the value of `customerId` in the route `/customers/:customerId`)."
-            },
-            "metadata": {
-              "description": "A function to add additional data to the audit logs."
+            "include": {
+              "type": "object",
+              "description": "Controls which potentially-sensitive parts of each request are captured in the auto-emitted audit event. Disable fields to satisfy your own data-handling and PII policies. All are enabled by default.",
+              "additionalProperties": false,
+              "properties": {
+                "queryParams": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the request's query-string parameters in the logged URL. Disable if query strings may contain sensitive data."
+                },
+                "user": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the authenticated user / actor identity (subject, email, connection)."
+                },
+                "ipAddress": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the caller's IP address."
+                },
+                "geolocation": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the caller's geolocation (country, region, city)."
+                }
+              }
             }
           }
         }
       },
       "examples": [
         {
-          "export": "AuditLogsInboundPolicy",
+          "export": "AuditLogInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "logGeolocation": true,
-            "logIpAddress": true,
-            "logQueryParameters": true,
-            "logRouteParameters": true,
-            "logUser": true
+            "eventTypeBase": "com.zuplo.api",
+            "include": {
+              "geolocation": true,
+              "ipAddress": true,
+              "queryParams": true,
+              "user": true
+            },
+            "samplingRate": 1
           }
         }
       ]

package/docs/policies/monetization-inbound/doc.md

@@ -59,6 +59,32 @@ import { MonetizationInboundPolicy } from "@zuplo/runtime";
 const meters = MonetizationInboundPolicy.getMeters(context);
 ```
 
+### Flush (send) runtime meters mid-request
+
+Use `flushMeters` to send accumulated runtime meters immediately and reset their
+counts. This is useful for long-running requests where you want to report
+partial usage before the response is sent (for example, after each chunk of work
+in a streaming handler).
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 500 });
+await MonetizationInboundPolicy.flushMeters(context);
+
+// Runtime meters are cleared before the backend send begins so a concurrent
+// final hook cannot double-count them. Meters are restored if the send fails.
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 300 });
+```
+
+Static `options.meters` are not included in `flushMeters`; they are still sent
+in the final response hook.
+
+Note: `flushMeters` performs entitlement validation and will throw if called
+before the monetization policy runs on the request or if you send meters that
+aren’t present/accessible on the subscription. Wrap in `try/catch` if you want
+to continue the request when a flush fails.
+
 ## Subscription data (for customization)
 
 The monetization policy validates the API key and attaches the **subscription**
@@ -163,4 +189,7 @@ For a meter key like `api` with `options.meters.api = 1`:
 
 - `setMeters` replaces current request meter increments.
 - `addMeters` accumulates values across multiple calls.
+- `flushMeters` sends runtime meters immediately, clears them before the backend
+  send (to avoid duplicate sends if the final hook runs concurrently), and
+  restores them if the send fails.
 - Entitlements are validated before usage is sent.

package/package.json

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