@smplkit/sdk 1.3.23 → 1.3.24

package/dist/index.d.cts

@@ -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;
@@ -66,7 +51,7 @@ 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.
@@ -118,23 +103,17 @@ declare class Config {
 
 /**
  * LiveConfigProxy — live configuration access.
- *
- * Property reads always return the latest resolved values. When the
- * underlying config changes, subsequent reads automatically reflect
- * the new values.
  */
 
 /**
- * A live proxy that auto-updates when the underlying config changes.
- *
- * Access properties directly — each read returns the latest resolved value.
+ * 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>> {
@@ -163,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`.
  */
@@ -207,15 +186,13 @@ declare class ConfigClient {
     /**
      * Resolve a config's values for the current environment.
      *
-     * Returns a flat dict of resolved key-value pairs with inherited
-     * values and environment overrides applied.
-     *
+     * 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.
      */
@@ -229,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 and re-resolve values.
-     * 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 */
@@ -487,7 +464,7 @@ declare class Context {
     toString(): string;
 }
 /**
- * Fluent builder for JSON Logic rule dicts.
+ * Fluent builder for flag targeting rules.
  *
  * @example
  * ```typescript
@@ -498,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;
@@ -518,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 (creates if new, updates if existing).
- * Runtime: call `get()` to evaluate the flag locally.
+ * Call `save()` to persist changes. Call `get()` to evaluate the flag.
  */
 declare class Flag {
     /** UUID of the flag, or `null` if unsaved. */
@@ -581,24 +552,24 @@ declare class Flag {
      */
     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.
+     * 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[];
@@ -633,7 +604,7 @@ declare class JsonFlag extends Flag {
 }
 
 /**
- * FlagsClient — management + prescriptive runtime for Smpl Flags.
+ * FlagsClient — management and runtime for Smpl Flags.
  */
 
 type FlagResource = components["schemas"]["FlagResource"];
@@ -643,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`.
  */
@@ -746,40 +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;
     /**
      * Register context(s) with the server.
      *
-     * Accepts a single Context or an array. Registration is asynchronous
-     * and 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>;
     /**
      * Evaluate a flag with an explicit environment and context.
-     *
-     * Stateless — does not use the context provider or cached results.
      */
     evaluate(key: string, options: {
         environment: string;
@@ -831,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,15 +843,15 @@ declare class Logger {
      * 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,15 +898,15 @@ declare class LogGroup {
      * 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;
@@ -948,17 +914,14 @@ declare class LogGroup {
 }
 
 /**
- * Contract for pluggable logging framework integration.
- *
- * Adapters bridge the smplkit logging runtime to a specific logging
- * framework (e.g., Winston, Pino).
+ * 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;
@@ -966,26 +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.
+ * 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`.
  */
@@ -1013,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. */
@@ -1046,18 +1008,15 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * Discovers loggers from registered adapters, syncs them with the
-     * server, applies server-side log levels, and subscribes to live
-     * level 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;
@@ -1154,10 +1113,6 @@ declare class SmplClient {
 
 /**
  * Winston logging framework adapter.
- *
- * Integrates the smplkit logging runtime with Winston. Discovers
- * existing loggers, tracks new logger creation, and applies
- * server-managed log levels.
  */
 
 interface WinstonAdapterConfig {
@@ -1183,9 +1138,6 @@ declare class WinstonAdapter implements LoggingAdapter {
 
 /**
  * Pino logging framework adapter.
- *
- * Integrates the smplkit logging runtime with Pino. Tracks logger
- * instances (including child loggers) for discovery and level control.
  */
 
 interface PinoAdapterConfig {