feat: introduce transport agnostic client

package.json

@@ -71,7 +71,7 @@
     "clean": "gts clean",
     "build": "tsup",
     "pretest": "npm run build",
-    "test": "mocha test/**/*.spec.ts",
+    "test": "mocha \"test/**/*.spec.ts\"",
     "lint": "npx eslint .",
     "format:readme": "prettier --write ./README.md",
     "lint:fix": "npx eslint . --fix",

src/client/client.ts

@@ -23,6 +23,7 @@ import {
 } from '../types.js'; // Assuming schema.ts is in the same directory or appropriately pathed
 import { AGENT_CARD_PATH } from '../constants.js';
 import { JsonRpcTransport } from './transports/json_rpc_transport.js';
+import { RequestOptions } from './transports/transport.js';
 
 export type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 
@@ -38,6 +39,8 @@ export interface A2AClientOptions {
  * Only JSON-RPC transport is supported.
  */
 export class A2AClient {
+  private static emptyOptions?: RequestOptions = undefined;
+
   private readonly agentCardPromise: Promise<AgentCard>;
   private readonly customFetchImpl?: typeof fetch;
   private serviceEndpointUrl?: string; // To be populated from AgentCard after fetchin
@@ -150,7 +153,7 @@ export class A2AClient {
    */
   public async sendMessage(params: MessageSendParams): Promise<SendMessageResponse> {
     return await this.invokeJsonRpc<MessageSendParams, SendMessageResponse>(
-      (t, p, id) => t.sendMessage(p, id),
+      (t, p, id) => t.sendMessage(p, A2AClient.emptyOptions, id),
       params
     );
   }
@@ -196,7 +199,7 @@ export class A2AClient {
     return await this.invokeJsonRpc<
       TaskPushNotificationConfig,
       SetTaskPushNotificationConfigResponse
-    >((t, p, id) => t.setTaskPushNotificationConfig(p, id), params);
+    >((t, p, id) => t.setTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
   }
 
   /**
@@ -208,7 +211,7 @@ export class A2AClient {
     params: TaskIdParams
   ): Promise<GetTaskPushNotificationConfigResponse> {
     return await this.invokeJsonRpc<TaskIdParams, GetTaskPushNotificationConfigResponse>(
-      (t, p, id) => t.getTaskPushNotificationConfig(p, id),
+      (t, p, id) => t.getTaskPushNotificationConfig(p, A2AClient.emptyOptions, id),
       params
     );
   }
@@ -224,7 +227,7 @@ export class A2AClient {
     return await this.invokeJsonRpc<
       ListTaskPushNotificationConfigParams,
       ListTaskPushNotificationConfigResponse
-    >((t, p, id) => t.listTaskPushNotificationConfig(p, id), params);
+    >((t, p, id) => t.listTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
   }
 
   /**
@@ -238,7 +241,7 @@ export class A2AClient {
     return await this.invokeJsonRpc<
       DeleteTaskPushNotificationConfigParams,
       DeleteTaskPushNotificationConfigResponse
-    >((t, p, id) => t.deleteTaskPushNotificationConfig(p, id), params);
+    >((t, p, id) => t.deleteTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
   }
 
   /**
@@ -248,7 +251,7 @@ export class A2AClient {
    */
   public async getTask(params: TaskQueryParams): Promise<GetTaskResponse> {
     return await this.invokeJsonRpc<TaskQueryParams, GetTaskResponse>(
-      (t, p, id) => t.getTask(p, id),
+      (t, p, id) => t.getTask(p, A2AClient.emptyOptions, id),
       params
     );
   }
@@ -260,7 +263,7 @@ export class A2AClient {
    */
   public async cancelTask(params: TaskIdParams): Promise<CancelTaskResponse> {
     return await this.invokeJsonRpc<TaskIdParams, CancelTaskResponse>(
-      (t, p, id) => t.cancelTask(p, id),
+      (t, p, id) => t.cancelTask(p, A2AClient.emptyOptions, id),
       params
     );
   }

src/client/factory.ts

@@ -0,0 +1,86 @@
+import { TransportProtocolName } from '../core.js';
+import { AgentCard } from '../types.js';
+import { Client, ClientConfig } from './multitransport-client.js';
+import { JsonRpcTransportFactory } from './transports/json_rpc_transport.js';
+import { TransportFactory } from './transports/transport.js';
+
+export interface ClientFactoryOptions {
+  /**
+   * Transport factories to use.
+   * Effectively defines transports supported by this client factory.
+   */
+  transports: ReadonlyArray<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[];
+}
+
+export const ClientFactoryOptions = {
+  Default: {
+    transports: [new JsonRpcTransportFactory()],
+  },
+};
+
+export class ClientFactory {
+  private readonly transportsByName = new Map<string, TransportFactory>();
+
+  constructor(public readonly options: ClientFactoryOptions = ClientFactoryOptions.Default) {
+    if (!options.transports || options.transports.length === 0) {
+      throw new Error('No transports provided');
+    }
+    for (const transport of options.transports) {
+      if (this.transportsByName.has(transport.protocolName)) {
+        throw new Error(`Duplicate transport name: ${transport.protocolName}`);
+      }
+      this.transportsByName.set(transport.protocolName, transport);
+    }
+    for (const transport of options.preferredTransports ?? []) {
+      const factory = this.options.transports.find((t) => t.protocolName === transport);
+      if (!factory) {
+        throw new Error(
+          `Unknown preferred transport: ${transport}, available transports: ${[...this.transportsByName.keys()].join()}`
+        );
+      }
+    }
+  }
+
+  async createFromAgentCard(agentCard: AgentCard): Promise<Client> {
+    const agentCardPreferred = agentCard.preferredTransport ?? JsonRpcTransportFactory.name;
+    const additionalInterfaces = agentCard.additionalInterfaces ?? [];
+    const urlsPerAgentTransports = new Map<string, string>([
+      [agentCardPreferred, agentCard.url],
+      ...additionalInterfaces.map<[string, string]>((i) => [i.transport, i.url]),
+    ]);
+    const transportsByPreference = [
+      ...(this.options.preferredTransports ?? []),
+      agentCardPreferred,
+      ...additionalInterfaces.map((i) => i.transport),
+    ];
+    for (const transport of transportsByPreference) {
+      if (!urlsPerAgentTransports.has(transport)) {
+        continue;
+      }
+      const factory = this.transportsByName.get(transport);
+      if (!factory) {
+        continue;
+      }
+      return new Client(
+        await factory.create(urlsPerAgentTransports.get(transport), agentCard),
+        agentCard,
+        this.options.clientConfig
+      );
+    }
+    throw new Error(
+      'No compatible transport found, available transports: ' +
+        [...this.transportsByName.keys()].join()
+    );
+  }
+}

src/client/multitransport-client.ts

@@ -0,0 +1,155 @@
+import { PushNotificationNotSupportedError } from '../errors.js';
+import {
+  MessageSendParams,
+  TaskPushNotificationConfig,
+  DeleteTaskPushNotificationConfigParams,
+  ListTaskPushNotificationConfigParams,
+  Task,
+  TaskIdParams,
+  TaskQueryParams,
+  PushNotificationConfig,
+  AgentCard,
+} from '../types.js';
+import { A2AStreamEventData, SendMessageResult } from './client.js';
+import { Transport } from './transports/transport.js';
+
+export 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;
+}
+
+export class Client {
+  constructor(
+    public readonly transport: Transport,
+    public readonly agentCard: AgentCard,
+    public readonly config?: ClientConfig
+  ) {}
+
+  /**
+   * 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): Promise<SendMessageResult> {
+    params = this.applyClientConfig({
+      params,
+      blocking: !(this.config?.polling ?? false),
+    });
+    return this.transport.sendMessage(params);
+  }
+
+  /**
+   * 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.
+   */
+  async *sendMessageStream(
+    params: MessageSendParams
+  ): AsyncGenerator<A2AStreamEventData, void, undefined> {
+    params = this.applyClientConfig({ params, blocking: true });
+    if (!this.agentCard.capabilities.streaming) {
+      yield this.transport.sendMessage(params);
+      return;
+    }
+    yield* this.transport.sendMessageStream(params);
+  }
+
+  /**
+   * Sets or updates the push notification configuration for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  setTaskPushNotificationConfig(
+    params: TaskPushNotificationConfig
+  ): Promise<TaskPushNotificationConfig> {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.transport.setTaskPushNotificationConfig(params);
+  }
+
+  /**
+   * Retrieves the current push notification configuration for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  getTaskPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig> {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.transport.getTaskPushNotificationConfig(params);
+  }
+
+  /**
+   * Retrieves the associated push notification configurations for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  listTaskPushNotificationConfig(
+    params: ListTaskPushNotificationConfigParams
+  ): Promise<TaskPushNotificationConfig[]> {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.transport.listTaskPushNotificationConfig(params);
+  }
+
+  /**
+   * Deletes an associated push notification configuration for a task.
+   */
+  deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams): Promise<void> {
+    return this.transport.deleteTaskPushNotificationConfig(params);
+  }
+
+  /**
+   * Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task.
+   */
+  getTask(params: TaskQueryParams): Promise<Task> {
+    return this.transport.getTask(params);
+  }
+
+  /**
+   * 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): Promise<Task> {
+    return this.transport.cancelTask(params);
+  }
+
+  /**
+   * Allows a client to reconnect to an updates stream for an ongoing task after a previous connection was interrupted.
+   */
+  async *resubscribeTask(
+    params: TaskIdParams
+  ): AsyncGenerator<A2AStreamEventData, void, undefined> {
+    yield* this.transport.resubscribeTask(params);
+  }
+
+  private applyClientConfig({
+    params,
+    blocking,
+  }: {
+    params: MessageSendParams;
+    blocking: boolean;
+  }): MessageSendParams {
+    const result = { ...params, configuration: params.configuration ?? {} };
+
+    if (!result.configuration.acceptedOutputModes && this.config?.acceptedOutputModes) {
+      result.configuration.acceptedOutputModes = this.config.acceptedOutputModes;
+    }
+    if (!result.configuration.pushNotificationConfig && this.config?.pushNotificationConfig) {
+      result.configuration.pushNotificationConfig = this.config.pushNotificationConfig;
+    }
+    result.configuration.blocking ??= blocking;
+    return result;
+  }
+}