@zuplo/runtime 6.52.4 → 6.52.5

package/out/types/index.d.ts

@@ -2,6 +2,10 @@ import { KeyLike } from 'jose';
 import { RequestGeneric as RequestGeneric_2 } from '../../request.js';
 import type { ValidateFunction as ValidateFunction_2 } from 'ajv';
 
+/**
+ * Entry format for Akamai API Security logger
+ * @public
+ */
 export declare interface AkamaiApiSecurityLoggerEntry {
     ip: {
         v: string;
@@ -46,12 +50,20 @@ export declare interface AkamaiApiSecurityLoggerEntry {
     };
 }
 
+/**
+ * Plugin for integrating with Akamai API Security service for request logging and protection
+ * @public
+ */
 export declare class AkamaiApiSecurityPlugin extends SystemRuntimePlugin {
     #private;
     constructor(options: AkamaiApiSecurityPluginOptions);
     initialize(runtime: RuntimeExtensions): Promise<void>;
 }
 
+/**
+ * Configuration options for the Akamai API Security plugin
+ * @public
+ */
 export declare interface AkamaiApiSecurityPluginOptions {
     /**
      * The hostname of the Akamai API Security service
@@ -99,6 +111,7 @@ export declare function AmberfloMeteringInboundPolicy(request: ZuploRequest, con
 
 /**
  * The options for this policy. Many of them can be overridden at the code level in a request using the `AmberfloMeteringPolicy.setRequestProperties` method.
+ * @public
  */
 export declare interface AmberfloMeteringInboundPolicyOptions {
     /**
@@ -145,6 +158,10 @@ declare interface AmberfloMeteringIngestPayload {
     dimensions: Record<string, string>;
 }
 
+/**
+ * Helper class for Amberflo metering policy
+ * @public
+ */
 export declare class AmberfloMeteringPolicy {
     static setRequestProperties(context: ZuploContext, properties: AmberfloMeteringProperties): void;
 }
@@ -173,6 +190,7 @@ export declare const ApiAuthKeyInboundPolicy: typeof ApiKeyInboundPolicy;
 /**
  * @deprecated
  * The options for this policy.
+ * @public
  */
 export declare interface ApiAuthKeyInboundPolicyOptions {
     /**
@@ -182,20 +200,76 @@ export declare interface ApiAuthKeyInboundPolicyOptions {
 }
 
 /**
- * Authenticates requests based on API Keys using Zuplo API Management.
+ * Authenticates requests based on API Keys using Zuplo's built-in API key management.
+ * This policy validates API keys against Zuplo's key storage, caches results for performance,
+ * and automatically adds user information to authenticated requests.
  *
  * @title API Key Authentication
  * @public
- * @param request - The ZuploRequest
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @param unparsedOptions - The policy options set in policies.json
- * @param policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
+ * @param unparsedOptions - The policy configuration options
+ * @param policyName - The name of the policy instance
+ * @returns The authenticated request with user info, or a 401 response if unauthorized
+ *
+ * @example
+ * ```json
+ * // policies.json - Basic API key authentication
+ * {
+ *   "name": "api-key-auth",
+ *   "policyType": "api-key-inbound",
+ *   "handler": {
+ *     "export": "ApiKeyInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "bucketName": "$env(API_KEY_BUCKET)",
+ *       "cacheTtlSeconds": 300
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Custom header and auth scheme
+ * {
+ *   "handler": {
+ *     "export": "ApiKeyInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "bucketName": "$env(API_KEY_BUCKET)",
+ *       "authHeader": "x-api-key",
+ *       "authScheme": "",
+ *       "allowUnauthenticatedRequests": false
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Access authenticated user data in handler
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   // User is automatically added by API key policy
+ *   const user = request.user;
+ *   context.log.info(`Request from API key: ${user.sub}`);
+ *
+ *   // Access custom metadata stored with the key
+ *   const metadata = user.data as { plan: string; limit: number };
+ *
+ *   return Response.json({
+ *     message: `Hello ${user.sub}`,
+ *     plan: metadata.plan
+ *   });
+ * }
+ * ```
  */
 export declare function ApiKeyInboundPolicy(request: ZuploRequest, context: ZuploContext, unparsedOptions: ApiKeyInboundPolicyOptions, policyName: string): Promise<Response | ZuploRequest<RequestGeneric_2>>;
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ApiKeyInboundPolicyOptions {
     /**
@@ -236,6 +310,7 @@ export declare function apiServices<TResponse, TRequest = unknown>(path: string,
 
 /**
  * Authentication options for api token authentication.
+ * @public
  */
 declare interface APITokenCredentialConfig {
     /**
@@ -258,6 +333,7 @@ declare interface APITokenCredentialConfig {
 
 /**
  * A list of attributes that will be included in the authorization request.
+ * @public
  */
 declare type Attribute = {
     /**
@@ -272,6 +348,7 @@ declare type Attribute = {
 
 /**
  * A list of attributes that will be included in the authorization request.
+ * @public
  */
 declare type Attribute1 = {
     /**
@@ -286,6 +363,7 @@ declare type Attribute1 = {
 
 /**
  * A list of attributes that will be included in the authorization request.
+ * @public
  */
 declare type Attribute2 = {
     /**
@@ -306,17 +384,29 @@ declare interface Attribute_2 {
     IncludeInResult?: boolean;
 }
 
+/**
+ * Configuration for DataStax audit log provider
+ * @public
+ */
 export declare interface AuditLogDataStaxInit {
     url: string;
     xCassandraToken: string;
 }
 
+/**
+ * DataStax audit log output provider
+ * @public
+ */
 export declare class AuditLogDataStaxProvider implements AuditLogOutputProvider {
     #private;
     constructor(options: AuditLogDataStaxInit);
     writeLogBatch: (entries: AuditLogEntry[]) => Promise<void>;
 }
 
+/**
+ * Represents an audit log entry
+ * @public
+ */
 declare interface AuditLogEntry {
     timestamp: Date;
     durationMs: number;
@@ -337,6 +427,10 @@ declare interface AuditLogEntry {
     };
 }
 
+/**
+ * Configuration options for audit logging
+ * @public
+ */
 export declare interface AuditLogInit {
     requestFilter?: AuditLogRequestFilter;
     include?: {
@@ -351,16 +445,28 @@ export declare interface AuditLogInit {
     };
 }
 
+/**
+ * Interface for audit log output providers
+ * @public
+ */
 declare interface AuditLogOutputProvider {
     writeLogBatch: (entries: AuditLogEntry[]) => Promise<void>;
 }
 
+/**
+ * Audit log plugin for tracking API requests and responses
+ * @public
+ */
 export declare class AuditLogPlugin extends SystemRuntimePlugin {
     #private;
     constructor(outputProvider: AuditLogOutputProvider, init?: AuditLogInit);
     initialize(runtimeInit: RuntimeExtensions): Promise<void>;
 }
 
+/**
+ * Filter function to determine if a request should be audited
+ * @public
+ */
 declare interface AuditLogRequestFilter {
     (request: ZuploRequest, context: ZuploContext): Promise<boolean>;
 }
@@ -380,6 +486,7 @@ export declare const Auth0JwtInboundPolicy: InboundPolicyHandler<Auth0JwtInbound
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface Auth0JwtInboundPolicyOptions {
     /**
@@ -436,6 +543,7 @@ export declare class AuthZenInboundPolicy extends InboundPolicy<AuthZenInboundPo
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface AuthZenInboundPolicyOptions {
     /**
@@ -505,6 +613,10 @@ export declare interface AuthZenTypeIdPair {
     id: string;
 }
 
+/**
+ * AWS Lambda Event format version 1.0
+ * @public
+ */
 declare interface AwsLambdaEventV1 {
     [key: string]: string | null | undefined | number | boolean | object;
     version: "1.0";
@@ -563,6 +675,10 @@ declare interface AwsLambdaEventV1 {
     stageVariables: null | Record<string, string>;
 }
 
+/**
+ * AWS Lambda Event format version 2.0
+ * @public
+ */
 declare interface AwsLambdaEventV2 {
     [key: string]: string | null | undefined | number | boolean | object;
     version: "2.0";
@@ -613,14 +729,61 @@ declare interface AwsLambdaEventV2 {
 }
 
 /**
- * Proxy requests to a different url
- * @param request - The ZuploRequest
+ * Handler that proxies requests to AWS Lambda functions.
+ * Supports both Lambda proxy integration formats (v1.0 and v2.0).
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @returns
- * @beta
+ * @returns A Response from the Lambda function
+ *
+ * @public
+ * @example
+ * ```json
+ * // routes.oas.json
+ * {
+ *   "paths": {
+ *     "/api/lambda-function": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "awsLambdaHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "accessKeyId": "$env(AWS_ACCESS_KEY_ID)",
+ *             "secretAccessKey": "$env(AWS_SECRET_ACCESS_KEY)",
+ *             "region": "us-east-1",
+ *             "functionName": "my-lambda-function",
+ *             "useLambdaProxyIntegration": true,
+ *             "payloadFormatVersion": "2.0",
+ *             "binaryMediaTypes": ["image/*", "application/pdf"]
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function awsLambdaHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
+/**
+ * Extensions for customizing AWS Lambda handler behavior.
+ * @public
+ * @example
+ * ```typescript
+ * import { AwsLambdaHandlerExtensions } from "@zuplo/runtime";
+ *
+ * // In zuplo.runtime.ts
+ * export function runtimeInit(runtime: RuntimeExtensions) {
+ *   AwsLambdaHandlerExtensions.addSendingAwsLambdaEventHook(
+ *     async (request, context, event) => {
+ *       // Add custom headers or modify the event
+ *       event.headers["X-Custom-Header"] = "value";
+ *       return event;
+ *     }
+ *   );
+ * }
+ * ```
+ */
 export declare const AwsLambdaHandlerExtensions: {
     addSendingAwsLambdaEventHook: (hook: OnSendingAwsLambdaEventHook) => void;
 };
@@ -637,6 +800,10 @@ declare interface AWSLoggingOptions {
     fields?: CustomLogFields;
 }
 
+/**
+ * AWS CloudWatch logging plugin
+ * @public
+ */
 export declare class AWSLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: AWSLoggingOptions);
@@ -681,6 +848,7 @@ export declare class AxiomaticsAuthZInboundPolicy extends InboundPolicy<Axiomati
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface AxiomaticsAuthZInboundPolicyOptions {
     /**
@@ -720,16 +888,28 @@ export declare interface AxiomaticsAuthZInboundPolicyOptions {
     actionAttributes?: Attribute2;
 }
 
+/**
+ * Function to generate blob names
+ * @public
+ */
 export declare interface AzureBlobGenerateName<T> {
     (entries: T[]): string;
 }
 
+/**
+ * Azure Blob Storage request logger plugin
+ * @public
+ */
 export declare class AzureBlobPlugin<T extends BasicDictionary> extends SystemRuntimePlugin {
     #private;
     constructor(options: AzureBlobPluginOptions<T>);
     initialize(runtime: RuntimeExtensions): Promise<void>;
 }
 
+/**
+ * Options for Azure Blob request logger plugin
+ * @public
+ */
 export declare interface AzureBlobPluginOptions<T> {
     sasUrl: string;
     batchPeriodSeconds: number;
@@ -737,6 +917,10 @@ export declare interface AzureBlobPluginOptions<T> {
     generateBlobName?: AzureBlobGenerateName<T>;
 }
 
+/**
+ * Azure Event Hubs request logger plugin
+ * @public
+ */
 export declare class AzureEventHubsRequestLoggerPlugin<T extends BasicDictionary> extends SystemRuntimePlugin {
     #private;
     constructor(options: AzureEventHubsRequestLoggerPluginOptions<T>);
@@ -747,6 +931,10 @@ export declare class AzureEventHubsRequestLoggerPlugin<T extends BasicDictionary
     initialize(runtime: RuntimeExtensions): Promise<void>;
 }
 
+/**
+ * Options for Azure Event Hubs request logger plugin
+ * @public
+ */
 export declare interface AzureEventHubsRequestLoggerPluginOptions<T> {
     /** Full connection string from Azure Portal (with Endpoint=..., etc.) */
     connectionString: string;
@@ -760,12 +948,66 @@ export declare interface AzureEventHubsRequestLoggerPluginOptions<T> {
     batchPeriodSeconds: number;
 }
 
+/**
+ * Utility for batching and dispatching events in the background.
+ * Useful for aggregating logs, metrics, or other data before sending to external services.
+ * The dispatcher automatically batches items and sends them after a configurable delay.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { BackgroundDispatcher, ZuploContext } from "@zuplo/runtime";
+ *
+ * // Define your payload type
+ * interface LogEntry {
+ *   timestamp: string;
+ *   level: string;
+ *   message: string;
+ *   metadata?: Record<string, any>;
+ * }
+ *
+ * // Create a dispatcher function
+ * const sendLogs = async (logs: LogEntry[]) => {
+ *   await fetch("https://logging.example.com/bulk", {
+ *     method: "POST",
+ *     headers: { "Content-Type": "application/json" },
+ *     body: JSON.stringify({ logs })
+ *   });
+ * };
+ *
+ * // Initialize the dispatcher
+ * const logDispatcher = new BackgroundDispatcher(sendLogs, {
+ *   msDelay: 1000, // Batch logs every 1 second
+ *   name: "log-dispatcher"
+ * });
+ *
+ * // Use in your handler
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   // Queue logs for batched sending
+ *   logDispatcher.enqueue({
+ *     timestamp: new Date().toISOString(),
+ *     level: "info",
+ *     message: "Request processed",
+ *     metadata: {
+ *       userId: request.user?.sub,
+ *       path: request.url
+ *     }
+ *   });
+ *
+ *   return new Response("OK");
+ * }
+ * ```
+ */
 export declare class BackgroundDispatcher<TPayload> {
     #private;
     constructor(dispatcher: DispatchFunction<TPayload>, options: BatchDispatcherOptions);
     enqueue: (payload: TPayload) => void;
 }
 
+/**
+ * A utility for loading and caching data in the background with automatic refresh
+ * @public
+ */
 export declare class BackgroundLoader<T = unknown> {
     #private;
     constructor(loader: BackgroundLoaderFunction<T>, options: BackgroundLoaderOptions);
@@ -776,10 +1018,18 @@ export declare class BackgroundLoader<T = unknown> {
     get(key: string): Promise<T>;
 }
 
+/**
+ * Function to load data in the background
+ * @public
+ */
 export declare interface BackgroundLoaderFunction<T> {
     (key: string): Promise<T>;
 }
 
+/**
+ * Options for background loader
+ * @public
+ */
 declare interface BackgroundLoaderOptions {
     ttlSeconds: number;
     loaderTimeoutSeconds?: number;
@@ -811,6 +1061,7 @@ declare class BaseOpenFGAAuthZInboundPolicy extends InboundPolicy<OpenFGAAuthZIn
 
 /**
  * An account object.
+ * @public
  */
 declare interface BasicAuthAccount {
     /**
@@ -844,6 +1095,7 @@ export declare const BasicAuthInboundPolicy: InboundPolicyHandler<BasicAuthInbou
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface BasicAuthInboundPolicyOptions {
     /**
@@ -856,11 +1108,19 @@ export declare interface BasicAuthInboundPolicyOptions {
     allowUnauthenticatedRequests?: boolean;
 }
 
+/**
+ * Basic dictionary type for log entries
+ * @public
+ */
 declare interface BasicDictionary extends Record<string, string | number | boolean | null | undefined> {
 }
 
 /* Excluded from this release type: BatchDispatch */
 
+/**
+ * Options for configuring a BackgroundDispatcher.
+ * @public
+ */
 declare interface BatchDispatcherOptions {
     msDelay: number;
     name?: string;
@@ -885,6 +1145,7 @@ export declare class BrownoutInboundPolicy extends InboundPolicy<BrownoutInbound
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface BrownoutInboundPolicyOptions {
     /**
@@ -917,6 +1178,9 @@ export declare interface BrownoutInboundPolicyOptions {
 
 /* Excluded from this release type: BuildEnvironment */
 
+/**
+ * @public
+ */
 declare interface BuildRouteConfiguration {
     path: string;
     methods: HttpMethod[];
@@ -980,6 +1244,7 @@ export declare function CachingInboundPolicy(request: ZuploRequest, context: Zup
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface CachingInboundPolicyOptions {
     /**
@@ -1030,6 +1295,7 @@ export declare const ChangeMethodInboundPolicy: InboundPolicyHandler<ChangeMetho
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ChangeMethodInboundPolicyOptions {
     /**
@@ -1053,6 +1319,7 @@ export declare const ClearHeadersInboundPolicy: InboundPolicyHandler<ClearHeader
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ClearHeadersInboundPolicyOptions {
     /**
@@ -1076,6 +1343,7 @@ export declare const ClearHeadersOutboundPolicy: OutboundPolicyHandler<ClearHead
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ClearHeadersOutboundPolicyOptions {
     /**
@@ -1099,6 +1367,7 @@ export declare const ClerkJwtInboundPolicy: InboundPolicyHandler<ClerkJwtInbound
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ClerkJwtInboundPolicyOptions {
     /**
@@ -1113,6 +1382,7 @@ export declare interface ClerkJwtInboundPolicyOptions {
 
 /**
  * Authentication options for OIDC authentication.
+ * @public
  */
 declare interface ClientCredentialsConfig {
     /**
@@ -1152,6 +1422,7 @@ export declare const CognitoJwtInboundPolicy: InboundPolicyHandler<CognitoJwtInb
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface CognitoJwtInboundPolicyOptions {
     /**
@@ -1227,6 +1498,10 @@ export declare interface ComplexCustomRateLimitDetails extends CustomRateLimitDe
     limits?: Record<string, number>;
 }
 
+/**
+ * Function type for complex rate limiting
+ * @public
+ */
 export declare type ComplexRateLimitFunction = RateLimitFunction<ComplexCustomRateLimitDetails>;
 
 /**
@@ -1256,6 +1531,7 @@ export declare class ComplexRateLimitInboundPolicy extends InboundPolicy<Complex
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ComplexRateLimitInboundPolicyOptions {
     rateLimitBy: RateLimitByType;
@@ -1305,6 +1581,7 @@ export declare const CompositeInboundPolicy: InboundPolicyHandler<CompositeInbou
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface CompositeInboundPolicyOptions {
     /**
@@ -1328,6 +1605,7 @@ export declare const CompositeOutboundPolicy: OutboundPolicyHandler<CompositeOut
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface CompositeOutboundPolicyOptions {
     /**
@@ -1337,10 +1615,31 @@ export declare interface CompositeOutboundPolicyOptions {
 }
 
 /**
- * Errors caused by invalid user configuration -i.e. invalid parameters on policies,
- * handlers that are not functions, etc. This is not for zuplo system configuration errors,
- * use SystemError for that.
+ * Errors caused by invalid user configuration such as invalid parameters on policies,
+ * handlers that are not functions, or missing required configuration values.
+ *
  * @public
+ * @example
+ * ```typescript
+ * import { ConfigurationError } from "@zuplo/runtime";
+ *
+ * // In a policy
+ * export const myPolicy: InboundPolicy = async (request, context, options) => {
+ *   if (!options.apiKey) {
+ *     throw new ConfigurationError(
+ *       "API key is required in policy configuration"
+ *     );
+ *   }
+ *
+ *   if (typeof options.timeout !== "number" || options.timeout < 0) {
+ *     throw new ConfigurationError(
+ *       "Timeout must be a positive number"
+ *     );
+ *   }
+ *
+ *   // Policy logic...
+ * };
+ * ```
  */
 export declare class ConfigurationError extends RuntimeError {
     constructor(message: string, options?: ErrorOptions);
@@ -1356,11 +1655,15 @@ export declare class ConfigurationError extends RuntimeError {
  *
  * @example
  * Using static methods
- * ```
+ * ```typescript
+ * import { ContextData, ZuploContext } from "@zuplo/runtime";
+ *
+ * // In a policy or handler
  * ContextData.set(context, "my-data", { prop1: "hello world" });
  *
+ * // Later in the pipeline
  * const data = ContextData.get(context, "my-data");
- * ContextData.set(context, data);
+ * console.log(data?.prop1); // "hello world"
  * ```
  *
  * @example
@@ -1369,36 +1672,98 @@ export declare class ConfigurationError extends RuntimeError {
  * The shared module allows other modules to access the same storage without
  * passing the string name or type around.
  *
- * ```
- * export const myData =
- *    new ContextData<{ prop1: string }>("my-data");
+ * ```typescript
+ * // shared-data.ts
+ * import { ContextData } from "@zuplo/runtime";
+ *
+ * interface UserData {
+ *   userId: string;
+ *   roles: string[];
+ * }
+ *
+ * export const userData = new ContextData<UserData>("user-data");
  * ```
  *
  * Then use the class in another module.
  *
- * ```
- * import { myData } from "./my-module.js";
+ * ```typescript
+ * // policy.ts
+ * import { userData } from "./shared-data.js";
+ * import { InboundPolicy, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+ *
+ * export const authenticateUser: InboundPolicy = async (
+ *   request: ZuploRequest,
+ *   context: ZuploContext
+ * ) => {
+ *   // Store user data after authentication
+ *   userData.set(context, {
+ *     userId: "user-123",
+ *     roles: ["admin", "user"]
+ *   });
  *
+ *   return request;
+ * };
  *
- * const data = myData.get(context)
- * myData.set(context, data);
+ * // handler.ts
+ * import { userData } from "./shared-data.js";
  *
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   const user = userData.get(context);
+ *   if (user?.roles.includes("admin")) {
+ *     // Handle admin access
+ *   }
+ * }
  * ```
  */
 export declare class ContextData<T = any> {
     #private;
+    /**
+     * Creates a new ContextData instance for type-safe context storage.
+     * @param name - A unique string or symbol identifier for this data
+     */
     constructor(name: string | symbol);
+    /**
+     * Stores data in the context under this instance's name.
+     * @param context - The ZuploContext to store data in
+     * @param data - The data to store
+     */
     set(context: ZuploContext, data: T): void;
+    /**
+     * Retrieves data from the context stored under this instance's name.
+     * @param context - The ZuploContext to retrieve data from
+     * @returns The stored data or undefined if not found
+     */
     get(context: ZuploContext): T | undefined;
+    /**
+     * Stores data in the context under the specified name.
+     * @param context - The ZuploContext to store data in
+     * @param name - The unique identifier for this data
+     * @param data - The data to store
+     */
     static set<T = any>(context: ZuploContext, name: string | symbol, data: T): void;
+    /**
+     * Retrieves data from the context stored under the specified name.
+     * @param context - The ZuploContext to retrieve data from
+     * @param name - The unique identifier for the data
+     * @returns The stored data or undefined if not found
+     */
     static get<T = any>(context: ZuploContext, name: string | symbol): T | undefined;
 }
 
-/** The 2-letter continent codes Cloudflare uses */
+/**
+ * The 2-letter continent codes Cloudflare uses
+ * @public
+ */
 declare type ContinentCode = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
 
+/**
+ * @public
+ */
 export declare type CorsPolicy = string | "anything-goes" | "none";
 
+/**
+ * @public
+ */
 export declare interface CorsPolicyConfiguration {
     name: string;
     allowCredentials?: boolean;
@@ -1487,6 +1852,7 @@ declare interface CronDefinition {
 
 /**
  * @deprecated Use standard `crypto` API instead.
+ * @public
  */
 export declare class CryptoBeta extends BaseCryptoBeta {
     digest(algorithm: string, data: string): Promise<string>;
@@ -1507,6 +1873,7 @@ export declare const CurityPhantomTokenInboundPolicy: InboundPolicyHandler<Curit
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface CurityPhantomTokenInboundPolicyOptions {
     /**
@@ -1530,6 +1897,7 @@ export declare interface CurityPhantomTokenInboundPolicyOptions {
 declare type CustomLogFields = Record<string, number | string | boolean>;
 
 /**
+ * Custom rate limit details that can override policy options.
  * @public
  */
 export declare interface CustomRateLimitDetails extends CustomRateLimitDetailsBase {
@@ -1541,6 +1909,10 @@ declare interface CustomRateLimitDetailsBase {
     timeWindowMinutes?: number;
 }
 
+/**
+ * Function type for custom rate limiting
+ * @public
+ */
 export declare type CustomRateLimitFunction = RateLimitFunction<CustomRateLimitDetails>;
 
 declare interface DataDogLoggingOptions {
@@ -1560,6 +1932,10 @@ declare interface DataDogLoggingOptions {
     tags?: Record<string, unknown>;
 }
 
+/**
+ * DataDog logging plugin
+ * @public
+ */
 export declare class DataDogLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: DataDogLoggingOptions);
@@ -1578,6 +1954,10 @@ declare interface DataDogMetricsOptions {
     include?: IncludeMetrics;
 }
 
+/**
+ * DataDog metrics plugin
+ * @public
+ */
 export declare class DataDogMetricsPlugin extends MetricsPlugin {
     private options;
     constructor(options: DataDogMetricsOptions);
@@ -1585,6 +1965,10 @@ export declare class DataDogMetricsPlugin extends MetricsPlugin {
     static setContext(context: ZuploContext, data: DataDogMetricsContext): void;
 }
 
+/**
+ * Default function to generate Hydrolix log entries
+ * @public
+ */
 export declare const defaultGenerateHydrolixEntry: GenerateRequestLoggerEntry<HydrolixDefaultEntry>;
 
 /* Excluded from this release type: DevPortalRuntimeConfig */
@@ -1594,6 +1978,10 @@ export declare const defaultGenerateHydrolixEntry: GenerateRequestLoggerEntry<Hy
  */
 export declare type DispatchFunction<TPayload> = (batch: TPayload[]) => Promise<void>;
 
+/**
+ * Function to dispatch request logger entries
+ * @public
+ */
 export declare interface DispatchRequestLoggerEntries<T> {
     (entries: T[]): Promise<void>;
 }
@@ -1607,6 +1995,10 @@ declare interface DynaTraceLoggingOptions {
     fields?: CustomLogFields;
 }
 
+/**
+ * Dynatrace logging plugin
+ * @public
+ */
 export declare class DynaTraceLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: DynaTraceLoggingOptions);
@@ -1625,6 +2017,10 @@ declare interface DynatraceMetricsOptions {
     include?: IncludeMetrics;
 }
 
+/**
+ * Dynatrace metrics plugin
+ * @public
+ */
 export declare class DynatraceMetricsPlugin extends MetricsPlugin {
     private options;
     constructor(options: DynatraceMetricsOptions);
@@ -1668,6 +2064,7 @@ export declare const FirebaseJwtInboundPolicy: InboundPolicyHandler<FirebaseJwtI
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface FirebaseJwtInboundPolicyOptions {
     /**
@@ -1695,6 +2092,7 @@ export declare const FormDataToJsonInboundPolicy: InboundPolicyHandler<FormDataT
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface FormDataToJsonInboundPolicyOptions {
     /**
@@ -1709,6 +2107,10 @@ export declare interface FormDataToJsonInboundPolicyOptions {
 
 /* Excluded from this release type: Gateway */
 
+/**
+ * Function to generate request logger entries
+ * @public
+ */
 export declare interface GenerateRequestLoggerEntry<T> {
     (response: Response, request: ZuploRequest, context: ZuploContext, metadata: RequestLoggerMetaData): Promise<T>;
 }
@@ -1728,6 +2130,7 @@ export declare const GeoFilterInboundPolicy: InboundPolicyHandler<GeoFilterInbou
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface GeoFilterInboundPolicyOptions {
     block?: GeoSpec;
@@ -1753,11 +2156,11 @@ declare interface GeoSpec {
     asns?: string;
 }
 
-export declare function getIdForParameterSchema(path: string, operation: string, type: string, name: string): string;
+/* Excluded from this release type: getIdForParameterSchema */
 
-export declare function getIdForRefSchema(oasFileName: string, ref: string): string;
+/* Excluded from this release type: getIdForRefSchema */
 
-export declare function getIdForRequestBodySchema(path: string, operation: string, contentType: string): string;
+/* Excluded from this release type: getIdForRequestBodySchema */
 
 /**
  * The function to get the anchor date for the quota.
@@ -1777,7 +2180,7 @@ declare interface GetQuotaResult {
     meters: Record<string, number>;
 }
 
-export declare function getRawOperationDataIdentifierName(oasFileName: string, path: string, operation: string): string;
+/* Excluded from this release type: getRawOperationDataIdentifierName */
 
 declare interface GoogleCloudLoggingOptions {
     serviceAccountJson: string;
@@ -1788,14 +2191,59 @@ declare interface GoogleCloudLoggingOptions {
     fields?: CustomLogFields;
 }
 
+/**
+ * Google Cloud logging plugin
+ * @public
+ */
 export declare class GoogleCloudLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: GoogleCloudLoggingOptions);
     /* Excluded from this release type: getTransport */
 }
 
-/* Excluded from this release type: Handler */
+/**
+ * The main request handler for the Zuplo runtime. This class initializes the gateway
+ * and handles all incoming HTTP requests through the configured pipeline.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { Handler } from "@zuplo/runtime";
+ *
+ * // This is typically used internally by Zuplo runtime,
+ * // but can be useful for testing or custom deployments
+ * const handler = new Handler(
+ *   routeLoader,
+ *   buildEnvironment,
+ *   runtimeSettings,
+ *   serviceProvider,
+ *   schemaValidations,
+ *   runtimeInit
+ * );
+ *
+ * // Handle a request
+ * const response = await handler.requestHandler(
+ *   request,
+ *   runtimeEnvironment,
+ *   event
+ * );
+ * ```
+ */
+export declare class Handler {
+    routeLoader: () => Promise<RouteData>;
+    buildEnvironment: BuildEnvironment;
+    runtimeSettings: RuntimeSettings;
+    private serviceProvider;
+    private schemaValidations;
+    private runtimeInit;
+    constructor(routeLoader: () => Promise<RouteData>, buildEnvironment: BuildEnvironment, runtimeSettings: RuntimeSettings, serviceProvider: ServiceProvider, schemaValidations: any, runtimeInit: RuntimeExtensionsFunction | undefined);
+    requestHandler: (request: Request, runtimeEnvironment: RuntimeEnvironment, event: ZuploEventContext) => Promise<Response>;
+    handleError(err: Error, detail: string, request: Request): Response;
+}
 
+/**
+ * @public
+ */
 export declare interface HandlerDefinition {
     module: any;
     export: string;
@@ -1808,6 +2256,7 @@ declare interface HandleRequestOptions {
 
 /**
  * Request header authentication.
+ * @public
  */
 declare interface HeaderCredentialsConfig {
     /**
@@ -1820,12 +2269,85 @@ declare interface HeaderCredentialsConfig {
     headerName: string;
 }
 
+/**
+ * @public
+ */
 export declare type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH";
 
 declare type HttpMethod_2 = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 
 /**
- * @beta
+ * Utility class for generating standardized HTTP problem responses following RFC 7807.
+ * Provides static methods for all standard HTTP status codes with automatic request tracking,
+ * trace information, and consistent error formatting.
+ *
+ * @public
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7807|RFC 7807 - Problem Details for HTTP APIs}
+ *
+ * @example
+ * ```typescript
+ * import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+ *
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   // Simple 404 response
+ *   if (!resource) {
+ *     return HttpProblems.notFound(request, context);
+ *   }
+ *
+ *   // 400 with custom detail
+ *   if (!request.headers.get("x-api-key")) {
+ *     return HttpProblems.badRequest(request, context, {
+ *       detail: "Missing required header: x-api-key"
+ *     });
+ *   }
+ *
+ *   // 401 with additional headers
+ *   if (!authenticated) {
+ *     return HttpProblems.unauthorized(request, context, {
+ *       detail: "Invalid credentials"
+ *     }, {
+ *       "WWW-Authenticate": "Bearer realm=\"api\""
+ *     });
+ *   }
+ *
+ *   // 429 with retry information
+ *   if (rateLimited) {
+ *     return HttpProblems.tooManyRequests(request, context, {
+ *       detail: "Rate limit exceeded",
+ *       extensions: {
+ *         limit: 100,
+ *         remaining: 0,
+ *         reset: new Date(Date.now() + 60000).toISOString()
+ *       }
+ *     }, {
+ *       "Retry-After": "60"
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom problem formatter
+ * import { HttpProblems, ProblemResponseDetails } from "@zuplo/runtime";
+ *
+ * // Format a custom problem
+ * const problem: ProblemResponseDetails = {
+ *   problem: {
+ *     type: "https://example.com/probs/out-of-credit",
+ *     title: "Out of credit",
+ *     status: 402,
+ *     detail: "Your current balance is 30, but that costs 50.",
+ *     instance: "/account/12345/msgs/abc",
+ *     extensions: {
+ *       balance: 30,
+ *       accounts: ["/account/12345", "/account/67890"]
+ *     }
+ *   }
+ * };
+ *
+ * return HttpProblems.format(problem.problem, request, context);
+ * ```
  */
 export declare class HttpProblems extends HttpProblemsBase {
     #private;
@@ -2885,6 +3407,10 @@ declare type HttpStatusCodeRangeDefinition = "1XX" | "2XX" | "3XX" | "4XX" | "5X
 
 /* Excluded from this release type: httpStatuses */
 
+/**
+ * Default entry structure for Hydrolix logs
+ * @public
+ */
 export declare interface HydrolixDefaultEntry extends BasicDictionary {
     deploymentName: string;
     timestamp: string;
@@ -2914,12 +3440,20 @@ export declare interface HydrolixDefaultEntry extends BasicDictionary {
     zuploUserAgent?: string;
 }
 
+/**
+ * Hydrolix request logger plugin
+ * @public
+ */
 export declare class HydrolixRequestLoggerPlugin<T extends BasicDictionary> extends SystemRuntimePlugin {
     #private;
     constructor(options: HydrolixRequestLoggerPluginOptions<T>);
     initialize(runtime: RuntimeExtensions): Promise<void>;
 }
 
+/**
+ * Options for Hydrolix request logger plugin
+ * @public
+ */
 export declare interface HydrolixRequestLoggerPluginOptions<T> {
     hostname: string;
     username: string;
@@ -2932,35 +3466,100 @@ export declare interface HydrolixRequestLoggerPluginOptions<T> {
 }
 
 /**
- * @beta
  * A policy that can modify the incoming HTTP request before it is sent to
  * the handler. If a response is returned, the request is short-circuited and
  * the response is returned to the client. If a Request is returned, policies
  * or a handler that follow are executed.
- */
-export declare abstract class InboundPolicy<TOptions = any> extends PolicyBase<TOptions> {
-    /**
-     * The handler that is called each time this policy is invoked
-     *
-     * @param request - The incoming Request
-     * @param context - The current context of the Request
-     * @returns A Response or Request object
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { InboundPolicy, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+ *
+ * interface MyPolicyOptions {
+ *   headerName: string;
+ *   headerValue: string;
+ * }
+ *
+ * export class AddHeaderPolicy extends InboundPolicy<MyPolicyOptions> {
+ *   async handler(request: ZuploRequest, context: ZuploContext) {
+ *     // Add a custom header
+ *     request.headers.set(this.options.headerName, this.options.headerValue);
+ *
+ *     // Log the action
+ *     context.log.info(`Added header ${this.options.headerName}`);
+ *
+ *     // Continue to next policy/handler
+ *     return request;
+ *   }
+ * }
+ *
+ * // Usage in policies.json:
+ * // {
+ * //   "name": "add-custom-header",
+ * //   "policyType": "custom-add-header-policy",
+ * //   "handler": {
+ * //     "export": "AddHeaderPolicy",
+ * //     "module": "$import(./policies/add-header)",
+ * //     "options": {
+ * //       "headerName": "X-Custom-Header",
+ * //       "headerValue": "My Value"
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+export declare abstract class InboundPolicy<TOptions = any> extends PolicyBase<TOptions> {
+    /**
+     * The handler that is called each time this policy is invoked
+     *
+     * @param request - The incoming Request
+     * @param context - The current context of the Request
+     * @returns A Response or Request object
      */
     abstract handler(request: ZuploRequest, context: ZuploContext): Promise<ZuploRequest | Response>;
 }
 
 /**
- * @public
- * A policy that can modify the incoming HTTP request before it is sent to
- * the handler. If a response is returned, the request is short-circuited and
- * the response is returned to the client. If a Request is returned, policies
- * or a handler that follow are executed.
+ * A function-based inbound policy that can modify the incoming HTTP request.
+ * This is the simplest way to create custom policies without extending a class.
  *
  * @param request - The incoming Request
  * @param context - The current context of the Request
  * @param options - The configuration options for the policy
  * @param policyName - The name set on the policy in the configuration
- * @returns A Response or Request object
+ * @returns A Response to short-circuit or a Request to continue
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { InboundPolicyHandler } from "@zuplo/runtime";
+ *
+ * interface RateLimitOptions {
+ *   requests: number;
+ *   windowMs: number;
+ * }
+ *
+ * export const rateLimitPolicy: InboundPolicyHandler<RateLimitOptions> = async (
+ *   request,
+ *   context,
+ *   options,
+ *   policyName
+ * ) => {
+ *   const key = request.headers.get("x-api-key") || "anonymous";
+ *   const count = await incrementCounter(key, options.windowMs);
+ *
+ *   if (count > options.requests) {
+ *     return new Response("Too Many Requests", { status: 429 });
+ *   }
+ *
+ *   // Add rate limit headers
+ *   request.headers.set("X-RateLimit-Limit", options.requests.toString());
+ *   request.headers.set("X-RateLimit-Remaining", (options.requests - count).toString());
+ *
+ *   return request;
+ * };
+ * ```
  */
 export declare interface InboundPolicyHandler<TOptions = any> {
     (request: ZuploRequest, context: ZuploContext, options: TOptions, policyName: string): Promise<ZuploRequest | Response>;
@@ -2973,6 +3572,9 @@ declare interface IncludeMetrics {
     path?: boolean;
 }
 
+/**
+ * @public
+ */
 declare interface IncomingRequestProperties {
     /**
      * ASN of the incoming request, for example, 395747.
@@ -3040,7 +3642,10 @@ declare interface IncomingRequestProperties {
     readonly httpProtocol: string | undefined;
 }
 
-/** ISO 3166-1 Alpha-2 codes */
+/**
+ * ISO 3166-1 Alpha-2 codes
+ * @public
+ */
 declare type Iso3166Alpha2Code = "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BQ" | "BR" | "BS" | "BT" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CW" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SV" | "SX" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZM" | "ZW";
 
 /**
@@ -3058,6 +3663,7 @@ export declare const JWTScopeValidationInboundPolicy: InboundPolicyHandler<JWTSc
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface JWTScopeValidationInboundPolicyOptions {
     /**
@@ -3146,6 +3752,7 @@ declare type LogSourceType = "runtime" | "request";
 
 /**
  * A logging plugin that sends logs to a Loki server.
+ * @public
  */
 export declare class LokiLoggingPlugin extends LogPlugin {
     private options;
@@ -3202,10 +3809,57 @@ declare type LokiTransportVersion = 1 | 2;
  */
 export declare function mcpServerHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
+/**
+ * A two-tier cache that combines in-memory caching with zone-level caching.
+ * Data is first checked in memory cache for fastest access, then falls back to
+ * zone cache if not found. Writes update both cache tiers.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { MemoryZoneReadThroughCache, ZuploContext } from "@zuplo/runtime";
+ *
+ * export async function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   const cache = new MemoryZoneReadThroughCache<UserData>("user-cache", context);
+ *
+ *   // Try to get cached data
+ *   const cachedUser = await cache.get("user-123");
+ *   if (cachedUser) {
+ *     return Response.json(cachedUser);
+ *   }
+ *
+ *   // Fetch fresh data
+ *   const user = await fetchUserFromDatabase("user-123");
+ *
+ *   // Cache for 5 minutes (300 seconds)
+ *   cache.put("user-123", user, 300);
+ *
+ *   return Response.json(user);
+ * }
+ * ```
+ */
 export declare class MemoryZoneReadThroughCache<T = unknown> {
     #private;
+    /**
+     * Creates a new MemoryZoneReadThroughCache instance.
+     * @param name - A unique name for this cache instance
+     * @param context - The ZuploContext from the current request
+     */
     constructor(name: string, context: ZuploContext);
+    /**
+     * Retrieves a value from the cache by key. First checks memory cache,
+     * then falls back to zone cache if not found in memory.
+     * @param key - The cache key to retrieve
+     * @returns The cached value or undefined if not found or expired
+     */
     get(key: string): Promise<T | undefined>;
+    /**
+     * Stores a value in both memory and zone cache with the specified TTL.
+     * The write to zone cache is performed asynchronously in the background.
+     * @param key - The cache key
+     * @param data - The value to cache
+     * @param ttlSeconds - Time to live in seconds
+     */
     put(key: string, data: T, ttlSeconds: number): void;
     /* Excluded from this release type: delete */
 }
@@ -3302,6 +3956,7 @@ declare interface MetricsType {
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface MockApiInboundOptions {
     /**
@@ -3361,6 +4016,7 @@ export declare function MoesifInboundPolicy(request: ZuploRequest, context: Zupl
 
 /**
  * The options for this policy. Many of them can be overridden at the code level in a request using the `AmberfloMeteringPolicy.setRequestProperties` method.
+ * @public
  */
 export declare interface MoesifInboundPolicyOptions {
     /**
@@ -3397,6 +4053,7 @@ export declare class MonetizationInboundPolicy extends InboundPolicy<Monetizatio
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface MonetizationInboundPolicyOptions {
     /**
@@ -3468,6 +4125,10 @@ declare interface NewRelicLoggingOptions {
     service?: string;
 }
 
+/**
+ * New Relic logging plugin
+ * @public
+ */
 export declare class NewRelicLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: NewRelicLoggingOptions);
@@ -3486,6 +4147,10 @@ declare interface NewRelicMetricsOptions {
     include?: IncludeMetrics;
 }
 
+/**
+ * New Relic metrics plugin
+ * @public
+ */
 export declare class NewRelicMetricsPlugin extends MetricsPlugin {
     private options;
     constructor(options: NewRelicMetricsOptions);
@@ -3514,6 +4179,7 @@ export declare class OktaFGAAuthZInboundPolicy extends BaseOpenFGAAuthZInboundPo
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface OktaFGAAuthZInboundPolicyOptions {
     /**
@@ -3560,6 +4226,7 @@ export declare const OktaJwtInboundPolicy: InboundPolicyHandler<OktaJwtInboundPo
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface OktaJwtInboundPolicyOptions {
     /**
@@ -3597,15 +4264,61 @@ declare interface OnResponseSendingHook {
     (response: Response, request: ZuploRequest, context: ZuploContext): Promise<Response> | Response;
 }
 
+/**
+ * Hook function called before sending an AWS Lambda event.
+ * Allows modification of the event before it's sent to Lambda.
+ * @public
+ */
 declare interface OnSendingAwsLambdaEventHook {
     (request: ZuploRequest, context: ZuploContext, event: AwsLambdaEventV1 | AwsLambdaEventV2): Promise<AwsLambdaEventV1 | AwsLambdaEventV2>;
 }
 
 /**
- * @beta
- * @param request - The ZuploRequest
+ * Handler that serves OpenAPI specification files.
+ * Use this to expose your API documentation in a standard format that can be
+ * consumed by tools like Swagger UI, Postman, or API documentation generators.
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @returns ZuploResponse
+ * @returns A Response containing the OpenAPI specification
+ *
+ * @public
+ * @example
+ * ```json
+ * // routes.oas.json - Serve OpenAPI spec at /openapi
+ * {
+ *   "paths": {
+ *     "/openapi": {
+ *       "get": {
+ *         "summary": "Get OpenAPI specification",
+ *         "x-zuplo-route": {
+ *           "handler": {
+ *             "export": "openApiSpecHandler",
+ *             "module": "$import(@zuplo/runtime)",
+ *             "options": {
+ *               "openApiFilePath": "./config/api-spec.oas.json"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Serve different specs based on environment
+ * {
+ *   "handler": {
+ *     "export": "openApiSpecHandler",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "openApiFilePath": "./config/${env.API_VERSION}.oas.json"
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function openApiSpecHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
@@ -4088,6 +4801,7 @@ export declare class OpenFGAAuthZInboundPolicy extends BaseOpenFGAAuthZInboundPo
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface OpenFGAAuthZInboundPolicyOptions {
     /**
@@ -4149,6 +4863,7 @@ declare interface OpenIdJwtInboundPolicyInternalOptions extends Omit<OpenIdJwtIn
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface OpenIdJwtInboundPolicyOptions {
     /**
@@ -4188,9 +4903,36 @@ export declare interface OpenIdJwtInboundPolicyOptions {
 }
 
 /**
- * @beta
  * A policy that can modify the outgoing HTTP response before it is returned
- * to the client.
+ * to the client. Outbound policies run after the handler has generated a response.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { OutboundPolicy, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+ *
+ * interface ResponseHeadersOptions {
+ *   headers: Record<string, string>;
+ * }
+ *
+ * export class AddResponseHeadersPolicy extends OutboundPolicy<ResponseHeadersOptions> {
+ *   async handler(
+ *     response: Response,
+ *     request: ZuploRequest,
+ *     context: ZuploContext
+ *   ) {
+ *     // Clone the response to make headers mutable
+ *     const newResponse = new Response(response.body, response);
+ *
+ *     // Add configured headers
+ *     for (const [name, value] of Object.entries(this.options.headers)) {
+ *       newResponse.headers.set(name, value);
+ *     }
+ *
+ *     return newResponse;
+ *   }
+ * }
+ * ```
  */
 export declare abstract class OutboundPolicy<TOptions = any> extends PolicyBase<TOptions> {
     /**
@@ -4204,30 +4946,70 @@ export declare abstract class OutboundPolicy<TOptions = any> extends PolicyBase<
 }
 
 /**
- * @public
- * A policy that can modify the outgoing HTTP response before it is returned
- * to the client.
+ * A function-based outbound policy that can modify the outgoing HTTP response.
+ * This is the simplest way to create custom outbound policies without extending a class.
  *
- * @param response - The outgoing Response
- * @param request - The incoming Request
+ * @param response - The outgoing Response from the handler
+ * @param request - The original incoming Request
  * @param context - The current context of the Request
  * @param options - The configuration options for the policy
  * @param policyName - The name set on the policy in the configuration
- * @returns A Response object
+ * @returns A modified Response object
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { OutboundPolicyHandler } from "@zuplo/runtime";
+ *
+ * interface CacheControlOptions {
+ *   maxAge: number;
+ *   sMaxAge?: number;
+ *   public?: boolean;
+ * }
+ *
+ * export const cacheControlPolicy: OutboundPolicyHandler<CacheControlOptions> = async (
+ *   response,
+ *   request,
+ *   context,
+ *   options
+ * ) => {
+ *   // Only cache successful responses
+ *   if (response.status !== 200) {
+ *     return response;
+ *   }
+ *
+ *   // Build cache control header
+ *   const directives = [`max-age=${options.maxAge}`];
+ *   if (options.sMaxAge !== undefined) {
+ *     directives.push(`s-maxage=${options.sMaxAge}`);
+ *   }
+ *   if (options.public) {
+ *     directives.push("public");
+ *   }
+ *
+ *   // Clone and modify response
+ *   const newResponse = new Response(response.body, response);
+ *   newResponse.headers.set("Cache-Control", directives.join(", "));
+ *
+ *   return newResponse;
+ * };
+ * ```
  */
 export declare interface OutboundPolicyHandler<TOptions = any> {
     (response: Response, request: ZuploRequest, context: ZuploContext, options: TOptions, policyName: string): Promise<Response>;
 }
 
 /**
- * @beta
+ * Base object for parameter definitions
+ * @public
  */
 export declare type ParameterBaseObject = Modify<Omit<OpenAPIV3_1.ParameterBaseObject, "content" | "allowEmptyValue" | "style" | "allowReserved" | "explode" | "example" | "examples">, {
     schema: OpenAPIV3_1.SchemaObject;
 }>;
 
 /**
- * @beta
+ * Definition of a parameter
+ * @public
  */
 export declare interface ParameterDefinition extends ParameterBaseObject {
     name: string;
@@ -4249,13 +5031,18 @@ declare interface ParsedCorsPolicyConfiguration {
     exposeHeaders?: string;
 }
 
+/**
+ * @public
+ */
 declare interface ParsedRouteData extends Omit<RouteData, "corsPolicies"> {
     corsPolicies: ParsedCorsPolicyConfiguration[];
 }
 
 /**
+ * The base class for inbound and outbound policies.
+ * Provides common functionality for all policy types.
+ *
  * @public
- * The base class for inbound and outbound policies
  */
 declare abstract class PolicyBase<TOptions = any> {
     options: TOptions;
@@ -4264,6 +5051,9 @@ declare abstract class PolicyBase<TOptions = any> {
     /* Excluded from this release type: __constructor */
 }
 
+/**
+ * @public
+ */
 export declare interface PolicyConfiguration {
     name: string;
     policyType: string;
@@ -4283,7 +5073,7 @@ declare type Primitive = null | undefined | string | number | boolean | symbol |
 /**
  * Problem Details for HTTP APIs
  * @see {@link https://www.rfc-editor.org/rfc/rfc7807 |RFC7807}
- * @beta
+ * @public
  */
 declare interface ProblemDetails {
     /**
@@ -4357,7 +5147,7 @@ declare interface ProblemDetails {
 }
 
 /**
- * @beta
+ * @public
  */
 export declare interface ProblemResponseDetails {
     problem: ProblemDetails;
@@ -4373,14 +5163,14 @@ export declare interface ProblemResponseDetails {
 }
 
 /**
- * @beta
+ * @public
  */
 export declare interface ProblemResponseFormat {
     (problemDetails: ProblemResponseDetails, request: ZuploRequest, context: ZuploContext): Promise<Response> | Response;
 }
 
 /**
- * @beta
+ * @public
  */
 export declare class ProblemResponseFormatter {
     static format(problemDetails: ProblemResponseDetails, request: ZuploRequest, context: ZuploContext): Promise<Response>;
@@ -4404,6 +5194,7 @@ export declare const PromptInjectionDetectionOutboundPolicy: OutboundPolicyHandl
 
 /**
  * The options for Prompt Injection Detection Outbound policy.
+ * @public
  */
 export declare interface PromptInjectionDetectionOutboundPolicyOptions {
     /**
@@ -4435,6 +5226,7 @@ export declare const PropelAuthJwtInboundPolicy: InboundPolicyHandler<PropelAuth
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface PropelAuthJwtInboundPolicyOptions {
     /**
@@ -4466,6 +5258,7 @@ export declare const QueryParamToHeaderInboundPolicy: InboundPolicyHandler<Query
 
 /**
  * The options for the query parameter to header inbound policy.
+ * @public
  */
 export declare interface QueryParamToHeaderInboundPolicyOptions {
     /**
@@ -4514,6 +5307,7 @@ export declare class QuotaInboundPolicy extends InboundPolicy<QuotaInboundPolicy
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface QuotaInboundPolicyOptions {
     /**
@@ -4559,11 +5353,13 @@ export declare interface QuotaInboundPolicyOptions {
 
 /**
  * The identifying element of the request that enforces distinct rate limits. For example, you can limit by `user`, `ip`, `function` or `all` - function allows you to specify a simple function to create a string identifier to create a rate-limit group.
+ * @public
  */
 declare type RateLimitByType = "user" | "ip" | "function" | "all";
 
 /**
  * The identifying element of the request that enforces distinct rate limits. For example, you can limit by `user`, `ip`, `function` or `all` - function allows you to specify a simple function to create a string identifier to create a rate-limit group.
+ * @public
  */
 declare type RateLimitByType_2 = "user" | "ip" | "function" | "all";
 
@@ -4571,25 +5367,101 @@ declare type RateLimitFunction<T extends CustomRateLimitDetailsBase> = (request:
 
 /**
  * Adds the retry-after header.
+ * @public
  */
 declare type RateLimitHeaderMode = "none" | "retry-after";
 
 /**
  * Adds the retry-after header.
+ * @public
  */
 declare type RateLimitHeaderMode_2 = "none" | "retry-after";
 
 /**
- * The rate-limiting policy is used to limit the number of requests that
- * can be made against your API based on a key.
+ * Rate limiting policy to control the number of requests to your API.
+ * Supports multiple identification strategies (by user, IP, header, etc.) and
+ * can operate in strict or async mode for different performance characteristics.
  *
  * @title Rate Limiting
  * @public
- * @param request - The ZuploRequest
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @param options - The policy options set in policies.json
- * @param policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
+ * @param options - The rate limiting configuration
+ * @param policyName - The name of the policy instance
+ * @returns The request if allowed, or a 429 Too Many Requests response
+ *
+ * @example
+ * ```json
+ * // policies.json - Rate limit by authenticated user
+ * {
+ *   "name": "rate-limit-by-user",
+ *   "policyType": "rate-limit-inbound",
+ *   "handler": {
+ *     "export": "RateLimitInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "rateLimitBy": "user",
+ *       "requestsAllowed": 100,
+ *       "timeWindowMinutes": 1
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Rate limit by custom header
+ * {
+ *   "handler": {
+ *     "export": "RateLimitInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "rateLimitBy": "header",
+ *       "headerName": "x-customer-id",
+ *       "requestsAllowed": 1000,
+ *       "timeWindowMinutes": 60,
+ *       "mode": "strict"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom rate limit function
+ * import { CustomRateLimitFunction } from "@zuplo/runtime";
+ *
+ * export const customRateLimit: CustomRateLimitFunction = async (
+ *   request,
+ *   context
+ * ) => {
+ *   // Different limits for different plan tiers
+ *   const user = request.user;
+ *   const plan = (user?.data as any)?.plan || "free";
+ *
+ *   switch (plan) {
+ *     case "enterprise":
+ *       return {
+ *         key: user.sub,
+ *         requestsAllowed: 10000,
+ *         timeWindowMinutes: 60
+ *       };
+ *     case "pro":
+ *       return {
+ *         key: user.sub,
+ *         requestsAllowed: 1000,
+ *         timeWindowMinutes: 60
+ *       };
+ *     default:
+ *       return {
+ *         key: user?.sub || request.headers.get("cf-connecting-ip") || "anonymous",
+ *         requestsAllowed: 100,
+ *         timeWindowMinutes: 60
+ *       };
+ *   }
+ * };
+ * ```
  */
 declare const RateLimitInboundPolicy: InboundPolicyHandler<RateLimitInboundPolicyOptions>;
 export { RateLimitInboundPolicy as BasicRateLimitInboundPolicy }
@@ -4597,6 +5469,7 @@ export { RateLimitInboundPolicy }
 
 /**
  * The options for this policy.
+ * @public
  */
 declare interface RateLimitInboundPolicyOptions {
     rateLimitBy: RateLimitByType_2;
@@ -4633,16 +5506,19 @@ export { RateLimitInboundPolicyOptions }
 
 /**
  * The mode of the policy. If set to `async`, the policy will check if the request is over the rate limit without blocking. This can result in some requests allowed over the rate limit.
+ * @public
  */
 declare type RateLimitMode = "strict" | "async";
 
 /**
  * The mode of the policy. If set to `async`, the policy will check if the request is over the rate limit without blocking. This can result in some requests allowed over the rate limit.
+ * @public
  */
 declare type RateLimitMode_2 = "strict" | "async";
 
 /**
  * The options for this policy. Many of them can be overridden at the code level in a request using the `AmberfloMeteringPolicy.setRequestProperties` method.
+ * @public
  */
 declare interface ReadmeMeteringInboundPolicyOptions {
     /**
@@ -4686,10 +5562,48 @@ declare interface ReadmeMeteringInboundPolicyOptions {
 export declare function ReadmeMetricsInboundPolicy(request: ZuploRequest, context: ZuploContext, options: ReadmeMeteringInboundPolicyOptions, policyName: string): Promise<ZuploRequest<RequestGeneric_2>>;
 
 /**
- * @beta
- * @param request - The ZuploRequest
+ * Handler that returns HTTP redirects.
+ * Useful for URL shortening, legacy URL handling, or routing to external services.
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @returns ZuploResponse
+ * @returns A redirect Response with the specified status code
+ *
+ * @public
+ * @example
+ * ```json
+ * // routes.oas.json
+ * {
+ *   "paths": {
+ *     "/old-api": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "redirectHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "location": "https://api.example.com/v2",
+ *             "status": 301
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Temporary redirect (302 is default)
+ * {
+ *   "handler": {
+ *     "export": "redirectHandler",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "location": "https://maintenance.example.com"
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function redirectHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
@@ -4728,6 +5642,7 @@ export declare const RemoveHeadersInboundPolicy: InboundPolicyHandler<RemoveHead
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RemoveHeadersInboundPolicyOptions {
     /**
@@ -4751,6 +5666,7 @@ export declare const RemoveHeadersOutboundPolicy: OutboundPolicyHandler<RemoveHe
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RemoveHeadersOutboundPolicyOptions {
     /**
@@ -4774,6 +5690,7 @@ export declare const RemoveQueryParamsInboundPolicy: InboundPolicyHandler<Remove
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RemoveQueryParamsInboundPolicyOptions {
     /**
@@ -4797,6 +5714,7 @@ export declare const ReplaceStringOutboundPolicy: OutboundPolicyHandler<ReplaceS
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ReplaceStringOutboundPolicyOptions {
     /**
@@ -4814,7 +5732,8 @@ export declare interface ReplaceStringOutboundPolicyOptions {
 }
 
 /**
- * The types of the properties in a request
+ * Generic type parameters for a request.
+ * Extends RequestInitGeneric and adds query parameter typing.
  * @public
  */
 export declare interface RequestGeneric extends RequestInitGeneric {
@@ -4826,7 +5745,8 @@ export declare interface RequestGeneric extends RequestInitGeneric {
 /* Excluded from this release type: RequestHandlerProxy */
 
 /**
- * The types of the properties in a request init object
+ * Generic type parameters for request initialization.
+ * Used to strongly type the user data and path parameters.
  * @public
  */
 export declare interface RequestInitGeneric {
@@ -4834,6 +5754,10 @@ export declare interface RequestInitGeneric {
     Params?: RequestParamsDefault;
 }
 
+/**
+ * Metadata for request logger entries
+ * @public
+ */
 export declare interface RequestLoggerMetaData {
     requestStartTime: Date;
     durationMs: number;
@@ -4842,6 +5766,10 @@ export declare interface RequestLoggerMetaData {
     systemUserAgent: string;
 }
 
+/**
+ * Options for request logger
+ * @public
+ */
 export declare interface RequestLoggerOptions<T> {
     name: string;
     dispatchFunction: DispatchRequestLoggerEntries<T>;
@@ -4849,6 +5777,10 @@ export declare interface RequestLoggerOptions<T> {
     batchPeriodSeconds?: number;
 }
 
+/**
+ * Request logger plugin
+ * @public
+ */
 export declare class RequestLoggerPlugin<T extends BasicDictionary> extends SystemRuntimePlugin {
     #private;
     constructor(options: RequestLoggerOptions<T>);
@@ -4878,6 +5810,7 @@ export declare const RequestSizeLimitInboundPolicy: InboundPolicyHandler<Request
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RequestSizeLimitInboundPolicyOptions {
     /**
@@ -4891,8 +5824,24 @@ export declare interface RequestSizeLimitInboundPolicyOptions {
 }
 
 /**
- * The authorized identity on the incoming request
+ * Represents an authenticated user on the request.
+ * Set by authentication policies like API key, JWT, or OAuth.
+ *
  * @public
+ * @example
+ * ```typescript
+ * // Access user info in a handler
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   if (!request.user) {
+ *     return new Response("Unauthorized", { status: 401 });
+ *   }
+ *
+ *   const userId = request.user.sub;
+ *   const customData = request.user.data as { role: string; tenantId: string };
+ *
+ *   context.log.info(`Request from user ${userId} with role ${customData.role}`);
+ * }
+ * ```
  */
 export declare interface RequestUser<TUserData> {
     sub: string;
@@ -4900,20 +5849,101 @@ export declare interface RequestUser<TUserData> {
 }
 
 /**
- * Validate inbound requests based on Open API specification.
+ * Validates incoming requests against your OpenAPI specification.
+ * Checks query parameters, path parameters, headers, and request body
+ * to ensure they match the defined schema before processing.
  *
  * @title Request Validation
  * @public
- * @param request - The ZuploRequest
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @param options - The policy options set in policies.json
- * @param policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
+ * @param options - Validation configuration options
+ * @param policyName - The name of the policy instance
+ * @returns The validated request or a 400 Bad Request response with validation errors
+ *
+ * @example
+ * ```json
+ * // policies.json - Validate all request components
+ * {
+ *   "name": "validate-request",
+ *   "policyType": "request-validation-inbound",
+ *   "handler": {
+ *     "export": "RequestValidationInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "validateBody": true,
+ *       "validateQueryParameters": true,
+ *       "validatePathParameters": true,
+ *       "validateHeaders": true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Validate only body with custom error handling
+ * {
+ *   "handler": {
+ *     "export": "RequestValidationInboundPolicy",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "validateBody": {
+ *         "enabled": true,
+ *         "logging": true,
+ *         "requestSizeLimit": 1048576
+ *       },
+ *       "validateQueryParameters": false,
+ *       "validatePathParameters": false,
+ *       "validateHeaders": false
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```yaml
+ * # OpenAPI schema definition
+ * paths:
+ *   /users/{userId}:
+ *     post:
+ *       parameters:
+ *         - name: userId
+ *           in: path
+ *           required: true
+ *           schema:
+ *             type: string
+ *             format: uuid
+ *         - name: include
+ *           in: query
+ *           schema:
+ *             type: array
+ *             items:
+ *               type: string
+ *               enum: [profile, settings, history]
+ *       requestBody:
+ *         required: true
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               required: [name, email]
+ *               properties:
+ *                 name:
+ *                   type: string
+ *                   minLength: 1
+ *                   maxLength: 100
+ *                 email:
+ *                   type: string
+ *                   format: email
+ * ```
  */
 export declare const RequestValidationInboundPolicy: InboundPolicyHandler<RequestValidationInboundPolicyOptions>;
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RequestValidationInboundPolicyOptions {
     /**
@@ -4945,6 +5975,7 @@ export declare const RequireOriginInboundPolicy: InboundPolicyHandler<RequireOri
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface RequireOriginInboundPolicyOptions {
     /**
@@ -4964,7 +5995,8 @@ declare type ResolveRequestQuery<TQuery extends RequestQueryDefault | undefined>
 declare type ResolveUserData<TUserData extends UserDataDefault | undefined> = TUserData extends UserDataDefault ? TUserData : UserDataDefault;
 
 /**
- * @beta
+ * Definition of responses for a route
+ * @public
  */
 export declare type ResponsesDefinition = Record<HttpStatusCode | HttpStatusCodeRangeDefinition, Modify<Omit<OpenAPIV3_1.ResponseObject, "links">, {
     headers?: {
@@ -4972,18 +6004,29 @@ export declare type ResponsesDefinition = Record<HttpStatusCode | HttpStatusCode
     };
 }>>;
 
+/**
+ * Event fired before a response is sent
+ * @public
+ */
 export declare class ResponseSendingEvent extends Event {
     constructor(request: ZuploRequest, response: Response);
     readonly request: ZuploRequest;
     mutableResponse: Response | Promise<Response>;
 }
 
+/**
+ * Event fired after a response has been sent
+ * @public
+ */
 export declare class ResponseSentEvent extends Event {
     constructor(request: ZuploRequest, response: Response);
     readonly request: ZuploRequest;
     readonly response: Response;
 }
 
+/**
+ * @public
+ */
 export declare interface RouteConfiguration extends Omit<BuildRouteConfiguration, "raw"> {
     /**
      * @deprecated Please switch to "raw().operationId"
@@ -5011,6 +6054,9 @@ export declare interface RouteConfiguration extends Omit<BuildRouteConfiguration
     raw<T = any>(): T;
 }
 
+/**
+ * @public
+ */
 export declare interface RouteData {
     /**
      * @deprecated This property is not used and will be removed in future versions
@@ -5033,10 +6079,35 @@ export declare interface RouteHandler<T = unknown> {
 /* Excluded from this release type: RuntimeEnvironment */
 
 /**
- * Used to indicate errors that are caused by user input
- * These errors are shown to the user and logged in user logs
- * These errors are NOT fatal and will not cause monitoring alerts
+ * Used to indicate errors that are caused by user input or runtime conditions.
+ * These errors are shown to the user and logged in user logs.
+ * They are NOT fatal and will not cause monitoring alerts.
+ *
  * @public
+ * @example
+ * ```typescript
+ * import { RuntimeError } from "@zuplo/runtime";
+ *
+ * // Simple error
+ * throw new RuntimeError("Invalid API key format");
+ *
+ * // Error with cause
+ * try {
+ *   await someOperation();
+ * } catch (err) {
+ *   throw new RuntimeError("Failed to process request", { cause: err });
+ * }
+ *
+ * // Error with extension members for additional context
+ * throw new RuntimeError({
+ *   message: "Rate limit exceeded",
+ *   extensionMembers: {
+ *     limit: 100,
+ *     window: "1m",
+ *     retryAfter: 60
+ *   }
+ * });
+ * ```
  */
 export declare class RuntimeError extends Error {
     extensionMembers: Record<string, unknown> | undefined;
@@ -5074,6 +6145,10 @@ export declare interface RuntimeExtensions {
     addPreRoutingHook(hook: PreRoutingHook): void;
 }
 
+/**
+ * Function to configure runtime extensions
+ * @public
+ */
 export declare interface RuntimeExtensionsFunction {
     (runtime: RuntimeExtensions): Promise<void>;
 }
@@ -5088,10 +6163,11 @@ declare abstract class RuntimePlugin {
 
 declare type RuntimeType = "deno" | "cloudflare";
 
-export declare function sanitizedIdentifierName(name: string): string;
+/* Excluded from this release type: sanitizedIdentifierName */
 
 /**
  * @deprecated Use RequestValidationInboundPolicy instead
+ * @public
  */
 export declare const SchemaBasedRequestValidation: InboundPolicyHandler<RequestValidationInboundPolicyOptions>;
 
@@ -5111,6 +6187,7 @@ export declare const SecretMaskingOutboundPolicy: OutboundPolicyHandler<SecretMa
 
 /**
  * The options for the secret masking policy.
+ * @public
  */
 export declare interface SecretMaskingOutboundPolicyOptions {
     /**
@@ -5154,6 +6231,7 @@ export declare function SemanticCacheInboundPolicy(request: ZuploRequest, contex
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare type SemanticCacheInboundPolicyOptions = {
     [k: string]: unknown;
@@ -5233,6 +6311,7 @@ export declare const SetBodyInboundPolicy: InboundPolicyHandler<SetBodyInboundPo
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SetBodyInboundPolicyOptions {
     /**
@@ -5256,6 +6335,7 @@ export declare const SetHeadersInboundPolicy: InboundPolicyHandler<SetHeadersInb
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SetHeadersInboundPolicyOptions {
     /**
@@ -5292,6 +6372,7 @@ export declare const SetHeadersOutboundPolicy: OutboundPolicyHandler<SetHeadersO
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SetHeadersOutboundPolicyOptions {
     /**
@@ -5313,6 +6394,12 @@ export declare interface SetHeadersOutboundPolicyOptions {
     }[];
 }
 
+/**
+ * Sets custom context data that will be included with Moesif analytics events
+ * @public
+ * @param context - The ZuploContext for the current request
+ * @param moesifContext - Custom data to include with Moesif events (userId, companyId, metadata, etc.)
+ */
 export declare function setMoesifContext(context: ZuploContext, moesifContext: MoesifContext): void;
 
 /**
@@ -5330,6 +6417,7 @@ export declare const SetQueryParamsInboundPolicy: InboundPolicyHandler<SetQueryP
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SetQueryParamsInboundPolicyOptions {
     /**
@@ -5366,6 +6454,7 @@ export declare const SetStatusOutboundPolicy: OutboundPolicyHandler<SetStatusOut
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SetStatusOutboundPolicyOptions {
     /**
@@ -5402,6 +6491,7 @@ export declare const SleepInboundPolicy: InboundPolicyHandler<SleepInboundPolicy
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SleepInboundPolicyOptions {
     /**
@@ -5446,6 +6536,10 @@ declare interface SplunkLoggingOptions {
     channel?: string;
 }
 
+/**
+ * Splunk logging plugin
+ * @public
+ */
 export declare class SplunkLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: SplunkLoggingOptions);
@@ -5455,10 +6549,44 @@ export declare class SplunkLoggingPlugin extends LogPlugin {
 /* Excluded from this release type: StandardEnv */
 
 /**
- * The StreamingZoneCache is a wrapper around the zone cache that allows
- * storing a ReadableStream by wrapping it in a Response. The key
- * is stored as the request URL for retrieval later.
- * @beta This is a beta feature and may change in the future.
+ * A specialized zone cache for storing and retrieving ReadableStreams.
+ * Unlike regular ZoneCache which serializes to JSON, this cache stores raw stream data,
+ * making it ideal for caching response bodies, file uploads, or other streaming content.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { StreamingZoneCache, ZuploContext } from "@zuplo/runtime";
+ *
+ * export async function cacheStreamingResponse(
+ *   request: ZuploRequest,
+ *   context: ZuploContext
+ * ) {
+ *   const cache = new StreamingZoneCache("stream-cache", context);
+ *   const cacheKey = `api-response-${request.url}`;
+ *
+ *   // Check cache first
+ *   const cachedStream = await cache.get(cacheKey);
+ *   if (cachedStream) {
+ *     return new Response(cachedStream, {
+ *       headers: { "X-Cache": "HIT" }
+ *     });
+ *   }
+ *
+ *   // Fetch fresh data
+ *   const response = await fetch("https://api.example.com/large-file");
+ *
+ *   // Clone the response so we can cache and return it
+ *   const [cacheStream, returnStream] = response.body!.tee();
+ *
+ *   // Cache for 5 minutes
+ *   await cache.put(cacheKey, cacheStream, 300);
+ *
+ *   return new Response(returnStream, {
+ *     headers: { "X-Cache": "MISS" }
+ *   });
+ * }
+ * ```
  */
 export declare class StreamingZoneCache {
     #private;
@@ -5567,6 +6695,7 @@ export declare class StripeWebhookVerificationInboundPolicy extends InboundPolic
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface StripeWebhookVerificationInboundPolicyOptions {
     /**
@@ -5599,6 +6728,10 @@ declare interface SumoLogicLoggingOptions {
     fields?: CustomLogFields;
 }
 
+/**
+ * Sumo Logic logging plugin
+ * @public
+ */
 export declare class SumoLogicLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: SumoLogicLoggingOptions);
@@ -5621,6 +6754,7 @@ export declare const SupabaseJwtInboundPolicy: InboundPolicyHandler<SupabaseJwtI
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface SupabaseJwtInboundPolicyOptions {
     /**
@@ -5698,6 +6832,7 @@ declare interface TupleKey {
 
 /**
  * No authentication.
+ * @public
  */
 declare interface UnauthenticatedCredentialConfig {
     /**
@@ -5722,6 +6857,7 @@ export declare const UpstreamAzureAdServiceAuthInboundPolicy: InboundPolicyHandl
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamAzureAdServiceAuthInboundPolicyOptions {
     /**
@@ -5762,6 +6898,7 @@ export declare const UpstreamFirebaseAdminAuthInboundPolicy: InboundPolicyHandle
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamFirebaseAdminAuthInboundPolicyOptions {
     /**
@@ -5794,6 +6931,7 @@ export declare const UpstreamFirebaseUserAuthInboundPolicy: InboundPolicyHandler
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamFirebaseUserAuthInboundPolicyOptions {
     /**
@@ -5857,6 +6995,7 @@ export declare class UpstreamGcpFederatedAuthInboundPolicy extends InboundPolicy
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamGcpFederatedAuthInboundPolicyOptions {
     /**
@@ -5903,6 +7042,7 @@ export declare const UpstreamGcpJwtInboundPolicy: InboundPolicyHandler<UpstreamG
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamGcpJwtInboundPolicyOptions {
     /**
@@ -5932,6 +7072,7 @@ export declare const UpstreamGcpServiceAuthInboundPolicy: InboundPolicyHandler<U
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface UpstreamGcpServiceAuthInboundPolicyOptions {
     /**
@@ -5966,19 +7107,99 @@ export declare interface UpstreamGcpServiceAuthInboundPolicyOptions {
 }
 
 /**
- * @beta
- * @param request - The ZuploRequest
+ * Handler that forwards requests to a different base URL while preserving the path.
+ * Ideal for proxying requests to backend services or creating API gateways.
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @returns ZuploResponse
+ * @returns A Response from the forwarded URL
+ *
+ * @public
+ * @example
+ * ```json
+ * // routes.oas.json - Forward all /api/* requests to backend
+ * {
+ *   "paths": {
+ *     "/api/{path}*": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "urlForwardHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "baseUrl": "https://backend.example.com",
+ *             "forwardSearch": true
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Forward with dynamic base URL based on environment
+ * {
+ *   "handler": {
+ *     "export": "urlForwardHandler",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "baseUrl": "$env(BACKEND_URL)",
+ *       "forwardSearch": false,
+ *       "followRedirects": true
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function urlForwardHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
 /**
- * Proxy requests to a different url
- * @param request - The ZuploRequest
+ * Handler that rewrites the request URL based on a pattern.
+ * Useful for routing requests to different backends based on path parameters,
+ * query strings, or other request properties.
+ *
+ * @param request - The incoming ZuploRequest
  * @param context - The ZuploContext
- * @returns
- * @beta
+ * @returns A Response from the rewritten URL
+ *
+ * @public
+ * @example
+ * ```json
+ * // routes.oas.json - Route to different API versions
+ * {
+ *   "paths": {
+ *     "/api/{version}/users/{id}": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "urlRewriteHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "rewritePattern": "https://api-${params.version}.example.com/users/${params.id}",
+ *             "forwardSearch": true
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Route to backend service with custom headers
+ * {
+ *   "handler": {
+ *     "export": "urlRewriteHandler",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "rewritePattern": "https://backend.internal/api${url.pathname}",
+ *       "forwardSearch": false,
+ *       "followRedirects": true
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function urlRewriteHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
@@ -6010,6 +7231,7 @@ declare interface ValidateJsonSchemaInboundInternalOptions extends Omit<Validate
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface ValidateJsonSchemaInboundOptions {
     /**
@@ -6020,21 +7242,25 @@ export declare interface ValidateJsonSchemaInboundOptions {
 
 /**
  * The action to perform when validation fails.
+ * @public
  */
 declare type ValidationOptions = "none" | "log-only" | "reject-and-log" | "reject-only";
 
 /**
  * The action to perform when validation fails.
+ * @public
  */
 declare type ValidationOptions1 = "none" | "log-only" | "reject-and-log" | "reject-only";
 
 /**
  * The action to perform when validation fails.
+ * @public
  */
 declare type ValidationOptions2 = "none" | "log-only" | "reject-and-log" | "reject-only";
 
 /**
  * The action to perform when validation fails.
+ * @public
  */
 declare type ValidationOptions3 = "none" | "log-only" | "reject-and-log" | "reject-only";
 
@@ -6067,6 +7293,10 @@ declare interface VMWareLogInsightLoggingOptions {
     onMessageSending?: (event: LogInsightLogEntry) => LogInsightLogEntry;
 }
 
+/**
+ * VMware Log Insight logging plugin
+ * @public
+ */
 export declare class VMWareLogInsightLoggingPlugin extends LogPlugin {
     private options;
     constructor(options: VMWareLogInsightLoggingOptions);
@@ -6095,6 +7325,7 @@ export declare const WebBotAuthInboundPolicy: InboundPolicyHandler<WebBotAuthInb
 
 /**
  * Options for the Web Bot Auth Inbound Policy.
+ * @public
  */
 export declare interface WebBotAuthInboundPolicyOptions {
     /**
@@ -6116,11 +7347,53 @@ export declare interface WebBotAuthInboundPolicyOptions {
 }
 
 /**
- * Handle websocket requests to a different url
- * @param request - The ZuploRequest
+ * Handler that proxies WebSocket connections to a different URL.
+ * Enables WebSocket support in your API gateway for real-time communication.
+ *
+ * @param request - The incoming ZuploRequest with WebSocket upgrade headers
  * @param context - The ZuploContext
- * @returns
+ * @returns A WebSocket upgrade Response (101 Switching Protocols)
+ *
  * @beta
+ * @example
+ * ```json
+ * // routes.oas.json - WebSocket endpoint
+ * {
+ *   "paths": {
+ *     "/ws/chat": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "webSocketHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "rewritePattern": "wss://chat-backend.example.com/ws"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * // Dynamic WebSocket routing based on path parameters
+ * {
+ *   "paths": {
+ *     "/ws/{room}": {
+ *       "x-zuplo-route": {
+ *         "handler": {
+ *           "export": "webSocketHandler",
+ *           "module": "$import(@zuplo/runtime)",
+ *           "options": {
+ *             "rewritePattern": "wss://chat.example.com/rooms/${params.room}"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare function webSocketHandler(request: ZuploRequest, context: ZuploContext): Promise<Response>;
 
@@ -6176,6 +7449,7 @@ export declare class XmlToJsonOutboundPolicy extends OutboundPolicy<XmlToJsonPol
 
 /**
  * The options for this policy.
+ * @public
  */
 export declare interface XmlToJsonPolicyOptions {
     /**
@@ -6217,23 +7491,70 @@ export declare interface XmlToJsonPolicyOptions {
 }
 
 /**
- * This is a simple wrapper around the data-center HTTP cache
- * to enable simple objects to be stored by a string key. This is
- * useful to us and customers and provides a very high-performance
- * read-through cache that stores data in the same data-center. It is
- * not replicated.
+ * A high-performance cache that stores data in the same data center (zone).
+ * Uses the underlying HTTP cache API to store JSON-serializable objects by string keys.
+ * Data is not replicated across zones, making it ideal for zone-local caching scenarios.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { ZoneCache, ZuploContext } from "@zuplo/runtime";
+ *
+ * export async function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   const cache = new ZoneCache<ProductData>("product-cache", context);
+ *
+ *   // Store product data for 10 minutes
+ *   await cache.put("product-123", {
+ *     id: "123",
+ *     name: "Widget",
+ *     price: 99.99
+ *   }, 600);
+ *
+ *   // Retrieve cached data
+ *   const product = await cache.get("product-123");
+ *   if (product) {
+ *     return Response.json(product);
+ *   }
+ *
+ *   return new Response("Product not found", { status: 404 });
+ * }
+ * ```
  */
 export declare class ZoneCache<T = any> {
     #private;
+    /**
+     * Creates a new ZoneCache instance.
+     * @param name - A unique name for this cache instance
+     * @param context - The ZuploContext from the current request
+     */
     constructor(name: string, context: ZuploContext);
     /* Excluded from this release type: __constructor */
+    /**
+     * Retrieves a value from the zone cache by key.
+     * @param key - The cache key to retrieve
+     * @returns The cached value or undefined if not found, expired, or on error
+     */
     get(key: string): Promise<T | undefined>;
+    /**
+     * Stores a value in the zone cache with the specified TTL.
+     * @param key - The cache key
+     * @param data - The value to cache (must be JSON-serializable)
+     * @param ttlSeconds - Time to live in seconds
+     */
     put(key: string, data: T, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes a key from the zone cache.
+     * @param key - The cache key to delete
+     */
     delete(key: string): Promise<void>;
     deleteFallback(key: string): Promise<void>;
     logDebug(...messages: unknown[]): void;
 }
 
+/**
+ * The ZuploContext provides information about the current request and helper methods.
+ * @public
+ */
 export declare interface ZuploContext extends EventTarget {
     /**
      * The unique identifier of this context
@@ -6306,10 +7627,70 @@ export declare interface ZuploContext extends EventTarget {
 /* Excluded from this release type: ZuploEventContext */
 
 /**
- * ZuploRequest includes various parsed objects from the
- * incoming Request. This object inherits from the web
- * standard {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}.
+ * Enhanced Request class that extends the standard Web Request API with
+ * convenient properties for accessing path parameters, query strings, and user data.
+ * This is the request type passed to all handlers and policies in Zuplo.
+ *
  * @public
+ * @example
+ * ```typescript
+ * import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
+ *
+ * export function myHandler(request: ZuploRequest, context: ZuploContext) {
+ *   // Access query parameters
+ *   const page = request.query.page || "1";
+ *   const limit = request.query.limit || "10";
+ *
+ *   // Access path parameters (e.g., from /users/:userId)
+ *   const userId = request.params.userId;
+ *
+ *   // Access authenticated user
+ *   const user = request.user;
+ *
+ *   // Standard Request properties still available
+ *   const contentType = request.headers.get("content-type");
+ *   const method = request.method;
+ *
+ *   return Response.json({
+ *     userId,
+ *     page,
+ *     limit,
+ *     authenticated: !!user
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Strongly typed request parameters
+ * interface MyParams {
+ *   userId: string;
+ *   orderId: string;
+ * }
+ *
+ * interface MyQuery {
+ *   include?: string;
+ *   format?: "json" | "xml";
+ * }
+ *
+ * interface MyUserData {
+ *   role: "admin" | "user";
+ *   tenantId: string;
+ * }
+ *
+ * type MyRequest = ZuploRequest<{
+ *   Params: MyParams;
+ *   Query: MyQuery;
+ *   UserData: MyUserData;
+ * }>;
+ *
+ * export function typedHandler(request: MyRequest, context: ZuploContext) {
+ *   // All properties are now strongly typed
+ *   const userId = request.params.userId; // string
+ *   const format = request.query.format; // "json" | "xml" | undefined
+ *   const role = request.user?.data.role; // "admin" | "user" | undefined
+ * }
+ * ```
  */
 export declare class ZuploRequest<TOptions extends RequestGeneric = RequestGeneric> extends Request {
     #private;
@@ -6362,7 +7743,8 @@ export declare class ZuploRequest<TOptions extends RequestGeneric = RequestGener
 }
 
 /**
- * The initialization values of a request
+ * Options for creating a new ZuploRequest.
+ * Extends the standard RequestInit with Zuplo-specific properties.
  * @public
  */
 export declare interface ZuploRequestInit<TOptions extends RequestInitGeneric = RequestInitGeneric> extends RequestInit {