@artinet/sdk 0.5.18 → 0.6.0-preview.1

package/dist/extensions/otel.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview OpenTelemetry integration for Artinet SDK.
+ *
+ * Lightweight utilities for integrating user-configured OpenTelemetry
+ * with the SDK's tracing and logging interfaces.
+ *
+ * @module @artinet/sdk/otel
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel, withSpan } from '@artinet/sdk/otel';
+ *
+ * // User initializes their own OpenTelemetry setup
+ * // ... NodeSDK setup, exporters, etc. ...
+ *
+ * // Get tracer and configure SDK
+ * const tracer = trace.getTracer('my-agent');
+ * configure({
+ *   tracer,
+ *   logger: configureOtel({ level: 'debug' })
+ * });
+ * ```
+ */
+import { trace, context, SpanKind, SpanStatusCode, Tracer, Span, Context } from "@opentelemetry/api";
+import type { ILogger } from "../config/observability.js";
+/**
+ * Options for configuring the OTel-aware logger.
+ */
+export interface OtelLoggerOptions {
+    /**
+     * Base logger to wrap (logs go here AND to spans).
+     * If not provided, logs only go to spans.
+     */
+    baseLogger?: ILogger;
+    /**
+     * Log level.
+     * @default 'info'
+     */
+    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+}
+/**
+ * Create a logger that adds log events to the current span.
+ *
+ * This logger optionally wraps a base logger and adds all log messages
+ * as span events in the current trace context.
+ *
+ * @param options - Logger options
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel } from '@artinet/sdk/otel';
+ * import { configurePino } from '@artinet/sdk/pino';
+ * import pino from 'pino';
+ *
+ * // Logs go to both Pino AND span events
+ * configure({
+ *   logger: configureOtel({
+ *     baseLogger: configurePino(pino()),
+ *     level: 'debug'
+ *   })
+ * });
+ * ```
+ */
+export declare function configureOtel(options?: OtelLoggerOptions): ILogger;
+/**
+ * Execute a function within a new span.
+ *
+ * @param tracer - User's tracer instance
+ * @param name - Span name
+ * @param fn - Function to execute
+ * @param options - Optional span options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { withSpan } from '@artinet/sdk/otel';
+ *
+ * const tracer = trace.getTracer('my-agent');
+ * const result = await withSpan(tracer, 'processTask', async (span) => {
+ *   span.setAttribute('taskId', '123');
+ *   return await doWork();
+ * });
+ * ```
+ */
+export declare function withSpan<T>(tracer: Tracer, name: string, fn: (span: Span) => Promise<T>, options?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+}): Promise<T>;
+/**
+ * Re-export OpenTelemetry API types for convenience.
+ */
+export { trace, context, SpanKind, SpanStatusCode, type Tracer, type Span, type Context, };
+export default configureOtel;

package/dist/extensions/otel.js

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview OpenTelemetry integration for Artinet SDK.
+ *
+ * Lightweight utilities for integrating user-configured OpenTelemetry
+ * with the SDK's tracing and logging interfaces.
+ *
+ * @module @artinet/sdk/otel
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel, withSpan } from '@artinet/sdk/otel';
+ *
+ * // User initializes their own OpenTelemetry setup
+ * // ... NodeSDK setup, exporters, etc. ...
+ *
+ * // Get tracer and configure SDK
+ * const tracer = trace.getTracer('my-agent');
+ * configure({
+ *   tracer,
+ *   logger: configureOtel({ level: 'debug' })
+ * });
+ * ```
+ */
+import { trace, context, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { formatError } from "../config/observability.js";
+/**
+ * Level priority for filtering.
+ */
+const LEVEL_PRIORITY = {
+    trace: 0,
+    verbose: 1,
+    debug: 2,
+    info: 3,
+    warn: 4,
+    error: 5,
+    silent: 6,
+};
+/**
+ * Create a logger that adds log events to the current span.
+ *
+ * This logger optionally wraps a base logger and adds all log messages
+ * as span events in the current trace context.
+ *
+ * @param options - Logger options
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel } from '@artinet/sdk/otel';
+ * import { configurePino } from '@artinet/sdk/pino';
+ * import pino from 'pino';
+ *
+ * // Logs go to both Pino AND span events
+ * configure({
+ *   logger: configureOtel({
+ *     baseLogger: configurePino(pino()),
+ *     level: 'debug'
+ *   })
+ * });
+ * ```
+ */
+export function configureOtel(options = {}) {
+    let currentLevel = options.level ?? "info";
+    const baseLogger = options.baseLogger;
+    function shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[currentLevel];
+    }
+    function addSpanEvent(level, msg, args) {
+        const span = trace.getActiveSpan();
+        if (!span)
+            return;
+        const attributes = {
+            "log.level": level,
+        };
+        args.forEach((arg, idx) => {
+            if (typeof arg === "object" && arg !== null) {
+                Object.entries(arg).forEach(([key, value]) => {
+                    if (typeof value === "string" ||
+                        typeof value === "number" ||
+                        typeof value === "boolean") {
+                        attributes[key] = value;
+                    }
+                    else {
+                        attributes[key] = JSON.stringify(value);
+                    }
+                });
+            }
+            else if (arg !== undefined) {
+                attributes[`arg${idx}`] = String(arg);
+            }
+        });
+        span.addEvent(msg, attributes);
+    }
+    return {
+        get level() {
+            return currentLevel;
+        },
+        debug(msg, ...args) {
+            if (!shouldLog("debug"))
+                return;
+            addSpanEvent("debug", msg, args);
+            baseLogger?.debug(msg, ...args);
+        },
+        info(msg, ...args) {
+            if (!shouldLog("info"))
+                return;
+            addSpanEvent("info", msg, args);
+            baseLogger?.info(msg, ...args);
+        },
+        warn(msg, ...args) {
+            if (!shouldLog("warn"))
+                return;
+            addSpanEvent("warn", msg, args);
+            baseLogger?.warn(msg, ...args);
+        },
+        error(msg, err) {
+            if (!shouldLog("error"))
+                return;
+            addSpanEvent("error", msg, [formatError(err)]);
+            baseLogger?.error(msg, err);
+        },
+        setLevel(level) {
+            currentLevel = level;
+            baseLogger?.setLevel?.(level);
+        },
+        getLevel() {
+            return currentLevel;
+        },
+        child(ctx) {
+            return configureOtel({
+                baseLogger: baseLogger?.child?.(ctx),
+                level: currentLevel,
+            });
+        },
+    };
+}
+/**
+ * Execute a function within a new span.
+ *
+ * @param tracer - User's tracer instance
+ * @param name - Span name
+ * @param fn - Function to execute
+ * @param options - Optional span options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { withSpan } from '@artinet/sdk/otel';
+ *
+ * const tracer = trace.getTracer('my-agent');
+ * const result = await withSpan(tracer, 'processTask', async (span) => {
+ *   span.setAttribute('taskId', '123');
+ *   return await doWork();
+ * });
+ * ```
+ */
+export async function withSpan(tracer, name, fn, options) {
+    return tracer.startActiveSpan(name, { kind: options?.kind ?? SpanKind.INTERNAL }, async (span) => {
+        if (options?.attributes) {
+            Object.entries(options.attributes).forEach(([key, value]) => {
+                span.setAttribute(key, value);
+            });
+        }
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Re-export OpenTelemetry API types for convenience.
+ */
+export { trace, context, SpanKind, SpanStatusCode, };
+export default configureOtel;

package/dist/extensions/pino.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Pino logger adapter for Artinet SDK.
+ *
+ * Lightweight wrapper that adapts a user-configured Pino instance
+ * to the SDK's ILogger interface.
+ *
+ * @module @artinet/sdk/pino
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { configure } from '@artinet/sdk';
+ * import { configurePino } from '@artinet/sdk/pino';
+ *
+ * // User configures their own pino instance
+ * const pinoLogger = pino({
+ *   level: 'debug',
+ *   transport: { target: 'pino-pretty' }
+ * });
+ *
+ * // Wrap and configure SDK
+ * configure({ logger: configurePino(pinoLogger) });
+ * ```
+ */
+import type { Logger as PinoLogger } from "pino";
+import type { ILogger } from "../config/observability.js";
+/**
+ * Wrap a Pino logger instance to implement ILogger.
+ *
+ * @param pinoLogger - User-configured Pino logger instance
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { configure } from '@artinet/sdk';
+ * import { configurePino } from '@artinet/sdk/pino';
+ *
+ * const myPino = pino({ level: 'debug' });
+ * configure({ logger: configurePino(myPino) });
+ * ```
+ */
+export declare function configurePino(pinoLogger: PinoLogger): ILogger;
+export default configurePino;

package/dist/extensions/pino.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Pino logger adapter for Artinet SDK.
+ *
+ * Lightweight wrapper that adapts a user-configured Pino instance
+ * to the SDK's ILogger interface.
+ *
+ * @module @artinet/sdk/pino
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { configure } from '@artinet/sdk';
+ * import { configurePino } from '@artinet/sdk/pino';
+ *
+ * // User configures their own pino instance
+ * const pinoLogger = pino({
+ *   level: 'debug',
+ *   transport: { target: 'pino-pretty' }
+ * });
+ *
+ * // Wrap and configure SDK
+ * configure({ logger: configurePino(pinoLogger) });
+ * ```
+ */
+/**
+ * Level mapping from Pino to Artinet.
+ */
+const LEVEL_MAP = {
+    trace: "trace",
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+    fatal: "error",
+    silent: "silent",
+};
+/**
+ * Reverse level mapping from Artinet to Pino.
+ */
+const ARTINET_TO_PINO = {
+    trace: "trace",
+    verbose: "debug",
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+    silent: "silent",
+};
+function mergeArgs(args) {
+    if (args.length === 0)
+        return undefined;
+    if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+        return args[0];
+    }
+    return args.reduce((acc, arg, idx) => {
+        if (typeof arg === "object" && arg !== null) {
+            return { ...acc, [idx]: arg };
+        }
+        acc[`${idx}`] = arg;
+        return acc;
+    }, {});
+}
+/**
+ * Wrap a Pino logger instance to implement ILogger.
+ *
+ * @param pinoLogger - User-configured Pino logger instance
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { configure } from '@artinet/sdk';
+ * import { configurePino } from '@artinet/sdk/pino';
+ *
+ * const myPino = pino({ level: 'debug' });
+ * configure({ logger: configurePino(myPino) });
+ * ```
+ */
+export function configurePino(pinoLogger) {
+    return {
+        get level() {
+            return LEVEL_MAP[pinoLogger.level] ?? "info";
+        },
+        debug(msg, ...args) {
+            pinoLogger.debug(mergeArgs(args), msg);
+        },
+        info(msg, ...args) {
+            pinoLogger.info(mergeArgs(args), msg);
+        },
+        warn(msg, ...args) {
+            pinoLogger.warn(mergeArgs(args), msg);
+        },
+        error(msg, err) {
+            pinoLogger.error(err, msg);
+        },
+        setLevel(level) {
+            pinoLogger.level = ARTINET_TO_PINO[level] ?? "info";
+        },
+        getLevel() {
+            return LEVEL_MAP[pinoLogger.level] ?? "info";
+        },
+        child(context) {
+            return configurePino(pinoLogger.child(context));
+        },
+    };
+}
+export default configurePino;

package/dist/extensions/winston.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Winston logger adapter for Artinet SDK.
+ *
+ * Lightweight wrapper that adapts a user-configured Winston instance
+ * to the SDK's ILogger interface.
+ *
+ * @module @artinet/sdk/winston
+ *
+ * @example
+ * ```typescript
+ * import winston from 'winston';
+ * import { configure } from '@artinet/sdk';
+ * import { configureWinston } from '@artinet/sdk/winston';
+ *
+ * // User configures their own winston instance
+ * const winstonLogger = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * // Wrap and configure SDK
+ * configure({ logger: configureWinston(winstonLogger) });
+ * ```
+ */
+import type { Logger as WinstonLogger } from "winston";
+import type { ILogger } from "../config/observability.js";
+/**
+ * Wrap a Winston logger instance to implement ILogger.
+ *
+ * @param winstonLogger - User-configured Winston logger instance
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import winston from 'winston';
+ * import { configure } from '@artinet/sdk';
+ * import { configureWinston } from '@artinet/sdk/winston';
+ *
+ * const myWinston = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ * configure({ logger: configureWinston(myWinston) });
+ * ```
+ */
+export declare function configureWinston(winstonLogger: WinstonLogger): ILogger;
+export default configureWinston;

package/dist/extensions/winston.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Winston logger adapter for Artinet SDK.
+ *
+ * Lightweight wrapper that adapts a user-configured Winston instance
+ * to the SDK's ILogger interface.
+ *
+ * @module @artinet/sdk/winston
+ *
+ * @example
+ * ```typescript
+ * import winston from 'winston';
+ * import { configure } from '@artinet/sdk';
+ * import { configureWinston } from '@artinet/sdk/winston';
+ *
+ * // User configures their own winston instance
+ * const winstonLogger = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * // Wrap and configure SDK
+ * configure({ logger: configureWinston(winstonLogger) });
+ * ```
+ */
+/**
+ * Level mapping from Winston to Artinet.
+ */
+const LEVEL_MAP = {
+    silly: "trace",
+    verbose: "verbose",
+    debug: "debug",
+    http: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+    silent: "silent",
+};
+/**
+ * Reverse level mapping from Artinet to Winston.
+ */
+const ARTINET_TO_WINSTON = {
+    trace: "silly",
+    verbose: "verbose",
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+    silent: "silent",
+};
+/**
+ * Merge spread args into metadata object for Winston.
+ */
+function mergeArgs(args) {
+    if (args.length === 0)
+        return {};
+    if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+        return args[0];
+    }
+    return args.reduce((acc, arg, idx) => {
+        if (typeof arg === "object" && arg !== null) {
+            return { ...acc, ...arg };
+        }
+        acc[`arg${idx}`] = arg;
+        return acc;
+    }, {});
+}
+/**
+ * Wrap a Winston logger instance to implement ILogger.
+ *
+ * @param winstonLogger - User-configured Winston logger instance
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import winston from 'winston';
+ * import { configure } from '@artinet/sdk';
+ * import { configureWinston } from '@artinet/sdk/winston';
+ *
+ * const myWinston = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ * configure({ logger: configureWinston(myWinston) });
+ * ```
+ */
+export function configureWinston(winstonLogger) {
+    return {
+        get level() {
+            return LEVEL_MAP[winstonLogger.level] ?? "info";
+        },
+        debug(msg, ...args) {
+            winstonLogger.debug(msg, mergeArgs(args));
+        },
+        info(msg, ...args) {
+            winstonLogger.info(msg, mergeArgs(args));
+        },
+        warn(msg, ...args) {
+            winstonLogger.warn(msg, mergeArgs(args));
+        },
+        error(msg, err) {
+            winstonLogger.error(msg, err);
+        },
+        setLevel(level) {
+            winstonLogger.level = ARTINET_TO_WINSTON[level] ?? "info";
+        },
+        getLevel() {
+            return LEVEL_MAP[winstonLogger.level] ?? "info";
+        },
+        child(context) {
+            return configureWinston(winstonLogger.child(context));
+        },
+    };
+}
+export default configureWinston;

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from "./server/index.js";
 export * from "./services/index.js";
 export * from "./transport/index.js";
 export * from "./utils/index.js";
+export * from "./config/index.js";
+export * from "./config/default.js";

package/dist/index.js

@@ -4,3 +4,5 @@ export * from "./server/index.js";
 export * from "./services/index.js";
 export * from "./transport/index.js";
 export * from "./utils/index.js";
+export * from "./config/index.js";
+export * from "./config/default.js";

package/dist/server/express/errors.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { SystemError, INTERNAL_ERROR } from "../../utils/index.js";
-import { logError } from "../../utils/logging/index.js";
+import { logger } from "../../config/index.js";
 import escapeHtml from "escape-html";
 /**
  * Express error handler middleware.
@@ -13,7 +13,7 @@ export const errorHandler = (err, req, res, _) => {
     if (res.headersSent) {
         headersSent = true;
     }
-    logError("errorHandler", JSON.stringify(err, null, 2), err);
+    logger.error("errorHandler", err);
     let reqId = null;
     try {
         if (req.body && typeof req.body === "object" && "id" in req.body) {
@@ -21,7 +21,7 @@ export const errorHandler = (err, req, res, _) => {
         }
     }
     catch (e) {
-        logError("A2AServer", "Error extracting request ID", e);
+        logger.error("errorHandler: Error extracting request ID", e);
     }
     let jsonRpcError;
     if (err instanceof SystemError) {

package/dist/server/express/middeware.d.ts

@@ -3,5 +3,5 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { NextFunction, Request, Response } from "express";
-import { A2AServiceInterface, AgentCard } from "../../types/index.js";
-export declare function jsonRPCMiddleware(service: A2AServiceInterface, req: Request, res: Response, next: NextFunction, extendedAgentCard?: AgentCard): Promise<void>;
+import { A2A } from "../../types/index.js";
+export declare function jsonRPCMiddleware(service: A2A.Service, req: Request, res: Response, next: NextFunction, extendedAgentCard?: A2A.AgentCard): Promise<void>;