@lleverage-ai/agent-sdk 0.0.1

package/dist/observability/logger.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Structured Logging System.
+ *
+ * Provides a flexible, structured logging system with support for:
+ * - Log levels (debug, info, warn, error)
+ * - Structured context/metadata
+ * - Custom formatters and transports
+ * - Child loggers with inherited context
+ *
+ * @packageDocumentation
+ */
+/**
+ * Log levels in order of severity.
+ *
+ * @category Observability
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Numeric values for log levels, used for filtering.
+ *
+ * @internal
+ */
+export declare const LOG_LEVEL_VALUES: Record<LogLevel, number>;
+/**
+ * A structured log entry.
+ *
+ * @category Observability
+ */
+export interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Optional context/metadata */
+    context?: Record<string, unknown>;
+    /** Optional error object */
+    error?: Error;
+    /** Optional duration in milliseconds */
+    durationMs?: number;
+    /** Logger name/namespace */
+    logger?: string;
+}
+/**
+ * A transport writes log entries to a destination.
+ *
+ * @category Observability
+ */
+export interface LogTransport {
+    /** Transport name for identification */
+    name: string;
+    /** Write a log entry */
+    write(entry: LogEntry): void | Promise<void>;
+    /** Optional flush for async transports */
+    flush?(): void | Promise<void>;
+    /** Optional close for cleanup */
+    close?(): void | Promise<void>;
+}
+/**
+ * A formatter converts log entries to strings.
+ *
+ * @category Observability
+ */
+export interface LogFormatter {
+    /** Format a log entry to a string */
+    format(entry: LogEntry): string;
+}
+/**
+ * Options for creating a logger.
+ *
+ * @category Observability
+ */
+export interface LoggerOptions {
+    /** Logger name/namespace */
+    name?: string;
+    /** Minimum log level to emit */
+    level?: LogLevel;
+    /** Transports to write to */
+    transports?: LogTransport[];
+    /** Base context to include in all log entries */
+    context?: Record<string, unknown>;
+    /** Custom formatter */
+    formatter?: LogFormatter;
+}
+/**
+ * A structured logger interface.
+ *
+ * @category Observability
+ */
+export interface Logger {
+    /** Logger name */
+    readonly name: string;
+    /** Current log level */
+    level: LogLevel;
+    /** Log at debug level */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /** Log at info level */
+    info(message: string, context?: Record<string, unknown>): void;
+    /** Log at warn level */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /** Log at error level */
+    error(message: string, errorOrContext?: Error | Record<string, unknown>, context?: Record<string, unknown>): void;
+    /**
+     * Log with explicit level.
+     */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with additional context.
+     */
+    child(contextOrName: string | Record<string, unknown>): Logger;
+    /**
+     * Create a timed operation that logs duration.
+     *
+     * @example
+     * ```typescript
+     * const timer = logger.startTimer("api-call");
+     * await fetch(url);
+     * timer.end(); // logs with durationMs
+     * ```
+     */
+    startTimer(operation: string, context?: Record<string, unknown>): LogTimer;
+    /**
+     * Flush all transports.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close all transports.
+     */
+    close(): Promise<void>;
+}
+/**
+ * A timer for measuring operation duration.
+ *
+ * @category Observability
+ */
+export interface LogTimer {
+    /** End the timer and log the duration */
+    end(context?: Record<string, unknown>): void;
+    /** End with error */
+    error(error: Error, context?: Record<string, unknown>): void;
+}
+/**
+ * Creates a JSON formatter for structured logging.
+ *
+ * @returns A JSON formatter
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({
+ *   formatter: createJsonFormatter(),
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createJsonFormatter(): LogFormatter;
+/**
+ * Creates a human-readable formatter with colors.
+ *
+ * @param options - Formatter options
+ * @returns A pretty formatter
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({
+ *   formatter: createPrettyFormatter({ colors: true }),
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createPrettyFormatter(options?: {
+    /** Enable ANSI colors */
+    colors?: boolean;
+    /** Include timestamp */
+    timestamp?: boolean;
+}): LogFormatter;
+/**
+ * Creates a console transport.
+ *
+ * @param options - Transport options
+ * @returns A console transport
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({
+ *   transports: [createConsoleTransport()],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createConsoleTransport(options?: {
+    /** Custom formatter */
+    formatter?: LogFormatter;
+    /** Output stream for each level */
+    streams?: Partial<Record<LogLevel, (message: string) => void>>;
+}): LogTransport;
+/**
+ * Creates a memory transport that stores log entries.
+ *
+ * Useful for testing or collecting logs for later analysis.
+ *
+ * @param options - Transport options
+ * @returns A memory transport with access to stored entries
+ *
+ * @example
+ * ```typescript
+ * const memoryTransport = createMemoryTransport({ maxEntries: 100 });
+ * const logger = createLogger({ transports: [memoryTransport] });
+ *
+ * logger.info("Test");
+ * console.log(memoryTransport.entries); // [{ level: "info", ... }]
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createMemoryTransport(options?: {
+    /** Maximum entries to store (default: 1000) */
+    maxEntries?: number;
+}): LogTransport & {
+    entries: LogEntry[];
+    clear(): void;
+};
+/**
+ * Creates a callback transport that invokes a function for each entry.
+ *
+ * @param callback - Function to call for each log entry
+ * @returns A callback transport
+ *
+ * @example
+ * ```typescript
+ * const transport = createCallbackTransport((entry) => {
+ *   sendToExternalService(entry);
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createCallbackTransport(callback: (entry: LogEntry) => void | Promise<void>): LogTransport;
+/**
+ * Creates a filtered transport that only passes entries matching criteria.
+ *
+ * @param transport - The underlying transport
+ * @param filter - Filter function
+ * @returns A filtered transport
+ *
+ * @example
+ * ```typescript
+ * // Only log errors
+ * const errorTransport = createFilteredTransport(
+ *   createConsoleTransport(),
+ *   (entry) => entry.level === "error"
+ * );
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createFilteredTransport(transport: LogTransport, filter: (entry: LogEntry) => boolean): LogTransport;
+/**
+ * Creates a structured logger.
+ *
+ * @param options - Logger options
+ * @returns A logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({
+ *   name: "my-agent",
+ *   level: "info",
+ *   context: { version: "1.0.0" },
+ * });
+ *
+ * logger.info("Agent started", { model: "claude-3" });
+ * logger.debug("Debug info"); // Not logged (level is info)
+ *
+ * const childLogger = logger.child("tools");
+ * childLogger.info("Tool called"); // Logs with logger="my-agent:tools"
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * The default global logger instance.
+ *
+ * Can be used directly or replaced with a custom logger.
+ *
+ * @example
+ * ```typescript
+ * import { defaultLogger } from "@lleverage-ai/agent-sdk";
+ *
+ * defaultLogger.info("Application started");
+ * ```
+ *
+ * @category Observability
+ */
+export declare let defaultLogger: Logger;
+/**
+ * Sets the default global logger.
+ *
+ * @param logger - The logger to use as default
+ *
+ * @example
+ * ```typescript
+ * const customLogger = createLogger({
+ *   name: "my-app",
+ *   level: "debug",
+ * });
+ *
+ * setDefaultLogger(customLogger);
+ * ```
+ *
+ * @category Observability
+ */
+export declare function setDefaultLogger(logger: Logger): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"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"}