@artinet/sdk 0.6.0-preview.1 → 0.6.0-preview.2

package/dist/create/task-builder.js

@@ -0,0 +1,384 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { v4 as uuidv4 } from "uuid";
+import { getCurrentTimestamp } from "../utils/common/utils.js";
+import { isMessageParams, Message,
+// type BuilderMessageParams,
+ } from "./message-builder.js";
+export const isArtifactParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" && params !== null && "parts" in params));
+};
+export class Artifact {
+    _artifact;
+    constructor(artifact_params = {}) {
+        this._artifact = {
+            artifactId: uuidv4(),
+            parts: [],
+            ...artifact_params,
+        };
+    }
+    get artifact() {
+        return this._artifact;
+    }
+    static create(params = {}) {
+        return new Artifact(typeof params === "string"
+            ? { parts: [{ text: params, kind: "text" }] }
+            : params).artifact;
+    }
+}
+export const artifact = Artifact.create;
+export const isStatusParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" &&
+            params !== null &&
+            "state" in params &&
+            params.state in A2A.TaskState) ||
+        (typeof params === "object" &&
+            params !== null &&
+            "message" in params &&
+            isMessageParams(params.message)));
+};
+export class TaskStatus {
+    _status;
+    constructor(params = {}) {
+        const timestamp = params.timestamp ?? getCurrentTimestamp();
+        this._status = {
+            ...params,
+            state: params.state ?? A2A.TaskState.working,
+            timestamp,
+        };
+    }
+    get status() {
+        return this._status;
+    }
+    static create(params = {}) {
+        if (typeof params === "string" && params in A2A.TaskState) {
+            return new TaskStatus({ state: params }).status;
+        }
+        else if (isMessageParams(params)) {
+            return new TaskStatus({
+                state: A2A.TaskState.working,
+                message: Message.create(params),
+            }).status;
+        }
+        return new TaskStatus(params).status;
+    }
+}
+/**
+ * Convenience factory function for creating a task status with default parameters.
+ *
+ * @returns New {@link A2A.TaskStatus} with default parameters
+ * @defaults {
+ *   state: "working",
+ *   timestamp: getCurrentTimestamp(),
+ * }
+ *
+ * @example
+ * ```typescript
+ * const status = status("working");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const status = TaskStatus.create;
+export class Task {
+    _task;
+    constructor(params = {}) {
+        const id = params.id ?? uuidv4();
+        this._task = {
+            ...params,
+            id,
+            contextId: params.contextId ?? id,
+            kind: A2A.Kind.task,
+            status: TaskStatus.create(params.status),
+        };
+    }
+    get task() {
+        return this._task;
+    }
+    static create(params = {}) {
+        if (isStatusParams(params)) {
+            return new Task({ status: TaskStatus.create(params) }).task;
+        }
+        return new Task(params).task;
+    }
+}
+/**
+ * Convenience factory function for creating a task with default parameters.
+ *
+ * @returns New {@link A2A.Task} with default parameters
+ * @defaults:
+ * - `id`: uuidv4()
+ * - `contextId`: id
+ * - `status`: { state: "working" }
+ * @example
+ * ```typescript
+ * const task = task({ status: { state: "working" } });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const task = Task.create;
+export class TaskStatusUpdateEvent {
+    _event;
+    constructor(params) {
+        const taskId = params.taskId ?? params.status.message?.taskId ?? uuidv4();
+        const contextId = params.contextId ?? params.status.message?.contextId ?? taskId;
+        this._event = {
+            ...params,
+            taskId,
+            contextId,
+            kind: A2A.Kind["status-update"],
+            final: params.final ?? false,
+        };
+    }
+    get event() {
+        return this._event;
+    }
+    static create(params) {
+        if (isStatusParams(params)) {
+            return new TaskStatusUpdateEvent({
+                /*allows for a mixture of Update & Status Params*/
+                ...(typeof params === "object" ? params : {}),
+                status: TaskStatus.create(params),
+            }).event;
+        }
+        return new TaskStatusUpdateEvent(params).event;
+    }
+}
+export class TaskArtifactUpdateEvent {
+    _event;
+    constructor(params) {
+        const taskId = params.taskId ?? uuidv4();
+        this._event = {
+            ...params,
+            taskId,
+            contextId: params.contextId ?? taskId,
+            kind: A2A.Kind["artifact-update"],
+        };
+    }
+    get event() {
+        return this._event;
+    }
+    static create(params) {
+        if (isArtifactParams(params)) {
+            return new TaskArtifactUpdateEvent({
+                artifact: Artifact.create(params),
+            }).event;
+        }
+        return new TaskArtifactUpdateEvent({
+            ...params,
+            artifact: Artifact.create(params.artifact),
+        }).event;
+    }
+}
+const strict_update = (params) => {
+    return TaskStatusUpdateEvent.create(params);
+};
+function _buildUpdate(state, params, final) {
+    return strict_update({
+        taskId: params.taskId,
+        contextId: params.contextId,
+        status: {
+            state: state,
+            message: params.message,
+            timestamp: params.timestamp,
+        },
+        final: final ?? params.final,
+        metadata: params.metadata,
+    });
+}
+function _working(params) {
+    return _buildUpdate(A2A.TaskState.working, params);
+}
+function _canceled(params) {
+    return _buildUpdate(A2A.TaskState.canceled, params, true);
+}
+function _submitted(params) {
+    return _buildUpdate(A2A.TaskState.submitted, params);
+}
+function _failed(params) {
+    return _buildUpdate(A2A.TaskState.failed, params, true);
+}
+function _completed(params) {
+    return _buildUpdate(A2A.TaskState.completed, params, true);
+}
+function _inputRequired(params) {
+    return _buildUpdate(A2A.TaskState["input-required"], params);
+}
+function _rejected(params) {
+    return _buildUpdate(A2A.TaskState.rejected, params);
+}
+function _authRequired(params) {
+    return _buildUpdate(A2A.TaskState["auth-required"], params);
+}
+function _unknown(params) {
+    return _buildUpdate(A2A.TaskState["unknown"], params);
+}
+/**
+ * Convenience factory function for creating a task status and artifact update events with default parameters.
+ *
+ * @returns New {@link A2A.TaskStatusUpdateEvent} and {@link A2A.TaskArtifactUpdateEvent} with default parameters
+ *
+ * @example
+ * ```typescript
+ * const artifactEvent = update.artifact({
+ *   artifact: "result"
+ * });
+ * const statusEvent = update.status({
+ *   status: "working"
+ * });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const update = {
+    /**
+     * Convenience factory function for creating a task artifact update event.
+     * @returns New {@link A2A.TaskArtifactUpdateEvent}
+     * @example
+     * ```typescript
+     * const event = update.artifact({
+     *   artifact: "result"
+     * });
+     * ```
+     */
+    artifact: TaskArtifactUpdateEvent.create,
+    /**
+     * Convenience factory function for creating a task status update event.
+     * @returns New {@link A2A.TaskStatusUpdateEvent}
+     * @example
+     * ```typescript
+     * const event = update.status({
+     *   message: "Working on the task"
+     * });
+     * ```
+     */
+    status: TaskStatusUpdateEvent.create,
+    /**
+     * Convenience factory function for creating a task status update event with the working state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.working} state
+     * @example
+     * ```typescript
+     * const event = update.working({
+     *   message: "Working on the task"
+     * });
+     * ```
+     */
+    working: _working,
+    /**
+     * Convenience factory function for creating a task status update event with the canceled state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.canceled} state
+     * @example
+     * ```typescript
+     * const event = update.canceled({
+     *   message: "Task canceled"
+     * });
+     * ```
+     */
+    canceled: _canceled,
+    /**
+     * Convenience factory function for creating a task status update event with the submitted state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.submitted} state
+     * @example
+     * ```typescript
+     * const event = update.submitted({
+     *   message: "Task submitted"
+     * });
+     * ```
+     */
+    submitted: _submitted,
+    /**
+     * Convenience factory function for creating a task status update event with the failed state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.failed} state
+     * @example
+     * ```typescript
+     * const event = update.failed({
+     *   message: "Task failed"
+     * });
+     * ```
+     */
+    failed: _failed,
+    /**
+     * Convenience factory function for creating a task status update event with the completed state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.completed} state
+     * @example
+     * ```typescript
+     * const event = update.completed({
+     *   message: "Task completed"
+     * });
+     * ```
+     */
+    completed: _completed,
+    /**
+     * Convenience factory function for creating a task status update event with the input required state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState["input-required"]} state
+     * @example
+     * ```typescript
+     * const event = update.inputRequired({
+     *   message: "Task input required"
+     * });
+     * ```
+     */
+    inputRequired: _inputRequired,
+    /**
+     * Convenience factory function for creating a task status update event with the rejected state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.rejected} state
+     * @example
+     * ```typescript
+     * const event = update.rejected({
+     *   message: "Task rejected"
+     * });
+     * ```
+     */
+    rejected: _rejected,
+    /**
+     * Convenience factory function for creating a task status update event with the auth required state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState["auth-required"]} state
+     * @example
+     * ```typescript
+     * const event = update.authRequired({
+     *   message: {
+     *   role: "agent"
+     *   parts: [
+     *     {
+     *       text: "Task auth required"
+     *     }
+     *   ]
+     *   kind: "message"
+     * });
+     * ```
+     */
+    authRequired: _authRequired,
+    /**
+     * Convenience factory function for creating a task status update event with the unknown state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.unknown} state
+     * @example
+     * ```typescript
+     * const event = update.unknown({
+     *   message: "Task unknown"
+     * });
+     * ```
+     */
+    unknown: _unknown,
+};
+/**
+ * @description A temporary compatibility function for updating a task status, purely for migration purposes.
+ * @deprecated Use {@link update.status} instead
+ * @since 0.6.0
+ */
+export const update_compat = (taskId, contextId, state, message, timestamp, final = false) => {
+    return _buildUpdate(state, {
+        taskId: taskId,
+        contextId: contextId,
+        message: message,
+        timestamp: timestamp,
+    }, final);
+};

package/dist/create/transform.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import * as Builder from "./agent-builder.js";
+import { MessageParams } from "./message-builder.js";
+import { StatusUpdateParams, ArtifactUpdateParams, TaskParams } from "./task-builder.js";
+export declare function hasCarry<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>): ret is Builder.ReturnAndCarry<Ret, Carried>;
+export declare function hasReply<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>): ret is Builder.ReturnValue<Ret>;
+export declare function Parts(kind: "text" | "file" | "data"): Builder.Transform<Builder.AcceptedParts>;
+export declare function Message(): Builder.Transform<Builder.Stateless<MessageParams>>;
+export declare function Artifact(): Builder.Transform<Builder.Stateless<ArtifactUpdateParams>>;
+export declare function Status(): Builder.Transform<Builder.Stateless<StatusUpdateParams>>;
+export declare function Task(): Builder.Transform<Builder.Stateless<TaskParams>>;
+export declare function Reply<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>, context: A2A.Context, transform: Builder.Transform<Ret>): AsyncGenerator<A2A.Update, Carried | undefined, unknown>;

package/dist/create/transform.js

@@ -0,0 +1,106 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe } from "./index.js";
+import { TaskStatus, } from "./task-builder.js";
+export function hasCarry(ret) {
+    return (ret !== null && typeof ret === "object" && "reply" in ret && "args" in ret);
+}
+export function hasReply(ret) {
+    return ret !== null && typeof ret === "object" && "reply" in ret;
+}
+function messagePart(params) {
+    switch (params.kind) {
+        case "text": {
+            return describe.part.text(params.part);
+        }
+        case "file": {
+            return describe.part.file(params.part);
+        }
+        case "data": {
+            return describe.part.data(params.part);
+        }
+        default:
+            throw new Error("Invalid part detected", { cause: params });
+    }
+}
+export function Parts(kind) {
+    return async function* (payload, { taskId, contextId }) {
+        const parts = (Array.isArray(payload) ? payload : [payload]).map((part) => messagePart({ kind, part }));
+        yield describe.update.working({
+            taskId,
+            contextId,
+            message: describe.message({ role: "agent", parts }),
+        });
+        return;
+    };
+}
+export function Message() {
+    return async function* (payload, { taskId, contextId }) {
+        if (Array.isArray(payload)) {
+            throw new Error("Array of messages is not supported");
+        }
+        const message = typeof payload === "string" ? describe.message(payload) : payload;
+        yield describe.message({
+            ...message,
+            taskId,
+            contextId,
+        });
+        return;
+    };
+}
+export function Artifact() {
+    return async function* (payload, { taskId, contextId }) {
+        const updates = Array.isArray(payload) ? payload : [payload];
+        for (const update of updates) {
+            const artifact = typeof update === "string" ? describe.artifact(update) : update;
+            yield describe.update.artifact({
+                ...artifact,
+                taskId,
+                contextId,
+            });
+        }
+        return;
+    };
+}
+export function Status() {
+    return async function* (payload, { taskId, contextId }) {
+        const updates = Array.isArray(payload) ? payload : [payload];
+        for (const update of updates) {
+            const status = typeof update === "string" ? TaskStatus.create(update) : update;
+            yield describe.update.status({
+                ...status,
+                taskId,
+                contextId,
+            });
+        }
+        return;
+    };
+}
+export function Task() {
+    return async function* (payload, { taskId, contextId }) {
+        if (Array.isArray(payload)) {
+            throw new Error("Array of tasks is not supported");
+        }
+        const task = typeof payload === "string" ? describe.task(payload) : payload;
+        yield describe.task({ ...task, taskId, contextId });
+        return;
+    };
+}
+export async function* Reply(ret, context, transform) {
+    if (Array.isArray(ret)) {
+        yield* transform(ret, context);
+    }
+    else if (hasCarry(ret)) {
+        yield* transform(ret.reply, context);
+        return ret.args;
+    }
+    else if (hasReply(ret)) {
+        yield* transform(ret.reply, context);
+    }
+    else {
+        yield* transform(ret, context);
+    }
+    return;
+}

package/dist/index.d.ts

@@ -6,3 +6,5 @@ export * from "./transport/index.js";
 export * from "./utils/index.js";
 export * from "./config/index.js";
 export * from "./config/default.js";
+export * from "./create/create.js";
+export * from "./create/index.js";

package/dist/index.js

@@ -6,3 +6,5 @@ export * from "./transport/index.js";
 export * from "./utils/index.js";
 export * from "./config/index.js";
 export * from "./config/default.js";
+export * from "./create/create.js";
+export * from "./create/index.js";

package/dist/server/express/errors.js

@@ -2,9 +2,10 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { SystemError, INTERNAL_ERROR } from "../../utils/index.js";
+import { SystemError } from "../../utils/index.js";
 import { logger } from "../../config/index.js";
 import escapeHtml from "escape-html";
+import { A2AError } from "@a2a-js/sdk/server";
 /**
  * Express error handler middleware.
  */
@@ -24,16 +25,11 @@ export const errorHandler = (err, req, res, _) => {
         logger.error("errorHandler: Error extracting request ID", e);
     }
     let jsonRpcError;
-    if (err instanceof SystemError) {
+    if (err instanceof A2AError || err instanceof SystemError) {
         jsonRpcError = { code: err.code, message: err.message, data: err.data };
     }
     else {
-        const internalError = INTERNAL_ERROR(err.stack);
-        jsonRpcError = {
-            code: internalError.code,
-            message: internalError.message,
-            data: internalError.data,
-        };
+        jsonRpcError = A2AError.internalError(err.message, err.data).toJSONRPCError();
     }
     const errorResponse = {
         jsonrpc: "2.0",

package/dist/server/express/middeware.js

@@ -2,9 +2,9 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { A2A } from "../../types/index.js";
-import { PUSH_NOTIFICATION_NOT_SUPPORTED, INVALID_REQUEST, INVALID_PARAMS, METHOD_NOT_FOUND, AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED, } from "../../utils/index.js";
 import { logger } from "../../config/index.js";
+import { formatJson } from "../../utils/common/utils.js";
+import { A2AError } from "@a2a-js/sdk/server";
 const isValidMethod = (method) => {
     return (method &&
         method !== "" &&
@@ -14,41 +14,35 @@ const isValidMethod = (method) => {
 };
 const checkParams = (params, method) => {
     if (!params || (typeof params !== "object" && !Array.isArray(params))) {
-        throw INVALID_PARAMS({
-            data: {
-                message: "Invalid params",
-                method,
-            },
+        throw A2AError.invalidParams("Invalid Parameters", {
+            params,
+            method,
         });
     }
     else if (typeof params === "object" && Object.keys(params).length === 0) {
-        throw INVALID_PARAMS({
-            data: {
-                message: "No params provided",
-                method,
-            },
+        throw A2AError.invalidParams("Params Required", {
+            params,
+            method,
         });
     }
 };
 export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCard) {
     const { method, params, id, jsonrpc } = req.body;
     if (jsonrpc !== "2.0" ||
-        (id && typeof id !== "string" && typeof id !== "number" && id !== null)) {
+        (typeof id !== "string" &&
+            typeof id === "number" &&
+            !Number.isInteger(id) &&
+            id !== null)) {
         res.json({
             jsonrpc: "2.0",
             id: id || null,
-            error: { code: A2A.ErrorCodeInvalidRequest, message: "Invalid Request" },
+            error: A2AError.invalidRequest(`Invalid JSONRPC info: ${formatJson({ method, params, id, jsonrpc })}`).toJSONRPCError(),
         });
         return;
     }
     try {
         if (!isValidMethod(method)) {
-            throw INVALID_REQUEST({
-                data: {
-                    message: "No method provided",
-                    method,
-                },
-            });
+            throw A2AError.invalidRequest("No method provided");
         }
         let result;
         switch (method) {
@@ -101,34 +95,19 @@ export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCa
             case "tasks/pushNotificationConfig/get":
             case "tasks/pushNotificationConfig/delete":
             case "task/pushNotificationConfig/list": {
-                throw PUSH_NOTIFICATION_NOT_SUPPORTED({
-                    data: {
-                        message: "Push notifications not supported",
-                        method,
-                    },
-                });
+                throw A2AError.pushNotificationNotSupported();
             }
             case "agent/getAuthenticatedExtendedCard": {
                 if (!extendedAgentCard ||
                     (await service.getAgentCard()).supportsAuthenticatedExtendedCard !==
                         true) {
-                    throw AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED({
-                        data: {
-                            message: "Authenticated Extended Card is not configured",
-                            method,
-                        },
-                    });
+                    throw A2AError.authenticatedExtendedCardNotConfigured();
                 }
                 result = extendedAgentCard;
                 break;
             }
             default:
-                throw METHOD_NOT_FOUND({
-                    data: {
-                        message: "Method not found",
-                        method,
-                    },
-                });
+                throw A2AError.methodNotFound(method);
         }
         res.json({ jsonrpc: "2.0", id, result });
     }

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

@@ -11,14 +11,19 @@ export interface ServerParams {
     app?: express.Express;
     corsOptions?: CorsOptions;
     basePath?: string;
+    port?: number;
+    /**
+     * Your agentCard must have supportsAuthenticatedExtendedCard set to true
+     */
     extendedAgentCard?: A2A.AgentCard;
     agent: Agent | CreateAgentParams;
     agentCardPath?: string;
     register?: boolean;
 }
 export declare function rpcParser(req: express.Request, res: express.Response, next: express.NextFunction): void;
-export declare function createAgentServer({ app, basePath, agentCardPath, agent, corsOptions, extendedAgentCard, }: ServerParams): {
+export declare function createAgentServer({ app, basePath, agentCardPath, agent, corsOptions, extendedAgentCard, register, port, }: ServerParams): {
     app: express.Express;
     agent: Agent;
+    start: (_port?: number) => import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
 };
 export type ExpressAgentServer = ReturnType<typeof createAgentServer>;