@artinet/sdk 0.6.0-preview.2 → 0.6.0

package/dist/client/a2a-client.js

@@ -1,237 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { executeJsonRpcRequest, executeGetRequest, } from "../transport/rpc/rpc-client.js";
-import { executeStreamEvents } from "../transport/streaming/event-stream.js";
-import { INTERNAL_ERROR } from "../utils/common/errors.js";
-import { logger } from "../config/index.js";
-import * as describe from "../create/describe.js";
-/**
- * A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
- * It provides methods for sending tasks, retrieving statuses, canceling operations, and handling streaming responses.
- */
-export class A2AClient {
-    baseUrl;
-    cachedAgentCard = null;
-    customHeaders = {};
-    fallbackPath;
-    agentUrl;
-    mergePath;
-    /**
-     * Creates a new A2AClient instance.
-     * @param baseUrl The base URL for the A2A server.
-     * @param headers Optional custom headers to include in all requests.
-     * @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
-     * @example
-     * const client = new A2AClient("http://localhost:4000/a2a");
-     * const card = await client.agentCard();
-     * console.log(card);
-     * @example
-     * const client = new A2AClient("http://localhost:4000/a2a", {}, "/agent-card");
-     * const card = await client.agentCard();
-     * console.log(card);
-     */
-    constructor(baseUrl, headers = {}, fallbackPath, mergePath = false) {
-        this.baseUrl = typeof baseUrl === "string" ? new URL(baseUrl) : baseUrl;
-        this.customHeaders = headers;
-        this.fallbackPath = fallbackPath ?? "/agent-card";
-        this.agentUrl = this.baseUrl;
-        this.mergePath = mergePath;
-    }
-    /**
-     * Retrieves the AgentCard from the A2A server.
-     * Caches the result after the first successful fetch.
-     * @returns A promise resolving to the AgentCard.
-     */
-    async agentCard() {
-        if (this.cachedAgentCard) {
-            return this.cachedAgentCard;
-        }
-        // Standard location for agent cards
-        const wellKnownUrl = new URL("/.well-known/agent-card.json", this.baseUrl);
-        if (this.mergePath) {
-            wellKnownUrl.pathname = this.baseUrl.pathname + wellKnownUrl.pathname;
-        }
-        try {
-            try {
-                if (!URL.canParse(wellKnownUrl)) {
-                    throw new Error("Invalid well-known URL");
-                }
-                const card = await executeGetRequest(wellKnownUrl, this.customHeaders, "agent card (well-known)");
-                if (!card.name || card.name === null || card.name === undefined) {
-                    throw new Error("No agent card found");
-                }
-                this.cachedAgentCard = card;
-            }
-            catch (error) {
-                logger.error("A2AClient:agentCard: Failed to fetch agent card (well-known):", error);
-                const fallbackUrl = new URL(this.fallbackPath, this.baseUrl);
-                if (this.mergePath) {
-                    fallbackUrl.pathname = this.baseUrl.pathname + fallbackUrl.pathname;
-                }
-                const fallbackCard = await executeGetRequest(fallbackUrl, this.customHeaders, "agent card (fallback)");
-                if (!fallbackCard.name ||
-                    fallbackCard.name === null ||
-                    fallbackCard.name === undefined) {
-                    throw new Error("No fallback agent card found" + error);
-                }
-                this.cachedAgentCard = fallbackCard;
-            }
-        }
-        catch (error) {
-            logger.error("A2AClient:agentCard: Failed to fetch or parse agent card:", error);
-            throw INTERNAL_ERROR(error);
-        }
-        this.agentUrl = new URL(this.cachedAgentCard.url, this.baseUrl);
-        return this.cachedAgentCard;
-    }
-    /**
-     * Retrieves the AgentCard from the A2A server.
-     * @returns A promise resolving to the AgentCard.
-     */
-    getAgentCard() {
-        return this.agentCard();
-    }
-    /**
-     * Refreshes the cached AgentCard by fetching it again from the server.
-     * @returns A promise resolving to the updated AgentCard.
-     */
-    async refreshAgentCard() {
-        this.cachedAgentCard = null;
-        return this.agentCard();
-    }
-    /**
-     * Sends a Message to an agent server.
-     * @param params The parameters for the message/send method.
-     * @returns A promise resolving to Message/Task response from the agent server or null.
-     */
-    async sendMessage(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "message/send", typeof params === "string"
-            ? describe.messageSendParams(params)
-            : typeof params === "object" && "message" in params
-                ? params
-                : describe.messageSendParams({ message: params }), this.customHeaders);
-    }
-    /**
-     * @deprecated Use sendMessage instead.
-     * Sends a task request to the agent (non-streaming).
-     * @param params The parameters for the message/send method.
-     * @returns A promise resolving to the Task object or null.
-     */
-    async sendTask(params) {
-        return await this.sendMessage(params);
-    }
-    /**
-     * Sends a Message and returns a stream of status and artifact updates.
-     * @param params Task parameters for the request
-     * @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
-     */
-    sendStreamingMessage(params) {
-        return executeStreamEvents(this.agentUrl, "message/stream", describe.messageSendParams(params), this.customHeaders);
-    }
-    /**
-     * @deprecated Use sendStreamingMessage instead.
-     * Sends a task and returns a subscription to status and artifact updates.
-     * @param params Task parameters for the request
-     * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
-     */
-    sendTaskSubscribe(params) {
-        return this.sendStreamingMessage(params);
-    }
-    /**
-     * Retrieves the current state of a task.
-     * @param params The parameters for the tasks/get method.
-     * @returns A promise resolving to the Task object or null.
-     */
-    async getTask(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "tasks/get", params, this.customHeaders);
-    }
-    /**
-     * Cancels a currently running task.
-     * @param params The parameters for the tasks/cancel method.
-     * @returns A promise resolving to the updated Task object (usually canceled state) or null.
-     */
-    async cancelTask(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "tasks/cancel", params, this.customHeaders);
-    }
-    /**
-     * Sets or updates the push notification config for a task.
-     * @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
-     * @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
-     */
-    async setTaskPushNotification(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/set", params, this.customHeaders);
-    }
-    /**
-     * Retrieves the currently configured push notification config for a task.
-     * @param params The parameters for the tasks/pushNotificationConfig/get method.
-     * @returns A promise resolving to the TaskPushNotificationConfig or null.
-     */
-    async getTaskPushNotification(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/get", params, this.customHeaders);
-    }
-    /**
-     * Resubscribes to an existing task's update stream.
-     * @param params Parameters identifying the task to resubscribe to
-     * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
-     */
-    resubscribeTask(params) {
-        return executeStreamEvents(this.agentUrl, "tasks/resubscribe", params, this.customHeaders);
-    }
-    /**
-     * Checks if the server supports a specific capability based on the agent card.
-     * @param capability The capability to check (e.g., 'streaming', 'pushNotifications').
-     * @returns A promise resolving to true if the capability is supported.
-     */
-    async supports(capability) {
-        try {
-            const card = await this.agentCard();
-            if (!card.capabilities) {
-                return false;
-            }
-            switch (capability) {
-                case "streaming":
-                    return !!card.capabilities.streaming;
-                case "pushNotifications":
-                    return !!card.capabilities.pushNotifications;
-                case "stateTransitionHistory":
-                    return !!card.capabilities.stateTransitionHistory;
-                default:
-                    return false;
-            }
-        }
-        catch (error) {
-            logger.error(`A2AClient:supports: Failed to determine support for capability '${capability}':`, error);
-            return false; // Assume not supported if card fetch fails
-        }
-    }
-    /**
-     * Sets custom headers to be included in all requests.
-     * @param headers A record of header name/value pairs.
-     */
-    setHeaders(headers) {
-        this.customHeaders = { ...headers };
-    }
-    /**
-     * Adds a single custom header to be included in all requests.
-     * @param name The header name.
-     * @param value The header value.
-     */
-    addHeader(name, value) {
-        this.customHeaders[name] = value;
-    }
-    /**
-     * Removes a custom header.
-     * @param name The header name to remove.
-     */
-    removeHeader(name) {
-        delete this.customHeaders[name];
-    }
-    /**
-     * Clears all custom headers.
-     */
-    clearHeaders() {
-        this.customHeaders = {};
-    }
-}

package/dist/client/index.d.ts

@@ -1 +0,0 @@
-export * from "./a2a-client.js";

package/dist/client/index.js

@@ -1 +0,0 @@
-export * from "./a2a-client.js";

package/dist/server/express/errors.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { type ErrorRequestHandler } from "express";
-/**
- * Express error handler middleware.
- */
-export declare const errorHandler: ErrorRequestHandler;

package/dist/server/express/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./server.js";
-export * from "./middeware.js";
-export * from "./errors.js";

package/dist/server/express/index.js

@@ -1,3 +0,0 @@
-export * from "./server.js";
-export * from "./middeware.js";
-export * from "./errors.js";

package/dist/server/express/middeware.d.ts

@@ -1,7 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { NextFunction, Request, Response } from "express";
-import { A2A } from "../../types/index.js";
-export declare function jsonRPCMiddleware(service: A2A.Service, req: Request, res: Response, next: NextFunction, extendedAgentCard?: A2A.AgentCard): Promise<void>;

package/dist/server/express/middeware.js

@@ -1,121 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { logger } from "../../config/index.js";
-import { formatJson } from "../../utils/common/utils.js";
-import { A2AError } from "@a2a-js/sdk/server";
-const isValidMethod = (method) => {
-    return (method &&
-        method !== "" &&
-        method !== null &&
-        method !== undefined &&
-        typeof method === "string");
-};
-const checkParams = (params, method) => {
-    if (!params || (typeof params !== "object" && !Array.isArray(params))) {
-        throw A2AError.invalidParams("Invalid Parameters", {
-            params,
-            method,
-        });
-    }
-    else if (typeof params === "object" && Object.keys(params).length === 0) {
-        throw A2AError.invalidParams("Params Required", {
-            params,
-            method,
-        });
-    }
-};
-export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCard) {
-    const { method, params, id, jsonrpc } = req.body;
-    if (jsonrpc !== "2.0" ||
-        (typeof id !== "string" &&
-            typeof id === "number" &&
-            !Number.isInteger(id) &&
-            id !== null)) {
-        res.json({
-            jsonrpc: "2.0",
-            id: id || null,
-            error: A2AError.invalidRequest(`Invalid JSONRPC info: ${formatJson({ method, params, id, jsonrpc })}`).toJSONRPCError(),
-        });
-        return;
-    }
-    try {
-        if (!isValidMethod(method)) {
-            throw A2AError.invalidRequest("No method provided");
-        }
-        let result;
-        switch (method) {
-            case "message/send": {
-                checkParams(params, method);
-                result = await service.sendMessage(params);
-                break;
-            }
-            case "message/stream": {
-                checkParams(params, method);
-                res.writeHead(200, {
-                    "Content-Type": "text/event-stream",
-                    "Cache-Control": "no-cache",
-                    Connection: "keep-alive",
-                });
-                const stream = service.streamMessage(params);
-                for await (const data of stream) {
-                    res.write(`data: ${JSON.stringify({ jsonrpc: "2.0", id, result: data })}\n\n`);
-                }
-                res.end();
-                return;
-            }
-            case "tasks/resubscribe": {
-                checkParams(params, method);
-                const stream = service.resubscribe(params);
-                res.writeHead(200, {
-                    "Content-Type": "text/event-stream",
-                    "Cache-Control": "no-cache",
-                    Connection: "keep-alive",
-                });
-                for await (const data of stream) {
-                    res.write(`data: ${JSON.stringify({ jsonrpc: "2.0", id, result: data })}\n\n`);
-                }
-                res.end();
-                return;
-            }
-            case "tasks/get": {
-                checkParams(params, method);
-                result = await service.getTask(params);
-                break;
-            }
-            case "tasks/cancel": {
-                checkParams(params, method);
-                result = await service.cancelTask(params);
-                break;
-            }
-            //todo: Implement push notifications
-            //todo: Implement Tasks List
-            case "tasks/pushNotificationConfig/set":
-            case "tasks/pushNotificationConfig/get":
-            case "tasks/pushNotificationConfig/delete":
-            case "task/pushNotificationConfig/list": {
-                throw A2AError.pushNotificationNotSupported();
-            }
-            case "agent/getAuthenticatedExtendedCard": {
-                if (!extendedAgentCard ||
-                    (await service.getAgentCard()).supportsAuthenticatedExtendedCard !==
-                        true) {
-                    throw A2AError.authenticatedExtendedCardNotConfigured();
-                }
-                result = extendedAgentCard;
-                break;
-            }
-            default:
-                throw A2AError.methodNotFound(method);
-        }
-        res.json({ jsonrpc: "2.0", id, result });
-    }
-    catch (error) {
-        logger.error("jsonRPCMiddleware[Error]:", error);
-        logger.warn("jsonRPCMiddleware[Error]: Request body", {
-            request: req.body,
-        });
-        return next(error);
-    }
-}

package/dist/transport/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./rpc/rpc-client.js";
-export * from "./streaming/event-stream.js";
-export * from "./rpc/parser.js";

package/dist/transport/index.js

@@ -1,4 +0,0 @@
-export * from "./rpc/rpc-client.js";
-export * from "./streaming/event-stream.js";
-export * from "./rpc/parser.js";
-// export * from "./trpc/index.js";

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

@@ -1,15 +0,0 @@
-/**
- * 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.JSONRPCErrorResponse>(data: string): Res;

package/dist/transport/rpc/parser.js

@@ -1,49 +0,0 @@
-/**
- * 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) {
-            //MCP Error defs may be a wee bit restrictive
-            const parsedError = MCP.JSONRPCErrorResponseSchema.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/transport/rpc/rpc-client.d.ts

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