feat(api)!: Update codebase to use only Proto based types (#337)

# Description

Updated the codebase to only use Proto based types and remove the old
JSON types.ts completely.

This change unifies the usage of types with other SDKs and is part of
the 1.0.0 scope. Equivalent PR on the Python SDK:
a2aproject/a2a-python#572.

# Important

This is a breaking change and therefore it is going to be merged into an
epic `v1.0` branch instead of `main`. Later 1.0 release will introduce
this in the `main` branch.

---------

Co-authored-by: Bartek Gralewicz <bgralewicz@google.com>
Co-authored-by: Ivan Shymko <ishymko@google.com>

Author: bartek-gralewicz

.betterer.results

@@ -4,9 +4,9 @@ name: Run Build Tests
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
     paths-ignore:
       - '**.md'
       - 'LICENSE'

.github/workflows/build-tests.yml

@@ -2,9 +2,9 @@ name: Run Linter & Formatter
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
     paths-ignore:
       - '**.md'
       - 'LICENSE'

.github/workflows/lint.yml

@@ -5,9 +5,9 @@ name: Run Unit Tests
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "epic/**" ]
     paths-ignore:
       - '**.md'
       - 'LICENSE'

.github/workflows/unit-tests.yml

@@ -5,11 +5,11 @@ import {
   CancelTaskResponse,
   SetTaskPushNotificationConfigResponse,
   GetTaskPushNotificationConfigResponse,
-  JSONRPCErrorResponse,
   ListTaskPushNotificationConfigSuccessResponse,
   DeleteTaskPushNotificationConfigSuccessResponse,
   GetAuthenticatedExtendedCardSuccessResponse,
-} from './types.js';
+  JSONRPCErrorResponse,
+} from './json_rpc_types.js';
 
 /**
  * Represents any valid JSON-RPC response defined in the A2A protocol.

src/a2a_response.ts

@@ -1,5 +1,5 @@
 import { AGENT_CARD_PATH } from '../constants.js';
-import { AgentCard } from '../types.js';
+import { AgentCard } from '../index.js';
 
 export interface AgentCardResolverOptions {
   path?: string;

src/client/card-resolver.ts

@@ -1,26 +1,19 @@
 import {
   AgentCard,
-  JSONRPCResponse,
-  MessageSendParams,
-  SendMessageResponse,
-  TaskQueryParams,
-  GetTaskResponse,
-  TaskIdParams,
-  CancelTaskResponse,
   TaskPushNotificationConfig, // Renamed from PushNotificationConfigParams for direct schema alignment
-  SetTaskPushNotificationConfigResponse,
-  GetTaskPushNotificationConfigResponse,
-  ListTaskPushNotificationConfigParams,
-  ListTaskPushNotificationConfigResponse,
-  DeleteTaskPushNotificationConfigResponse,
-  DeleteTaskPushNotificationConfigParams,
   Message,
   Task,
   TaskArtifactUpdateEvent,
   TaskStatusUpdateEvent,
-  A2ARequest,
-  JSONRPCErrorResponse,
-} from '../types.js'; // Assuming schema.ts is in the same directory or appropriately pathed
+  CancelTaskRequest,
+  CreateTaskPushNotificationConfigRequest,
+  DeleteTaskPushNotificationConfigRequest,
+  GetTaskPushNotificationConfigRequest,
+  GetTaskRequest,
+  ListTaskPushNotificationConfigRequest,
+  SendMessageRequest,
+  TaskSubscriptionRequest,
+} from '../index.js';
 import { AGENT_CARD_PATH } from '../constants.js';
 import { JsonRpcTransport } from './transports/json_rpc_transport.js';
 import { RequestOptions } from './multitransport-client.js';
@@ -152,11 +145,9 @@ export class A2AClient {
    * @param params The parameters for sending the message, including the message content and configuration.
    * @returns A Promise resolving to SendMessageResponse, which can be a Message, Task, or an error.
    */
-  public async sendMessage(params: MessageSendParams): Promise<SendMessageResponse> {
-    return await this.invokeJsonRpc<MessageSendParams, SendMessageResponse>(
-      (t, p, id) => t.sendMessage(p, A2AClient.emptyOptions, id),
-      params
-    );
+  public async sendMessage(params: SendMessageRequest): Promise<SendMessageResult> {
+    const transport = await this._getOrCreateTransport();
+    return transport.sendMessage(params, A2AClient.emptyOptions, this.requestIdCounter++);
   }
 
   /**
@@ -169,7 +160,7 @@ export class A2AClient {
    * The generator throws an error if streaming is not supported or if an HTTP/SSE error occurs.
    */
   public async *sendMessageStream(
-    params: MessageSendParams
+    params: SendMessageRequest
   ): AsyncGenerator<A2AStreamEventData, void, undefined> {
     const agentCard = await this.agentCardPromise; // Ensure agent card is fetched
     if (!agentCard.capabilities?.streaming) {
@@ -189,18 +180,24 @@ export class A2AClient {
    * @returns A Promise resolving to SetTaskPushNotificationConfigResponse.
    */
   public async setTaskPushNotificationConfig(
-    params: TaskPushNotificationConfig
-  ): Promise<SetTaskPushNotificationConfigResponse> {
+    params: CreateTaskPushNotificationConfigRequest
+  ): Promise<TaskPushNotificationConfig> {
     const agentCard = await this.agentCardPromise;
     if (!agentCard.capabilities?.pushNotifications) {
       throw new Error(
         'Agent does not support push notifications (AgentCard.capabilities.pushNotifications is not true).'
       );
     }
-    return await this.invokeJsonRpc<
-      TaskPushNotificationConfig,
-      SetTaskPushNotificationConfigResponse
-    >((t, p, id) => t.setTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
+    if (!params.config?.pushNotificationConfig) {
+      throw new Error('Push notification configuration is required.');
+    }
+
+    const transport = await this._getOrCreateTransport();
+    return transport.setTaskPushNotificationConfig(
+      params,
+      A2AClient.emptyOptions,
+      this.requestIdCounter++
+    );
   }
 
   /**
@@ -209,11 +206,13 @@ export class A2AClient {
    * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
    */
   public async getTaskPushNotificationConfig(
-    params: TaskIdParams
-  ): Promise<GetTaskPushNotificationConfigResponse> {
-    return await this.invokeJsonRpc<TaskIdParams, GetTaskPushNotificationConfigResponse>(
-      (t, p, id) => t.getTaskPushNotificationConfig(p, A2AClient.emptyOptions, id),
-      params
+    params: GetTaskPushNotificationConfigRequest
+  ): Promise<TaskPushNotificationConfig> {
+    const transport = await this._getOrCreateTransport();
+    return transport.getTaskPushNotificationConfig(
+      params,
+      A2AClient.emptyOptions,
+      this.requestIdCounter++
     );
   }
 
@@ -223,12 +222,14 @@ export class A2AClient {
    * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
    */
   public async listTaskPushNotificationConfig(
-    params: ListTaskPushNotificationConfigParams
-  ): Promise<ListTaskPushNotificationConfigResponse> {
-    return await this.invokeJsonRpc<
-      ListTaskPushNotificationConfigParams,
-      ListTaskPushNotificationConfigResponse
-    >((t, p, id) => t.listTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
+    params: ListTaskPushNotificationConfigRequest
+  ): Promise<TaskPushNotificationConfig[]> {
+    const transport = await this._getOrCreateTransport();
+    return transport.listTaskPushNotificationConfig(
+      params,
+      A2AClient.emptyOptions,
+      this.requestIdCounter++
+    );
   }
 
   /**
@@ -237,36 +238,34 @@ export class A2AClient {
    * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
    */
   public async deleteTaskPushNotificationConfig(
-    params: DeleteTaskPushNotificationConfigParams
-  ): Promise<DeleteTaskPushNotificationConfigResponse> {
-    return await this.invokeJsonRpc<
-      DeleteTaskPushNotificationConfigParams,
-      DeleteTaskPushNotificationConfigResponse
-    >((t, p, id) => t.deleteTaskPushNotificationConfig(p, A2AClient.emptyOptions, id), params);
+    params: DeleteTaskPushNotificationConfigRequest
+  ): Promise<void> {
+    const transport = await this._getOrCreateTransport();
+    return transport.deleteTaskPushNotificationConfig(
+      params,
+      A2AClient.emptyOptions,
+      this.requestIdCounter++
+    );
   }
 
   /**
    * Retrieves a task by its ID.
    * @param params Parameters containing the taskId and optional historyLength.
    * @returns A Promise resolving to GetTaskResponse, which contains the Task object or an error.
    */
-  public async getTask(params: TaskQueryParams): Promise<GetTaskResponse> {
-    return await this.invokeJsonRpc<TaskQueryParams, GetTaskResponse>(
-      (t, p, id) => t.getTask(p, A2AClient.emptyOptions, id),
-      params
-    );
+  public async getTask(params: GetTaskRequest): Promise<Task> {
+    const transport = await this._getOrCreateTransport();
+    return transport.getTask(params, A2AClient.emptyOptions, this.requestIdCounter++);
   }
 
   /**
    * Cancels a task by its ID.
    * @param params Parameters containing the taskId.
    * @returns A Promise resolving to CancelTaskResponse, which contains the updated Task object or an error.
    */
-  public async cancelTask(params: TaskIdParams): Promise<CancelTaskResponse> {
-    return await this.invokeJsonRpc<TaskIdParams, CancelTaskResponse>(
-      (t, p, id) => t.cancelTask(p, A2AClient.emptyOptions, id),
-      params
-    );
+  public async cancelTask(params: CancelTaskRequest): Promise<Task> {
+    const transport = await this._getOrCreateTransport();
+    return transport.cancelTask(params, A2AClient.emptyOptions, this.requestIdCounter++);
   }
 
   /**
@@ -277,26 +276,16 @@ export class A2AClient {
    * @param params Extension paramters defined in the AgentCard's extensions.
    * @returns A Promise that resolves to the RPC response.
    */
-  public async callExtensionMethod<TExtensionParams, TExtensionResponse extends JSONRPCResponse>(
+  public async callExtensionMethod<TExtensionParams, TExtensionResponse>(
     method: string,
     params: TExtensionParams
   ) {
     const transport = await this._getOrCreateTransport();
-    try {
-      return await transport.callExtensionMethod<TExtensionParams, TExtensionResponse>(
-        method,
-        params,
-        this.requestIdCounter++
-      );
-    } catch (e) {
-      // For compatibility, return JSON-RPC errors as errors instead of throwing transport-agnostic errors
-      // produced by JsonRpcTransport.
-      const errorResponse = extractJSONRPCError(e);
-      if (errorResponse) {
-        return errorResponse as TExtensionResponse;
-      }
-      throw e;
-    }
+    return await transport.callExtensionMethod<TExtensionParams, TExtensionResponse>(
+      method,
+      params,
+      this.requestIdCounter++
+    );
   }
 
   /**
@@ -307,7 +296,7 @@ export class A2AClient {
    * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
    */
   public async *resubscribeTask(
-    params: TaskIdParams
+    params: TaskSubscriptionRequest
   ): AsyncGenerator<A2AStreamEventData, void, undefined> {
     const agentCard = await this.agentCardPromise;
     if (!agentCard.capabilities?.streaming) {
@@ -434,54 +423,4 @@ export class A2AClient {
     }
     return this.serviceEndpointUrl;
   }
-
-  private async invokeJsonRpc<TParams extends JsonRpcParams, TResponse extends JSONRPCResponse>(
-    caller: JsonRpcCaller<TParams, TResponse>,
-    params?: TParams
-  ): Promise<TResponse> {
-    const transport = await this._getOrCreateTransport();
-    const requestId = this.requestIdCounter++;
-    try {
-      const result = await caller(transport, params, requestId);
-      return {
-        id: requestId,
-        jsonrpc: '2.0',
-        result: result ?? null, // JSON-RPC requires result property on success, it will be null for "void" methods.
-      } as TResponse;
-    } catch (e) {
-      // For compatibility, return JSON-RPC errors as response objects instead of throwing transport-agnostic errors
-      // produced by JsonRpcTransport.
-      const errorResponse = extractJSONRPCError(e);
-      if (errorResponse) {
-        return errorResponse as TResponse;
-      }
-      throw e;
-    }
-  }
 }
-
-function extractJSONRPCError(error: unknown): JSONRPCErrorResponse {
-  if (
-    error instanceof Object &&
-    'errorResponse' in error &&
-    error.errorResponse instanceof Object &&
-    'jsonrpc' in error.errorResponse &&
-    error.errorResponse.jsonrpc === '2.0' &&
-    'error' in error.errorResponse &&
-    error.errorResponse.error !== null
-  ) {
-    return error.errorResponse as JSONRPCErrorResponse;
-  } else {
-    return undefined;
-  }
-}
-
-// Utility unexported types to properly factor out common "compatibility" logic via invokeJsonRpc.
-type ParamsOf<T> = T extends { params: unknown } ? T['params'] : undefined;
-type ResultOf<T> = T extends { result: unknown } ? T['result'] : void;
-type JsonRpcParams = ParamsOf<A2ARequest>;
-type JsonRpcCaller<TParams extends JsonRpcParams, TResponse extends JSONRPCResponse> = (
-  transport: JsonRpcTransport,
-  params: TParams,
-  idOverride: number
-) => Promise<ResultOf<TResponse>>;

src/client/client.ts

@@ -1,5 +1,5 @@
 import { TransportProtocolName } from '../core.js';
-import { AgentCard } from '../types.js';
+import { AgentCard } from '../index.js';
 import { AgentCardResolver } from './card-resolver.js';
 import { Client, ClientConfig } from './multitransport-client.js';
 import { JsonRpcTransportFactory } from './transports/json_rpc_transport.js';

src/client/factory.ts

@@ -1,4 +1,4 @@
-import { AgentCard } from '../types.js';
+import { AgentCard } from '../index.js';
 import { A2AStreamEventData } from './client.js';
 import { Client } from './multitransport-client.js';
 import { RequestOptions } from './multitransport-client.js';