@artinet/sdk 0.5.18 → 0.6.0-preview.2

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,7 @@ 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";
+export * from "./create/create.js";
+export * from "./create/index.js";

package/dist/index.js

@@ -4,3 +4,7 @@ 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";
+export * from "./create/create.js";
+export * from "./create/index.js";

package/dist/server/express/errors.js

@@ -2,9 +2,10 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { SystemError, INTERNAL_ERROR } from "../../utils/index.js";
-import { logError } from "../../utils/logging/index.js";
+import { SystemError } from "../../utils/index.js";
+import { logger } from "../../config/index.js";
 import escapeHtml from "escape-html";
+import { A2AError } from "@a2a-js/sdk/server";
 /**
  * Express error handler middleware.
  */
@@ -13,7 +14,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,19 +22,14 @@ 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) {
+    if (err instanceof A2AError || err instanceof SystemError) {
         jsonRpcError = { code: err.code, message: err.message, data: err.data };
     }
     else {
-        const internalError = INTERNAL_ERROR(err.stack);
-        jsonRpcError = {
-            code: internalError.code,
-            message: internalError.message,
-            data: internalError.data,
-        };
+        jsonRpcError = A2AError.internalError(err.message, err.data).toJSONRPCError();
     }
     const errorResponse = {
         jsonrpc: "2.0",

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>;

package/dist/server/express/middeware.js

@@ -2,8 +2,9 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { PUSH_NOTIFICATION_NOT_SUPPORTED, INVALID_REQUEST, INVALID_PARAMS, METHOD_NOT_FOUND, AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED, } from "../../utils/index.js";
-import { logError } from "../../utils/logging/index.js";
+import { logger } from "../../config/index.js";
+import { formatJson } from "../../utils/common/utils.js";
+import { A2AError } from "@a2a-js/sdk/server";
 const isValidMethod = (method) => {
     return (method &&
         method !== "" &&
@@ -13,41 +14,35 @@ const isValidMethod = (method) => {
 };
 const checkParams = (params, method) => {
     if (!params || (typeof params !== "object" && !Array.isArray(params))) {
-        throw INVALID_PARAMS({
-            data: {
-                message: "Invalid params",
-                method,
-            },
+        throw A2AError.invalidParams("Invalid Parameters", {
+            params,
+            method,
         });
     }
     else if (typeof params === "object" && Object.keys(params).length === 0) {
-        throw INVALID_PARAMS({
-            data: {
-                message: "No params provided",
-                method,
-            },
+        throw A2AError.invalidParams("Params Required", {
+            params,
+            method,
         });
     }
 };
 export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCard) {
     const { method, params, id, jsonrpc } = req.body;
     if (jsonrpc !== "2.0" ||
-        (id && typeof id !== "string" && typeof id !== "number" && id !== null)) {
+        (typeof id !== "string" &&
+            typeof id === "number" &&
+            !Number.isInteger(id) &&
+            id !== null)) {
         res.json({
             jsonrpc: "2.0",
             id: id || null,
-            error: { code: -32600, message: "Invalid Request" },
+            error: A2AError.invalidRequest(`Invalid JSONRPC info: ${formatJson({ method, params, id, jsonrpc })}`).toJSONRPCError(),
         });
         return;
     }
     try {
         if (!isValidMethod(method)) {
-            throw INVALID_REQUEST({
-                data: {
-                    message: "No method provided",
-                    method,
-                },
-            });
+            throw A2AError.invalidRequest("No method provided");
         }
         let result;
         switch (method) {
@@ -94,42 +89,33 @@ export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCa
                 result = await service.cancelTask(params);
                 break;
             }
+            //todo: Implement push notifications
+            //todo: Implement Tasks List
             case "tasks/pushNotificationConfig/set":
             case "tasks/pushNotificationConfig/get":
             case "tasks/pushNotificationConfig/delete":
             case "task/pushNotificationConfig/list": {
-                throw PUSH_NOTIFICATION_NOT_SUPPORTED({
-                    data: {
-                        message: "Push notifications not supported",
-                        method,
-                    },
-                });
+                throw A2AError.pushNotificationNotSupported();
             }
             case "agent/getAuthenticatedExtendedCard": {
                 if (!extendedAgentCard ||
-                    service.agentCard.supportsAuthenticatedExtendedCard !== true) {
-                    throw AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED({
-                        data: {
-                            message: "Authenticated Extended Card is not configured",
-                            method,
-                        },
-                    });
+                    (await service.getAgentCard()).supportsAuthenticatedExtendedCard !==
+                        true) {
+                    throw A2AError.authenticatedExtendedCardNotConfigured();
                 }
                 result = extendedAgentCard;
                 break;
             }
             default:
-                throw METHOD_NOT_FOUND({
-                    data: {
-                        message: "Method not found",
-                        method,
-                    },
-                });
+                throw A2AError.methodNotFound(method);
         }
         res.json({ jsonrpc: "2.0", id, result });
     }
     catch (error) {
-        logError("jsonRPCMiddleware", "error detected", error, req.body);
+        logger.error("jsonRPCMiddleware[Error]:", error);
+        logger.warn("jsonRPCMiddleware[Error]: Request body", {
+            request: req.body,
+        });
         return next(error);
     }
 }