@artinet/sdk
Version:
A TypeScript SDK for building collaborative AI agents.
380 lines (379 loc) • 11.4 kB
JavaScript
/**
* 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/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 {
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 {
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 {
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 {
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 {
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);
};