@mailmodo/a2a 0.3.3 → 0.3.5

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

@@ -0,0 +1,25 @@
+import { Request, Express, RequestHandler, ErrorRequestHandler } from 'express';
+import { U as User, a as UnauthenticatedUser, A as A2ARequestHandler } from '../../a2a_request_handler-DPkhsCMt.mjs';
+import '../../types-Due_Cv6t.mjs';
+
+type UserBuilder = (req: Request) => Promise<User>;
+declare const UserBuilder: {
+    NoAuthentication: () => Promise<UnauthenticatedUser>;
+};
+
+declare class A2AExpressApp {
+    private requestHandler;
+    private userBuilder;
+    constructor(requestHandler: A2ARequestHandler, userBuilder?: UserBuilder);
+    /**
+     * Adds A2A routes to an existing Express app.
+     * @param app Optional existing Express app.
+     * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
+     * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
+     * @returns The Express app with A2A routes.
+     */
+    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;
+}
+
+export { A2AExpressApp, UserBuilder };

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

@@ -0,0 +1,25 @@
+import { Request, Express, RequestHandler, ErrorRequestHandler } from 'express';
+import { U as User, a as UnauthenticatedUser, A as A2ARequestHandler } from '../../a2a_request_handler-DQfg1Q-R.js';
+import '../../types-Due_Cv6t.js';
+
+type UserBuilder = (req: Request) => Promise<User>;
+declare const UserBuilder: {
+    NoAuthentication: () => Promise<UnauthenticatedUser>;
+};
+
+declare class A2AExpressApp {
+    private requestHandler;
+    private userBuilder;
+    constructor(requestHandler: A2ARequestHandler, userBuilder?: UserBuilder);
+    /**
+     * Adds A2A routes to an existing Express app.
+     * @param app Optional existing Express app.
+     * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
+     * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
+     * @returns The Express app with A2A routes.
+     */
+    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;
+}
+
+export { A2AExpressApp, UserBuilder };

package/dist/server/express/index.js

@@ -0,0 +1,468 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/express/index.ts
+var express_exports = {};
+__export(express_exports, {
+  A2AExpressApp: () => A2AExpressApp,
+  UserBuilder: () => UserBuilder
+});
+module.exports = __toCommonJS(express_exports);
+
+// src/server/express/a2a_express_app.ts
+var import_express3 = __toESM(require("express"));
+
+// src/constants.ts
+var AGENT_CARD_PATH = ".well-known/agent-card.json";
+var HTTP_EXTENSION_HEADER = "X-A2A-Extensions";
+
+// src/server/express/json_rpc_handler.ts
+var import_express = __toESM(require("express"));
+
+// src/server/error.ts
+var A2AError = class _A2AError extends Error {
+  code;
+  data;
+  taskId;
+  // Optional task ID context
+  constructor(code, message, data, taskId) {
+    super(message);
+    this.name = "A2AError";
+    this.code = code;
+    this.data = data;
+    this.taskId = taskId;
+  }
+  /**
+   * Formats the error into a standard JSON-RPC error object structure.
+   */
+  toJSONRPCError() {
+    const errorObject = {
+      code: this.code,
+      message: this.message
+    };
+    if (this.data !== void 0) {
+      errorObject.data = this.data;
+    }
+    return errorObject;
+  }
+  // Static factory methods for common errors
+  static parseError(message, data) {
+    return new _A2AError(-32700, message, data);
+  }
+  static invalidRequest(message, data) {
+    return new _A2AError(-32600, message, data);
+  }
+  static methodNotFound(method) {
+    return new _A2AError(-32601, `Method not found: ${method}`);
+  }
+  static invalidParams(message, data) {
+    return new _A2AError(-32602, message, data);
+  }
+  static internalError(message, data) {
+    return new _A2AError(-32603, message, data);
+  }
+  static taskNotFound(taskId) {
+    return new _A2AError(-32001, `Task not found: ${taskId}`, void 0, taskId);
+  }
+  static taskNotCancelable(taskId) {
+    return new _A2AError(-32002, `Task not cancelable: ${taskId}`, void 0, taskId);
+  }
+  static pushNotificationNotSupported() {
+    return new _A2AError(-32003, "Push Notification is not supported");
+  }
+  static unsupportedOperation(operation) {
+    return new _A2AError(-32004, `Unsupported operation: ${operation}`);
+  }
+  static authenticatedExtendedCardNotConfigured() {
+    return new _A2AError(-32007, `Extended card not configured.`);
+  }
+};
+
+// src/server/transports/jsonrpc_transport_handler.ts
+var JsonRpcTransportHandler = class {
+  requestHandler;
+  constructor(requestHandler) {
+    this.requestHandler = requestHandler;
+  }
+  /**
+   * Handles an incoming JSON-RPC request.
+   * For streaming methods, it returns an AsyncGenerator of JSONRPCResult.
+   * For non-streaming methods, it returns a Promise of a single JSONRPCMessage (Result or ErrorResponse).
+   */
+  async handle(requestBody, context) {
+    let rpcRequest;
+    try {
+      if (typeof requestBody === "string") {
+        rpcRequest = JSON.parse(requestBody);
+      } else if (typeof requestBody === "object" && requestBody !== null) {
+        rpcRequest = requestBody;
+      } else {
+        throw A2AError.parseError("Invalid request body type.");
+      }
+      if (!this.isRequestValid(rpcRequest)) {
+        throw A2AError.invalidRequest("Invalid JSON-RPC Request.");
+      }
+    } catch (error) {
+      const a2aError = error instanceof A2AError ? error : A2AError.parseError(
+        error instanceof SyntaxError && error.message || "Failed to parse JSON request."
+      );
+      return {
+        jsonrpc: "2.0",
+        id: rpcRequest?.id !== void 0 ? rpcRequest.id : null,
+        error: a2aError.toJSONRPCError()
+      };
+    }
+    const { method, id: requestId = null } = rpcRequest;
+    try {
+      if (method !== "agent/getAuthenticatedExtendedCard" && !this.paramsAreValid(rpcRequest.params)) {
+        throw A2AError.invalidParams(`Invalid method parameters.`);
+      }
+      if (method === "message/stream" || method === "tasks/resubscribe") {
+        const params = rpcRequest.params;
+        const agentCard = await this.requestHandler.getAgentCard();
+        if (!agentCard.capabilities.streaming) {
+          throw A2AError.unsupportedOperation(`Method ${method} requires streaming capability.`);
+        }
+        const agentEventStream = method === "message/stream" ? this.requestHandler.sendMessageStream(params, context) : this.requestHandler.resubscribe(params, context);
+        return (async function* jsonRpcEventStream() {
+          try {
+            for await (const event of agentEventStream) {
+              yield {
+                jsonrpc: "2.0",
+                id: requestId,
+                // Use the original request ID for all streamed responses
+                result: event
+              };
+            }
+          } catch (streamError) {
+            console.error(
+              `Error in agent event stream for ${method} (request ${requestId}):`,
+              streamError
+            );
+            throw streamError;
+          }
+        })();
+      } else {
+        let result;
+        switch (method) {
+          case "message/send":
+            result = await this.requestHandler.sendMessage(rpcRequest.params, context);
+            break;
+          case "tasks/get":
+            result = await this.requestHandler.getTask(rpcRequest.params, context);
+            break;
+          case "tasks/cancel":
+            result = await this.requestHandler.cancelTask(rpcRequest.params, context);
+            break;
+          case "tasks/pushNotificationConfig/set":
+            result = await this.requestHandler.setTaskPushNotificationConfig(
+              rpcRequest.params,
+              context
+            );
+            break;
+          case "tasks/pushNotificationConfig/get":
+            result = await this.requestHandler.getTaskPushNotificationConfig(
+              rpcRequest.params,
+              context
+            );
+            break;
+          case "tasks/pushNotificationConfig/delete":
+            await this.requestHandler.deleteTaskPushNotificationConfig(rpcRequest.params, context);
+            result = null;
+            break;
+          case "tasks/pushNotificationConfig/list":
+            result = await this.requestHandler.listTaskPushNotificationConfigs(
+              rpcRequest.params,
+              context
+            );
+            break;
+          case "agent/getAuthenticatedExtendedCard":
+            result = await this.requestHandler.getAuthenticatedExtendedAgentCard(context);
+            break;
+          default:
+            throw A2AError.methodNotFound(method);
+        }
+        return {
+          jsonrpc: "2.0",
+          id: requestId,
+          result
+        };
+      }
+    } catch (error) {
+      let a2aError;
+      if (error instanceof A2AError) {
+        a2aError = error;
+      } else {
+        a2aError = A2AError.internalError(
+          error instanceof Error && error.message || "An unexpected error occurred."
+        );
+      }
+      return {
+        jsonrpc: "2.0",
+        id: requestId,
+        error: a2aError.toJSONRPCError()
+      };
+    }
+  }
+  // Validates the basic structure of a JSON-RPC request
+  isRequestValid(rpcRequest) {
+    if (rpcRequest.jsonrpc !== "2.0") {
+      return false;
+    }
+    if ("id" in rpcRequest) {
+      const id = rpcRequest.id;
+      const isString = typeof id === "string";
+      const isInteger = typeof id === "number" && Number.isInteger(id);
+      const isNull = id === null;
+      if (!isString && !isInteger && !isNull) {
+        return false;
+      }
+    }
+    if (!rpcRequest.method || typeof rpcRequest.method !== "string") {
+      return false;
+    }
+    return true;
+  }
+  // Validates that params is an object with non-empty string keys
+  paramsAreValid(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+      return false;
+    }
+    for (const key of Object.keys(params)) {
+      if (key === "") {
+        return false;
+      }
+    }
+    return true;
+  }
+};
+
+// src/server/context.ts
+var ServerCallContext = class {
+  _requestedExtensions;
+  _user;
+  _activatedExtensions;
+  constructor(requestedExtensions, user) {
+    this._requestedExtensions = requestedExtensions;
+    this._user = user;
+  }
+  get user() {
+    return this._user;
+  }
+  get activatedExtensions() {
+    return this._activatedExtensions;
+  }
+  get requestedExtensions() {
+    return this._requestedExtensions;
+  }
+  addActivatedExtension(uri) {
+    if (this._requestedExtensions?.has(uri)) {
+      if (!this._activatedExtensions) {
+        this._activatedExtensions = /* @__PURE__ */ new Set();
+      }
+      this._activatedExtensions.add(uri);
+    }
+  }
+};
+
+// src/server/utils.ts
+function getRequestedExtensions(values) {
+  if (!values) {
+    return /* @__PURE__ */ new Set();
+  }
+  return new Set(
+    values.split(",").map((ext) => ext.trim()).filter((ext) => ext.length > 0)
+  );
+}
+
+// src/server/authentication/user.ts
+var UnauthenticatedUser = class {
+  get isAuthenticated() {
+    return false;
+  }
+  get userName() {
+    return "";
+  }
+};
+
+// src/server/express/json_rpc_handler.ts
+function jsonRpcHandler(options) {
+  const jsonRpcTransportHandler = new JsonRpcTransportHandler(options.requestHandler);
+  const router = import_express.default.Router();
+  router.use(import_express.default.json(), jsonErrorHandler);
+  router.post("/", async (req, res) => {
+    try {
+      const user = await options.userBuilder(req);
+      const context = new ServerCallContext(
+        getRequestedExtensions(req.header(HTTP_EXTENSION_HEADER)),
+        user ?? new UnauthenticatedUser()
+      );
+      const rpcResponseOrStream = await jsonRpcTransportHandler.handle(req.body, context);
+      if (context.activatedExtensions) {
+        res.setHeader(HTTP_EXTENSION_HEADER, Array.from(context.activatedExtensions));
+      }
+      if (typeof rpcResponseOrStream?.[Symbol.asyncIterator] === "function") {
+        const stream = rpcResponseOrStream;
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+        res.flushHeaders();
+        try {
+          for await (const event of stream) {
+            res.write(`id: ${(/* @__PURE__ */ new Date()).getTime()}
+`);
+            res.write(`data: ${JSON.stringify(event)}
+
+`);
+          }
+        } catch (streamError) {
+          console.error(`Error during SSE streaming (request ${req.body?.id}):`, streamError);
+          let a2aError;
+          if (streamError instanceof A2AError) {
+            a2aError = streamError;
+          } else {
+            a2aError = A2AError.internalError(
+              streamError instanceof Error && streamError.message || "Streaming error."
+            );
+          }
+          const errorResponse = {
+            jsonrpc: "2.0",
+            id: req.body?.id || null,
+            // Use original request ID if available
+            error: a2aError.toJSONRPCError()
+          };
+          if (!res.headersSent) {
+            res.status(500).json(errorResponse);
+          } else {
+            res.write(`id: ${(/* @__PURE__ */ new Date()).getTime()}
+`);
+            res.write(`event: error
+`);
+            res.write(`data: ${JSON.stringify(errorResponse)}
+
+`);
+          }
+        } finally {
+          if (!res.writableEnded) {
+            res.end();
+          }
+        }
+      } else {
+        const rpcResponse = rpcResponseOrStream;
+        res.status(200).json(rpcResponse);
+      }
+    } catch (error) {
+      console.error("Unhandled error in JSON-RPC POST handler:", error);
+      const a2aError = error instanceof A2AError ? error : A2AError.internalError("General processing error.");
+      const errorResponse = {
+        jsonrpc: "2.0",
+        id: req.body?.id || null,
+        error: a2aError.toJSONRPCError()
+      };
+      if (!res.headersSent) {
+        res.status(500).json(errorResponse);
+      } else if (!res.writableEnded) {
+        res.end();
+      }
+    }
+  });
+  return router;
+}
+var jsonErrorHandler = (err, _req, res, next) => {
+  if (err instanceof SyntaxError && "body" in err) {
+    const a2aError = A2AError.parseError("Invalid JSON payload.");
+    const errorResponse = {
+      jsonrpc: "2.0",
+      id: null,
+      error: a2aError.toJSONRPCError()
+    };
+    return res.status(400).json(errorResponse);
+  }
+  next(err);
+};
+
+// src/server/express/agent_card_handler.ts
+var import_express2 = __toESM(require("express"));
+function agentCardHandler(options) {
+  const router = import_express2.default.Router();
+  const provider = typeof options.agentCardProvider === "function" ? options.agentCardProvider : options.agentCardProvider.getAgentCard.bind(options.agentCardProvider);
+  router.get("/", async (_req, res) => {
+    try {
+      const agentCard = await provider();
+      res.json(agentCard);
+    } catch (error) {
+      console.error("Error fetching agent card:", error);
+      res.status(500).json({ error: "Failed to retrieve agent card" });
+    }
+  });
+  return router;
+}
+
+// src/server/express/common.ts
+var UserBuilder = {
+  NoAuthentication: () => Promise.resolve(new UnauthenticatedUser())
+};
+
+// src/server/express/a2a_express_app.ts
+var A2AExpressApp = class {
+  requestHandler;
+  userBuilder;
+  constructor(requestHandler, userBuilder = UserBuilder.NoAuthentication) {
+    this.requestHandler = requestHandler;
+    this.userBuilder = userBuilder;
+  }
+  /**
+   * Adds A2A routes to an existing Express app.
+   * @param app Optional existing Express app.
+   * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
+   * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
+   * @returns The Express app with A2A routes.
+   */
+  setupRoutes(app, baseUrl = "", middlewares, agentCardPath = AGENT_CARD_PATH) {
+    const router = import_express3.default.Router();
+    router.use(import_express3.default.json(), jsonErrorHandler);
+    if (middlewares && middlewares.length > 0) {
+      router.use(middlewares);
+    }
+    router.use(
+      jsonRpcHandler({
+        requestHandler: this.requestHandler,
+        userBuilder: this.userBuilder
+      })
+    );
+    router.use(`/${agentCardPath}`, agentCardHandler({ agentCardProvider: this.requestHandler }));
+    app.use(baseUrl, router);
+    return app;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2AExpressApp,
+  UserBuilder
+});

package/dist/server/express/index.mjs

@@ -0,0 +1,10 @@
+import {
+  A2AExpressApp,
+  UserBuilder
+} from "../../chunk-HZFUOBJQ.mjs";
+import "../../chunk-PHP7LM4Y.mjs";
+import "../../chunk-LVD4GF26.mjs";
+export {
+  A2AExpressApp,
+  UserBuilder
+};

package/dist/server/index.d.mts

@@ -0,0 +1,26 @@
+import { P as PushNotificationSender, a as PushNotificationStore } from '../error-DExKs0Q3.mjs';
+export { i as A2AError, b as AgentExecutionEvent, A as AgentExecutor, D as DefaultExecutionEventBus, d as DefaultExecutionEventBusManager, f as DefaultRequestHandler, E as ExecutionEventBus, c as ExecutionEventBusManager, e as ExecutionEventQueue, g as ExtendedAgentCardProvider, j as InMemoryPushNotificationStore, I as InMemoryTaskStore, J as JsonRpcTransportHandler, R as RequestContext, h as ResultManager, T as TaskStore } from '../error-DExKs0Q3.mjs';
+export { A as A2ARequestHandler, S as ServerCallContext, a as UnauthenticatedUser, U as User } from '../a2a_request_handler-DPkhsCMt.mjs';
+import { T as Task } from '../types-Due_Cv6t.mjs';
+import 'events';
+
+interface DefaultPushNotificationSenderOptions {
+    /**
+     * Timeout in milliseconds for the abort controller. Defaults to 5000ms.
+     */
+    timeout?: number;
+    /**
+     * Custom header name for the token. Defaults to 'X-A2A-Notification-Token'.
+     */
+    tokenHeaderName?: string;
+}
+declare class DefaultPushNotificationSender implements PushNotificationSender {
+    private readonly pushNotificationStore;
+    private notificationChain;
+    private readonly options;
+    constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
+    send(task: Task): Promise<void>;
+    private _dispatchNotification;
+}
+
+export { DefaultPushNotificationSender, type DefaultPushNotificationSenderOptions, PushNotificationSender, PushNotificationStore };

package/dist/server/index.d.ts

@@ -0,0 +1,26 @@
+import { P as PushNotificationSender, a as PushNotificationStore } from '../error-j1vYKII2.js';
+export { i as A2AError, b as AgentExecutionEvent, A as AgentExecutor, D as DefaultExecutionEventBus, d as DefaultExecutionEventBusManager, f as DefaultRequestHandler, E as ExecutionEventBus, c as ExecutionEventBusManager, e as ExecutionEventQueue, g as ExtendedAgentCardProvider, j as InMemoryPushNotificationStore, I as InMemoryTaskStore, J as JsonRpcTransportHandler, R as RequestContext, h as ResultManager, T as TaskStore } from '../error-j1vYKII2.js';
+export { A as A2ARequestHandler, S as ServerCallContext, a as UnauthenticatedUser, U as User } from '../a2a_request_handler-DQfg1Q-R.js';
+import { T as Task } from '../types-Due_Cv6t.js';
+import 'events';
+
+interface DefaultPushNotificationSenderOptions {
+    /**
+     * Timeout in milliseconds for the abort controller. Defaults to 5000ms.
+     */
+    timeout?: number;
+    /**
+     * Custom header name for the token. Defaults to 'X-A2A-Notification-Token'.
+     */
+    tokenHeaderName?: string;
+}
+declare class DefaultPushNotificationSender implements PushNotificationSender {
+    private readonly pushNotificationStore;
+    private notificationChain;
+    private readonly options;
+    constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
+    send(task: Task): Promise<void>;
+    private _dispatchNotification;
+}
+
+export { DefaultPushNotificationSender, type DefaultPushNotificationSenderOptions, PushNotificationSender, PushNotificationStore };