@artinet/sdk 0.5.16 → 0.5.18

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

@@ -0,0 +1,61 @@
+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 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 { JSONRPCResponse } 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 JSONRPCResponse>(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 { JSONRPCErrorSchema, } from "../../types/index.js";
+import { SystemError, PARSE_ERROR } from "../../utils/common/errors.js";
+import { logError } from "../../utils/logging/log.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 = JSONRPCErrorSchema.safeParse(parsed.error);
+            if (!parsedError.success) {
+                throw PARSE_ERROR(parsedError.error);
+            }
+            throw new SystemError(parsedError.data.message, parsedError.data.code, parsedError.data.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) {
+            logError("parseResponse", "SystemError:", error.message);
+            throw error;
+        }
+        logError("parseResponse", "Error parsing response:", data);
+        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 { JSONRPCRequest, JSONRPCResponse, A2ARequest } 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 A2ARequest>(method: Req["method"], params: Req["params"], requestId?: string | number): 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 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 JSONRPCResponse>(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 A2ARequest, Res extends JSONRPCResponse>(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 { logError, logWarn } from "../../utils/logging/log.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) {
+        logError("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) {
+        logError("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) {
+                logWarn("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) {
+        logError("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) {
+        logError("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 type { JSONRPCResponse, A2ARequest } 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 JSONRPCResponse>(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 A2ARequest, StreamRes extends JSONRPCResponse>(baseUrl: URL, method: Req["method"], params: Req["params"], customHeaders: Record<string, string>): AsyncIterable<NonNullable<StreamRes["result"]>>;

package/dist/browser/transport/streaming/event-stream.js

@@ -0,0 +1,99 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Event stream utilities for handling Server-Sent Events (SSE).
+ */
+import { parseResponse } from "../rpc/parser.js";
+import { createParser, } from "eventsource-parser";
+import { sendJsonRpcRequest } from "../rpc/rpc-client.js";
+import { logError, logWarn, logDebug } from "../../utils/logging/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 async function* handleEventStream(response) {
+    if (!response.ok || !response.body) {
+        let errorText = null;
+        try {
+            errorText = await response.text();
+        }
+        catch (_) { }
+        logError("handleEventStream", `HTTP error [${response.status}:${response.statusText}] - ${errorText}`, new Error(`HTTP error [${response.status}:${response.statusText}] - ${errorText}`));
+        throw new Error(`HTTP error [${response.status}:${response.statusText}] - ${errorText}`);
+    }
+    // Use eventsource-parser to process the SSE stream
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const events = [];
+    const parser = createParser({
+        onEvent: (event) => {
+            if (event.data) {
+                if (event.event === "close") {
+                    logDebug("handleEventStream", "Stream closed");
+                    return;
+                }
+                try {
+                    const parsedData = parseResponse(event.data);
+                    const eventResult = parsedData.result;
+                    if (eventResult) {
+                        events.push(eventResult);
+                    }
+                    else {
+                        logWarn("handleEventStream", "Failed to parse SSE data", parsedData);
+                    }
+                    // if (parsedData.final && parsedData.final === true) {
+                    //   logDebug("handleEventStream", "Stream completed");
+                    //   return;
+                    // }
+                }
+                catch (e) {
+                    logWarn("handleEventStream", "Failed to parse SSE data", e);
+                }
+            }
+        },
+        onError: (error) => {
+            logError("handleEventStream", "Error parsing SSE data", error);
+        },
+        onRetry: (retry) => {
+            logWarn("handleEventStream", "Retrying SSE connection", retry);
+        },
+    });
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = decoder.decode(value, { stream: true });
+            parser.feed(chunk);
+            while (events.length > 0) {
+                yield events.shift();
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * 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 async function* executeStreamEvents(baseUrl, method, params, customHeaders) {
+    logDebug("executeStreamEvents", `Sending streaming request to: ${baseUrl.toString()}, method: ${method}`);
+    const responsePromise = sendJsonRpcRequest(baseUrl, method, params, customHeaders, "text/event-stream");
+    const response = await responsePromise;
+    logDebug("executeStreamEvents", "Response", response);
+    yield* handleEventStream(response);
+}

package/dist/browser/types/ext.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * For artinet specific conventions
+ * AgentInfo will expand to incorporate additional details required from other protocols
+ * (e.g. AgentFAQ(NANDA), AgentCard(A2A), etc.)
+ */
+export { AgentCardSchema as AgentInfoSchema } from "./schemas/a2a/index.js";
+export type { AgentCard as AgentInfo } from "./schemas/a2a/index.js";
+export type { A2AEngine as AgentEngine } from "./interfaces/services/a2a/index.js";
+export type { A2AServiceInterface as Agent } from "./interfaces/services/a2a/index.js";

package/dist/browser/types/ext.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * For artinet specific conventions
+ * AgentInfo will expand to incorporate additional details required from other protocols
+ * (e.g. AgentFAQ(NANDA), AgentCard(A2A), etc.)
+ */
+export { AgentCardSchema as AgentInfoSchema } from "./schemas/a2a/index.js";

package/dist/browser/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ext.js";
+export * from "./schemas/index.js";
+export * from "./interfaces/index.js";
+export * from "./utils/index.js";

package/dist/browser/types/index.js

@@ -0,0 +1,4 @@
+export * from "./ext.js";
+export * from "./schemas/index.js";
+export * from "./interfaces/index.js";
+export * from "./utils/index.js";