@smplkit/sdk 1.3.22 → 1.3.24

package/dist/index.d.ts

@@ -1,24 +1,9 @@
 /**
- * Shared WebSocket connection to the app service event gateway.
- *
- * A single {@link SharedWebSocket} instance is shared across all product
- * modules (config, flags) within one {@link SmplClient}.  Product modules
- * register listeners for specific event types; the shared connection
- * dispatches incoming events to the appropriate listeners.
- *
- * Protocol:
- * - Connect to `wss://app.smplkit.com/api/ws/v1/events?api_key={key}`
- * - Receive `{"type": "connected"}` on success
- * - Receive events: `{"event": "config_changed", ...}`, `{"event": "flag_changed", ...}`
- * - No subscribe message — the API key determines the account
- * - Heartbeat: server sends `ping`, client responds with `pong`
- * - Reconnect with exponential backoff
+ * Shared WebSocket connection for real-time event delivery.
  */
 type EventCallback = (data: Record<string, any>) => void;
 /**
- * Manages a single WebSocket connection to the app service event gateway.
- *
- * Shared across config and flags modules for efficient multiplexing.
+ * Manages a WebSocket connection for real-time event delivery.
  */
 declare class SharedWebSocket {
     private readonly _appBaseUrl;
@@ -53,7 +38,7 @@ declare class SharedWebSocket {
  * A configuration resource managed by the smplkit platform.
  *
  * Management: mutate properties directly and call `save()` to persist.
- * POST if `id` is null (new), PUT if `id` is set (update).
+ * Creates if new, updates if existing.
  */
 declare class Config {
     /** UUID of the config, or `null` if unsaved. */
@@ -66,12 +51,11 @@ declare class Config {
     description: string | null;
     /** Parent config UUID, or null if this is a root config. */
     parent: string | null;
-    /** Base key-value pairs (unwrapped from typed item definitions). */
+    /** Base key-value pairs. */
     items: Record<string, unknown>;
     /**
      * Per-environment overrides.
-     * Stored as `{ env_name: { values: { key: value } } }` — values are
-     * unwrapped from the server's `{ value: raw }` wrapper.
+     * Structured as `{ env_name: { values: { key: value } } }`.
      */
     environments: Record<string, unknown>;
     /** When the config was created, or null if unavailable. */
@@ -95,7 +79,7 @@ declare class Config {
     /**
      * Persist this config to the server.
      *
-     * POST if `id` is null (new config), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
@@ -118,24 +102,18 @@ declare class Config {
 }
 
 /**
- * LiveConfigProxy — ES6 Proxy-based live configuration access.
- *
- * Property reads are delegated to the latest resolved values in the
- * ConfigClient cache. When the cache updates via WebSocket, subsequent
- * reads automatically reflect the new values.
+ * LiveConfigProxy — live configuration access.
  */
 
 /**
- * A live proxy that auto-updates when the underlying config changes.
- *
- * Access properties directly — each read re-resolves from the cache.
+ * A live proxy whose properties always reflect the latest config values.
  *
  * @example
  * ```typescript
  * const proxy = await client.config.subscribe("user-service");
- * console.log(proxy.timeout);  // reads from live cache
- * // ... later, after a WebSocket update ...
- * console.log(proxy.timeout);  // reads the updated value
+ * console.log(proxy.timeout);  // current value
+ * // ... later, after a config change ...
+ * console.log(proxy.timeout);  // updated value
  * ```
  */
 declare class LiveConfigProxy<T = Record<string, unknown>> {
@@ -164,7 +142,7 @@ interface ConfigChangeEvent {
     source: "websocket" | "manual";
 }
 /**
- * Client for the smplkit Config API — management plane + runtime.
+ * Client for the smplkit Config API.
  *
  * Obtained via `SmplClient.config`.
  */
@@ -208,15 +186,13 @@ declare class ConfigClient {
     /**
      * Resolve a config's values for the current environment.
      *
-     * Returns a flat dict of resolved key-value pairs, walking the
-     * parent chain and applying environment overrides.
-     *
+     * Returns the resolved key-value pairs for the given config.
      * Optionally pass a model class to map the resolved values.
      */
     resolve<T = Record<string, unknown>>(key: string, model?: new (data: any) => T): Promise<T>;
     /**
-     * Subscribe to a config's values — returns a live proxy that
-     * auto-updates when the underlying config changes.
+     * Subscribe to a config's values. Returns a proxy whose properties
+     * always reflect the latest resolved values.
      *
      * Optionally pass a model class to map the resolved values.
      */
@@ -230,8 +206,8 @@ declare class ConfigClient {
      */
     onChange(callbackOrConfigKey: string | ((event: ConfigChangeEvent) => void), callbackOrItemKey?: string | ((event: ConfigChangeEvent) => void), callback?: (event: ConfigChangeEvent) => void): void;
     /**
-     * Re-fetch all configs, re-resolve values, and update the cache.
-     * Fires change listeners for any values that differ.
+     * Refresh all config values from the server.
+     * Fires change listeners for any values that changed.
      */
     refresh(): Promise<void>;
     /** @internal */
@@ -488,7 +464,7 @@ declare class Context {
     toString(): string;
 }
 /**
- * Fluent builder for JSON Logic rule dicts.
+ * Fluent builder for flag targeting rules.
  *
  * @example
  * ```typescript
@@ -499,8 +475,7 @@ declare class Context {
  *     .build()
  * ```
  *
- * Multiple `.when()` calls are AND'd.  `.environment()` tags the
- * built dict with an environment key for use with `Flag.addRule()`.
+ * Multiple `.when()` calls are combined with AND logic.
  */
 declare class Rule {
     private _description;
@@ -519,18 +494,13 @@ declare class Rule {
 }
 
 /**
- * Unified Flag hierarchy — management model + runtime handle.
- *
- * A single {@link Flag} class replaces the old separate Flag + FlagHandle
- * classes. Typed subclasses ({@link BooleanFlag}, {@link StringFlag},
- * {@link NumberFlag}, {@link JsonFlag}) override `get()` for type safety.
+ * Flag model hierarchy with typed subclasses for type-safe evaluation.
  */
 
 /**
- * A flag resource that doubles as a runtime handle.
+ * A flag resource.
  *
- * Management: call `save()` to persist (POST if new, PUT if existing).
- * Runtime: call `get()` for local JSON Logic evaluation.
+ * Call `save()` to persist changes. Call `get()` to evaluate the flag.
  */
 declare class Flag {
     /** UUID of the flag, or `null` if unsaved. */
@@ -577,29 +547,29 @@ declare class Flag {
     /**
      * Persist this flag to the server.
      *
-     * POST if `id` is null (new flag), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
     /**
-     * Add a rule to a specific environment (sync local mutation).
+     * Add a rule to a specific environment.
      *
      * The built rule must include an `environment` key (set via
-     * `Rule(...).environment("env_key")`). No HTTP call is made.
+     * `Rule(...).environment("env_key")`). Call `save()` to persist.
      *
      * @returns `this` for chaining.
      */
     addRule(builtRule: Record<string, any>): Flag;
-    /** Enable or disable a flag in a specific environment (sync local mutation). */
+    /** Enable or disable a flag in a specific environment. Call `save()` to persist. */
     setEnvironmentEnabled(envKey: string, enabled: boolean): void;
-    /** Set the default value for a specific environment (sync local mutation). */
+    /** Set the default value for a specific environment. Call `save()` to persist. */
     setEnvironmentDefault(envKey: string, defaultValue: unknown): void;
-    /** Clear all rules for a specific environment (sync local mutation). */
+    /** Clear all rules for a specific environment. Call `save()` to persist. */
     clearRules(envKey: string): void;
     /**
-     * Evaluate the flag locally (sync, no HTTP).
+     * Evaluate the flag and return its current value.
      *
-     * Requires `initialize()` to have been called.
+     * Requires `initialize()` to have been called on the flags client.
      */
     get(options?: {
         context?: Context[];
@@ -634,11 +604,7 @@ declare class JsonFlag extends Flag {
 }
 
 /**
- * FlagsClient — management + prescriptive runtime for Smpl Flags.
- *
- * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
- * `openapi-fetch` for all flag HTTP calls. Context registration uses
- * the generated app service types (`src/generated/app.d.ts`).
+ * FlagsClient — management and runtime for Smpl Flags.
  */
 
 type FlagResource = components["schemas"]["FlagResource"];
@@ -648,14 +614,14 @@ declare class FlagChangeEvent {
     readonly source: string;
     constructor(key: string, source: string);
 }
-/** Cache statistics for the flags runtime. */
+/** Evaluation statistics for the flags runtime. */
 declare class FlagStats {
     readonly cacheHits: number;
     readonly cacheMisses: number;
     constructor(cacheHits: number, cacheMisses: number);
 }
 /**
- * Client for the smplkit Flags API — management plane + prescriptive runtime.
+ * Client for the smplkit Flags API.
  *
  * Obtained via `SmplClient.flags`.
  */
@@ -751,38 +717,37 @@ declare class FlagsClient {
      */
     contextProvider(fn: () => Context[]): () => Context[];
     /**
-     * Initialize the flags runtime: fetch definitions and wire WebSocket.
+     * Initialize the flags runtime.
      *
      * Idempotent — safe to call multiple times. Must be called (and awaited)
      * before using `.get()` on flag handles.
      */
     initialize(): Promise<void>;
-    /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
+    /** Disconnect the flags runtime and release resources. */
     disconnect(): Promise<void>;
-    /** Re-fetch all flag definitions and clear cache. */
+    /** Refresh all flag definitions from the server. */
     refresh(): Promise<void>;
-    /** Return the current WebSocket connection status. */
+    /** Return the current real-time connection status. */
     connectionStatus(): string;
-    /** Return cache statistics. */
+    /** Return evaluation statistics. */
     stats(): FlagStats;
     /**
      * Register a change listener.
      *
-     * - `onChange(callback)` — fires for any flag change (global).
+     * - `onChange(callback)` — fires for any flag change.
      * - `onChange(key, callback)` — fires only for the specified flag key.
      */
     onChange(callbackOrKey: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
     /**
-     * Explicitly register context(s) for background batch registration.
+     * Register context(s) with the server.
      *
-     * Accepts a single Context or an array. Fire-and-forget — never
-     * blocks. Works before `initialize()` is called.
+     * Accepts a single Context or an array. Works before `initialize()` is called.
      */
     register(context: Context | Context[]): void;
     /** Flush pending context registrations to the server. */
     flushContexts(): Promise<void>;
     /**
-     * Tier 1 explicit evaluation — stateless, no provider or cache.
+     * Evaluate a flag with an explicit environment and context.
      */
     evaluate(key: string, options: {
         environment: string;
@@ -834,9 +799,7 @@ interface LoggerChangeEvent {
 /**
  * A logger resource managed by the smplkit platform.
  *
- * Management: mutate properties and call `save()` to persist.
- * Convenience methods (`setLevel`, `setEnvironmentLevel`, etc.) are
- * sync local mutations — no HTTP until `save()`.
+ * Mutate properties or use convenience methods, then call `save()` to persist.
  */
 declare class Logger {
     /** UUID of the logger, or `null` if unsaved. */
@@ -877,18 +840,18 @@ declare class Logger {
     /**
      * Persist this logger to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
-    /** Set the base log level (sync local mutation). */
+    /** Set the base log level. Call `save()` to persist. */
     setLevel(level: LogLevel): void;
-    /** Clear the base log level (sync local mutation). */
+    /** Clear the base log level. Call `save()` to persist. */
     clearLevel(): void;
-    /** Set an environment-specific log level (sync local mutation). */
+    /** Set an environment-specific log level. Call `save()` to persist. */
     setEnvironmentLevel(env: string, level: LogLevel): void;
-    /** Clear an environment-specific log level (sync local mutation). */
+    /** Clear an environment-specific log level. Call `save()` to persist. */
     clearEnvironmentLevel(env: string): void;
-    /** Clear all environment-specific log levels (sync local mutation). */
+    /** Clear all environment-specific log levels. Call `save()` to persist. */
     clearAllEnvironmentLevels(): void;
     /** @internal — copy all fields from another Logger instance. */
     _apply(other: Logger): void;
@@ -932,18 +895,18 @@ declare class LogGroup {
     /**
      * Persist this log group to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
-    /** Set the base log level (sync local mutation). */
+    /** Set the base log level. Call `save()` to persist. */
     setLevel(level: LogLevel): void;
-    /** Clear the base log level (sync local mutation). */
+    /** Clear the base log level. Call `save()` to persist. */
     clearLevel(): void;
-    /** Set an environment-specific log level (sync local mutation). */
+    /** Set an environment-specific log level. Call `save()` to persist. */
     setEnvironmentLevel(env: string, level: LogLevel): void;
-    /** Clear an environment-specific log level (sync local mutation). */
+    /** Clear an environment-specific log level. Call `save()` to persist. */
     clearEnvironmentLevel(env: string): void;
-    /** Clear all environment-specific log levels (sync local mutation). */
+    /** Clear all environment-specific log levels. Call `save()` to persist. */
     clearAllEnvironmentLevels(): void;
     /** @internal — copy all fields from another LogGroup instance. */
     _apply(other: LogGroup): void;
@@ -951,20 +914,14 @@ declare class LogGroup {
 }
 
 /**
- * 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.
+ * Contract for logging framework adapters.
  */
 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.
+     * Return all existing loggers known to the framework.
+     * Each entry contains a name and a level string.
      */
     discover(): Array<{
         name: string;
@@ -972,29 +929,25 @@ interface LoggingAdapter {
     }>;
     /**
      * Set the level on a specific logger.
-     * @param loggerName - The original (non-normalized) logger name.
+     * @param loggerName - The 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.
+     * Install a hook that fires whenever a new logger is created in the framework.
+     * The callback receives the logger name and level string.
      */
     installHook(onNewLogger: (name: string, level: string) => void): void;
-    /** Remove the hook installed by installHook(). Called on client close(). */
+    /** Remove the hook installed by `installHook()`. */
     uninstallHook(): void;
 }
 
 /**
- * LoggingClient — management plane + scaffolded runtime for Smpl Logging.
- *
- * Uses the generated OpenAPI types (`src/generated/logging.d.ts`) via
- * `openapi-fetch` for all HTTP calls.
+ * LoggingClient — management and runtime for Smpl Logging.
  */
 
 /**
- * Client for the smplkit Logging API — management plane + scaffolded runtime.
+ * Client for the smplkit Logging API.
  *
  * Obtained via `SmplClient.logging`.
  */
@@ -1022,8 +975,8 @@ declare class LoggingClient {
     /**
      * Register a logging framework adapter.
      *
-     * Must be called before `start()`. Disables auto-loading of built-in
-     * adapters — only explicitly registered adapters will be used.
+     * Must be called before `start()`. When called, only explicitly
+     * registered adapters will be used.
      */
     registerAdapter(adapter: LoggingAdapter): void;
     /** Create an unsaved logger. Call `.save()` to persist. */
@@ -1055,23 +1008,15 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * 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
-     *
-     * Idempotent — safe to call multiple times.
-     * Management methods work without start().
+     * Synchronizes loggers with the server and subscribes to live level
+     * updates. Idempotent — safe to call multiple times.
+     * Management methods work without calling `start()`.
      */
     start(): Promise<void>;
     /**
      * Register a change listener.
      *
-     * - `onChange(callback)` — fires for any logger change (global).
+     * - `onChange(callback)` — fires for any logger change.
      * - `onChange(key, callback)` — fires only for the specified logger key.
      */
     onChange(callbackOrKey: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
@@ -1168,11 +1113,6 @@ declare class SmplClient {
 
 /**
  * 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 {
@@ -1198,11 +1138,6 @@ declare class WinstonAdapter implements LoggingAdapter {
 
 /**
  * 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 {