@artinet/sdk 0.5.17 → 0.6.0-preview.1

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: () => { },
+};

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;