@smplkit/sdk 1.3.20 → 1.3.22

package/dist/index.d.cts

@@ -950,6 +950,42 @@ declare class LogGroup {
     toString(): string;
 }
 
+/**
+ * Contract for pluggable logging framework integration.
+ *
+ * Adapters bridge the smplkit logging runtime to a specific logging framework.
+ * The core LoggingClient delegates all framework-specific work through this interface.
+ *
+ * Adapters are NOT responsible for: key normalization, caching, bulk registration,
+ * level resolution, or WebSocket handling. Those remain in the core client.
+ */
+interface LoggingAdapter {
+    /** Human-readable adapter name for diagnostics (e.g., 'winston'). */
+    readonly name: string;
+    /**
+     * Scan the runtime for existing loggers.
+     * Returns an array of { name, level } where level is a smplkit level string.
+     */
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    /**
+     * Set the level on a specific logger.
+     * @param loggerName - The original (non-normalized) logger name.
+     * @param level - smplkit level string (e.g., 'DEBUG', 'INFO', 'WARN').
+     */
+    applyLevel(loggerName: string, level: string): void;
+    /**
+     * Install continuous discovery hook.
+     * The callback receives (original_name, smplkit_level_string) whenever
+     * a new logger is created in the framework.
+     */
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    /** Remove the hook installed by installHook(). Called on client close(). */
+    uninstallHook(): void;
+}
+
 /**
  * LoggingClient — management plane + scaffolded runtime for Smpl Logging.
  *
@@ -979,8 +1015,17 @@ declare class LoggingClient {
     private _started;
     private _globalListeners;
     private _keyListeners;
+    private _adapters;
+    private _explicitAdapters;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
+    /**
+     * Register a logging framework adapter.
+     *
+     * Must be called before `start()`. Disables auto-loading of built-in
+     * adapters — only explicitly registered adapters will be used.
+     */
+    registerAdapter(adapter: LoggingAdapter): void;
     /** Create an unsaved logger. Call `.save()` to persist. */
     new(key: string, options?: {
         name?: string;
@@ -1010,11 +1055,17 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * Fetches existing loggers/groups and wires WebSocket listeners for
-     * live updates. Idempotent — safe to call multiple times.
+     * Performs the full runtime pipeline:
+     *   1. Auto-load adapters (if none registered explicitly)
+     *   2. Discover existing loggers from each adapter
+     *   3. Install hooks on each adapter for new logger creation
+     *   4. Bulk-register discovered loggers with the server
+     *   5. Fetch all loggers and groups from the server
+     *   6. Resolve levels and apply to adapters
+     *   7. Wire WebSocket for live updates
      *
-     * Note: Node.js auto-discovery (equivalent to Python's logging module
-     * monkey-patching) is deferred. Management methods work without start().
+     * Idempotent — safe to call multiple times.
+     * Management methods work without start().
      */
     start(): Promise<void>;
     /**
@@ -1026,6 +1077,12 @@ declare class LoggingClient {
     onChange(callbackOrKey: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
     /** @internal */
     _close(): void;
+    /** Auto-load built-in adapters by attempting to require each framework. */
+    private _autoLoadAdapters;
+    /** Apply resolved levels from server loggers to all adapters. */
+    private _applyLevels;
+    /** Called by adapter hooks when a new logger is created in the framework. */
+    private _onAdapterNewLogger;
     private _handleLoggerChanged;
     private _loggerToModel;
     private _groupToModel;
@@ -1109,6 +1166,68 @@ declare class SmplClient {
     close(): void;
 }
 
+/**
+ * Winston logging framework adapter.
+ *
+ * Bridges the smplkit logging runtime to winston's logger container.
+ * Discovers loggers via `winston.loggers` (the Container), hooks into
+ * new logger creation by monkey-patching `Container.add()`, and applies
+ * levels by setting `logger.level` on the winston logger instance.
+ */
+
+interface WinstonAdapterConfig {
+    /** Whether to include the default logger in discovery (default: true). */
+    discoverDefault?: boolean;
+    /** @internal — inject a winston module for testing. */
+    _winston?: unknown;
+}
+declare class WinstonAdapter implements LoggingAdapter {
+    readonly name = "winston";
+    private readonly _discoverDefault;
+    private _winston;
+    private _originalAdd;
+    constructor(config?: WinstonAdapterConfig);
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    applyLevel(loggerName: string, level: string): void;
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    uninstallHook(): void;
+}
+
+/**
+ * Pino logging framework adapter.
+ *
+ * Pino has no global logger registry. This adapter builds its own internal
+ * registry by monkey-patching the pino module's default export and the
+ * `child()` method on created loggers. Logger instances are tracked via
+ * WeakRef to avoid memory leaks.
+ */
+
+interface PinoAdapterConfig {
+    /** Which binding field to use as the logger name (default: 'name'). */
+    nameField?: string;
+    /** @internal — inject a pino module for testing. */
+    _pino?: unknown;
+}
+declare class PinoAdapter implements LoggingAdapter {
+    readonly name = "pino";
+    private readonly _nameField;
+    private _pino;
+    private _registry;
+    private _originalPino;
+    private _pinoModule;
+    constructor(config?: PinoAdapterConfig);
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    applyLevel(loggerName: string, level: string): void;
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    uninstallHook(): void;
+}
+
 /**
  * Structured SDK error types.
  *
@@ -1155,4 +1274,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, LoggingClient, NumberFlag, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag };
+export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, type LoggingAdapter, LoggingClient, NumberFlag, PinoAdapter, type PinoAdapterConfig, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag, WinstonAdapter, type WinstonAdapterConfig };

package/dist/index.d.ts

@@ -950,6 +950,42 @@ declare class LogGroup {
     toString(): string;
 }
 
+/**
+ * Contract for pluggable logging framework integration.
+ *
+ * Adapters bridge the smplkit logging runtime to a specific logging framework.
+ * The core LoggingClient delegates all framework-specific work through this interface.
+ *
+ * Adapters are NOT responsible for: key normalization, caching, bulk registration,
+ * level resolution, or WebSocket handling. Those remain in the core client.
+ */
+interface LoggingAdapter {
+    /** Human-readable adapter name for diagnostics (e.g., 'winston'). */
+    readonly name: string;
+    /**
+     * Scan the runtime for existing loggers.
+     * Returns an array of { name, level } where level is a smplkit level string.
+     */
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    /**
+     * Set the level on a specific logger.
+     * @param loggerName - The original (non-normalized) logger name.
+     * @param level - smplkit level string (e.g., 'DEBUG', 'INFO', 'WARN').
+     */
+    applyLevel(loggerName: string, level: string): void;
+    /**
+     * Install continuous discovery hook.
+     * The callback receives (original_name, smplkit_level_string) whenever
+     * a new logger is created in the framework.
+     */
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    /** Remove the hook installed by installHook(). Called on client close(). */
+    uninstallHook(): void;
+}
+
 /**
  * LoggingClient — management plane + scaffolded runtime for Smpl Logging.
  *
@@ -979,8 +1015,17 @@ declare class LoggingClient {
     private _started;
     private _globalListeners;
     private _keyListeners;
+    private _adapters;
+    private _explicitAdapters;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
+    /**
+     * Register a logging framework adapter.
+     *
+     * Must be called before `start()`. Disables auto-loading of built-in
+     * adapters — only explicitly registered adapters will be used.
+     */
+    registerAdapter(adapter: LoggingAdapter): void;
     /** Create an unsaved logger. Call `.save()` to persist. */
     new(key: string, options?: {
         name?: string;
@@ -1010,11 +1055,17 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * Fetches existing loggers/groups and wires WebSocket listeners for
-     * live updates. Idempotent — safe to call multiple times.
+     * Performs the full runtime pipeline:
+     *   1. Auto-load adapters (if none registered explicitly)
+     *   2. Discover existing loggers from each adapter
+     *   3. Install hooks on each adapter for new logger creation
+     *   4. Bulk-register discovered loggers with the server
+     *   5. Fetch all loggers and groups from the server
+     *   6. Resolve levels and apply to adapters
+     *   7. Wire WebSocket for live updates
      *
-     * Note: Node.js auto-discovery (equivalent to Python's logging module
-     * monkey-patching) is deferred. Management methods work without start().
+     * Idempotent — safe to call multiple times.
+     * Management methods work without start().
      */
     start(): Promise<void>;
     /**
@@ -1026,6 +1077,12 @@ declare class LoggingClient {
     onChange(callbackOrKey: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
     /** @internal */
     _close(): void;
+    /** Auto-load built-in adapters by attempting to require each framework. */
+    private _autoLoadAdapters;
+    /** Apply resolved levels from server loggers to all adapters. */
+    private _applyLevels;
+    /** Called by adapter hooks when a new logger is created in the framework. */
+    private _onAdapterNewLogger;
     private _handleLoggerChanged;
     private _loggerToModel;
     private _groupToModel;
@@ -1109,6 +1166,68 @@ declare class SmplClient {
     close(): void;
 }
 
+/**
+ * Winston logging framework adapter.
+ *
+ * Bridges the smplkit logging runtime to winston's logger container.
+ * Discovers loggers via `winston.loggers` (the Container), hooks into
+ * new logger creation by monkey-patching `Container.add()`, and applies
+ * levels by setting `logger.level` on the winston logger instance.
+ */
+
+interface WinstonAdapterConfig {
+    /** Whether to include the default logger in discovery (default: true). */
+    discoverDefault?: boolean;
+    /** @internal — inject a winston module for testing. */
+    _winston?: unknown;
+}
+declare class WinstonAdapter implements LoggingAdapter {
+    readonly name = "winston";
+    private readonly _discoverDefault;
+    private _winston;
+    private _originalAdd;
+    constructor(config?: WinstonAdapterConfig);
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    applyLevel(loggerName: string, level: string): void;
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    uninstallHook(): void;
+}
+
+/**
+ * Pino logging framework adapter.
+ *
+ * Pino has no global logger registry. This adapter builds its own internal
+ * registry by monkey-patching the pino module's default export and the
+ * `child()` method on created loggers. Logger instances are tracked via
+ * WeakRef to avoid memory leaks.
+ */
+
+interface PinoAdapterConfig {
+    /** Which binding field to use as the logger name (default: 'name'). */
+    nameField?: string;
+    /** @internal — inject a pino module for testing. */
+    _pino?: unknown;
+}
+declare class PinoAdapter implements LoggingAdapter {
+    readonly name = "pino";
+    private readonly _nameField;
+    private _pino;
+    private _registry;
+    private _originalPino;
+    private _pinoModule;
+    constructor(config?: PinoAdapterConfig);
+    discover(): Array<{
+        name: string;
+        level: string;
+    }>;
+    applyLevel(loggerName: string, level: string): void;
+    installHook(onNewLogger: (name: string, level: string) => void): void;
+    uninstallHook(): void;
+}
+
 /**
  * Structured SDK error types.
  *
@@ -1155,4 +1274,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, LoggingClient, NumberFlag, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag };
+export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, type LoggingAdapter, LoggingClient, NumberFlag, PinoAdapter, type PinoAdapterConfig, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag, WinstonAdapter, type WinstonAdapterConfig };