@utcp/http 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -1,13 +1,437 @@
+import { z } from 'zod';
+import { CallTemplate, Auth, Serializer, CommunicationProtocol, IUtcpClient, RegisterManualResult, UtcpManual } from '@utcp/sdk';
+
+/**
+ * REQUIRED
+ * Provider configuration for HTTP-based tools.
+ *
+ * Supports RESTful HTTP/HTTPS APIs with various HTTP methods, authentication,
+ * custom headers, and flexible request/response handling. Supports URL path
+ * parameters using {parameter_name} syntax.
+ */
+interface HttpCallTemplate extends CallTemplate {
+    call_template_type: 'http';
+    http_method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    url: string;
+    content_type: string;
+    headers?: Record<string, string>;
+    body_field?: string;
+    header_fields?: string[];
+    auth_tools?: Auth | null;
+}
+/**
+ * HTTP Call Template schema for RESTful HTTP/HTTPS API tools.
+ * Extends the base CallTemplate and defines HTTP-specific configuration.
+ */
+declare const HttpCallTemplateSchema: z.ZodType<HttpCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for HttpCallTemplate.
+ */
+declare class HttpCallTemplateSerializer extends Serializer<HttpCallTemplate> {
+    toDict(obj: HttpCallTemplate): Record<string, unknown>;
+    validateDict(obj: Record<string, unknown>): HttpCallTemplate;
+}
+
+/**
+ * HTTP communication protocol implementation for UTCP client.
+ *
+ * Handles communication with HTTP-based tool providers, supporting various
+ * authentication methods, URL path parameters, and automatic tool discovery.
+ * Enforces security by requiring HTTPS or localhost connections.
+ */
+declare class HttpCommunicationProtocol implements CommunicationProtocol {
+    private _oauthTokens;
+    private _axiosInstance;
+    constructor();
+    private _logInfo;
+    private _logError;
+    /**
+     * Registers a manual and its tools from an HTTP provider.
+     * Supports UTCP Manuals directly or OpenAPI specifications which are converted.
+     *
+     * @param caller The UTCP client instance.
+     * @param manualCallTemplate The HTTP call template for discovery.
+     * @returns A RegisterManualResult object.
+     */
+    registerManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<RegisterManualResult>;
+    /**
+     * Deregisters an HTTP manual. This is a no-op for stateless HTTP communication.
+     * @param caller The UTCP client instance.
+     * @param manualCallTemplate The HTTP call template to deregister.
+     */
+    deregisterManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<void>;
+    /**
+     * Executes a tool call through the HTTP protocol.
+     *
+     * @param caller The UTCP client instance.
+     * @param toolName Name of the tool to call.
+     * @param toolArgs Dictionary of arguments to pass to the tool.
+     * @param toolCallTemplate The HTTP call template for the tool.
+     * @returns The tool's response.
+     */
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): Promise<any>;
+    /**
+     * Executes a tool call through this transport streamingly.
+     * For standard HTTP, this typically means fetching the full response and yielding it as a single chunk.
+     * Real streaming for protocols like SSE or HTTP chunked transfer would be in their specific implementations.
+     *
+     * @param caller The UTCP client instance.
+     * @param toolName Name of the tool to call.
+     * @param toolArgs Dictionary of arguments to pass to the tool.
+     * @param toolCallTemplate The HTTP call template for the tool.
+     * @returns An async generator that yields chunks of the tool's response.
+     */
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): AsyncGenerator<any, void, unknown>;
+    /**
+     * Closes any persistent connections or resources held by the communication protocol.
+     * For stateless HTTP, this clears OAuth tokens.
+     */
+    close(): Promise<void>;
+    /**
+     * Applies authentication details from the HttpCallTemplate to the Axios request configuration.
+     * This modifies `requestConfig.headers`, `requestConfig.params`, `requestConfig.auth`, and returns cookies.
+     *
+     * @param httpCallTemplate The CallTemplate containing authentication details.
+     * @param requestConfig The Axios request configuration to modify.
+     * @returns A Promise that resolves to an object containing any cookies to be set.
+     */
+    private _applyAuthToRequestConfig;
+    /**
+     * Handles OAuth2 client credentials flow, trying both body and auth header methods.
+     * Caches tokens and automatically refreshes if expired.
+     *
+     * @param authDetails The OAuth2 authentication details.
+     * @returns The access token.
+     * @throws Error if token cannot be fetched.
+     */
+    private _handleOAuth2;
+    /**
+     * Builds a URL by substituting path parameters from the provided arguments.
+     * Used arguments are removed from the `args` object.
+     *
+     * @param urlTemplate The URL template with path parameters in `{param_name}` format.
+     * @param args The dictionary of arguments; modified to remove path parameters.
+     * @returns The URL with path parameters substituted.
+     * @throws Error if a required path parameter is missing.
+     */
+    private _buildUrlWithPathParams;
+}
+
+/**
+ * REQUIRED
+ * Provider configuration for HTTP streaming tools.
+ *
+ * Uses HTTP Chunked Transfer Encoding to enable streaming of large responses
+ * or real-time data. Useful for tools that return large datasets or provide
+ * progressive results. All tool arguments not mapped to URL body, headers
+ * or query pattern parameters are passed as query parameters using '?arg_name={arg_value}'.
+ *
+ * Attributes:
+ *     call_template_type: Always "streamable_http" for HTTP streaming providers.
+ *     url: The streaming HTTP endpoint URL. Supports path parameters.
+ *     http_method: The HTTP method to use (GET or POST).
+ *     content_type: The Content-Type header for requests.
+ *     chunk_size: Size of each chunk in bytes for reading the stream.
+ *     timeout: Request timeout in milliseconds.
+ *     headers: Optional static headers to include in requests.
+ *     auth: Optional authentication configuration.
+ *     body_field: Optional tool argument name to map to HTTP request body.
+ *     header_fields: List of tool argument names to map to HTTP request headers.
+ */
+interface StreamableHttpCallTemplate extends CallTemplate {
+    call_template_type: 'streamable_http';
+    url: string;
+    http_method: 'GET' | 'POST';
+    content_type: string;
+    chunk_size: number;
+    timeout: number;
+    headers?: Record<string, string>;
+    body_field?: string | null;
+    header_fields?: string[] | null;
+}
+/**
+ * Streamable HTTP Call Template schema.
+ */
+declare const StreamableHttpCallTemplateSchema: z.ZodType<StreamableHttpCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for StreamableHttpCallTemplate.
+ */
+declare class StreamableHttpCallTemplateSerializer extends Serializer<StreamableHttpCallTemplate> {
+    /**
+     * REQUIRED
+     * Convert StreamableHttpCallTemplate to dictionary.
+     */
+    toDict(obj: StreamableHttpCallTemplate): Record<string, unknown>;
+    /**
+     * REQUIRED
+     * Validate dictionary and convert to StreamableHttpCallTemplate.
+     */
+    validateDict(obj: Record<string, unknown>): StreamableHttpCallTemplate;
+}
+
+/**
+ * Streamable HTTP Communication Protocol for UTCP.
+ *
+ * Handles HTTP streaming with chunked transfer encoding for real-time data.
+ */
+
+/**
+ * REQUIRED
+ * Streamable HTTP communication protocol implementation for UTCP client.
+ *
+ * Handles HTTP streaming with chunked transfer encoding for real-time data.
+ */
+declare class StreamableHttpCommunicationProtocol implements CommunicationProtocol {
+    private oauthTokens;
+    private _logInfo;
+    private _logError;
+    private _applyAuth;
+    /**
+     * REQUIRED
+     * Register a manual and its tools from a StreamableHttp provider.
+     */
+    registerManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<RegisterManualResult>;
+    /**
+     * REQUIRED
+     * Deregister a manual (no-op for HTTP streaming).
+     */
+    deregisterManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<void>;
+    /**
+     * REQUIRED
+     * Call a tool using HTTP (non-streaming).
+     */
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): Promise<any>;
+    /**
+     * REQUIRED
+     * Call a tool using HTTP streaming.
+     * Returns an async generator that yields chunks of data.
+     */
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): AsyncGenerator<any, void, unknown>;
+    /**
+     * REQUIRED
+     * Close all active connections and clear internal state.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * REQUIRED
+ * Provider configuration for Server-Sent Events (SSE) tools.
+ *
+ * Enables real-time streaming of events from server to client using the
+ * Server-Sent Events protocol. Supports automatic reconnection and
+ * event type filtering. All tool arguments not mapped to URL body, headers
+ * or query pattern parameters are passed as query parameters using '?arg_name={arg_value}'.
+ *
+ * Attributes:
+ *     call_template_type: Always "sse" for SSE providers.
+ *     url: The SSE endpoint URL to connect to.
+ *     event_type: Optional filter for specific event types. If None, all events are received.
+ *     reconnect: Whether to automatically reconnect on connection loss.
+ *     retry_timeout: Timeout in milliseconds before attempting reconnection.
+ *     auth: Optional authentication configuration.
+ *     headers: Optional static headers for the initial connection.
+ *     body_field: Optional tool argument name to map to request body during connection.
+ *     header_fields: List of tool argument names to map to HTTP headers during connection.
+ */
+interface SseCallTemplate extends CallTemplate {
+    call_template_type: 'sse';
+    url: string;
+    event_type?: string | null;
+    reconnect: boolean;
+    retry_timeout: number;
+    headers?: Record<string, string>;
+    body_field?: string | null;
+    header_fields?: string[] | null;
+}
+/**
+ * SSE Call Template schema.
+ */
+declare const SseCallTemplateSchema: z.ZodType<SseCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for SseCallTemplate.
+ */
+declare class SseCallTemplateSerializer extends Serializer<SseCallTemplate> {
+    /**
+     * REQUIRED
+     * Convert SseCallTemplate to dictionary.
+     */
+    toDict(obj: SseCallTemplate): Record<string, unknown>;
+    /**
+     * REQUIRED
+     * Validate dictionary and convert to SseCallTemplate.
+     */
+    validateDict(obj: Record<string, unknown>): SseCallTemplate;
+}
+
+/**
+ * Server-Sent Events (SSE) Communication Protocol for UTCP.
+ *
+ * Handles Server-Sent Events based tool providers with streaming capabilities.
+ */
+
+/**
+ * REQUIRED
+ * SSE communication protocol implementation for UTCP client.
+ *
+ * Handles Server-Sent Events based tool providers with streaming capabilities.
+ */
+declare class SseCommunicationProtocol implements CommunicationProtocol {
+    private oauthTokens;
+    private _logInfo;
+    private _logError;
+    private _applyAuth;
+    /**
+     * REQUIRED
+     * Register a manual and its tools from an SSE provider.
+     */
+    registerManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<RegisterManualResult>;
+    /**
+     * REQUIRED
+     * Deregister a manual (no-op for SSE).
+     */
+    deregisterManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<void>;
+    /**
+     * REQUIRED
+     * Call a tool using SSE (non-streaming).
+     */
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): Promise<any>;
+    /**
+     * REQUIRED
+     * Call a tool using SSE streaming.
+     * Returns an async generator that yields SSE events.
+     */
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): AsyncGenerator<any, void, unknown>;
+    /**
+     * REQUIRED
+     * Close all active connections and clear internal state.
+     */
+    close(): Promise<void>;
+}
+
+interface OpenApiConverterOptions {
+    specUrl?: string;
+    callTemplateName?: string;
+    authTools?: Auth;
+}
+/**
+ * REQUIRED
+ * Converts OpenAPI specifications into UTCP tool definitions.
+ *
+ * Processes OpenAPI 2.0 and 3.0 specifications to generate equivalent UTCP
+ * tools, handling schema resolution, authentication mapping, and proper
+ * HTTP call_template configuration. Each operation in the OpenAPI spec becomes
+ * a UTCP tool with appropriate input/output schemas.
+ */
+declare class OpenApiConverter {
+    private spec;
+    private spec_url;
+    private auth_tools;
+    private placeholder_counter;
+    private call_template_name;
+    /**
+     * Initializes the OpenAPI converter.
+     *
+     * @param openapi_spec Parsed OpenAPI specification as a dictionary.
+     * @param options Optional settings including spec_url, call_template_name, and auth_tools.
+     *     - specUrl: URL where the specification was retrieved from.
+     *     - callTemplateName: Custom name for the call_template if spec title not provided.
+     *     - authTools: Optional auth configuration for generated tools.
+     */
+    constructor(openapi_spec: Record<string, any>, options?: OpenApiConverterOptions);
+    private _generateUuid;
+    private _incrementPlaceholderCounter;
+    private _getPlaceholder;
+    /**
+     * Parses the OpenAPI specification and returns a UtcpManual.
+     * @returns A UTCP manual containing tools derived from the OpenAPI specification.
+     */
+    /**
+     * REQUIRED
+     * Converts the loaded OpenAPI specification into a UtcpManual.
+     */
+    convert(): UtcpManual;
+    /**
+     * Resolves a local JSON reference within the OpenAPI spec.
+     * @param ref The reference string (e.g., '#/components/schemas/Pet').
+     * @returns The resolved schema object.
+     */
+    private _resolveRef;
+    /**
+     * Recursively resolves all $refs in a schema object, preventing infinite loops.
+     * @param schema The schema object that may contain references.
+     * @param visitedRefs A set of references already visited to detect cycles.
+     * @returns The resolved schema with all references replaced by their actual values.
+     */
+    private _resolveSchema;
+    /**
+     * Creates a Tool object from an OpenAPI operation.
+     * @param path The API path.
+     * @param method The HTTP method (GET, POST, etc.).
+     * @param operation The operation definition from OpenAPI.
+     * @param baseUrl The base URL for the API.
+     * @returns A Tool object or null if operationId is not defined.
+     */
+    private _createTool;
+    /**
+     * Extracts the input schema, header fields, and body field from an OpenAPI operation.
+     * - Merges path-level and operation-level parameters.
+     * - Resolves $ref for parameters.
+     * - Supports OpenAPI 2.0 body parameters and 3.0 requestBody.
+     * @param path The API path.
+     * @param operation The OpenAPI operation object.
+     * @returns An object containing the inputs schema, a list of header field names, and the body field name (if any).
+     */
+    private _extractInputs;
+    /**
+     * Extracts the output schema from an OpenAPI operation, resolving refs.
+     * @param operation The OpenAPI operation object.
+     * @returns The output schema.
+     */
+    private _extractOutputs;
+    /**
+     * Extracts authentication information from OpenAPI operation and global security schemes.
+     * Uses auth_tools configuration when compatible with OpenAPI auth requirements.
+     * Supports both OpenAPI 2.0 and 3.0 security schemes.
+     * @param operation The OpenAPI operation object.
+     * @returns An Auth object or undefined if no authentication is specified.
+     */
+    private _extractAuth;
+    /**
+     * Checks if auth_tools configuration is compatible with OpenAPI auth requirements.
+     *
+     * @param openapiAuth Auth generated from OpenAPI security scheme
+     * @param authTools Auth configuration from manual call template
+     * @returns True if compatible and auth_tools should be used, False otherwise
+     */
+    private _isAuthCompatible;
+    /**
+     * Gets security schemes supporting both OpenAPI 2.0 and 3.0.
+     * @returns A record of security schemes.
+     */
+    private _getSecuritySchemes;
+    /**
+     * Creates an Auth object from an OpenAPI security scheme.
+     * @param scheme The security scheme object.
+     * @param schemeName The name of the security scheme.
+     * @returns An Auth object or undefined if the scheme is not supported.
+     */
+    private _createAuthFromScheme;
+}
+declare global {
+    interface String {
+        lstrip(chars: string): string;
+    }
+}
+
 /**
  * Registers all HTTP-based protocol CallTemplate serializers
  * and their CommunicationProtocol implementations.
  * This function is called automatically when the package is imported.
  */
-export declare function register(override?: boolean): void;
-export * from './http_call_template';
-export * from './http_communication_protocol';
-export * from './streamable_http_call_template';
-export * from './streamable_http_communication_protocol';
-export * from './sse_call_template';
-export * from './sse_communication_protocol';
-export * from './openapi_converter';
+declare function register(override?: boolean): void;
+
+export { type HttpCallTemplate, HttpCallTemplateSchema, HttpCallTemplateSerializer, HttpCommunicationProtocol, OpenApiConverter, type SseCallTemplate, SseCallTemplateSchema, SseCallTemplateSerializer, SseCommunicationProtocol, type StreamableHttpCallTemplate, StreamableHttpCallTemplateSchema, StreamableHttpCallTemplateSerializer, StreamableHttpCommunicationProtocol, register };