@mailmodo/a2a 0.3.5 → 0.3.7

package/dist/client/index.mjs

@@ -1,13 +1,700 @@
 import {
-  A2AClient,
-  JsonRpcTransport,
-  JsonRpcTransportFactory,
+  A2A_ERROR_CODE,
+  AuthenticatedExtendedCardNotConfiguredError,
+  ContentTypeNotSupportedError,
+  InvalidAgentResponseError,
   PushNotificationNotSupportedError,
-  createAuthenticatingFetchWithRetry
-} from "../chunk-UBRSFN2J.mjs";
+  TaskNotCancelableError,
+  TaskNotFoundError,
+  UnsupportedOperationError,
+  parseSseStream
+} from "../chunk-BNBEZNW7.mjs";
 import {
-  AGENT_CARD_PATH
+  AGENT_CARD_PATH,
+  HTTP_EXTENSION_HEADER
 } from "../chunk-PHP7LM4Y.mjs";
+import {
+  Extensions
+} from "../chunk-7JFJW6P6.mjs";
+
+// src/client/transports/json_rpc_transport.ts
+var JsonRpcTransport = class _JsonRpcTransport {
+  customFetchImpl;
+  endpoint;
+  requestIdCounter = 1;
+  constructor(options) {
+    this.endpoint = options.endpoint;
+    this.customFetchImpl = options.fetchImpl;
+  }
+  async getExtendedAgentCard(options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest("agent/getAuthenticatedExtendedCard", void 0, idOverride, options);
+    return rpcResponse.result;
+  }
+  async sendMessage(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest(
+      "message/send",
+      params,
+      idOverride,
+      options
+    );
+    return rpcResponse.result;
+  }
+  async *sendMessageStream(params, options) {
+    yield* this._sendStreamingRequest("message/stream", params, options);
+  }
+  async setTaskPushNotificationConfig(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest("tasks/pushNotificationConfig/set", params, idOverride, options);
+    return rpcResponse.result;
+  }
+  async getTaskPushNotificationConfig(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest("tasks/pushNotificationConfig/get", params, idOverride, options);
+    return rpcResponse.result;
+  }
+  async listTaskPushNotificationConfig(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest("tasks/pushNotificationConfig/list", params, idOverride, options);
+    return rpcResponse.result;
+  }
+  async deleteTaskPushNotificationConfig(params, options, idOverride) {
+    await this._sendRpcRequest("tasks/pushNotificationConfig/delete", params, idOverride, options);
+  }
+  async getTask(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest(
+      "tasks/get",
+      params,
+      idOverride,
+      options
+    );
+    return rpcResponse.result;
+  }
+  async cancelTask(params, options, idOverride) {
+    const rpcResponse = await this._sendRpcRequest(
+      "tasks/cancel",
+      params,
+      idOverride,
+      options
+    );
+    return rpcResponse.result;
+  }
+  async *resubscribeTask(params, options) {
+    yield* this._sendStreamingRequest("tasks/resubscribe", params, options);
+  }
+  async callExtensionMethod(method, params, idOverride, options) {
+    return await this._sendRpcRequest(
+      method,
+      params,
+      idOverride,
+      options
+    );
+  }
+  _fetch(...args) {
+    if (this.customFetchImpl) {
+      return this.customFetchImpl(...args);
+    }
+    if (typeof fetch === "function") {
+      return fetch(...args);
+    }
+    throw new Error(
+      "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the A2ATransportOptions. "
+    );
+  }
+  async _sendRpcRequest(method, params, idOverride, options) {
+    const requestId = idOverride ?? this.requestIdCounter++;
+    const rpcRequest = {
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: requestId
+    };
+    const httpResponse = await this._fetchRpc(rpcRequest, "application/json", options);
+    if (!httpResponse.ok) {
+      let errorBodyText = "(empty or non-JSON response)";
+      let errorJson;
+      try {
+        errorBodyText = await httpResponse.text();
+        errorJson = JSON.parse(errorBodyText);
+      } catch (e) {
+        throw new Error(
+          `HTTP error for ${method}! Status: ${httpResponse.status} ${httpResponse.statusText}. Response: ${errorBodyText}`,
+          { cause: e }
+        );
+      }
+      if (errorJson.jsonrpc && errorJson.error) {
+        throw _JsonRpcTransport.mapToError(errorJson);
+      } else {
+        throw new Error(
+          `HTTP error for ${method}! Status: ${httpResponse.status} ${httpResponse.statusText}. Response: ${errorBodyText}`
+        );
+      }
+    }
+    const rpcResponse = await httpResponse.json();
+    if (rpcResponse.id !== requestId) {
+      console.error(
+        `CRITICAL: RPC response ID mismatch for method ${method}. Expected ${requestId}, got ${rpcResponse.id}.`
+      );
+    }
+    if ("error" in rpcResponse) {
+      throw _JsonRpcTransport.mapToError(rpcResponse);
+    }
+    return rpcResponse;
+  }
+  async _fetchRpc(rpcRequest, acceptHeader = "application/json", options) {
+    const requestInit = {
+      method: "POST",
+      headers: {
+        ...options?.serviceParameters,
+        "Content-Type": "application/json",
+        Accept: acceptHeader
+      },
+      body: JSON.stringify(rpcRequest),
+      signal: options?.signal
+    };
+    return this._fetch(this.endpoint, requestInit);
+  }
+  async *_sendStreamingRequest(method, params, options) {
+    const clientRequestId = this.requestIdCounter++;
+    const rpcRequest = {
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: clientRequestId
+    };
+    const response = await this._fetchRpc(rpcRequest, "text/event-stream", options);
+    if (!response.ok) {
+      let errorBody = "";
+      let errorJson;
+      try {
+        errorBody = await response.text();
+        errorJson = JSON.parse(errorBody);
+      } catch (e) {
+        throw new Error(
+          `HTTP error establishing stream for ${method}: ${response.status} ${response.statusText}. Response: ${errorBody || "(empty)"}`,
+          { cause: e }
+        );
+      }
+      if (errorJson.error) {
+        throw new Error(
+          `HTTP error establishing stream for ${method}: ${response.status} ${response.statusText}. RPC Error: ${errorJson.error.message} (Code: ${errorJson.error.code})`
+        );
+      }
+      throw new Error(
+        `HTTP error establishing stream for ${method}: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.headers.get("Content-Type")?.startsWith("text/event-stream")) {
+      throw new Error(
+        `Invalid response Content-Type for SSE stream for ${method}. Expected 'text/event-stream'.`
+      );
+    }
+    for await (const event of parseSseStream(response)) {
+      yield this._processSseEventData(event.data, clientRequestId);
+    }
+  }
+  _processSseEventData(jsonData, originalRequestId) {
+    if (!jsonData.trim()) {
+      throw new Error("Attempted to process empty SSE event data.");
+    }
+    try {
+      const sseJsonRpcResponse = JSON.parse(jsonData);
+      const a2aStreamResponse = sseJsonRpcResponse;
+      if (a2aStreamResponse.id !== originalRequestId) {
+        console.warn(
+          `SSE Event's JSON-RPC response ID mismatch. Client request ID: ${originalRequestId}, event response ID: ${a2aStreamResponse.id}.`
+        );
+      }
+      if ("error" in a2aStreamResponse) {
+        const err = a2aStreamResponse.error;
+        throw new Error(
+          `SSE event contained an error: ${err.message} (Code: ${err.code}) Data: ${JSON.stringify(err.data || {})}`
+        );
+      }
+      if (!("result" in a2aStreamResponse) || typeof a2aStreamResponse.result === "undefined") {
+        throw new Error(`SSE event JSON-RPC response is missing 'result' field. Data: ${jsonData}`);
+      }
+      return a2aStreamResponse.result;
+    } catch (e) {
+      if (e instanceof Error && (e.message.startsWith("SSE event contained an error") || e.message.startsWith("SSE event JSON-RPC response is missing 'result' field"))) {
+        throw e;
+      }
+      console.error(
+        "Failed to parse SSE event data string or unexpected JSON-RPC structure:",
+        jsonData,
+        e
+      );
+      throw new Error(
+        `Failed to parse SSE event data: "${jsonData.substring(0, 100)}...". Original error: ${e instanceof Error && e.message || "Unknown error"}`
+      );
+    }
+  }
+  static mapToError(response) {
+    switch (response.error.code) {
+      case -32001:
+        return new TaskNotFoundJSONRPCError(response);
+      case -32002:
+        return new TaskNotCancelableJSONRPCError(response);
+      case -32003:
+        return new PushNotificationNotSupportedJSONRPCError(response);
+      case -32004:
+        return new UnsupportedOperationJSONRPCError(response);
+      case -32005:
+        return new ContentTypeNotSupportedJSONRPCError(response);
+      case -32006:
+        return new InvalidAgentResponseJSONRPCError(response);
+      case -32007:
+        return new AuthenticatedExtendedCardNotConfiguredJSONRPCError(response);
+      default:
+        return new JSONRPCTransportError(response);
+    }
+  }
+};
+var JsonRpcTransportFactory = class _JsonRpcTransportFactory {
+  constructor(options) {
+    this.options = options;
+  }
+  static name = "JSONRPC";
+  get protocolName() {
+    return _JsonRpcTransportFactory.name;
+  }
+  async create(url, _agentCard) {
+    return new JsonRpcTransport({
+      endpoint: url,
+      fetchImpl: this.options?.fetchImpl
+    });
+  }
+};
+var JSONRPCTransportError = class extends Error {
+  constructor(errorResponse) {
+    super(
+      `JSON-RPC error: ${errorResponse.error.message} (Code: ${errorResponse.error.code}) Data: ${JSON.stringify(errorResponse.error.data || {})}`
+    );
+    this.errorResponse = errorResponse;
+  }
+};
+var TaskNotFoundJSONRPCError = class extends TaskNotFoundError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var TaskNotCancelableJSONRPCError = class extends TaskNotCancelableError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var PushNotificationNotSupportedJSONRPCError = class extends PushNotificationNotSupportedError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var UnsupportedOperationJSONRPCError = class extends UnsupportedOperationError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var ContentTypeNotSupportedJSONRPCError = class extends ContentTypeNotSupportedError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var InvalidAgentResponseJSONRPCError = class extends InvalidAgentResponseError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+var AuthenticatedExtendedCardNotConfiguredJSONRPCError = class extends AuthenticatedExtendedCardNotConfiguredError {
+  constructor(errorResponse) {
+    super();
+    this.errorResponse = errorResponse;
+  }
+};
+
+// src/client/client.ts
+var A2AClient = class _A2AClient {
+  static emptyOptions = void 0;
+  agentCardPromise;
+  customFetchImpl;
+  serviceEndpointUrl;
+  // To be populated from AgentCard after fetchin
+  // A2AClient is built around JSON-RPC types, so it will only support JSON-RPC transport, new client with transport agnostic interface is going to be created for multi-transport.
+  // New transport abstraction isn't going to expose individual transport specific fields, so to keep returning JSON-RPC IDs here for compatibility,
+  // keep counter here and pass it to JsonRpcTransport via an optional idOverride parameter (which is not visible via transport-agnostic A2ATransport interface).
+  transport;
+  requestIdCounter = 1;
+  /**
+   * Constructs an A2AClient instance from an AgentCard.
+   * @param agentCard The AgentCard object.
+   * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
+   */
+  constructor(agentCard, options) {
+    this.customFetchImpl = options?.fetchImpl;
+    if (typeof agentCard === "string") {
+      console.warn(
+        "Warning: Constructing A2AClient with a URL is deprecated. Please use A2AClient.fromCardUrl() instead."
+      );
+      this.agentCardPromise = this._fetchAndCacheAgentCard(agentCard, options?.agentCardPath);
+    } else {
+      if (!agentCard.url) {
+        throw new Error(
+          "Provided Agent Card does not contain a valid 'url' for the service endpoint."
+        );
+      }
+      this.serviceEndpointUrl = agentCard.url;
+      this.agentCardPromise = Promise.resolve(agentCard);
+    }
+  }
+  /**
+   * Dynamically resolves the fetch implementation to use for requests.
+   * Prefers a custom implementation if provided, otherwise falls back to the global fetch.
+   * @returns The fetch implementation.
+   * @param args Arguments to pass to the fetch implementation.
+   * @throws If no fetch implementation is available.
+   */
+  _fetch(...args) {
+    if (this.customFetchImpl) {
+      return this.customFetchImpl(...args);
+    }
+    if (typeof fetch === "function") {
+      return fetch(...args);
+    }
+    throw new Error(
+      "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the A2AClientOptions. For earlier Node.js versions (pre-v18), you can use a library like `node-fetch`."
+    );
+  }
+  /**
+   * Creates an A2AClient instance by fetching the AgentCard from a URL then constructing the A2AClient.
+   * @param agentCardUrl The URL of the agent card.
+   * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
+   * @returns A Promise that resolves to a new A2AClient instance.
+   */
+  static async fromCardUrl(agentCardUrl, options) {
+    const fetchImpl = options?.fetchImpl;
+    const requestInit = {
+      headers: { Accept: "application/json" }
+    };
+    let response;
+    if (fetchImpl) {
+      response = await fetchImpl(agentCardUrl, requestInit);
+    } else if (typeof fetch === "function") {
+      response = await fetch(agentCardUrl, requestInit);
+    } else {
+      throw new Error(
+        "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the A2AClientOptions. For earlier Node.js versions (pre-v18), you can use a library like `node-fetch`."
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`
+      );
+    }
+    let agentCard;
+    try {
+      agentCard = await response.json();
+    } catch (error) {
+      console.error("Failed to parse Agent Card JSON:", error);
+      throw new Error(
+        `Failed to parse Agent Card JSON from ${agentCardUrl}. Original error: ${error.message}`
+      );
+    }
+    return new _A2AClient(agentCard, options);
+  }
+  /**
+   * Sends a message to the agent.
+   * The behavior (blocking/non-blocking) and push notification configuration
+   * are specified within the `params.configuration` object.
+   * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
+   * @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.
+   */
+  async sendMessage(params) {
+    return await this.invokeJsonRpc(
+      (t, p, id) => t.sendMessage(p, _A2AClient.emptyOptions, id),
+      params
+    );
+  }
+  /**
+   * Sends a message to the agent and streams back responses using Server-Sent Events (SSE).
+   * Push notification configuration can be specified in `params.configuration`.
+   * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
+   * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
+   * @param params The parameters for sending the message.
+   * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
+   * The generator throws an error if streaming is not supported or if an HTTP/SSE error occurs.
+   */
+  async *sendMessageStream(params) {
+    const agentCard = await this.agentCardPromise;
+    if (!agentCard.capabilities?.streaming) {
+      throw new Error(
+        "Agent does not support streaming (AgentCard.capabilities.streaming is not true)."
+      );
+    }
+    const transport = await this._getOrCreateTransport();
+    yield* transport.sendMessageStream(params);
+  }
+  /**
+   * Sets or updates the push notification configuration for a given task.
+   * Requires the agent to support push notifications (`capabilities.pushNotifications: true` in AgentCard).
+   * @param params Parameters containing the taskId and the TaskPushNotificationConfig.
+   * @returns A Promise resolving to SetTaskPushNotificationConfigResponse.
+   */
+  async setTaskPushNotificationConfig(params) {
+    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((t, p, id) => t.setTaskPushNotificationConfig(p, _A2AClient.emptyOptions, id), params);
+  }
+  /**
+   * Gets the push notification configuration for a given task.
+   * @param params Parameters containing the taskId.
+   * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
+   */
+  async getTaskPushNotificationConfig(params) {
+    return await this.invokeJsonRpc(
+      (t, p, id) => t.getTaskPushNotificationConfig(p, _A2AClient.emptyOptions, id),
+      params
+    );
+  }
+  /**
+   * Lists the push notification configurations for a given task.
+   * @param params Parameters containing the taskId.
+   * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
+   */
+  async listTaskPushNotificationConfig(params) {
+    return await this.invokeJsonRpc((t, p, id) => t.listTaskPushNotificationConfig(p, _A2AClient.emptyOptions, id), params);
+  }
+  /**
+   * Deletes the push notification configuration for a given task.
+   * @param params Parameters containing the taskId and push notification configuration ID.
+   * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
+   */
+  async deleteTaskPushNotificationConfig(params) {
+    return await this.invokeJsonRpc((t, p, id) => t.deleteTaskPushNotificationConfig(p, _A2AClient.emptyOptions, id), params);
+  }
+  /**
+   * 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.
+   */
+  async getTask(params) {
+    return await this.invokeJsonRpc(
+      (t, p, id) => t.getTask(p, _A2AClient.emptyOptions, id),
+      params
+    );
+  }
+  /**
+   * 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.
+   */
+  async cancelTask(params) {
+    return await this.invokeJsonRpc(
+      (t, p, id) => t.cancelTask(p, _A2AClient.emptyOptions, id),
+      params
+    );
+  }
+  /**
+   * @template TExtensionParams The type of parameters for the custom extension method.
+   * @template TExtensionResponse The type of response expected from the custom extension method.
+   * This should extend JSONRPCResponse. This ensures the extension response is still a valid A2A response.
+   * @param method Custom JSON-RPC method defined in the AgentCard's extensions.
+   * @param params Extension paramters defined in the AgentCard's extensions.
+   * @returns A Promise that resolves to the RPC response.
+   */
+  async callExtensionMethod(method, params) {
+    const transport = await this._getOrCreateTransport();
+    try {
+      return await transport.callExtensionMethod(
+        method,
+        params,
+        this.requestIdCounter++
+      );
+    } catch (e) {
+      const errorResponse = extractJSONRPCError(e);
+      if (errorResponse) {
+        return errorResponse;
+      }
+      throw e;
+    }
+  }
+  /**
+   * Resubscribes to a task's event stream using Server-Sent Events (SSE).
+   * This is used if a previous SSE connection for an active task was broken.
+   * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
+   * @param params Parameters containing the taskId.
+   * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
+   */
+  async *resubscribeTask(params) {
+    const agentCard = await this.agentCardPromise;
+    if (!agentCard.capabilities?.streaming) {
+      throw new Error("Agent does not support streaming (required for tasks/resubscribe).");
+    }
+    const transport = await this._getOrCreateTransport();
+    yield* transport.resubscribeTask(params);
+  }
+  ////////////////////////////////////////////////////////////////////////////////
+  // Functions used to support old A2AClient Constructor to be deprecated soon
+  // TODOs:
+  // * remove `agentCardPromise`, and just use agentCard initialized
+  // * _getServiceEndpoint can be made synchronous or deleted and accessed via
+  //   agentCard.url
+  // * getAgentCard changed to this.agentCard
+  // * delete resolveAgentCardUrl(), _fetchAndCacheAgentCard(),
+  //   agentCardPath from A2AClientOptions
+  // * delete _getOrCreateTransport
+  ////////////////////////////////////////////////////////////////////////////////
+  async _getOrCreateTransport() {
+    if (this.transport) {
+      return this.transport;
+    }
+    const endpoint = await this._getServiceEndpoint();
+    this.transport = new JsonRpcTransport({ fetchImpl: this.customFetchImpl, endpoint });
+    return this.transport;
+  }
+  /**
+   * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
+   * This method is called by the constructor.
+   * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
+   * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
+   * @returns A Promise that resolves to the AgentCard.
+   */
+  async _fetchAndCacheAgentCard(agentBaseUrl, agentCardPath) {
+    try {
+      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
+      const response = await this._fetch(agentCardUrl, {
+        headers: { Accept: "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`
+        );
+      }
+      const agentCard = await response.json();
+      if (!agentCard.url) {
+        throw new Error(
+          "Fetched Agent Card does not contain a valid 'url' for the service endpoint."
+        );
+      }
+      this.serviceEndpointUrl = agentCard.url;
+      return agentCard;
+    } catch (error) {
+      console.error("Error fetching or parsing Agent Card:", error);
+      throw error;
+    }
+  }
+  /**
+   * 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.
+   */
+  async getAgentCard(agentBaseUrl, agentCardPath) {
+    if (agentBaseUrl) {
+      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
+      const response = await this._fetch(agentCardUrl, {
+        headers: { Accept: "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`
+        );
+      }
+      return await response.json();
+    }
+    return this.agentCardPromise;
+  }
+  /**
+   * Determines the agent card URL based on the agent URL.
+   * @param agentBaseUrl The agent URL.
+   * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
+   */
+  resolveAgentCardUrl(agentBaseUrl, agentCardPath = AGENT_CARD_PATH) {
+    return `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
+  }
+  /**
+   * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
+   * @returns A Promise that resolves to the service endpoint URL string.
+   */
+  async _getServiceEndpoint() {
+    if (this.serviceEndpointUrl) {
+      return this.serviceEndpointUrl;
+    }
+    await this.agentCardPromise;
+    if (!this.serviceEndpointUrl) {
+      throw new Error(
+        "Agent Card URL for RPC endpoint is not available. Fetching might have failed."
+      );
+    }
+    return this.serviceEndpointUrl;
+  }
+  async invokeJsonRpc(caller, params) {
+    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.
+      };
+    } catch (e) {
+      const errorResponse = extractJSONRPCError(e);
+      if (errorResponse) {
+        return errorResponse;
+      }
+      throw e;
+    }
+  }
+};
+function extractJSONRPCError(error) {
+  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;
+  } else {
+    return void 0;
+  }
+}
+
+// src/client/auth-handler.ts
+function createAuthenticatingFetchWithRetry(fetchImpl, authHandler) {
+  async function authFetch(url, init) {
+    const authHeaders = await authHandler.headers() || {};
+    const mergedInit = {
+      ...init || {},
+      headers: {
+        ...authHeaders,
+        ...init?.headers || {}
+      }
+    };
+    let response = await fetchImpl(url, mergedInit);
+    const updatedHeaders = await authHandler.shouldRetryWithHeaders(mergedInit, response);
+    if (updatedHeaders) {
+      const retryInit = {
+        ...init || {},
+        headers: {
+          ...updatedHeaders,
+          ...init?.headers || {}
+        }
+      };
+      response = await fetchImpl(url, retryInit);
+      if (response.ok && authHandler.onSuccessfulRetry) {
+        await authHandler.onSuccessfulRetry(updatedHeaders);
+      }
+    }
+    return response;
+  }
+  Object.setPrototypeOf(authFetch, Object.getPrototypeOf(fetchImpl));
+  Object.defineProperties(authFetch, Object.getOwnPropertyDescriptors(fetchImpl));
+  return authFetch;
+}
 
 // src/client/card-resolver.ts
 var DefaultAgentCardResolver = class {
@@ -37,7 +724,7 @@ var DefaultAgentCardResolver = class {
   }
 };
 var AgentCardResolver = {
-  Default: new DefaultAgentCardResolver()
+  default: new DefaultAgentCardResolver()
 };
 
 // src/client/multitransport-client.ts
@@ -47,6 +734,20 @@ var Client = class {
     this.agentCard = agentCard;
     this.config = config;
   }
+  /**
+   * 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.
+   */
+  async getAgentCard(options) {
+    if (this.agentCard.supportsAuthenticatedExtendedCard) {
+      this.agentCard = await this.executeWithInterceptors(
+        { method: "getAgentCard" },
+        options,
+        (_, options2) => this.transport.getExtendedAgentCard(options2)
+      );
+    }
+    return this.agentCard;
+  }
   /**
    * Sends a message to an agent to initiate a new interaction or to continue an existing one.
    * Uses blocking mode by default.
@@ -71,6 +772,7 @@ var Client = class {
     params = this.applyClientConfig({ params, blocking: true });
     const beforeArgs = {
       input: { method, value: params },
+      agentCard: this.agentCard,
       options
     };
     const beforeResult = await this.interceptBefore(beforeArgs);
@@ -78,6 +780,7 @@ var Client = class {
       const earlyReturn = beforeResult.earlyReturn.value;
       const afterArgs = {
         result: { method, value: earlyReturn },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs, beforeResult.executed);
@@ -88,6 +791,7 @@ var Client = class {
       const result = await this.transport.sendMessage(beforeArgs.input.value, beforeArgs.options);
       const afterArgs = {
         result: { method, value: result },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs);
@@ -100,6 +804,7 @@ var Client = class {
     )) {
       const afterArgs = {
         result: { method, value: event },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs);
@@ -187,12 +892,17 @@ var Client = class {
    */
   async *resubscribeTask(params, options) {
     const method = "resubscribeTask";
-    const beforeArgs = { input: { method, value: params }, options };
+    const beforeArgs = {
+      input: { method, value: params },
+      agentCard: this.agentCard,
+      options
+    };
     const beforeResult = await this.interceptBefore(beforeArgs);
     if (beforeResult) {
       const earlyReturn = beforeResult.earlyReturn.value;
       const afterArgs = {
         result: { method, value: earlyReturn },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs, beforeResult.executed);
@@ -205,6 +915,7 @@ var Client = class {
     )) {
       const afterArgs = {
         result: { method, value: event },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs);
@@ -231,6 +942,7 @@ var Client = class {
   async executeWithInterceptors(input, options, transportCall) {
     const beforeArgs = {
       input,
+      agentCard: this.agentCard,
       options
     };
     const beforeResult = await this.interceptBefore(beforeArgs);
@@ -240,6 +952,7 @@ var Client = class {
           method: input.method,
           value: beforeResult.earlyReturn.value
         },
+        agentCard: this.agentCard,
         options: beforeArgs.options
       };
       await this.interceptAfter(afterArgs2, beforeResult.executed);
@@ -248,6 +961,7 @@ var Client = class {
     const result = await transportCall(beforeArgs.input.value, beforeArgs.options);
     const afterArgs = {
       result: { method: input.method, value: result },
+      agentCard: this.agentCard,
       options: beforeArgs.options
     };
     await this.interceptAfter(afterArgs);
@@ -270,10 +984,8 @@ var Client = class {
     }
   }
   async interceptAfter(args, interceptors) {
-    if (!this.config?.interceptors || this.config.interceptors.length === 0) {
-      return;
-    }
-    for (const interceptor of interceptors ?? this.config.interceptors) {
+    const reversedInterceptors = [...interceptors ?? this.config?.interceptors ?? []].reverse();
+    for (const interceptor of reversedInterceptors) {
       await interceptor.after(args);
       if (args.earlyReturn) {
         return;
@@ -282,35 +994,283 @@ var Client = class {
   }
 };
 
+// src/client/transports/rest_transport.ts
+var RestTransport = class _RestTransport {
+  customFetchImpl;
+  endpoint;
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/+$/, "");
+    this.customFetchImpl = options.fetchImpl;
+  }
+  async getExtendedAgentCard(options) {
+    return this._sendRequest("GET", "/v1/card", void 0, options);
+  }
+  async sendMessage(params, options) {
+    return this._sendRequest("POST", "/v1/message:send", params, options);
+  }
+  async *sendMessageStream(params, options) {
+    yield* this._sendStreamingRequest("/v1/message:stream", params, options);
+  }
+  async setTaskPushNotificationConfig(params, options) {
+    return this._sendRequest(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(params.taskId)}/pushNotificationConfigs`,
+      {
+        pushNotificationConfig: params.pushNotificationConfig
+      },
+      options
+    );
+  }
+  async getTaskPushNotificationConfig(params, options) {
+    const { pushNotificationConfigId } = params;
+    if (!pushNotificationConfigId) {
+      throw new Error(
+        "pushNotificationConfigId is required for getTaskPushNotificationConfig with REST transport."
+      );
+    }
+    return this._sendRequest(
+      "GET",
+      `/v1/tasks/${encodeURIComponent(params.id)}/pushNotificationConfigs/${encodeURIComponent(pushNotificationConfigId)}`,
+      void 0,
+      options
+    );
+  }
+  async listTaskPushNotificationConfig(params, options) {
+    return this._sendRequest(
+      "GET",
+      `/v1/tasks/${encodeURIComponent(params.id)}/pushNotificationConfigs`,
+      void 0,
+      options
+    );
+  }
+  async deleteTaskPushNotificationConfig(params, options) {
+    await this._sendRequest(
+      "DELETE",
+      `/v1/tasks/${encodeURIComponent(params.id)}/pushNotificationConfigs/${encodeURIComponent(params.pushNotificationConfigId)}`,
+      void 0,
+      options
+    );
+  }
+  async getTask(params, options) {
+    const queryParams = new URLSearchParams();
+    if (params.historyLength !== void 0) {
+      queryParams.set("historyLength", String(params.historyLength));
+    }
+    const queryString = queryParams.toString();
+    const path = `/v1/tasks/${encodeURIComponent(params.id)}${queryString ? `?${queryString}` : ""}`;
+    return this._sendRequest("GET", path, void 0, options);
+  }
+  async cancelTask(params, options) {
+    return this._sendRequest(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(params.id)}:cancel`,
+      void 0,
+      options
+    );
+  }
+  async *resubscribeTask(params, options) {
+    yield* this._sendStreamingRequest(
+      `/v1/tasks/${encodeURIComponent(params.id)}:subscribe`,
+      void 0,
+      options
+    );
+  }
+  _fetch(...args) {
+    if (this.customFetchImpl) {
+      return this.customFetchImpl(...args);
+    }
+    if (typeof fetch === "function") {
+      return fetch(...args);
+    }
+    throw new Error(
+      "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the RestTransportOptions."
+    );
+  }
+  _buildHeaders(options, acceptHeader = "application/json") {
+    return {
+      ...options?.serviceParameters,
+      "Content-Type": "application/json",
+      Accept: acceptHeader
+    };
+  }
+  async _sendRequest(method, path, body, options) {
+    const url = `${this.endpoint}${path}`;
+    const requestInit = {
+      method,
+      headers: this._buildHeaders(options),
+      signal: options?.signal
+    };
+    if (body !== void 0 && method !== "GET") {
+      requestInit.body = JSON.stringify(body);
+    }
+    const response = await this._fetch(url, requestInit);
+    if (!response.ok) {
+      await this._handleErrorResponse(response, path);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const result = await response.json();
+    return result;
+  }
+  async _handleErrorResponse(response, path) {
+    let errorBodyText = "(empty or non-JSON response)";
+    let errorBody;
+    try {
+      errorBodyText = await response.text();
+      if (errorBodyText) {
+        errorBody = JSON.parse(errorBodyText);
+      }
+    } catch (e) {
+      throw new Error(
+        `HTTP error for ${path}! Status: ${response.status} ${response.statusText}. Response: ${errorBodyText}`,
+        { cause: e }
+      );
+    }
+    if (errorBody && typeof errorBody.code === "number") {
+      throw _RestTransport.mapToError(errorBody);
+    }
+    throw new Error(
+      `HTTP error for ${path}! Status: ${response.status} ${response.statusText}. Response: ${errorBodyText}`
+    );
+  }
+  async *_sendStreamingRequest(path, body, options) {
+    const url = `${this.endpoint}${path}`;
+    const requestInit = {
+      method: "POST",
+      headers: this._buildHeaders(options, "text/event-stream"),
+      signal: options?.signal
+    };
+    if (body !== void 0) {
+      requestInit.body = JSON.stringify(body);
+    }
+    const response = await this._fetch(url, requestInit);
+    if (!response.ok) {
+      await this._handleErrorResponse(response, path);
+    }
+    const contentType = response.headers.get("Content-Type");
+    if (!contentType?.startsWith("text/event-stream")) {
+      throw new Error(
+        `Invalid response Content-Type for SSE stream. Expected 'text/event-stream', got '${contentType}'.`
+      );
+    }
+    for await (const event of parseSseStream(response)) {
+      if (event.type === "error") {
+        const errorData = JSON.parse(event.data);
+        throw _RestTransport.mapToError(errorData);
+      }
+      yield this._processSseEventData(event.data);
+    }
+  }
+  _processSseEventData(jsonData) {
+    if (!jsonData.trim()) {
+      throw new Error("Attempted to process empty SSE event data.");
+    }
+    try {
+      const data = JSON.parse(jsonData);
+      return data;
+    } catch (e) {
+      console.error("Failed to parse SSE event data:", jsonData, e);
+      throw new Error(
+        `Failed to parse SSE event data: "${jsonData.substring(0, 100)}...". Original error: ${e instanceof Error && e.message || "Unknown error"}`
+      );
+    }
+  }
+  static mapToError(error) {
+    switch (error.code) {
+      case A2A_ERROR_CODE.TASK_NOT_FOUND:
+        return new TaskNotFoundError(error.message);
+      case A2A_ERROR_CODE.TASK_NOT_CANCELABLE:
+        return new TaskNotCancelableError(error.message);
+      case A2A_ERROR_CODE.PUSH_NOTIFICATION_NOT_SUPPORTED:
+        return new PushNotificationNotSupportedError(error.message);
+      case A2A_ERROR_CODE.UNSUPPORTED_OPERATION:
+        return new UnsupportedOperationError(error.message);
+      case A2A_ERROR_CODE.CONTENT_TYPE_NOT_SUPPORTED:
+        return new ContentTypeNotSupportedError(error.message);
+      case A2A_ERROR_CODE.INVALID_AGENT_RESPONSE:
+        return new InvalidAgentResponseError(error.message);
+      case A2A_ERROR_CODE.AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED:
+        return new AuthenticatedExtendedCardNotConfiguredError(error.message);
+      default:
+        return new Error(
+          `REST error: ${error.message} (Code: ${error.code})${error.data ? ` Data: ${JSON.stringify(error.data)}` : ""}`
+        );
+    }
+  }
+};
+var RestTransportFactory = class _RestTransportFactory {
+  constructor(options) {
+    this.options = options;
+  }
+  static name = "HTTP+JSON";
+  get protocolName() {
+    return _RestTransportFactory.name;
+  }
+  async create(url, _agentCard) {
+    return new RestTransport({
+      endpoint: url,
+      fetchImpl: this.options?.fetchImpl
+    });
+  }
+};
+
 // src/client/factory.ts
 var ClientFactoryOptions = {
-  Default: {
-    transports: [new JsonRpcTransportFactory()]
+  /**
+   * SDK default options for {@link ClientFactory}.
+   */
+  default: {
+    transports: [new JsonRpcTransportFactory(), new RestTransportFactory()]
+  },
+  /**
+   * 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, overrides) {
+    return {
+      ...original,
+      ...overrides,
+      transports: mergeTransports(original.transports, overrides.transports),
+      clientConfig: {
+        ...original.clientConfig ?? {},
+        ...overrides.clientConfig ?? {},
+        interceptors: mergeArrays(
+          original.clientConfig?.interceptors,
+          overrides.clientConfig?.interceptors
+        ),
+        acceptedOutputModes: overrides.clientConfig?.acceptedOutputModes ?? original.clientConfig?.acceptedOutputModes
+      },
+      preferredTransports: overrides.preferredTransports ?? original.preferredTransports
+    };
   }
 };
 var ClientFactory = class {
-  constructor(options = ClientFactoryOptions.Default) {
+  constructor(options = ClientFactoryOptions.default) {
     this.options = options;
     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);
-    }
+    this.transportsByName = transportsByName(options.transports);
     for (const transport of options.preferredTransports ?? []) {
-      const factory = this.options.transports.find((t) => t.protocolName === transport);
-      if (!factory) {
+      if (!this.transportsByName.has(transport)) {
         throw new Error(
           `Unknown preferred transport: ${transport}, available transports: ${[...this.transportsByName.keys()].join()}`
         );
       }
     }
-    this.agentCardResolver = options.cardResolver ?? AgentCardResolver.Default;
+    this.agentCardResolver = options.cardResolver ?? AgentCardResolver.default;
   }
-  transportsByName = /* @__PURE__ */ new Map();
+  transportsByName;
   agentCardResolver;
   /**
    * Creates a new client from the provided agent card.
@@ -318,7 +1278,7 @@ var ClientFactory = class {
   async createFromAgentCard(agentCard) {
     const agentCardPreferred = agentCard.preferredTransport ?? JsonRpcTransportFactory.name;
     const additionalInterfaces = agentCard.additionalInterfaces ?? [];
-    const urlsPerAgentTransports = new Map([
+    const urlsPerAgentTransports = new CaseInsensitiveMap([
       [agentCardPreferred, agentCard.url],
       ...additionalInterfaces.map((i) => [i.transport, i.url])
     ]);
@@ -348,20 +1308,141 @@ var ClientFactory = class {
   /**
    * 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
+   * ```
    */
-  async createFromAgentCardUrl(baseUrl, path) {
+  async createFromUrl(baseUrl, path) {
     const agentCard = await this.agentCardResolver.resolve(baseUrl, path);
-    return await this.createFromAgentCard(agentCard);
+    return this.createFromAgentCard(agentCard);
+  }
+};
+function mergeTransports(original, overrides) {
+  if (!overrides) {
+    return original;
+  }
+  const result = transportsByName(original);
+  const overridesByName = transportsByName(overrides);
+  for (const [name, factory] of overridesByName) {
+    result.set(name, factory);
+  }
+  return Array.from(result.values());
+}
+function transportsByName(transports) {
+  const result = new CaseInsensitiveMap();
+  if (!transports) {
+    return result;
+  }
+  for (const t of transports) {
+    if (result.has(t.protocolName)) {
+      throw new Error(`Duplicate protocol name: ${t.protocolName}`);
+    }
+    result.set(t.protocolName, t);
+  }
+  return result;
+}
+function mergeArrays(a1, a2) {
+  if (!a1 && !a2) {
+    return void 0;
+  }
+  return [...a1 ?? [], ...a2 ?? []];
+}
+var CaseInsensitiveMap = class extends Map {
+  normalizeKey(key) {
+    return key.toUpperCase();
+  }
+  set(key, value) {
+    return super.set(this.normalizeKey(key), value);
+  }
+  get(key) {
+    return super.get(this.normalizeKey(key));
+  }
+  has(key) {
+    return super.has(this.normalizeKey(key));
+  }
+  delete(key) {
+    return super.delete(this.normalizeKey(key));
+  }
+};
+
+// src/client/service-parameters.ts
+var ServiceParameters = {
+  create(...updates) {
+    return ServiceParameters.createFrom(void 0, ...updates);
+  },
+  createFrom: (serviceParameters, ...updates) => {
+    const result = serviceParameters ? { ...serviceParameters } : {};
+    for (const update of updates) {
+      update(result);
+    }
+    return result;
+  }
+};
+function withA2AExtensions(...extensions) {
+  return (parameters) => {
+    parameters[HTTP_EXTENSION_HEADER] = Extensions.toServiceParameter(extensions);
+  };
+}
+
+// src/client/context.ts
+var ClientCallContext = {
+  /**
+   * Create a new {@link ClientCallContext} with optional updates applied.
+   */
+  create: (...updates) => {
+    return ClientCallContext.createFrom(void 0, ...updates);
+  },
+  /**
+   * Create a new {@link ClientCallContext} based on an existing one with updates applied.
+   */
+  createFrom: (context, ...updates) => {
+    const result = context ? { ...context } : {};
+    for (const update of updates) {
+      update(result);
+    }
+    return result;
+  }
+};
+var ClientCallContextKey = class {
+  symbol;
+  constructor(description) {
+    this.symbol = Symbol(description);
+  }
+  set(value) {
+    return (context) => {
+      context[this.symbol] = value;
+    };
+  }
+  get(context) {
+    return context[this.symbol];
   }
 };
 export {
   A2AClient,
   AgentCardResolver,
+  AuthenticatedExtendedCardNotConfiguredError,
   Client,
+  ClientCallContext,
+  ClientCallContextKey,
   ClientFactory,
   ClientFactoryOptions,
+  ContentTypeNotSupportedError,
   DefaultAgentCardResolver,
+  InvalidAgentResponseError,
   JsonRpcTransport,
   JsonRpcTransportFactory,
-  createAuthenticatingFetchWithRetry
+  PushNotificationNotSupportedError,
+  RestTransport,
+  RestTransportFactory,
+  ServiceParameters,
+  TaskNotCancelableError,
+  TaskNotFoundError,
+  UnsupportedOperationError,
+  createAuthenticatingFetchWithRetry,
+  withA2AExtensions
 };