@artinet/sdk 0.5.18 → 0.6.0-preview.1

package/dist/client/a2a-client.js

@@ -5,7 +5,7 @@
 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 { logger } from "../config/index.js";
 import { createMessageSendParams } from "../services/a2a/helpers/message-builder.js";
 /**
  * A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
@@ -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"
+            ? createMessageSendParams(params)
+            : typeof params === "object" && "message" in params
+                ? params
+                : createMessageSendParams({ message: params }), this.customHeaders);
     }
     /**
      * @deprecated Use sendMessage 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/core';
+ *
+ * // 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/core';
+ *
+ * // 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/core';
+ * 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/core';
+ * 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,
+};

package/dist/config/observability.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** //todo move to @artinet/sdk from core v0.1
+ * @fileoverview Zero-dependency observability interfaces for the Artinet ecosystem.
+ *
+ * Provides minimal interfaces for logging and tracing that consumers can implement
+ * with their preferred tools (Pino, Winston, OpenTelemetry, etc.).
+ *
+ * Design principles:
+ * - Zero runtime dependencies
+ * - No-op defaults for zero overhead when not configured
+ * - Environment agnostic (Node, Deno, Bun, edge, browser)
+ * - Consumer brings their own implementation
+ *
+ * @module utils/observability
+ */
+/**
+ * Minimal logger interface.
+ *
+ * Consumers provide their own implementation using their preferred
+ * logging library (Pino, Winston, console, etc.).
+ *
+ * Uses spread args for maximum compatibility - works naturally with
+ * console.log, Pino, Winston, and most logging libraries.
+ *
+ * @example
+ * ```typescript
+ * // Console implementation (just works)
+ * const logger: ILogger = console;
+ *
+ * // Pino implementation
+ * import pino from 'pino';
+ * const pinoLogger = pino();
+ *
+ * const logger: ILogger = {
+ *   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),
+ * };
+ *
+ * // Winston implementation
+ * import winston from 'winston';
+ * const winstonLogger = winston.createLogger({ ... });
+ *
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => winstonLogger.error(msg, ...args),
+ * };
+ * ```
+ */
+export interface ILogger {
+    /**
+     * Log level.
+     * @default "info"
+     */
+    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Log debug-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    debug(msg: string, ...args: unknown[]): void;
+    /**
+     * Log info-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    info(msg: string, ...args: unknown[]): void;
+    /**
+     * Log warn-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    warn(msg: string, ...args: unknown[]): void;
+    /**
+     * Log error-level message.
+     * @param msg - Log message
+     * @param err - Error to log
+     */
+    error(msg: string, err: unknown): void;
+    /**
+     * Set log level.
+     * @param level - Log level
+     */
+    setLevel?(level: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent"): void;
+    /**
+     * Get log level.
+     * @returns Current log level or undefined if not set
+     */
+    getLevel?(): "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Create child logger with bound context.
+     * @param context - Context to bind to the child logger
+     * @returns Child logger or undefined if not implemented
+     */
+    child?(context: Record<string, unknown>): ILogger;
+}
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export declare function formatError(err: unknown): Record<string, unknown>;
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export declare const noopLogger: ILogger;

package/dist/config/observability.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export function formatError(err) {
+    if (err instanceof Error) {
+        return {
+            message: err.message,
+            stack: err.stack,
+            name: err.name,
+        };
+    }
+    return { error: String(err) };
+}
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};