@zuplo/runtime 6.58.0 → 6.58.4

package/out/types/index.d.ts

@@ -4658,71 +4658,23 @@ declare type LokiTransportVersion = 1 | 2;
 
 /* Excluded from this release type: LookupResult */
 
-/**
- * Plugin for adding MCP (Model Context Protocol) custom tools to Zuplo
- *
- * This plugin allows end users to create custom MCP tools using a simple SDK
- * that can perform complex operations including invoking multiple routes on the gateway or
- * implementing custom logic beyond simple route mapping.
- */
-export declare class McpCustomToolsPlugin extends SystemRuntimePlugin {
-  private options;
-  private mcpServer;
-  private transport;
-  constructor(options: McpCustomToolsPluginOptions);
-  private validateTools;
-  registerRoutes(options: {
-    router: Router;
-    runtimeSettings: RuntimeSettings;
-  }): void;
-  private createMcpHandler;
-  /**
-   * Lazy loads the MCP server, http transport, and tools on first call
-   */
-  private initializeMcpServer;
-  /**
-   * Registers individual custom tools from users given a McpToolDefinion
-   */
-  private registerTool;
-}
-
-/**
- * Configuration options for the MCP Custom Tools Plugin
- */
-export declare interface McpCustomToolsPluginOptions {
-  /**
-   * Name of the MCP server
-   */
-  name?: string;
-  /**
-   * Version of the MCP server
-   */
-  version?: string;
-  /**
-   * The endpoint path where the MCP server will be registered on the gateway
-   * Default: "/mcp"
-   */
-  endpoint?: string;
-  /**
-   * Custom tools to register with the MCP server
-   */
-  tools: McpToolDefinition[];
-}
-
 /**
  * SDK for creating and managing MCP custom tools
  *
  * Provides a fluent API for defining custom MCP tools that can perform
  * complex operations including calling multiple routes or implementing
  * custom logic beyond simple route mapping.
+ * @beta
  */
 export declare class McpCustomToolsSDK {
   /**
    * Create a new tool builder
+   * @beta
    */
   createTool(): McpToolBuilder;
   /**
    * Define a tool with a configuration object
+   * @beta
    */
   defineTool<TSchema extends z.ZodType>(config: {
     name: string;
@@ -4733,24 +4685,36 @@ export declare class McpCustomToolsSDK {
   }): McpToolDefinition<z.infer<TSchema>>;
   /**
    * Create a text response
+   * @beta
    */
   textResponse(text: string): CallToolResult;
   /**
    * Create a JSON response (automatically stringified and put in structured content)
+   * @beta
    */
   jsonResponse(data: any): CallToolResult;
   /**
    * Create an error response
+   * @beta
    */
   errorResponse(message: string): CallToolResult;
   /**
    * Create an image response
+   * @beta
    */
   imageResponse(data: string, mimeType: string): CallToolResult;
   /**
    * Create a resource response
+   * @beta
    */
   resourceResponse(uri: string, mimeType?: string): CallToolResult;
+  /**
+   * Fetches the original headers used to invoke the MCP server.
+   * This is especially useful for when re-invoking Gateway routes and passing through
+   * all captured headers.
+   * @beta
+   */
+  getInvokeHeaders(): Record<string, string>;
 }
 
 /**
@@ -4769,37 +4733,45 @@ export declare function mcpServerHandler(
 
 /**
  * Builder for creating MCP tools with type safety
+ * @beta
  */
 export declare class McpToolBuilder<TSchema extends z.ZodSchema = z.ZodAny> {
   private config;
   /**
    * Set the tool name
+   * @beta
    */
   name(name: string): this;
   /**
    * Set the tool description
+   * @beta
    */
   description(description: string): this;
   /**
    * Set the input schema for the tool
+   * @beta
    */
   schema<S extends z.ZodSchema>(schema: S): McpToolBuilder<S>;
   /**
    * Set the output schema for the tool
+   * @beta
    */
   outSchema<S extends z.ZodSchema>(schema: S): McpToolBuilder<S>;
   /**
    * Set the handler function for the tool
+   * @beta
    */
   handler(handler: McpToolHandler<z.infer<TSchema>>): this;
   /**
    * Build the tool definition
+   * @beta
    */
   build(): McpToolDefinition<z.infer<TSchema>>;
 }
 
 /**
  * Definition of a custom MCP tool
+ * @beta
  */
 export declare interface McpToolDefinition<TSchema = any> {
   name: string;
@@ -4811,6 +4783,7 @@ export declare interface McpToolDefinition<TSchema = any> {
 
 /**
  * Handler function for MCP tools
+ * @beta
  */
 export declare type McpToolHandler<TArgs = any> = (
   args: TArgs,
@@ -4904,6 +4877,52 @@ export declare class MemoryZoneReadThroughCache<T = unknown> {
   /* Excluded from this release type: delete */
 }
 
+declare interface Meter {
+  /**
+   * The event type. This is used to match the event to a meter.
+   */
+  type: string;
+  /**
+   * A dictionary of additional data to be sent to OpenMeter (extensible in code).
+   */
+  data?: {
+    [k: string]: unknown;
+  };
+}
+
+/**
+ * Represents a meter event that will be sent to OpenMeter.
+ * You can optionally override the CloudEvents fields like id, time, source, and subject.
+ *
+ * @example
+ * ```typescript
+ * const meter: Meter = {
+ *   type: "api-call",
+ *   data: {
+ *     endpoint: "/api/users",
+ *     method: "POST",
+ *     responseTime: 123
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom CloudEvents fields
+ * const meter: Meter = {
+ *   type: "llm-usage",
+ *   id: "custom-event-id-123",
+ *   subject: "user-456",
+ *   data: {
+ *     model: "gpt-4",
+ *     tokens: 1500
+ *   }
+ * };
+ * ```
+ * @public
+ */
+declare type Meter_2 = Partial<OpenMeterEvent> & Meter;
+
 /**
  * Base class for determining type of plugin
  * @public
@@ -5089,7 +5108,7 @@ export declare interface MoesifInboundPolicyOptions {
  * The Monetization policy enables you to track & monetize by your API's usage
  *
  * @title Monetization
- * @beta
+ * @deprecated - Zuplo monetization v1 has been deprecated and will be removed in the future.
  * @param request - The ZuploRequest
  * @param context - The ZuploContext
  * @param options - The policy options set in policies.json
@@ -6105,9 +6124,12 @@ export declare interface OpenIdJwtInboundPolicyOptions {
   oAuthResourceMetadataEnabled?: boolean;
 }
 
+/* Excluded from this release type: OpenMeterEvent */
+
 /**
  * OpenMeter is a usage metering service. This policy allows
  * you to send metering calls for each API to their event ingest endpoint.
+ * It also supports entitlement checking to verify if a subject has access to a feature.
  *
  * @title OpenMeter Metering
  * @public
@@ -6117,73 +6139,105 @@ export declare interface OpenIdJwtInboundPolicyOptions {
  * @param policyName - The name of the policy as set in policies.json
  * @returns A Request or a Response
  */
-export declare function OpenMeterMeteringInboundPolicy(
-  request: ZuploRequest,
-  context: ZuploContext,
-  options: OpenMeterMeteringInboundPolicy_2,
-  policyName: string
-): Promise<ZuploRequest<RequestGeneric_2>>;
+export declare class OpenMeterInboundPolicy extends InboundPolicy<OpenMeterInboundPolicyOptions> {
+  #private;
+  constructor(options: OpenMeterInboundPolicyOptions, policyName: string);
+  handler(
+    request: ZuploRequest<RequestGeneric>,
+    context: ZuploContext
+  ): Promise<ZuploRequest<RequestGeneric> | Response>;
+  /**
+   * Extracts the subject identifier from the request based on the configured subjectPath.
+   * The subject is used as the customer/user identifier in OpenMeter events.
+   *
+   * @param request - The incoming request
+   * @returns The subject identifier if found, undefined otherwise
+   * @throws RuntimeError if subjectPath is configured but request.user is undefined
+   */
+  private getSubject;
+  /**
+   * Checks if a subject has access to a specific feature by querying the OpenMeter entitlements API.
+   *
+   * @param subject - The subject/customer identifier
+   * @param featureKey - The feature key to check entitlements for
+   * @param context - The Zuplo context for logging
+   * @returns The entitlement result including access status and usage information
+   */
+  private checkEntitlement;
+  /**
+   * Sets up metering to send events to OpenMeter when the response matches the configured status codes.
+   * Events are batched and sent asynchronously after the response is sent.
+   *
+   * @param request - The incoming request
+   * @param context - The Zuplo context
+   */
+  private setupMetering;
+  /**
+   * Sets custom meters for the current request. This allows other policies or handlers
+   * to define specific metering events that should be sent to OpenMeter.
+   *
+   * @param context - The Zuplo context
+   * @param value - Array of meter configurations to use for this request
+   *
+   * @example
+   * ```typescript
+   * // In a custom policy or handler
+   * OpenMeterInboundPolicy.setMeters(context, [
+   *   {
+   *     type: "api-call",
+   *     data: {
+   *       endpoint: request.url,
+   *       method: request.method,
+   *       tokens: 150
+   *     }
+   *   },
+   *   {
+   *     type: "llm-usage",
+   *     data: {
+   *       model: "gpt-4",
+   *       prompt_tokens: 100,
+   *       completion_tokens: 50
+   *     }
+   *   }
+   * ]);
+   * ```
+   */
+  static setMeters(context: ZuploContext, value: Meter_2 | Meter_2[]): void;
+}
 
 /**
  * Send usage metrics to OpenMeter.
  * @public
  */
-declare interface OpenMeterMeteringInboundPolicy_2 {
+export declare interface OpenMeterInboundPolicyOptions {
   /**
    * The URL of the OpenMeter API endpoint.
    */
-  url: string;
+  apiUrl?: string;
   /**
    * The API key to use when sending metering calls to OpenMeter.
    */
-  apiKey?: string;
-  /**
-   * The type of event to use when sending metering calls to OpenMeter (overridable in code).
-   */
-  eventType?: string;
-  /**
-   * The value to use when sending metering calls to OpenMeter (overridable in code).
-   */
-  meterValue?: number;
+  apiKey: string;
   /**
-   * The path to the property on `request.user` contains the customer ID. For example `.data.accountNumber` would read the `request.user.data.accountNumber` property.
+   * A single meter configuration or an array of meter configurations for OpenMeter.
    */
-  customerIdPropertyPath?: string;
+  meter?: Meter | Meter[];
   /**
-   * The default customerId (subject) for all metering calls - overridable in code and by `customerIdPropertyPath`.
+   * A list of successful status codes and ranges "200-299, 304" that should trigger a metering event.
    */
-  customerId?: string;
+  meterOnStatusCodes?: string | number[];
   /**
-   * The source identifier for the event (e.g. service name).
+   * The event's source (e.g. the service name).
    */
-  source?: string;
+  eventSource?: string;
   /**
-   * A dictionary of additional data to be sent to OpenMeter (extensible in code).
+   * A list of entitlements (feature keys) required in order for the call to be allowed.
    */
-  data?: {
-    [k: string]: unknown;
-  };
+  requiredEntitlements?: string[];
   /**
-   * A list of successful status codes and ranges "200-299, 304" that should trigger a metering call to OpenMeter.
+   * The path to the property on `request.user` that contains the subject used for meters and entitlements. For example `.data.accountId` would read the `request.user.data.accountId` property.
    */
-  statusCodes: string | number[];
-}
-
-export declare type OpenMeterMeteringInboundPolicyOptions =
-  OpenMeterMeteringInboundPolicy_2;
-
-export declare class OpenMeterMeteringPolicy {
-  static setRequestProperties(
-    context: ZuploContext,
-    properties: OpenMeterMeteringProperties
-  ): void;
-}
-
-declare interface OpenMeterMeteringProperties {
-  eventType: string;
-  customerId: string;
-  meterValue?: number;
-  data?: Record<string, unknown>;
+  subjectPath?: string;
 }
 
 /**
@@ -8006,7 +8060,7 @@ export declare class StreamingZoneCache {
 
 /**
  * Adds stripe monetization routes and configuration
- * @beta
+ * @deprecated - This plugin is deprecated and will be removed in the future.
  */
 export declare class StripeMonetizationPlugin extends MeteringPlugin {
   private options;
@@ -8015,7 +8069,7 @@ export declare class StripeMonetizationPlugin extends MeteringPlugin {
 }
 
 /**
- * @beta
+ * @deprecated - This plugin is deprecated and will be removed in the future.
  */
 export declare interface StripeMonetizationPluginOptions {
   /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.58.0",
+  "version": "6.58.4",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {