@artinet/sdk 0.5.17 → 0.6.0-preview.1

package/dist/browser/config/observability.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** //todo move to @artinet/sdk from core v0.1
+ * @fileoverview Zero-dependency observability interfaces for the Artinet ecosystem.
+ *
+ * Provides minimal interfaces for logging and tracing that consumers can implement
+ * with their preferred tools (Pino, Winston, OpenTelemetry, etc.).
+ *
+ * Design principles:
+ * - Zero runtime dependencies
+ * - No-op defaults for zero overhead when not configured
+ * - Environment agnostic (Node, Deno, Bun, edge, browser)
+ * - Consumer brings their own implementation
+ *
+ * @module utils/observability
+ */
+/**
+ * Minimal logger interface.
+ *
+ * Consumers provide their own implementation using their preferred
+ * logging library (Pino, Winston, console, etc.).
+ *
+ * Uses spread args for maximum compatibility - works naturally with
+ * console.log, Pino, Winston, and most logging libraries.
+ *
+ * @example
+ * ```typescript
+ * // Console implementation (just works)
+ * const logger: ILogger = console;
+ *
+ * // Pino implementation
+ * import pino from 'pino';
+ * const pinoLogger = pino();
+ *
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
+ *   info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
+ *   warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
+ *   error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
+ * };
+ *
+ * // Winston implementation
+ * import winston from 'winston';
+ * const winstonLogger = winston.createLogger({ ... });
+ *
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => winstonLogger.error(msg, ...args),
+ * };
+ * ```
+ */
+export interface ILogger {
+    /**
+     * Log level.
+     * @default "info"
+     */
+    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Log debug-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    debug(msg: string, ...args: unknown[]): void;
+    /**
+     * Log info-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    info(msg: string, ...args: unknown[]): void;
+    /**
+     * Log warn-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    warn(msg: string, ...args: unknown[]): void;
+    /**
+     * Log error-level message.
+     * @param msg - Log message
+     * @param err - Error to log
+     */
+    error(msg: string, err: unknown): void;
+    /**
+     * Set log level.
+     * @param level - Log level
+     */
+    setLevel?(level: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent"): void;
+    /**
+     * Get log level.
+     * @returns Current log level or undefined if not set
+     */
+    getLevel?(): "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Create child logger with bound context.
+     * @param context - Context to bind to the child logger
+     * @returns Child logger or undefined if not implemented
+     */
+    child?(context: Record<string, unknown>): ILogger;
+}
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export declare function formatError(err: unknown): Record<string, unknown>;
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export declare const noopLogger: ILogger;

package/dist/browser/config/observability.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export function formatError(err) {
+    if (err instanceof Error) {
+        return {
+            message: err.message,
+            stack: err.stack,
+            name: err.name,
+        };
+    }
+    return { error: String(err) };
+}
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};

package/dist/browser/services/a2a/helpers/message-builder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export declare class MessageBuilder {
+    message: A2A.Message;
+    constructor(message?: Partial<A2A.Message>);
+    valueOf(): A2A.Message;
+}
+export declare const MESSAGE: (message?: Partial<A2A.Message>) => A2A.Message;
+export declare class MessageSendConfigurationBuilder {
+    configuration: A2A.MessageSendConfiguration;
+    constructor(configuration?: Partial<A2A.MessageSendConfiguration> | null);
+    valueOf(): A2A.MessageSendConfiguration;
+}
+export declare const createMessageSendParams: (messageSendParams: Partial<A2A.MessageSendParams> | string) => A2A.MessageSendParams;

package/dist/browser/services/a2a/helpers/message-builder.js

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { v4 as uuidv4 } from "uuid";
+export class MessageBuilder {
+    constructor(message = {}) {
+        this.message = {
+            role: "user",
+            parts: [],
+            metadata: undefined,
+            extensions: undefined,
+            referenceTaskIds: undefined,
+            messageId: uuidv4(),
+            taskId: undefined,
+            contextId: undefined,
+            kind: "message",
+        };
+        this.message.role = message.role ?? this.message.role;
+        this.message.parts = message.parts ?? this.message.parts;
+        this.message.metadata = message.metadata ?? this.message.metadata;
+        this.message.extensions = message.extensions ?? this.message.extensions;
+        this.message.referenceTaskIds =
+            message.referenceTaskIds ?? this.message.referenceTaskIds;
+        this.message.messageId = message.messageId ?? this.message.messageId;
+        this.message.taskId = message.taskId ?? this.message.taskId;
+        this.message.contextId = message.contextId ?? this.message.contextId;
+    }
+    valueOf() {
+        return this.message;
+    }
+}
+export const MESSAGE = (message = {}) => new MessageBuilder(message).message;
+export class MessageSendConfigurationBuilder {
+    constructor(configuration = {}) {
+        this.configuration = {
+            acceptedOutputModes: undefined,
+            historyLength: undefined,
+            pushNotificationConfig: undefined,
+            blocking: undefined,
+        };
+        this.configuration.acceptedOutputModes =
+            configuration?.acceptedOutputModes ??
+                this.configuration.acceptedOutputModes;
+        this.configuration.historyLength =
+            configuration?.historyLength ?? this.configuration.historyLength;
+        this.configuration.pushNotificationConfig =
+            configuration?.pushNotificationConfig ??
+                this.configuration.pushNotificationConfig;
+        this.configuration.blocking =
+            configuration?.blocking ?? this.configuration.blocking;
+    }
+    valueOf() {
+        return this.configuration;
+    }
+}
+export const createMessageSendParams = (messageSendParams) => {
+    const isString = typeof messageSendParams === "string";
+    return {
+        message: new MessageBuilder(isString
+            ? { parts: [{ text: messageSendParams, kind: "text" }] }
+            : messageSendParams.message).valueOf(),
+        configuration: new MessageSendConfigurationBuilder(isString ? undefined : messageSendParams.configuration).valueOf(),
+        metadata: isString ? undefined : messageSendParams.metadata,
+    };
+};

package/dist/browser/transport/rpc/parser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MCP } from "../../types/index.js";
+/**
+ * Parses a JSON-RPC response string and validates its structure.
+ * If the response contains an error, it is thrown as an A2AError.
+ * If the response contains neither a result nor an error, a validation error is thrown.
+ *
+ * @param data Response data as string
+ * @returns The parsed and validated response object
+ * @throws A2AError if the response contains an error or is invalid
+ */
+export declare function parseResponse<Res extends MCP.JSONRPCResponse | MCP.JSONRPCError>(data: string): Res;

package/dist/browser/transport/rpc/parser.js

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MCP } from "../../types/index.js";
+import { SystemError, PARSE_ERROR } from "../../utils/common/errors.js";
+import { logger } from "../../config/index.js";
+/**
+ * Parses a JSON-RPC response string and validates its structure.
+ * If the response contains an error, it is thrown as an A2AError.
+ * If the response contains neither a result nor an error, a validation error is thrown.
+ *
+ * @param data Response data as string
+ * @returns The parsed and validated response object
+ * @throws A2AError if the response contains an error or is invalid
+ */
+export function parseResponse(data) {
+    if (!data) {
+        throw PARSE_ERROR("Invalid response data");
+    }
+    try {
+        const parsed = JSON.parse(data); //todo: leverage safe parse
+        if (parsed.error) {
+            const parsedError = MCP.JSONRPCErrorSchema.safeParse(parsed);
+            if (!parsedError.success) {
+                throw PARSE_ERROR(parsedError.error);
+            }
+            throw new SystemError(parsedError.data.error.message, parsedError.data.error.code, parsedError.data.error.data);
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            parsed.jsonrpc !== "2.0") {
+            throw PARSE_ERROR("invalid jsonrpc");
+        }
+        if (parsed.result === undefined) {
+            throw PARSE_ERROR("result is undefined");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof SystemError) {
+            logger.error("parseResponse: SystemError:", error);
+            throw error;
+        }
+        logger.error("parseResponse: Error parsing response:", error);
+        throw PARSE_ERROR(error);
+    }
+}

package/dist/browser/transport/rpc/rpc-client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { A2A, MCP } from "../../types/index.js";
+/**
+ * Creates a JSON-RPC request body with the specified method and parameters.
+ *, ErrorCodeParseError
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param requestId Optional request ID (generates a UUID v4 if not provided)
+ * @returns A properly formatted JSON-RPC request object
+ */
+export declare function createJsonRpcRequest<Req extends A2A.A2ARequest>(method: Req["method"], params: Req["params"], requestId?: string | number): MCP.JSONRPCRequest;
+/**
+ * Sends a JSON-RPC request to the specified endpoint.
+ *
+ * @param baseUrl The API endpoint URL
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param headers Custom headers to include in the request
+ * @param acceptHeader The desired Accept header ('application/json' or 'text/event-stream')
+ * @returns A Promise resolving to the fetch Response object
+ * @throws RpcError if there's a network error
+ */
+export declare function sendJsonRpcRequest<Req extends A2A.A2ARequest>(baseUrl: URL, method: Req["method"], params: Req["params"], headers?: Record<string, string>, acceptHeader?: "application/json" | "text/event-stream"): Promise<Response>;
+/**
+ * Sends a GET request to the specified endpoint.
+ * This is used for non-JSON-RPC calls like agent card retrieval.
+ *
+ * @param url The endpoint URL
+ * @param headers Custom headers to include in the request
+ * @returns A Promise resolving to the fetch Response object
+ * @throws RpcError if there's a network error
+ */
+export declare function sendGetRequest(url: URL, headers?: Record<string, string>): Promise<Response>;
+/**
+ * Processes a standard JSON-RPC response (non-streaming).
+ * Parses the response, validates it, and returns the result payload.
+ *
+ * @param response The fetch Response object
+ * @param expectedMethod Optional method name for logging purposes
+ * @returns A promise resolving to the result payload
+ * @throws RpcError if there's an error in the response
+ */
+export declare function handleJsonRpcResponse<Res extends MCP.JSONRPCResultResponse>(response: Response, expectedMethod?: string): Promise<NonNullable<Res["result"]>>;
+/**
+ * Processes a JSON response from a regular GET request.
+ * Handles error checking and returns the parsed JSON.
+ *
+ * @param response The fetch Response object
+ * @param endpoint Optional endpoint description for logging purposes
+ * @returns A promise resolving to the parsed JSON
+ * @throws RpcError if there's a response error
+ */
+export declare function handleJsonResponse<T>(response: Response, endpoint?: string): Promise<T>;
+/**
+ * Sends a JSON-RPC request and processes the response in a single operation.
+ * This combines sendJsonRpcRequest and handleJsonRpcResponse into one call.
+ *
+ * @param baseUrl The API endpoint URL
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param headers Custom headers to include in the request
+ * @param acceptHeader The desired Accept header ('application/json' or 'text/event-stream')
+ * @returns A Promise resolving to the result payload
+ * @throws RpcError if there's a network error or error in the response
+ */
+export declare function executeJsonRpcRequest<Req extends A2A.A2ARequest, Res extends MCP.JSONRPCResultResponse>(baseUrl: URL, method: Req["method"], params: Req["params"], headers?: Record<string, string>, acceptHeader?: "application/json" | "text/event-stream"): Promise<NonNullable<Res["result"]>>;
+/**
+ * Sends a GET request and processes the JSON response.
+ * Helper for non-RPC REST endpoints.
+ *
+ * @param url The endpoint URL
+ * @param headers Custom headers to include in the request
+ * @param endpoint Optional endpoint description for logging
+ * @returns A Promise resolving to the parsed JSON
+ * @throws RpcError if there's a network error or error in the response
+ */
+export declare function executeGetRequest<T>(url: URL, headers?: Record<string, string>, endpoint?: string): Promise<T>;

package/dist/browser/transport/rpc/rpc-client.js

@@ -0,0 +1,189 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * HTTP JSON-RPC client utilities.
+ * Handles the common pattern of sending JSON-RPC requests and processing responses.
+ */
+import { v4 as uuidv4 } from "uuid";
+import { SystemError, INTERNAL_ERROR, PARSE_ERROR, } from "../../utils/common/errors.js";
+import { parseResponse } from "./parser.js";
+import { logger } from "../../config/index.js";
+/**
+ * Creates a JSON-RPC request body with the specified method and parameters.
+ *, ErrorCodeParseError
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param requestId Optional request ID (generates a UUID v4 if not provided)
+ * @returns A properly formatted JSON-RPC request object
+ */
+export function createJsonRpcRequest(method, params, requestId = uuidv4()) {
+    return {
+        jsonrpc: "2.0",
+        id: requestId,
+        method,
+        params,
+    };
+}
+/**
+ * Sends a JSON-RPC request to the specified endpoint.
+ *
+ * @param baseUrl The API endpoint URL
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param headers Custom headers to include in the request
+ * @param acceptHeader The desired Accept header ('application/json' or 'text/event-stream')
+ * @returns A Promise resolving to the fetch Response object
+ * @throws RpcError if there's a network error
+ */
+export async function sendJsonRpcRequest(baseUrl, method, params, headers = {}, acceptHeader = "application/json") {
+    const requestBody = createJsonRpcRequest(method, params);
+    try {
+        return await fetch(baseUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Access-Control-Allow-Origin": "*",
+                Accept: acceptHeader,
+                ...headers,
+            },
+            priority: "high",
+            mode: "cors",
+            keepalive: true,
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (networkError) {
+        logger.error("SendJsonRpcRequest: Network error during RPC call:", networkError);
+        // Wrap network errors into a standard error format
+        throw INTERNAL_ERROR(networkError);
+    }
+}
+/**
+ * Sends a GET request to the specified endpoint.
+ * This is used for non-JSON-RPC calls like agent card retrieval.
+ *
+ * @param url The endpoint URL
+ * @param headers Custom headers to include in the request
+ * @returns A Promise resolving to the fetch Response object
+ * @throws RpcError if there's a network error
+ */
+export async function sendGetRequest(url, headers = {}) {
+    try {
+        return await fetch(url, {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                ...headers,
+            },
+        });
+    }
+    catch (networkError) {
+        logger.error("SendGetRequest: Network error during GET request:", networkError);
+        throw INTERNAL_ERROR(networkError);
+    }
+}
+/**
+ * Processes a standard JSON-RPC response (non-streaming).
+ * Parses the response, validates it, and returns the result payload.
+ *
+ * @param response The fetch Response object
+ * @param expectedMethod Optional method name for logging purposes
+ * @returns A promise resolving to the result payload
+ * @throws RpcError if there's an error in the response
+ */
+export async function handleJsonRpcResponse(response, expectedMethod) {
+    let responseBody = null;
+    try {
+        responseBody = await response.text();
+        if (!response.ok) {
+            try {
+                // Try to parse error as JSON-RPC
+                parseResponse(responseBody);
+                // If we get here, it means there was no error in the response
+                // But the HTTP status was not OK, so we throw a generic error
+            }
+            catch (parseError) {
+                logger.warn("handleJsonRpcResponse", "Error parsing JSON-RPC response:", parseError);
+            }
+            // Throw a generic HTTP error if we couldn't extract an RPC error
+            throw new Error(`HTTP error ${response.status}: ${response.statusText}${responseBody ? ` - ${responseBody}` : ""}`);
+        }
+        // Parse and validate the response
+        // If it has an error, parseResponse will throw
+        // If it doesn't have a result, parseResponse will also throw
+        const jsonResponse = parseResponse(responseBody);
+        // At this point, we know we have a valid result
+        // NonNullable is used in the return type to ensure TypeScript knows this
+        return jsonResponse.result;
+    }
+    catch (error) {
+        logger.error(`handleJsonRpcResponse: Error processing response [${expectedMethod}]:`, error);
+        // Re-throw RpcError instances directly, wrap others
+        if (error instanceof SystemError) {
+            throw error;
+        }
+        else {
+            throw INTERNAL_ERROR(error);
+        }
+    }
+}
+/**
+ * Processes a JSON response from a regular GET request.
+ * Handles error checking and returns the parsed JSON.
+ *
+ * @param response The fetch Response object
+ * @param endpoint Optional endpoint description for logging purposes
+ * @returns A promise resolving to the parsed JSON
+ * @throws RpcError if there's a response error
+ */
+export async function handleJsonResponse(response, endpoint) {
+    let responseBody = null;
+    try {
+        responseBody = await response.text();
+        if (!response.ok) {
+            throw new Error(`HTTP error ${response.status}: ${response.statusText}${responseBody ? ` - ${responseBody}` : ""}`);
+        }
+        return JSON.parse(responseBody);
+    }
+    catch (error) {
+        logger.error(`handleJsonResponse: Error processing response for ${endpoint || "unknown endpoint"}:`, error);
+        if (error instanceof SystemError) {
+            throw error;
+        }
+        else {
+            throw PARSE_ERROR(error);
+        }
+    }
+}
+/**
+ * Sends a JSON-RPC request and processes the response in a single operation.
+ * This combines sendJsonRpcRequest and handleJsonRpcResponse into one call.
+ *
+ * @param baseUrl The API endpoint URL
+ * @param method The JSON-RPC method name
+ * @param params The parameters for the method
+ * @param headers Custom headers to include in the request
+ * @param acceptHeader The desired Accept header ('application/json' or 'text/event-stream')
+ * @returns A Promise resolving to the result payload
+ * @throws RpcError if there's a network error or error in the response
+ */
+export async function executeJsonRpcRequest(baseUrl, method, params, headers = {}, acceptHeader = "application/json") {
+    const response = await sendJsonRpcRequest(baseUrl, method, params, headers, acceptHeader);
+    return handleJsonRpcResponse(response, method);
+}
+/**
+ * Sends a GET request and processes the JSON response.
+ * Helper for non-RPC REST endpoints.
+ *
+ * @param url The endpoint URL
+ * @param headers Custom headers to include in the request
+ * @param endpoint Optional endpoint description for logging
+ * @returns A Promise resolving to the parsed JSON
+ * @throws RpcError if there's a network error or error in the response
+ */
+export async function executeGetRequest(url, headers = {}, endpoint) {
+    const response = await sendGetRequest(url, headers);
+    return handleJsonResponse(response, endpoint);
+}

package/dist/browser/transport/streaming/event-stream.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A, MCP } from "../../types/index.js";
+/**
+ * Creates an async generator for processing task events from an SSE stream
+ *
+ * @template T The type of task event to process (TaskStatusUpdateEvent or TaskArtifactUpdateEvent)
+ * @param response The fetch Response object containing the event stream
+ * @returns An async generator yielding the specified type of task events from StreamingResponse
+ */
+export declare function handleEventStream<StreamRes extends MCP.JSONRPCResultResponse>(response: Response): AsyncGenerator<NonNullable<StreamRes["result"]>>;
+/**
+ * Executes a streaming JSON-RPC request and yields events as they arrive
+ *
+ * @template Req The type of request being made
+ * @template StreamRes The type of streaming response expected
+ * @param baseUrl The base URL for the API
+ * @param method The JSON-RPC method to call
+ * @param params The parameters for the method
+ * @param customHeaders Any custom headers to include in the request
+ * @returns An AsyncIterable yielding events from the stream
+ */
+export declare function executeStreamEvents<Req extends A2A.A2ARequest, StreamRes extends MCP.JSONRPCResultResponse>(baseUrl: URL, method: Req["method"], params: Req["params"], customHeaders: Record<string, string>): AsyncIterable<NonNullable<StreamRes["result"]>>;