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

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/extensions/otel.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview OpenTelemetry integration for Artinet SDK.
  *
  * Lightweight utilities for integrating user-configured OpenTelemetry

package/dist/extensions/otel.js

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview OpenTelemetry integration for Artinet SDK.
  *
  * Lightweight utilities for integrating user-configured OpenTelemetry

package/dist/extensions/pino.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview Pino logger adapter for Artinet SDK.
  *
  * Lightweight wrapper that adapts a user-configured Pino instance

package/dist/extensions/pino.js

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview Pino logger adapter for Artinet SDK.
  *
  * Lightweight wrapper that adapts a user-configured Pino instance

package/dist/extensions/winston.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview Winston logger adapter for Artinet SDK.
  *
  * Lightweight wrapper that adapts a user-configured Winston instance

package/dist/extensions/winston.js

@@ -1,4 +1,7 @@
 /**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ *
  * @fileoverview Winston logger adapter for Artinet SDK.
  *
  * Lightweight wrapper that adapts a user-configured Winston instance

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",