@utcp/http 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# @utcp/http: HTTP Communication Protocol Plugin for UTCP
+
+The `@utcp/http` package provides the HTTP communication protocol implementation for the Universal Tool Calling Protocol (UTCP) client. It enables the `UtcpClient` to interact with RESTful HTTP/HTTPS APIs, supporting various authentication methods, URL path parameters, and automatic tool discovery from UTCP Manuals or OpenAPI specifications.
+
+## Features
+
+*   **HTTP `CallTemplate`**: Defines the specific configuration for HTTP-based tools (`HttpCallTemplate`), including HTTP method, URL, content type, authentication, and headers.
+*   **`HttpCommunicationProtocol`**: Implements the `CommunicationProtocol` interface for HTTP interactions:
+    *   **Tool Discovery**: Automatically registers tools from remote UTCP Manuals or OpenAPI (v2/v3) specifications (JSON/YAML).
+    *   **Tool Execution**: Handles `GET`, `POST`, `PUT`, `DELETE`, `PATCH` requests with:
+        *   URL path parameter substitution (`{param_name}`).
+        *   Query parameter handling.
+        *   Request body mapping (`body_field`).
+        *   Custom header fields.
+    *   **Authentication Support**: Integrates `ApiKeyAuth` (header, query, cookie), `BasicAuth`, and `OAuth2Auth` (client credentials flow with token caching and refresh).
+    *   **Security**: Enforces HTTPS or localhost connections for discovery and tool calls to prevent Man-in-the-Middle (MITM) attacks.
+*   **`OpenApiConverter`**: A utility for parsing OpenAPI specifications and transforming them into UTCP `Tool` definitions that leverage `HttpCallTemplate`.
+
+## Installation
+
+```bash
+bun add @utcp/http @utcp/core axios js-yaml
+```
+
+Note: `@utcp/core` is a peer dependency, and `axios` and `js-yaml` are direct dependencies required for HTTP communication and OpenAPI parsing.
+
+## Usage
+
+To use the HTTP plugin, you must register its capabilities with the core `UtcpClient` at application startup. This is typically done by calling the `registerHttpPlugin()` function exported from `@utcp/http`.
+
+```typescript
+// From your application's entry point
+
+import { UtcpClient } from '@utcp/core/client/utcp_client';
+import { UtcpClientConfigSchema } from '@utcp/core/client/utcp_client_config';
+import { registerHttpPlugin } from '@utcp/http'; // Import the registration function
+
+// --- IMPORTANT: Register the HTTP plugin once at the start of your application ---
+registerHttpPlugin();
+// -------------------------------------------------------------------------------
+
+async function main() {
+  const client = await UtcpClient.create(
+    UtcpClientConfigSchema.parse({
+      // Define variables for substitution in call templates (e.g., for API keys)
+      variables: {
+        OPENLIBRARY_API_KEY_1: 'your-openlibrary-key' // Example for OpenAPI-derived template
+      },
+      // Manually define HTTP call templates in the config to be registered at startup
+      manual_call_templates: [
+        {
+          name: 'openlibrary_api',
+          call_template_type: 'http',
+          url: 'https://openlibrary.org/static/openapi.json', // URL pointing to an OpenAPI spec
+          http_method: 'GET'
+          // Auth fields would be auto-generated by OpenApiConverter, but variables must be supplied
+        }
+      ],
+      // Or load variables from .env files
+      load_variables_from: [
+        { type: 'dotenv', env_file_path: './.env' }
+      ]
+    })
+  );
+
+  console.log('HTTP Plugin active. Searching for tools...');
+
+  // Search for tools (e.g., from the OpenLibrary API)
+  const bookSearchTools = await client.searchTools('search for books by author');
+  console.log('Found OpenLibrary tools:', bookSearchTools.map(t => t.name));
+
+  // Example: Call a tool (e.g., 'openlibrary_api.read_search_authors_json_search_authors_json_get')
+  if (bookSearchTools.length > 0) {
+    try {
+      const toolToCall = bookSearchTools.find(t => t.name.includes('search_authors'));
+      if (toolToCall) {
+        console.log(`Calling tool: ${toolToCall.name}`);
+        const result = await client.callTool(toolToCall.name, { q: 'J. K. Rowling' });
+        console.log('Tool call result:', result);
+      } else {
+        console.warn('No author search tool found for example call.');
+      }
+    } catch (error) {
+      console.error('Error calling HTTP tool:', error);
+    }
+  }
+
+  await client.close(); // Clean up HTTP client sessions, OAuth tokens, etc.
+}
+
+main().catch(console.error);
+```
+
+## Development
+
+Refer to the root `README.md` for monorepo development and testing instructions.

package/dist/http_call_template.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { Auth } from '@utcp/core/data/auth';
+import { CallTemplate } from '@utcp/core/data/call_template';
+import { Serializer } from '@utcp/core/interfaces/serializer';
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare const HttpCallTemplateSchema: z.ZodType<HttpCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for HttpCallTemplate.
+ */
+export declare class HttpCallTemplateSerializer extends Serializer<HttpCallTemplate> {
+    toDict(obj: HttpCallTemplate): Record<string, unknown>;
+    validateDict(obj: Record<string, unknown>): HttpCallTemplate;
+}

package/dist/http_call_template.js

@@ -0,0 +1,55 @@
+// packages/http/src/http_call_template.ts
+import { z } from 'zod';
+import { AuthSchema, AuthSerializer } from '@utcp/core/data/auth';
+import { Serializer } from '@utcp/core/interfaces/serializer';
+/**
+ * HTTP Call Template schema for RESTful HTTP/HTTPS API tools.
+ * Extends the base CallTemplate and defines HTTP-specific configuration.
+ */
+export const HttpCallTemplateSchema = z.object({
+    name: z.string().optional(),
+    call_template_type: z.literal('http'),
+    http_method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).default('GET'),
+    url: z.string().describe('The base URL for the HTTP endpoint. Supports path parameters like "https://api.example.com/users/{user_id}".'),
+    content_type: z.string().default('application/json').describe('The Content-Type header for requests.'),
+    auth: AuthSchema.optional().describe('Optional authentication configuration.'),
+    headers: z.record(z.string(), z.string()).optional().describe('Optional static headers to include in all requests.'),
+    body_field: z.string().optional().default('body').describe('The name of the single input field to be sent as the request body.'),
+    header_fields: z.array(z.string()).optional().describe('List of input fields to be sent as request headers.'),
+    auth_tools: AuthSchema.nullable().optional().transform((val) => {
+        if (val === null || val === undefined)
+            return null;
+        if (typeof val === 'object' && 'auth_type' in val) {
+            return new AuthSerializer().validateDict(val);
+        }
+        return val;
+    }).describe('Authentication configuration for generated tools'),
+});
+/**
+ * REQUIRED
+ * Serializer for HttpCallTemplate.
+ */
+export class HttpCallTemplateSerializer extends Serializer {
+    toDict(obj) {
+        return {
+            name: obj.name,
+            call_template_type: obj.call_template_type,
+            http_method: obj.http_method,
+            url: obj.url,
+            content_type: obj.content_type,
+            auth: obj.auth,
+            auth_tools: obj.auth_tools ? new AuthSerializer().toDict(obj.auth_tools) : null,
+            headers: obj.headers,
+            body_field: obj.body_field,
+            header_fields: obj.header_fields,
+        };
+    }
+    validateDict(obj) {
+        try {
+            return HttpCallTemplateSchema.parse(obj);
+        }
+        catch (e) {
+            throw new Error(`Invalid HttpCallTemplate: ${e.message}\n${e.stack || ''}`);
+        }
+    }
+}

package/dist/http_communication_protocol.d.ts

@@ -0,0 +1,88 @@
+import { CommunicationProtocol } from '@utcp/core/interfaces/communication_protocol';
+import { RegisterManualResult } from '@utcp/core/data/register_manual_result';
+import { CallTemplate } from '@utcp/core/data/call_template';
+import { IUtcpClient } from '@utcp/core/interfaces/utcp_client_interface';
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/http_communication_protocol.js

@@ -0,0 +1,337 @@
+// packages/http/src/http_communication_protocol.ts
+import axios from 'axios';
+import * as yaml from 'js-yaml';
+import { URLSearchParams } from 'url';
+import { UtcpManualSchema } from '@utcp/core/data/utcp_manual';
+import { HttpCallTemplateSchema } from '@utcp/http/http_call_template';
+import { OpenApiConverter } from '@utcp/http/openapi_converter';
+/**
+ * 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.
+ */
+export class HttpCommunicationProtocol {
+    _oauthTokens = new Map();
+    _axiosInstance;
+    constructor() {
+        this._axiosInstance = axios.create({
+            timeout: 30000,
+        });
+    }
+    _logInfo(message) {
+        console.log(`[HttpCommunicationProtocol] ${message}`);
+    }
+    _logError(message, error) {
+        console.error(`[HttpCommunicationProtocol Error] ${message}`, error);
+    }
+    /**
+     * 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.
+     */
+    async registerManual(caller, manualCallTemplate) {
+        const httpCallTemplate = HttpCallTemplateSchema.parse(manualCallTemplate);
+        try {
+            const url = httpCallTemplate.url;
+            if (!url.startsWith('https://') && !url.startsWith('http://localhost') && !url.startsWith('http://127.0.0.1')) {
+                throw new Error(`Security error: URL must use HTTPS or start with 'http://localhost' or 'http://127.0.0.1'. Got: ${url}. ` +
+                    "Non-secure URLs are vulnerable to man-in-the-middle attacks.");
+            }
+            this._logInfo(`Discovering tools from '${httpCallTemplate.name}' (HTTP) at ${url}`);
+            const requestConfig = {
+                method: httpCallTemplate.http_method,
+                url: url,
+                headers: { ...httpCallTemplate.headers },
+                params: {},
+                data: undefined,
+                auth: undefined,
+                timeout: 10000
+            };
+            await this._applyAuthToRequestConfig(httpCallTemplate, requestConfig);
+            const response = await this._axiosInstance.request(requestConfig);
+            const contentType = response.headers['content-type'] || '';
+            let responseData;
+            if (contentType.includes('yaml') || url.endsWith('.yaml') || url.endsWith('.yml')) {
+                responseData = yaml.load(response.data);
+            }
+            else {
+                responseData = response.data;
+            }
+            let utcpManual;
+            if (responseData && responseData.utcp_version && Array.isArray(responseData.tools)) {
+                this._logInfo(`Detected UTCP manual from '${httpCallTemplate.name}'.`);
+                utcpManual = UtcpManualSchema.parse(responseData);
+            }
+            else if (responseData && (responseData.openapi || responseData.swagger || responseData.paths)) {
+                this._logInfo(`Assuming OpenAPI spec from '${httpCallTemplate.name}'. Converting to UTCP manual.`);
+                const converter = new OpenApiConverter(responseData, {
+                    specUrl: httpCallTemplate.url,
+                    callTemplateName: httpCallTemplate.name
+                });
+                utcpManual = converter.convert();
+            }
+            else {
+                throw new Error("Response is neither a valid UTCP Manual nor an OpenAPI Specification.");
+            }
+            const toolsInManual = utcpManual.tools;
+            if (toolsInManual.length > 0) {
+                this._logInfo(`Found ${toolsInManual.length} tools.`);
+            }
+            return {
+                manualCallTemplate: httpCallTemplate,
+                manual: utcpManual,
+                success: true,
+                errors: []
+            };
+        }
+        catch (error) {
+            this._logError(`Error discovering tools from HTTP provider '${httpCallTemplate.name}':`, error);
+            return {
+                manualCallTemplate: httpCallTemplate,
+                manual: UtcpManualSchema.parse({ tools: [] }),
+                success: false,
+                errors: [axios.isAxiosError(error) ? error.message : String(error)]
+            };
+        }
+    }
+    /**
+     * 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.
+     */
+    async deregisterManual(caller, manualCallTemplate) {
+        this._logInfo(`Deregistering HTTP manual '${manualCallTemplate.name}' (no-op).`);
+        return Promise.resolve();
+    }
+    /**
+     * 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.
+     */
+    async callTool(caller, toolName, toolArgs, toolCallTemplate) {
+        const httpCallTemplate = HttpCallTemplateSchema.parse(toolCallTemplate);
+        const requestHeaders = { ...httpCallTemplate.headers };
+        let bodyContent = undefined;
+        const remainingArgs = { ...toolArgs };
+        const queryParams = {};
+        if (httpCallTemplate.header_fields) {
+            for (const fieldName of httpCallTemplate.header_fields) {
+                if (fieldName in remainingArgs) {
+                    requestHeaders[fieldName] = String(remainingArgs[fieldName]);
+                    delete remainingArgs[fieldName];
+                }
+            }
+        }
+        if (httpCallTemplate.body_field && httpCallTemplate.body_field in remainingArgs) {
+            bodyContent = remainingArgs[httpCallTemplate.body_field];
+            delete remainingArgs[httpCallTemplate.body_field];
+        }
+        const url = this._buildUrlWithPathParams(httpCallTemplate.url, remainingArgs);
+        Object.assign(queryParams, remainingArgs);
+        const requestConfig = {
+            method: httpCallTemplate.http_method,
+            url: url,
+            headers: requestHeaders,
+            params: queryParams,
+            data: bodyContent,
+            auth: undefined,
+            timeout: httpCallTemplate.timeout
+        };
+        await this._applyAuthToRequestConfig(httpCallTemplate, requestConfig);
+        try {
+            if (bodyContent !== undefined && !('Content-Type' in (requestConfig.headers || {}))) {
+                requestConfig.headers = {
+                    ...(requestConfig.headers || {}),
+                    'Content-Type': httpCallTemplate.content_type,
+                };
+            }
+            this._logInfo(`Executing HTTP tool '${toolName}' with URL: ${requestConfig.url} and method: ${requestConfig.method}`);
+            const response = await this._axiosInstance.request(requestConfig);
+            const contentType = response.headers['content-type'] || '';
+            if (contentType.includes('yaml') || url.endsWith('.yaml') || url.endsWith('.yml')) {
+                return yaml.load(response.data);
+            }
+            return response.data;
+        }
+        catch (error) {
+            this._logError(`Error calling HTTP tool '${toolName}':`, error);
+            throw error;
+        }
+    }
+    /**
+     * 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.
+     */
+    async *callToolStreaming(caller, toolName, toolArgs, toolCallTemplate) {
+        this._logInfo(`HTTP protocol does not inherently support streaming for '${toolName}'. Fetching full response.`);
+        const result = await this.callTool(caller, toolName, toolArgs, toolCallTemplate);
+        yield result;
+    }
+    /**
+     * Closes any persistent connections or resources held by the communication protocol.
+     * For stateless HTTP, this clears OAuth tokens.
+     */
+    async close() {
+        this._oauthTokens.clear();
+        this._logInfo("HTTP Communication Protocol closed. OAuth tokens cleared.");
+        return Promise.resolve();
+    }
+    /**
+     * 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.
+     */
+    async _applyAuthToRequestConfig(httpCallTemplate, requestConfig) {
+        const cookies = {};
+        if (httpCallTemplate.auth) {
+            if (httpCallTemplate.auth.auth_type === 'api_key') {
+                const apiKeyAuth = httpCallTemplate.auth;
+                if (!apiKeyAuth.api_key) {
+                    throw new Error("API key for ApiKeyAuth is empty.");
+                }
+                if (apiKeyAuth.location === 'header') {
+                    requestConfig.headers = { ...requestConfig.headers, [apiKeyAuth.var_name]: apiKeyAuth.api_key };
+                }
+                else if (apiKeyAuth.location === 'query') {
+                    requestConfig.params = { ...requestConfig.params, [apiKeyAuth.var_name]: apiKeyAuth.api_key };
+                }
+                else if (apiKeyAuth.location === 'cookie') {
+                    cookies[apiKeyAuth.var_name] = apiKeyAuth.api_key;
+                }
+            }
+            else if (httpCallTemplate.auth.auth_type === 'basic') {
+                const basicAuth = httpCallTemplate.auth;
+                requestConfig.auth = {
+                    username: basicAuth.username,
+                    password: basicAuth.password
+                };
+            }
+            else if (httpCallTemplate.auth.auth_type === 'oauth2') {
+                const oauth2Auth = httpCallTemplate.auth;
+                const token = await this._handleOAuth2(oauth2Auth);
+                requestConfig.headers = { ...requestConfig.headers, 'Authorization': `Bearer ${token}` };
+            }
+        }
+        return cookies;
+    }
+    /**
+     * 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.
+     */
+    async _handleOAuth2(authDetails) {
+        const clientId = authDetails.client_id;
+        const cachedToken = this._oauthTokens.get(clientId);
+        if (cachedToken && cachedToken.expiresAt > Date.now()) {
+            return cachedToken.accessToken;
+        }
+        this._logInfo(`Fetching new OAuth2 token for client: '${clientId}'`);
+        const tokenFetchPromises = [];
+        // Method 1: Send credentials in the request body
+        tokenFetchPromises.push((async () => {
+            try {
+                const bodyData = new URLSearchParams({
+                    'grant_type': 'client_credentials',
+                    'client_id': authDetails.client_id,
+                    'client_secret': authDetails.client_secret,
+                    'scope': authDetails.scope || ''
+                });
+                const response = await this._axiosInstance.post(authDetails.token_url, bodyData.toString(), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
+                if (!response.data.access_token) {
+                    throw new Error("Access token not found in response.");
+                }
+                const expiresAt = Date.now() + (response.data.expires_in * 1000 || 3600 * 1000);
+                this._oauthTokens.set(clientId, { accessToken: response.data.access_token, expiresAt });
+                this._logInfo(`OAuth2 token fetched via body for client: '${clientId}'.`);
+                return response.data.access_token;
+            }
+            catch (error) {
+                this._logError(`OAuth2 with credentials in body failed for '${clientId}':`, error);
+                throw error;
+            }
+        })());
+        // Method 2: Send credentials as Basic Auth header
+        tokenFetchPromises.push((async () => {
+            try {
+                const bodyData = new URLSearchParams({
+                    'grant_type': 'client_credentials',
+                    'scope': authDetails.scope || ''
+                });
+                const response = await this._axiosInstance.post(authDetails.token_url, bodyData.toString(), {
+                    auth: { username: authDetails.client_id, password: authDetails.client_secret },
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+                });
+                if (!response.data.access_token) {
+                    throw new Error("Access token not found in response.");
+                }
+                const expiresAt = Date.now() + (response.data.expires_in * 1000 || 3600 * 1000);
+                this._oauthTokens.set(clientId, { accessToken: response.data.access_token, expiresAt });
+                this._logInfo(`OAuth2 token fetched via Basic Auth header for client: '${clientId}'.`);
+                return response.data.access_token;
+            }
+            catch (error) {
+                this._logError(`OAuth2 with Basic Auth header failed for '${clientId}':`, error);
+                throw error;
+            }
+        })());
+        // Try both methods, and resolve if any succeed
+        try {
+            return await Promise.any(tokenFetchPromises);
+        }
+        catch (aggregateError) {
+            const errorMessages = aggregateError.errors ? aggregateError.errors.map((e) => e.message).join('; ') : String(aggregateError);
+            throw new Error(`Failed to fetch OAuth2 token for client '${clientId}' after trying all methods. Details: ${errorMessages}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    _buildUrlWithPathParams(urlTemplate, args) {
+        let url = urlTemplate;
+        const pathParams = urlTemplate.match(/\{([^}]+)\}/g) || [];
+        for (const param of pathParams) {
+            const paramName = param.slice(1, -1);
+            if (paramName in args) {
+                // URL-encode the parameter value to prevent path injection
+                url = url.replace(param, encodeURIComponent(String(args[paramName])));
+                delete args[paramName];
+            }
+            else {
+                throw new Error(`Missing required path parameter: ${paramName}`);
+            }
+        }
+        const remainingParams = url.match(/\{([^}]+)\}/g);
+        if (remainingParams && remainingParams.length > 0) {
+            throw new Error(`Missing required path parameters in URL template: ${remainingParams.join(', ')}`);
+        }
+        return url;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * HTTP Communication Protocol plugin for UTCP.
+ * Includes HTTP, Streamable HTTP, and SSE (Server-Sent Events) protocols.
+ */
+// packages/http/src/index.ts
+import { CommunicationProtocol } from '@utcp/core/interfaces/communication_protocol';
+import { CallTemplateSerializer } from '@utcp/core/data/call_template';
+import { ensureCorePluginsInitialized } from '@utcp/core/plugins/plugin_loader';
+import { HttpCallTemplateSerializer } from '@utcp/http/http_call_template';
+import { StreamableHttpCallTemplateSerializer } from '@utcp/http/streamable_http_call_template';
+import { SseCallTemplateSerializer } from '@utcp/http/sse_call_template';
+import { HttpCommunicationProtocol } from '@utcp/http/http_communication_protocol';
+import { StreamableHttpCommunicationProtocol } from '@utcp/http/streamable_http_communication_protocol';
+import { SseCommunicationProtocol } from '@utcp/http/sse_communication_protocol';
+/**
+ * Registers all HTTP-based protocol CallTemplate serializers
+ * and their CommunicationProtocol implementations.
+ * This function is called automatically when the package is imported.
+ */
+export function register(override = false) {
+    // Ensure core plugins (including auth serializers) are initialized first
+    ensureCorePluginsInitialized();
+    // Register HTTP
+    CallTemplateSerializer.registerCallTemplate('http', new HttpCallTemplateSerializer(), override);
+    CommunicationProtocol.communicationProtocols['http'] = new HttpCommunicationProtocol();
+    // Register Streamable HTTP
+    CallTemplateSerializer.registerCallTemplate('streamable_http', new StreamableHttpCallTemplateSerializer(), override);
+    CommunicationProtocol.communicationProtocols['streamable_http'] = new StreamableHttpCommunicationProtocol();
+    // Register SSE (Server-Sent Events)
+    CallTemplateSerializer.registerCallTemplate('sse', new SseCallTemplateSerializer(), override);
+    CommunicationProtocol.communicationProtocols['sse'] = new SseCommunicationProtocol();
+}
+// Automatically register HTTP plugins on import
+register();
+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';