@a2a-js/sdk 0.3.5 → 0.3.6

package/dist/client/index.d.ts

@@ -1,18 +1,23 @@
-import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, a5 as ListTaskPushNotificationConfigParams, j as ListTaskPushNotificationConfigResponse, a7 as DeleteTaskPushNotificationConfigParams, g as DeleteTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.js';
+import { ae as AgentCard, x as MessageSendParams, S as SendMessageResponse, F as Message, ay as Task, aQ as TaskStatusUpdateEvent, aS as TaskArtifactUpdateEvent, $ as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, Z as TaskIdParams, c as GetTaskPushNotificationConfigResponse, a7 as ListTaskPushNotificationConfigParams, k as ListTaskPushNotificationConfigResponse, a9 as DeleteTaskPushNotificationConfigParams, h as DeleteTaskPushNotificationConfigResponse, X as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, j as JSONRPCResponse, E as Extensions, a3 as GetTaskPushNotificationConfigParams, z as PushNotificationConfig } from '../extensions-DvruCIzw.js';
 
 type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+type SendMessageResult = Message | Task;
 interface A2AClientOptions {
     agentCardPath?: string;
     fetchImpl?: typeof fetch;
 }
 /**
  * A2AClient is a TypeScript HTTP client for interacting with A2A-compliant agents.
+ * Only JSON-RPC transport is supported.
+ * @deprecated Use {@link ClientFactory}
  */
 declare class A2AClient {
-    private agentCardPromise;
-    private requestIdCounter;
+    private static emptyOptions?;
+    private readonly agentCardPromise;
+    private readonly customFetchImpl?;
     private serviceEndpointUrl?;
-    private customFetchImpl?;
+    private transport?;
+    private requestIdCounter;
     /**
      * Constructs an A2AClient instance from an AgentCard.
      * @param agentCard The AgentCard object.
@@ -34,21 +39,6 @@ declare class A2AClient {
      * @returns A Promise that resolves to a new A2AClient instance.
      */
     static fromCardUrl(agentCardUrl: string, options?: A2AClientOptions): Promise<A2AClient>;
-    /**
-     * Helper method to make a generic JSON-RPC POST request.
-     * @param method The RPC method name.
-     * @param params The parameters for the RPC method.
-     * @returns A Promise that resolves to the RPC response.
-     */
-    private _postRpcRequest;
-    /**
-     * Internal helper method to fetch the RPC service endpoint.
-     * @param url The URL to fetch.
-     * @param rpcRequest The JSON-RPC request to send.
-     * @param acceptHeader The Accept header to use.  Defaults to "application/json".
-     * @returns A Promise that resolves to the fetch HTTP response.
-     */
-    private _fetchRpc;
     /**
      * Sends a message to the agent.
      * The behavior (blocking/non-blocking) and push notification configuration
@@ -122,25 +112,7 @@ declare class A2AClient {
      * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
      */
     resubscribeTask(params: TaskIdParams): AsyncGenerator<A2AStreamEventData, void, undefined>;
-    /**
-     * Parses an HTTP response body as an A2A Server-Sent Event stream.
-     * Each 'data' field of an SSE event is expected to be a JSON-RPC 2.0 Response object,
-     * specifically a SendStreamingMessageResponse (or similar structure for resubscribe).
-     * @param response The HTTP Response object whose body is the SSE stream.
-     * @param originalRequestId The ID of the client's JSON-RPC request that initiated this stream.
-     * Used to validate the `id` in the streamed JSON-RPC responses.
-     * @returns An AsyncGenerator yielding the `result` field of each valid JSON-RPC success response from the stream.
-     */
-    private _parseA2ASseStream;
-    /**
-     * Processes a single SSE event's data string, expecting it to be a JSON-RPC response.
-     * @param jsonData The string content from one or more 'data:' lines of an SSE event.
-     * @param originalRequestId The ID of the client's request that initiated the stream.
-     * @returns The `result` field of the parsed JSON-RPC success response.
-     * @throws Error if data is not valid JSON, not a valid JSON-RPC response, an error response, or ID mismatch.
-     */
-    private _processSseEventData;
-    isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
+    private _getOrCreateTransport;
     /**
      * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
      * This method is called by the constructor.
@@ -150,14 +122,14 @@ declare class A2AClient {
      */
     private _fetchAndCacheAgentCard;
     /**
-   * Retrieves the Agent Card.
-   * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
-   * Otherwise, it returns the card fetched and cached during client construction.
-   * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
-   * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
-   * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
-   * @returns A Promise that resolves to the AgentCard.
-   */
+     * Retrieves the Agent Card.
+     * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
+     * Otherwise, it returns the card fetched and cached during client construction.
+     * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
+     * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
+     * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
+     * @returns A Promise that resolves to the AgentCard.
+     */
     getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
     /**
      * Determines the agent card URL based on the agent URL.
@@ -170,6 +142,7 @@ declare class A2AClient {
      * @returns A Promise that resolves to the service endpoint URL string.
      */
     private _getServiceEndpoint;
+    private invokeJsonRpc;
 }
 
 interface HttpHeaders {
@@ -216,7 +189,7 @@ interface AuthenticationHandler {
      *
      * This callback allows transient headers to be saved for subsequent requests only when they
      * are validated by the server.
-    */
+     */
     onSuccessfulRetry?: (headers: HttpHeaders) => Promise<void>;
 }
 /**
@@ -234,4 +207,402 @@ interface AuthenticationHandler {
  */
 declare function createAuthenticatingFetchWithRetry(fetchImpl: typeof fetch, authHandler: AuthenticationHandler): typeof fetch;
 
-export { A2AClient, type A2AClientOptions, type AuthenticationHandler, type HttpHeaders, createAuthenticatingFetchWithRetry };
+interface AgentCardResolverOptions {
+    path?: string;
+    fetchImpl?: typeof fetch;
+}
+declare class DefaultAgentCardResolver implements AgentCardResolver {
+    readonly options?: AgentCardResolverOptions;
+    constructor(options?: AgentCardResolverOptions);
+    /**
+     * Fetches the agent card based on provided base URL and path.
+     * Path is selected in the following order:
+     * 1) path parameter
+     * 2) path from options
+     * 3) .well-known/agent-card.json
+     */
+    resolve(baseUrl: string, path?: string): Promise<AgentCard>;
+    private fetchImpl;
+}
+interface AgentCardResolver {
+    /**
+     * Fetches the agent card based on provided base URL and path,
+     */
+    resolve(baseUrl: string, path?: string): Promise<AgentCard>;
+}
+declare const AgentCardResolver: {
+    default: DefaultAgentCardResolver;
+};
+
+/**
+ * Function that applies an update to a {@link ClientCallContext}.
+ */
+type ContextUpdate = (context: ClientCallContext) => void;
+/**
+ * Opaque context object to carry per-call context data.
+ * Use {@link ClientCallContextKey} to create typed keys for storing and retrieving values.
+ */
+type ClientCallContext = Record<symbol, unknown>;
+declare const ClientCallContext: {
+    /**
+     * Create a new {@link ClientCallContext} with optional updates applied.
+     */
+    create: (...updates: ContextUpdate[]) => ClientCallContext;
+    /**
+     * Create a new {@link ClientCallContext} based on an existing one with updates applied.
+     */
+    createFrom: (context: ClientCallContext | undefined, ...updates: ContextUpdate[]) => ClientCallContext;
+};
+/**
+ * Each instance represents a unique key for storing
+ * and retrieving typed values in a {@link ClientCallContext}.
+ *
+ * @example
+ * ```ts
+ * const key = new ClientCallContextKey<string>('My key');
+ * const context = ClientCallContext.create(key.set('example-value'));
+ * const value = key.get(context); // 'example-value'
+ * ```
+ */
+declare class ClientCallContextKey<T> {
+    readonly symbol: symbol;
+    constructor(description: string);
+    set(value: T): ContextUpdate;
+    get(context: ClientCallContext): T | undefined;
+}
+
+interface CallInterceptor {
+    /**
+     * Invoked before transport method.
+     */
+    before(args: BeforeArgs): Promise<void>;
+    /**
+     * Invoked after transport method.
+     */
+    after(args: AfterArgs): Promise<void>;
+}
+interface BeforeArgs<K extends keyof Client = keyof Client> {
+    /**
+     * Identifies the client method invoked and its payload.
+     * Payload inside the input object can be modified.
+     */
+    readonly input: ClientCallInput<K>;
+    /**
+     * Identifies the agent card cached on the client
+     */
+    readonly agentCard: AgentCard;
+    /**
+     * If set by the interceptor, stops execution, invokes "after"
+     * for executed interceptors and returns the result. Transport is not called.
+     */
+    earlyReturn?: ClientCallResult<K>;
+    /**
+     * Options passed to the client.
+     */
+    options?: RequestOptions;
+}
+interface AfterArgs<K extends keyof Client = keyof Client> {
+    /**
+     * Identifies the client method invoked and its result.
+     * Payload inside the result object can be modified.
+     */
+    readonly result: ClientCallResult<K>;
+    /**
+     * Identifies the agent card cached on the client
+     */
+    readonly agentCard: AgentCard;
+    /**
+     * If set by the interceptor, stops execution and returns result value,
+     * remaining interceptors are not executed.
+     */
+    earlyReturn?: boolean;
+    /**
+     * Options passed to the client.
+     */
+    options?: RequestOptions;
+}
+type ClientCallInput<K extends keyof Client = keyof Client> = MethodInput<Client, K>;
+type ClientCallResult<K extends keyof Client = keyof Client> = MethodResult<Client, K, ResultsOverrides>;
+/**
+ * For
+ *
+ * interface Foo {
+ *   f1(arg: string): Promise<Result1>;
+ *   f2(arg: number): Promise<Result2>;
+ * }
+ *
+ * MethodInputs<Foo> resolves to
+ *
+ * {
+ *   readonly method: "f1";
+ *   value: string;
+ * } | {
+ *   readonly method: "f2";
+ *   value: number;
+ * }
+ */
+type MethodInput<T, TMembers extends keyof T = keyof T> = {
+    [M in TMembers]: T[M] extends (options: RequestOptions | undefined) => unknown ? {
+        readonly method: M;
+        value?: never;
+    } : T[M] extends (payload: infer P) => unknown ? {
+        readonly method: M;
+        value: P;
+    } : never;
+}[TMembers];
+/**
+ * For
+ *
+ * interface Foo {
+ *   f1(): Promise<Result1>;
+ *   f2(): Promise<Result2>;
+ * }
+ *
+ * MethodsResults<Foo> resolves to
+ *
+ * {
+ *   readonly method: "f1";
+ *   value: Result1;
+ * } | {
+ *   readonly method: "f2";
+ *   value: Result2;
+ * }
+ */
+type MethodResult<T, TMembers extends keyof T = keyof T, TOverrides = object> = {
+    [M in TMembers]: M extends keyof TOverrides ? {
+        readonly method: M;
+        value: TOverrides[M];
+    } : T[M] extends (payload: unknown) => infer R ? {
+        readonly method: M;
+        value: Awaited<R>;
+    } : never;
+}[TMembers];
+interface ResultsOverrides {
+    sendMessageStream: A2AStreamEventData;
+    resubscribeTask: A2AStreamEventData;
+}
+
+type ServiceParametersUpdate = (parameters: ServiceParameters) => void;
+type ServiceParameters = Record<string, string>;
+declare const ServiceParameters: {
+    create(...updates: ServiceParametersUpdate[]): ServiceParameters;
+    createFrom: (serviceParameters: ServiceParameters | undefined, ...updates: ServiceParametersUpdate[]) => ServiceParameters;
+};
+declare function withA2AExtensions(...extensions: Extensions): ServiceParametersUpdate;
+
+interface Transport {
+    getExtendedAgentCard(options?: RequestOptions): Promise<AgentCard>;
+    sendMessage(params: MessageSendParams, options?: RequestOptions): Promise<SendMessageResult>;
+    sendMessageStream(params: MessageSendParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig, options?: RequestOptions): Promise<TaskPushNotificationConfig>;
+    getTaskPushNotificationConfig(params: GetTaskPushNotificationConfigParams, options?: RequestOptions): Promise<TaskPushNotificationConfig>;
+    listTaskPushNotificationConfig(params: ListTaskPushNotificationConfigParams, options?: RequestOptions): Promise<TaskPushNotificationConfig[]>;
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams, options?: RequestOptions): Promise<void>;
+    getTask(params: TaskQueryParams, options?: RequestOptions): Promise<Task>;
+    cancelTask(params: TaskIdParams, options?: RequestOptions): Promise<Task>;
+    resubscribeTask(params: TaskIdParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+}
+interface TransportFactory {
+    get protocolName(): string;
+    create(url: string, agentCard: AgentCard): Promise<Transport>;
+}
+
+interface ClientConfig {
+    /**
+     * Whether client prefers to poll for task updates instead of blocking until a terminal state is reached.
+     * If set to true, non-streaming send message result might be a Message or a Task in any (including non-terminal) state.
+     * Callers are responsible for running the polling loop. This configuration does not apply to streaming requests.
+     */
+    polling?: boolean;
+    /**
+     * Specifies the default list of accepted media types to apply for all "send message" calls.
+     */
+    acceptedOutputModes?: string[];
+    /**
+     * Specifies the default push notification configuration to apply for every Task.
+     */
+    pushNotificationConfig?: PushNotificationConfig;
+    /**
+     * Interceptors invoked for each request.
+     */
+    interceptors?: CallInterceptor[];
+}
+interface RequestOptions {
+    /**
+     * Signal to abort request execution.
+     */
+    signal?: AbortSignal;
+    /**
+     * A key-value map for passing horizontally applicable context or parameters.
+     * All parameters are passed to the server via underlying transports (e.g. In JsonRPC via Headers).
+     */
+    serviceParameters?: ServiceParameters;
+    /**
+     * Arbitrary data available to interceptors and transport implementation.
+     */
+    context?: ClientCallContext;
+}
+declare class Client {
+    readonly transport: Transport;
+    private agentCard;
+    readonly config?: ClientConfig;
+    constructor(transport: Transport, agentCard: AgentCard, config?: ClientConfig);
+    /**
+     * If the current agent card supports the extended feature, it will try to fetch the extended agent card from the server,
+     * Otherwise it will return the current agent card value.
+     */
+    getAgentCard(options?: RequestOptions): Promise<AgentCard>;
+    /**
+     * Sends a message to an agent to initiate a new interaction or to continue an existing one.
+     * Uses blocking mode by default.
+     */
+    sendMessage(params: MessageSendParams, options?: RequestOptions): Promise<SendMessageResult>;
+    /**
+     * Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task.
+     * Performs fallback to non-streaming if not supported by the agent.
+     */
+    sendMessageStream(params: MessageSendParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    /**
+     * Sets or updates the push notification configuration for a specified task.
+     * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+     */
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig, options?: RequestOptions): Promise<TaskPushNotificationConfig>;
+    /**
+     * Retrieves the current push notification configuration for a specified task.
+     * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+     */
+    getTaskPushNotificationConfig(params: TaskIdParams, options?: RequestOptions): Promise<TaskPushNotificationConfig>;
+    /**
+     * Retrieves the associated push notification configurations for a specified task.
+     * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+     */
+    listTaskPushNotificationConfig(params: ListTaskPushNotificationConfigParams, options?: RequestOptions): Promise<TaskPushNotificationConfig[]>;
+    /**
+     * Deletes an associated push notification configuration for a task.
+     */
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams, options?: RequestOptions): Promise<void>;
+    /**
+     * Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task.
+     */
+    getTask(params: TaskQueryParams, options?: RequestOptions): Promise<Task>;
+    /**
+     * Requests the cancellation of an ongoing task. The server will attempt to cancel the task,
+     * but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage).
+     */
+    cancelTask(params: TaskIdParams, options?: RequestOptions): Promise<Task>;
+    /**
+     * Allows a client to reconnect to an updates stream for an ongoing task after a previous connection was interrupted.
+     */
+    resubscribeTask(params: TaskIdParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    private applyClientConfig;
+    private executeWithInterceptors;
+    private interceptBefore;
+    private interceptAfter;
+}
+
+type TransportProtocolName = 'JSONRPC' | 'HTTP+JSON' | 'GRPC' | (string & {});
+
+interface ClientFactoryOptions {
+    /**
+     * Transport factories to use.
+     * Effectively defines transports supported by this client factory.
+     */
+    transports: TransportFactory[];
+    /**
+     * Client config to be used for clients created by this factory.
+     */
+    clientConfig?: ClientConfig;
+    /**
+     * Transport preferences to override ones defined by the agent card.
+     * If no matches are found among preferred transports, agent card values are used next.
+     */
+    preferredTransports?: TransportProtocolName[];
+    /**
+     * Used for createFromAgentCardUrl to download agent card.
+     */
+    cardResolver?: AgentCardResolver;
+}
+declare const ClientFactoryOptions: {
+    /**
+     * SDK default options for {@link ClientFactory}.
+     */
+    default: Readonly<ClientFactoryOptions>;
+    /**
+     * Creates new options by merging an original and an override object.
+     * Transports are merged based on `TransportFactory.protocolName`,
+     * interceptors are concatenated, other fields are overriden.
+     *
+     * @example
+     * ```ts
+     * const options = ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+     *  transports: [new MyCustomTransportFactory()], // adds a custom transport
+     *  clientConfig: { interceptors: [new MyInterceptor()] }, // adds a custom interceptor
+     * });
+     * ```
+     */
+    createFrom(original: ClientFactoryOptions, overrides: Partial<ClientFactoryOptions>): ClientFactoryOptions;
+};
+declare class ClientFactory {
+    readonly options: ClientFactoryOptions;
+    private readonly transportsByName;
+    private readonly agentCardResolver;
+    constructor(options?: ClientFactoryOptions);
+    /**
+     * Creates a new client from the provided agent card.
+     */
+    createFromAgentCard(agentCard: AgentCard): Promise<Client>;
+    /**
+     * Downloads agent card using AgentCardResolver from options
+     * and creates a new client from the downloaded card.
+     *
+     * @example
+     * ```ts
+     * const factory = new ClientFactory(); // use default options and default {@link AgentCardResolver}.
+     * const client1 = await factory.createFromUrl('https://example.com'); // /.well-known/agent-card.json is used by default
+     * const client2 = await factory.createFromUrl('https://example.com', '/my-agent-card.json'); // specify custom path
+     * const client3 = await factory.createFromUrl('https://example.com/my-agent-card.json', ''); // specify full URL and set path to empty
+     * ```
+     */
+    createFromUrl(baseUrl: string, path?: string): Promise<Client>;
+}
+
+interface JsonRpcTransportOptions {
+    endpoint: string;
+    fetchImpl?: typeof fetch;
+}
+declare class JsonRpcTransport implements Transport {
+    private readonly customFetchImpl?;
+    private readonly endpoint;
+    private requestIdCounter;
+    constructor(options: JsonRpcTransportOptions);
+    getExtendedAgentCard(options?: RequestOptions, idOverride?: number): Promise<AgentCard>;
+    sendMessage(params: MessageSendParams, options?: RequestOptions, idOverride?: number): Promise<SendMessageResult>;
+    sendMessageStream(params: MessageSendParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig, options?: RequestOptions, idOverride?: number): Promise<TaskPushNotificationConfig>;
+    getTaskPushNotificationConfig(params: GetTaskPushNotificationConfigParams, options?: RequestOptions, idOverride?: number): Promise<TaskPushNotificationConfig>;
+    listTaskPushNotificationConfig(params: ListTaskPushNotificationConfigParams, options?: RequestOptions, idOverride?: number): Promise<TaskPushNotificationConfig[]>;
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams, options?: RequestOptions, idOverride?: number): Promise<void>;
+    getTask(params: TaskQueryParams, options?: RequestOptions, idOverride?: number): Promise<Task>;
+    cancelTask(params: TaskIdParams, options?: RequestOptions, idOverride?: number): Promise<Task>;
+    resubscribeTask(params: TaskIdParams, options?: RequestOptions): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    callExtensionMethod<TExtensionParams, TExtensionResponse extends JSONRPCResponse>(method: string, params: TExtensionParams, idOverride: number, options?: RequestOptions): Promise<TExtensionResponse>;
+    private _fetch;
+    private _sendRpcRequest;
+    private _fetchRpc;
+    private _sendStreamingRequest;
+    private _parseA2ASseStream;
+    private _processSseEventData;
+    private static mapToError;
+}
+declare class JsonRpcTransportFactoryOptions {
+    fetchImpl?: typeof fetch;
+}
+declare class JsonRpcTransportFactory implements TransportFactory {
+    private readonly options?;
+    static readonly name: TransportProtocolName;
+    constructor(options?: JsonRpcTransportFactoryOptions);
+    get protocolName(): string;
+    create(url: string, _agentCard: AgentCard): Promise<Transport>;
+}
+
+export { A2AClient, type A2AClientOptions, type AfterArgs, AgentCardResolver, type AgentCardResolverOptions, type AuthenticationHandler, type BeforeArgs, type CallInterceptor, Client, ClientCallContext, ClientCallContextKey, type ClientCallInput, type ClientCallResult, type ClientConfig, ClientFactory, ClientFactoryOptions, type ContextUpdate, DefaultAgentCardResolver, type HttpHeaders, JsonRpcTransport, JsonRpcTransportFactory, type JsonRpcTransportOptions, type RequestOptions, ServiceParameters, type ServiceParametersUpdate, type Transport, type TransportFactory, createAuthenticatingFetchWithRetry, withA2AExtensions };