@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/client/a2a-client.d.ts

@@ -2,8 +2,8 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { AgentCard, MessageSendParams, TaskQueryParams, TaskIdParams, TaskPushNotificationConfig, Task, Message, UpdateEvent } from "../types/index.js";
-import type { Client } from "../types/interfaces/client.js";
+import { A2A } from "../types/index.js";
+import type { Client } from "../types/client.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.
@@ -35,68 +35,69 @@ export declare class A2AClient implements Client {
      * Caches the result after the first successful fetch.
      * @returns A promise resolving to the AgentCard.
      */
-    agentCard(): Promise<AgentCard>;
+    agentCard(): Promise<A2A.AgentCard>;
     /**
-     * Refreshes the cached AgentCard by fetching it again from the server.
-     * @returns A promise resolving to the updated AgentCard.
+     * Retrieves the AgentCard from the A2A server.
+     * @returns A promise resolving to the AgentCard.
      */
-    refreshAgentCard(): Promise<AgentCard>;
+    getAgentCard(): Promise<A2A.AgentCard>;
     /**
-     * Sends a Message to an agent server.
-     * @param params The parameters for the message/send method.
-     * @returns A promise resolving to Message/Task response from the agent server or null.
+     * Refreshes the cached AgentCard by fetching it again from the server.
+     * @returns A promise resolving to the updated AgentCard.
      */
-    sendMessage(params: MessageSendParams | string): Promise<Message | Task | null>;
+    refreshAgentCard(): Promise<A2A.AgentCard>;
+    sendMessage(params: A2A.MessageSendParams): Promise<A2A.Message | A2A.Task | null>;
+    sendMessage(params: string | A2A.MessageSendParams["message"]): Promise<A2A.Message | A2A.Task | null>;
     /**
      * @deprecated Use sendMessage instead.
      * Sends a task request to the agent (non-streaming).
      * @param params The parameters for the message/send method.
      * @returns A promise resolving to the Task object or null.
      */
-    sendTask(params: MessageSendParams): Promise<Message | Task | null>;
+    sendTask(params: A2A.MessageSendParams): Promise<A2A.Message | A2A.Task | null>;
     /**
      * Sends a Message and returns a stream of status and artifact updates.
      * @param params Task parameters for the request
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
      */
-    sendStreamingMessage(params: MessageSendParams | string): AsyncIterable<UpdateEvent>;
+    sendStreamingMessage(params: A2A.MessageSendParams | string): AsyncIterable<A2A.Update>;
     /**
      * @deprecated Use sendStreamingMessage instead.
      * Sends a task and returns a subscription to status and artifact updates.
      * @param params Task parameters for the request
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
      */
-    sendTaskSubscribe(params: MessageSendParams): AsyncIterable<UpdateEvent>;
+    sendTaskSubscribe(params: A2A.MessageSendParams): AsyncIterable<A2A.Update>;
     /**
      * Retrieves the current state of a task.
      * @param params The parameters for the tasks/get method.
      * @returns A promise resolving to the Task object or null.
      */
-    getTask(params: TaskQueryParams): Promise<Task | null>;
+    getTask(params: A2A.TaskQueryParams): Promise<A2A.Task | null>;
     /**
      * Cancels a currently running task.
      * @param params The parameters for the tasks/cancel method.
      * @returns A promise resolving to the updated Task object (usually canceled state) or null.
      */
-    cancelTask(params: TaskIdParams): Promise<Task | null>;
+    cancelTask(params: A2A.TaskIdParams): Promise<A2A.Task | null>;
     /**
      * Sets or updates the push notification config for a task.
      * @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
      * @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
      */
-    setTaskPushNotification(params: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig | null>;
+    setTaskPushNotification(params: A2A.TaskPushNotificationConfig): Promise<A2A.TaskPushNotificationConfig | null>;
     /**
      * Retrieves the currently configured push notification config for a task.
      * @param params The parameters for the tasks/pushNotificationConfig/get method.
      * @returns A promise resolving to the TaskPushNotificationConfig or null.
      */
-    getTaskPushNotification(params: TaskIdParams): Promise<TaskPushNotificationConfig | null>;
+    getTaskPushNotification(params: A2A.TaskIdParams): Promise<A2A.TaskPushNotificationConfig | null>;
     /**
      * Resubscribes to an existing task's update stream.
      * @param params Parameters identifying the task to resubscribe to
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
      */
-    resubscribeTask(params: TaskQueryParams): AsyncIterable<UpdateEvent>;
+    resubscribeTask(params: A2A.TaskQueryParams): AsyncIterable<A2A.Update>;
     /**
      * Checks if the server supports a specific capability based on the agent card.
      * @param capability The capability to check (e.g., 'streaming', 'pushNotifications').

package/dist/client/a2a-client.js

@@ -5,8 +5,8 @@
 import { executeJsonRpcRequest, executeGetRequest, } from "../transport/rpc/rpc-client.js";
 import { executeStreamEvents } from "../transport/streaming/event-stream.js";
 import { INTERNAL_ERROR } from "../utils/common/errors.js";
-import { logError } from "../utils/logging/log.js";
-import { createMessageSendParams } from "../services/a2a/helpers/message-builder.js";
+import { logger } from "../config/index.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.
@@ -65,6 +65,7 @@ export class A2AClient {
                 this.cachedAgentCard = card;
             }
             catch (error) {
+                logger.error("A2AClient:agentCard: Failed to fetch agent card (well-known):", error);
                 const fallbackUrl = new URL(this.fallbackPath, this.baseUrl);
                 if (this.mergePath) {
                     fallbackUrl.pathname = this.baseUrl.pathname + fallbackUrl.pathname;
@@ -73,18 +74,25 @@ export class A2AClient {
                 if (!fallbackCard.name ||
                     fallbackCard.name === null ||
                     fallbackCard.name === undefined) {
-                    throw new Error("No fallback agent card found");
+                    throw new Error("No fallback agent card found" + error);
                 }
                 this.cachedAgentCard = fallbackCard;
             }
         }
         catch (error) {
-            logError("A2AClient:agentCard", "Failed to fetch or parse agent card:", error);
-            throw INTERNAL_ERROR(`Could not retrieve agent card: ${error instanceof Error ? error.message : String(error)}`);
+            logger.error("A2AClient:agentCard: Failed to fetch or parse agent card:", error);
+            throw INTERNAL_ERROR(error);
         }
         this.agentUrl = new URL(this.cachedAgentCard.url, this.baseUrl);
         return this.cachedAgentCard;
     }
+    /**
+     * Retrieves the AgentCard from the A2A server.
+     * @returns A promise resolving to the AgentCard.
+     */
+    getAgentCard() {
+        return this.agentCard();
+    }
     /**
      * Refreshes the cached AgentCard by fetching it again from the server.
      * @returns A promise resolving to the updated AgentCard.
@@ -99,7 +107,11 @@ export class A2AClient {
      * @returns A promise resolving to Message/Task response from the agent server or null.
      */
     async sendMessage(params) {
-        return await executeJsonRpcRequest(this.agentUrl, "message/send", createMessageSendParams(params), this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "message/send", typeof params === "string"
+            ? describe.messageSendParams(params)
+            : typeof params === "object" && "message" in params
+                ? params
+                : describe.messageSendParams({ message: params }), this.customHeaders);
     }
     /**
      * @deprecated Use sendMessage instead.
@@ -116,7 +128,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.
@@ -190,7 +202,7 @@ export class A2AClient {
             }
         }
         catch (error) {
-            logError("A2AClient:supports", `Failed to determine support for capability '${capability}':`, error);
+            logger.error(`A2AClient:supports: Failed to determine support for capability '${capability}':`, error);
             return false; // Assume not supported if card fetch fails
         }
     }

package/dist/config/default.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Default configuration for the Artinet runtime.
+ *
+ * Provides sensible defaults using built-in console for logging.
+ * Import and call `applyDefaults()` at application startup if you
+ * want logging enabled without custom configuration.
+ *
+ * @module config/default
+ *
+ * @example
+ * ```typescript
+ * import { applyDefaults } from '@artinet/armada';
+ *
+ * // Enable console logging with defaults
+ * applyDefaults();
+ *
+ * // Or override specific options
+ * applyDefaults({ logger: myCustomLogger });
+ * ```
+ */
+import { ArtinetConfig } from "./index.js";
+import { ILogger } from "./observability.js";
+/**
+ * Default logger implementation using console.
+ *
+ * Maps directly to console methods for zero-config logging.
+ */
+export declare const consoleLogger: ILogger;
+/**
+ * Default configuration with console logging enabled.
+ */
+export declare const defaultConfig: ArtinetConfig;
+/**
+ * Apply default configuration.
+ *
+ * Call this at application startup to enable console logging.
+ * Optionally pass overrides to customize specific options.
+ *
+ * @param overrides - Optional configuration to merge with defaults
+ *
+ * @example
+ * ```typescript
+ * // Use all defaults
+ * applyDefaults();
+ *
+ * // Use defaults but with custom tracer
+ * applyDefaults({ tracer: myTracer });
+ * ```
+ */
+export declare function applyDefaults(overrides?: Partial<ArtinetConfig>): void;

package/dist/config/default.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Default configuration for the Artinet runtime.
+ *
+ * Provides sensible defaults using built-in console for logging.
+ * Import and call `applyDefaults()` at application startup if you
+ * want logging enabled without custom configuration.
+ *
+ * @module config/default
+ *
+ * @example
+ * ```typescript
+ * import { applyDefaults } from '@artinet/armada';
+ *
+ * // Enable console logging with defaults
+ * applyDefaults();
+ *
+ * // Or override specific options
+ * applyDefaults({ logger: myCustomLogger });
+ * ```
+ */
+import { configure } from "./index.js";
+/**
+ * Default logger implementation using console.
+ *
+ * Maps directly to console methods for zero-config logging.
+ */
+export const consoleLogger = {
+    debug: (msg, ...args) => console.debug(`[DEBUG] ${msg}`, ...args),
+    info: (msg, ...args) => console.info(`[INFO] ${msg}`, ...args),
+    warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
+    error: (msg, err) => console.error(`[ERROR] ${msg}`, err),
+    child: (_) => consoleLogger,
+};
+/**
+ * Default configuration with console logging enabled.
+ */
+export const defaultConfig = {
+    logger: consoleLogger,
+};
+/**
+ * Apply default configuration.
+ *
+ * Call this at application startup to enable console logging.
+ * Optionally pass overrides to customize specific options.
+ *
+ * @param overrides - Optional configuration to merge with defaults
+ *
+ * @example
+ * ```typescript
+ * // Use all defaults
+ * applyDefaults();
+ *
+ * // Use defaults but with custom tracer
+ * applyDefaults({ tracer: myTracer });
+ * ```
+ */
+export function applyDefaults(overrides) {
+    configure({
+        ...defaultConfig,
+        ...overrides,
+    });
+}

package/dist/config/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Global configuration for the Artinet runtime.
+ *
+ * Provides a centralized configuration interface that consumers use to
+ * inject their implementations of observability, storage, and other
+ * platform-specific dependencies.
+ *
+ * Design principles:
+ * - Single configuration point for the entire SDK
+ * - No-op defaults for all optional dependencies
+ * - Type-safe configuration interface
+ * - Configure once at application startup
+ *
+ * @module config
+ *
+ * @example
+ * ```typescript
+ * import { configure, getLogger, getTracer } from '@artinet/armada';
+ * import pino from 'pino';
+ *
+ * // Configure at app startup
+ * configure({
+ *   logger: {
+ *     debug: (msg, ctx) => pino().debug(ctx, msg),
+ *     info: (msg, ctx) => pino().info(ctx, msg),
+ *     warn: (msg, ctx) => pino().warn(ctx, msg),
+ *     error: (msg, ctx) => pino().error(ctx, msg),
+ *   },
+ * });
+ *
+ * // Later in your code
+ * const logger = getLogger();
+ * logger.info('Application started');
+ * ```
+ */
+import { ILogger } from "./observability.js";
+import { Tracer } from "@opentelemetry/api";
+/**
+ * Artinet SDK configuration interface.
+ *
+ * All properties are optional - the SDK provides sensible no-op defaults.
+ * Configure only what you need.
+ */
+export interface ArtinetConfig {
+    /**
+     * Logger implementation for structured logging.
+     * @default noopLogger (no logging)
+     */
+    logger?: ILogger;
+    /**
+     * Tracer implementation for distributed tracing.
+     * @default trace.getTracer('artinet') (no tracing)
+     */
+    tracer?: Tracer;
+}
+/**
+ * Configure the Artinet SDK.
+ *
+ * Call this once at application startup to inject your implementations.
+ * Subsequent calls will merge with existing configuration.
+ *
+ * @param config - Configuration options
+ *
+ * @example
+ * ```typescript
+ * // Basic configuration with console
+ * configure({ logger: console });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Production configuration with Pino and OpenTelemetry
+ * import pino from 'pino';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const pinoLogger = pino();
+ *
+ * configure({
+ *   logger: {
+ *     debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
+ *     info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
+ *     warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
+ *     error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
+ *   },
+ *   tracer: {
+ *     startSpan: (name, attrs) => {
+ *       const span = trace.getTracer('my-app').startSpan(name);
+ *       // ... wrap span
+ *       return wrappedSpan;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function configure(config: ArtinetConfig): void;
+/**
+ * Reset configuration to defaults.
+ *
+ * Primarily useful for testing to ensure clean state between tests.
+ *
+ * @example
+ * ```typescript
+ * beforeEach(() => {
+ *   resetConfig();
+ * });
+ * ```
+ */
+export declare function resetConfig(): void;
+/**
+ * Get the current configuration.
+ *
+ * Returns a copy to prevent external mutation.
+ *
+ * @returns Current configuration (readonly copy)
+ */
+export declare function getConfig(): Readonly<ArtinetConfig>;
+/**
+ * Get the configured logger or no-op default.
+ *
+ * @returns Logger implementation
+ *
+ * @example
+ * ```typescript
+ * const logger = getLogger();
+ * logger.info('Processing request', { requestId: '123' }, 'extra data');
+ * ```
+ */
+export declare function getLogger(): ILogger;
+/**
+ * Get the configured tracer or no-op default.
+ *
+ * @returns Tracer implementation
+ *
+ * @example
+ * ```typescript
+ * const tracer = getTracer();
+ * const span = tracer.startSpan('processRequest', { requestId: '123' });
+ * try {
+ *   // ... do work
+ *   span.setStatus('ok');
+ * } catch (error) {
+ *   span.setStatus('error', error.message);
+ *   throw error;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+export declare function getTracer(): Tracer;
+export declare const logger: {
+    debug: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, err: unknown) => void;
+    setLevel: (level: "debug" | "info" | "warn" | "error") => void | undefined;
+    getLevel: () => "silent" | "error" | "debug" | "info" | "trace" | "verbose" | "warn";
+    child: (context: Record<string, unknown>) => ILogger;
+};

package/dist/config/index.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Global configuration for the Artinet runtime.
+ *
+ * Provides a centralized configuration interface that consumers use to
+ * inject their implementations of observability, storage, and other
+ * platform-specific dependencies.
+ *
+ * Design principles:
+ * - Single configuration point for the entire SDK
+ * - No-op defaults for all optional dependencies
+ * - Type-safe configuration interface
+ * - Configure once at application startup
+ *
+ * @module config
+ *
+ * @example
+ * ```typescript
+ * import { configure, getLogger, getTracer } from '@artinet/armada';
+ * import pino from 'pino';
+ *
+ * // Configure at app startup
+ * configure({
+ *   logger: {
+ *     debug: (msg, ctx) => pino().debug(ctx, msg),
+ *     info: (msg, ctx) => pino().info(ctx, msg),
+ *     warn: (msg, ctx) => pino().warn(ctx, msg),
+ *     error: (msg, ctx) => pino().error(ctx, msg),
+ *   },
+ * });
+ *
+ * // Later in your code
+ * const logger = getLogger();
+ * logger.info('Application started');
+ * ```
+ */
+import { noopLogger } from "./observability.js";
+import { trace } from "@opentelemetry/api";
+/**
+ * Internal configuration state.
+ * @internal
+ */
+let _config = {};
+/**
+ * Configure the Artinet SDK.
+ *
+ * Call this once at application startup to inject your implementations.
+ * Subsequent calls will merge with existing configuration.
+ *
+ * @param config - Configuration options
+ *
+ * @example
+ * ```typescript
+ * // Basic configuration with console
+ * configure({ logger: console });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Production configuration with Pino and OpenTelemetry
+ * import pino from 'pino';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const pinoLogger = pino();
+ *
+ * configure({
+ *   logger: {
+ *     debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
+ *     info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
+ *     warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
+ *     error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
+ *   },
+ *   tracer: {
+ *     startSpan: (name, attrs) => {
+ *       const span = trace.getTracer('my-app').startSpan(name);
+ *       // ... wrap span
+ *       return wrappedSpan;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function configure(config) {
+    _config = { ..._config, ...config };
+}
+/**
+ * Reset configuration to defaults.
+ *
+ * Primarily useful for testing to ensure clean state between tests.
+ *
+ * @example
+ * ```typescript
+ * beforeEach(() => {
+ *   resetConfig();
+ * });
+ * ```
+ */
+export function resetConfig() {
+    _config = {};
+}
+/**
+ * Get the current configuration.
+ *
+ * Returns a copy to prevent external mutation.
+ *
+ * @returns Current configuration (readonly copy)
+ */
+export function getConfig() {
+    return { ..._config };
+}
+/**
+ * Get the configured logger or no-op default.
+ *
+ * @returns Logger implementation
+ *
+ * @example
+ * ```typescript
+ * const logger = getLogger();
+ * logger.info('Processing request', { requestId: '123' }, 'extra data');
+ * ```
+ */
+export function getLogger() {
+    return _config.logger ?? noopLogger;
+}
+/**
+ * Get the configured tracer or no-op default.
+ *
+ * @returns Tracer implementation
+ *
+ * @example
+ * ```typescript
+ * const tracer = getTracer();
+ * const span = tracer.startSpan('processRequest', { requestId: '123' });
+ * try {
+ *   // ... do work
+ *   span.setStatus('ok');
+ * } catch (error) {
+ *   span.setStatus('error', error.message);
+ *   throw error;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+export function getTracer() {
+    return _config.tracer ?? trace.getTracer("artinet");
+}
+export const logger = {
+    debug: (msg, ...args) => getLogger()?.debug?.(msg, ...args),
+    info: (msg, ...args) => getLogger()?.info?.(msg, ...args),
+    warn: (msg, ...args) => getLogger()?.warn?.(msg, ...args),
+    error: (msg, err) => getLogger()?.error?.(msg, err),
+    setLevel: (level) => getLogger()?.setLevel?.(level),
+    getLevel: () => getLogger()?.getLevel?.() ?? "info",
+    child: (context) => getLogger()?.child?.(context) ?? noopLogger,
+};