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

package/README.md

@@ -55,7 +55,7 @@ npm install @artinet/sdk
 **Peer dependencies (required):**
 
 ```bash
-npm install @a2a-js/sdk @modelcontextprotocol/sdk
+npm install @a2a-js/sdk @modelcontextprotocol/sdk @trpc/server
 ```
 
 ## Requirements
@@ -67,22 +67,13 @@ npm install @a2a-js/sdk @modelcontextprotocol/sdk
 **Server:**
 
 ```typescript
-import { createAgentServer, AgentBuilder } from "@artinet/sdk";
-
-const { app } = createAgentServer({
-  agent: AgentBuilder()
-    .text(async ({ content }) => {
-      return `You said: ${content}`;
-    })
-    .createAgent({
-      agentCard: "QuickStart Agent",
-    }),
-  basePath: "/a2a",
-});
-
-app.listen(3000, () => {
-  console.log("A2A Server running at http://localhost:3000/a2a");
-});
+import { cr8 } from "@artinet/sdk";
+
+const { app } = cr8("QuickStart Agent")
+  .text(async ({ content }) => {
+    return `You said: ${content}`;
+  }) //start an a2a server on port 3000
+  .server.start(3000);
 ```
 
 **Client:**

package/dist/browser/client/a2a-client.js

@@ -6,7 +6,7 @@ import { executeJsonRpcRequest, executeGetRequest, } from "../transport/rpc/rpc-
 import { executeStreamEvents } from "../transport/streaming/event-stream.js";
 import { INTERNAL_ERROR } from "../utils/common/errors.js";
 import { logger } from "../config/index.js";
-import { createMessageSendParams } from "../services/a2a/helpers/message-builder.js";
+import * as describe from "../create/describe.js";
 /**
  * A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
  * It provides methods for sending tasks, retrieving statuses, canceling operations, and handling streaming responses.
@@ -104,10 +104,10 @@ export class A2AClient {
      */
     async sendMessage(params) {
         return await executeJsonRpcRequest(this.agentUrl, "message/send", typeof params === "string"
-            ? createMessageSendParams(params)
+            ? describe.messageSendParams(params)
             : typeof params === "object" && "message" in params
                 ? params
-                : createMessageSendParams({ message: params }), this.customHeaders);
+                : describe.messageSendParams({ message: params }), this.customHeaders);
     }
     /**
      * @deprecated Use sendMessage instead.
@@ -124,7 +124,7 @@ export class A2AClient {
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
      */
     sendStreamingMessage(params) {
-        return executeStreamEvents(this.agentUrl, "message/stream", createMessageSendParams(params), this.customHeaders);
+        return executeStreamEvents(this.agentUrl, "message/stream", describe.messageSendParams(params), this.customHeaders);
     }
     /**
      * @deprecated Use sendStreamingMessage instead.

package/dist/browser/config/index.d.ts

@@ -15,7 +15,7 @@
  *
  * @example
  * ```typescript
- * import { configure, getLogger, getTracer } from '@artinet/core';
+ * import { configure, getLogger, getTracer } from '@artinet/armada';
  * import pino from 'pino';
  *
  * // Configure at app startup

package/dist/browser/config/index.js

@@ -15,7 +15,7 @@
  *
  * @example
  * ```typescript
- * import { configure, getLogger, getTracer } from '@artinet/core';
+ * import { configure, getLogger, getTracer } from '@artinet/armada';
  * import pino from 'pino';
  *
  * // Configure at app startup

package/dist/browser/create/agentcard-builder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+export type AgentCardParams = (Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>) | string;
+export declare const isAgentCardParams: (params: any) => params is AgentCardParams;
+export declare class AgentCard {
+    private readonly _agentCard;
+    constructor(params: Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>);
+    get agentCard(): A2A.AgentCard;
+    static create(params: AgentCardParams): A2A.AgentCard;
+}
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export declare const AgentCardBuilder: typeof AgentCard;
+/**
+ * Convenience factory function for creating an {@link A2A.AgentCard} with default parameters.
+ *
+ * @returns New {@link A2A.AgentCard} with default parameters
+ * @defaults {
+ *   description: "An agent that can use the A2A protocol.",
+ *   url: "https://localhost:3000/a2a",
+ *   version: "0.0.0",
+ *   capabilities: {},
+ *   defaultInputModes: [],
+ *   defaultOutputModes: [],
+ *   skills: [],
+ *   preferredTransport: "JSONRPC",
+ * }
+ *
+ * @example
+ * ```typescript
+ * const agentCard = card("My Agent");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export declare const card: typeof AgentCard.create;
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export declare const createAgentCard: typeof AgentCard.create;

package/dist/browser/create/agentcard-builder.js

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const isAgentCardParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" && params !== null && "name" in params));
+};
+export class AgentCard {
+    constructor(params) {
+        this._agentCard = {
+            protocolVersion: "0.3.0",
+            description: "An agent that can use the A2A protocol.",
+            url: "https://localhost:3000/a2a",
+            version: "0.0.0",
+            capabilities: {},
+            defaultInputModes: [],
+            defaultOutputModes: [],
+            skills: [],
+            preferredTransport: "JSONRPC",
+            ...params,
+        };
+    }
+    get agentCard() {
+        return this._agentCard;
+    }
+    static create(params) {
+        return new AgentCard(typeof params === "string" ? { name: params } : params)
+            .agentCard;
+    }
+}
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export const AgentCardBuilder = AgentCard;
+/**
+ * Convenience factory function for creating an {@link A2A.AgentCard} with default parameters.
+ *
+ * @returns New {@link A2A.AgentCard} with default parameters
+ * @defaults {
+ *   description: "An agent that can use the A2A protocol.",
+ *   url: "https://localhost:3000/a2a",
+ *   version: "0.0.0",
+ *   capabilities: {},
+ *   defaultInputModes: [],
+ *   defaultOutputModes: [],
+ *   skills: [],
+ *   preferredTransport: "JSONRPC",
+ * }
+ *
+ * @example
+ * ```typescript
+ * const agentCard = card("My Agent");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const card = AgentCard.create;
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export const createAgentCard = AgentCard.create;

package/dist/browser/create/base.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utility type that omits the `kind` property from an object type.
+ */
+export type Kindless<T extends object> = Omit<T, "kind">;

package/dist/browser/create/base.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/create/describe.d.ts

@@ -0,0 +1,8 @@
+export { card, type AgentCardParams, isAgentCardParams, } from "./agentcard-builder.js";
+export { message, type MessageParams, isMessageParams, messageSendParams, type MessageSendParamsParams, } from "./message-builder.js";
+export { part } from "./part-builder.js";
+export { artifact, type ArtifactParams, isArtifactParams, type StatusParams, isStatusParams, status, type TaskParams, task, type StatusUpdateParams, type ArtifactUpdateParams, update, } from "./task-builder.js";
+/**
+ * Exports from describe are meant to be portable between different modules.
+ * As such, they should only be dependant on `./types` or other Factory files that are also portable.
+ */

package/dist/browser/create/describe.js

@@ -0,0 +1,8 @@
+export { card, isAgentCardParams, } from "./agentcard-builder.js";
+export { message, isMessageParams, messageSendParams, } from "./message-builder.js";
+export { part } from "./part-builder.js";
+export { artifact, isArtifactParams, isStatusParams, status, task, update, } from "./task-builder.js";
+/**
+ * Exports from describe are meant to be portable between different modules.
+ * As such, they should only be dependant on `./types` or other Factory files that are also portable.
+ */

package/dist/browser/create/message-builder.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { Kindless } from "./base.js";
+export declare class Message {
+    private readonly _message;
+    constructor(params?: Partial<Kindless<A2A.Message>>);
+    get message(): A2A.Message;
+    static create(params?: MessageParams): A2A.Message;
+}
+export type BaseMessageParams = Partial<Kindless<A2A.Message>>;
+export type MessageParams = BaseMessageParams | string;
+export declare const isMessageParams: (params: any) => params is MessageParams;
+/**
+ * Convenience factory function for creating a message builder with default parameters.
+ *
+ * @returns New {@link A2A.Message} with default parameters
+ * @defaults {
+ *   role: "agent",
+ *   parts: [],
+ *   messageId: uuidv4(),
+ *   kind: "message",
+ * }
+ * @example
+ * ```typescript
+ * const message = message();
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export declare const message: typeof Message.create;
+/**
+ * @deprecated Use {@link message} instead.
+ * @since 0.6.0
+ */
+export declare const MessageBuilder: typeof Message;
+export declare class MessageSendConfiguration {
+    private readonly _configuration;
+    constructor(params?: Partial<A2A.MessageSendConfiguration> | null | undefined);
+    get configuration(): A2A.MessageSendConfiguration;
+}
+/**
+ * @deprecated Use {@link messageSendParams} instead.
+ * @since 0.6.0
+ */
+export declare const MessageSendConfigurationBuilder: typeof MessageSendConfiguration;
+export type MessageSendParamsParams = Partial<Kindless<A2A.MessageSendParams>> | MessageParams;
+/**
+ * Convenience factory function for creating a message send params with default parameters.
+ *
+ * @returns New {@link A2A.MessageSendParams} with default parameters
+ * @defaults {
+ *   message: {
+ *     role: "agent",
+ *     parts: [],
+ *     messageId: uuidv4(),
+ *     kind: "message",
+ *   },
+ *   configuration: undefined,
+ *   metadata: undefined,
+ * }
+ * @example
+ * ```typescript
+ * const params = messageSendParams("hello there");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export declare function messageSendParams(params: MessageSendParamsParams): A2A.MessageSendParams;
+/**
+ * @deprecated Use {@link messageSendParams} instead.
+ * @since 0.6.0
+ */
+export declare const createMessageSendParams: typeof messageSendParams;

package/dist/browser/create/message-builder.js

@@ -0,0 +1,108 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { v4 as uuidv4 } from "uuid";
+export class Message {
+    constructor(params = {}) {
+        const messageId = params.messageId ?? uuidv4();
+        // TODO: Consider whether default role should be "user" when used in messageSendParams context.
+        // Currently defaults to "agent" which may be incorrect for MessageSendParams.
+        this._message = {
+            ...params,
+            role: params.role ?? "agent",
+            parts: params.parts ?? [],
+            messageId,
+            kind: A2A.Kind.message,
+        };
+    }
+    get message() {
+        return this._message;
+    }
+    static create(params = {}) {
+        return new Message(typeof params === "string"
+            ? { parts: [{ text: params, kind: "text" }] }
+            : params).message;
+    }
+}
+export const isMessageParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" && params !== null && "parts" in params));
+};
+/**
+ * Convenience factory function for creating a message builder with default parameters.
+ *
+ * @returns New {@link A2A.Message} with default parameters
+ * @defaults {
+ *   role: "agent",
+ *   parts: [],
+ *   messageId: uuidv4(),
+ *   kind: "message",
+ * }
+ * @example
+ * ```typescript
+ * const message = message();
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const message = Message.create;
+/**
+ * @deprecated Use {@link message} instead.
+ * @since 0.6.0
+ */
+export const MessageBuilder = Message;
+export class MessageSendConfiguration {
+    constructor(params = {}) {
+        this._configuration = !params
+            ? {}
+            : {
+                ...params,
+            };
+    }
+    get configuration() {
+        return this._configuration;
+    }
+}
+/**
+ * @deprecated Use {@link messageSendParams} instead.
+ * @since 0.6.0
+ */
+export const MessageSendConfigurationBuilder = MessageSendConfiguration;
+/**
+ * Convenience factory function for creating a message send params with default parameters.
+ *
+ * @returns New {@link A2A.MessageSendParams} with default parameters
+ * @defaults {
+ *   message: {
+ *     role: "agent",
+ *     parts: [],
+ *     messageId: uuidv4(),
+ *     kind: "message",
+ *   },
+ *   configuration: undefined,
+ *   metadata: undefined,
+ * }
+ * @example
+ * ```typescript
+ * const params = messageSendParams("hello there");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export function messageSendParams(params) {
+    const _isMessageParams = isMessageParams(params);
+    return {
+        message: message(_isMessageParams ? params : params.message),
+        configuration: new MessageSendConfiguration(_isMessageParams ? undefined : params.configuration).configuration,
+        metadata: _isMessageParams ? undefined : params.metadata,
+    };
+}
+/**
+ * @deprecated Use {@link messageSendParams} instead.
+ * @since 0.6.0
+ */
+export const createMessageSendParams = messageSendParams;

package/dist/browser/create/part-builder.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+export declare class TextPart {
+    private readonly _part;
+    constructor(params: string);
+    get part(): A2A.TextPart;
+    static create(params: string): A2A.TextPart;
+}
+export type FileParams = (Partial<A2A.File> & {
+    bytes: string;
+}) | (Partial<A2A.File> & {
+    uri: string;
+});
+export type FilePartParams = string | FileParams;
+export declare class FilePart {
+    private readonly _part;
+    constructor(params: FileParams);
+    get part(): A2A.FilePart;
+    static create(params: FilePartParams): A2A.FilePart;
+}
+export declare const filePart: typeof FilePart.create;
+export declare class DataPart {
+    private readonly _part;
+    constructor(params: Record<string, unknown>);
+    get part(): A2A.DataPart;
+    static create(params: Record<string, unknown>): A2A.DataPart;
+}
+/**
+ * Namespace for {@link A2A.Part} creation utilities.
+ *
+ * @example
+ * ```typescript
+ * const t = part.text("Hello");
+ * const f = part.file("https://example.com/file.pdf");
+ * const d = part.data({ key: "value" });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export declare const part: {
+    /**
+     * Create a text part.
+     * @see {@link A2A.TextPart}
+     */
+    text: typeof TextPart.create;
+    /**
+     * Create a file part.
+     * @see {@link A2A.FilePart}
+     */
+    file: typeof FilePart.create;
+    /**
+     * Create a data part.
+     * @see {@link A2A.DataPart}
+     */
+    data: typeof DataPart.create;
+};

package/dist/browser/create/part-builder.js

@@ -0,0 +1,81 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+export class TextPart {
+    constructor(params) {
+        this._part = {
+            text: params,
+            kind: A2A.Kind.text,
+        };
+    }
+    get part() {
+        return this._part;
+    }
+    static create(params) {
+        return new TextPart(params).part;
+    }
+}
+export class FilePart {
+    constructor(params) {
+        this._part = {
+            kind: A2A.Kind.file,
+            file: params,
+        };
+    }
+    get part() {
+        return this._part;
+    }
+    static create(params) {
+        if (typeof params === "string") {
+            return new FilePart({ uri: params }).part;
+        }
+        return new FilePart(params).part;
+    }
+}
+export const filePart = FilePart.create;
+export class DataPart {
+    constructor(params) {
+        this._part = {
+            data: params,
+            kind: A2A.Kind.data,
+        };
+    }
+    get part() {
+        return this._part;
+    }
+    static create(params) {
+        return new DataPart(params).part;
+    }
+}
+/**
+ * Namespace for {@link A2A.Part} creation utilities.
+ *
+ * @example
+ * ```typescript
+ * const t = part.text("Hello");
+ * const f = part.file("https://example.com/file.pdf");
+ * const d = part.data({ key: "value" });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const part = {
+    /**
+     * Create a text part.
+     * @see {@link A2A.TextPart}
+     */
+    text: TextPart.create,
+    /**
+     * Create a file part.
+     * @see {@link A2A.FilePart}
+     */
+    file: FilePart.create,
+    /**
+     * Create a data part.
+     * @see {@link A2A.DataPart}
+     */
+    data: DataPart.create,
+};