@smplkit/sdk 1.3.22 → 1.3.24

package/dist/index.cjs

@@ -16804,12 +16804,11 @@ var Config = class {
   description;
   /** Parent config UUID, or null if this is a root config. */
   parent;
-  /** Base key-value pairs (unwrapped from typed item definitions). */
+  /** Base key-value pairs. */
   items;
   /**
    * 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;
   /** When the config was created, or null if unavailable. */
@@ -16834,7 +16833,7 @@ var Config = class {
   /**
    * 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.
    */
   async save() {
@@ -17212,9 +17211,7 @@ var ConfigClient = class {
   /**
    * 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.
    */
   async resolve(key, model) {
@@ -17229,8 +17226,8 @@ var ConfigClient = class {
     return values;
   }
   /**
-   * 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.
    */
@@ -17276,8 +17273,8 @@ var ConfigClient = class {
   // Runtime: refresh
   // ------------------------------------------------------------------
   /**
-   * 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.
    */
   async refresh() {
     if (!this._initialized) {
@@ -17442,7 +17439,7 @@ var Flag = class {
   /**
    * 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.
    */
   async save() {
@@ -17455,10 +17452,10 @@ var Flag = class {
     }
   }
   /**
-   * 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.
    */
@@ -17479,7 +17476,7 @@ var Flag = class {
     this.environments = envs;
     return this;
   }
-  /** 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, enabled) {
     const envs = { ...this.environments };
     const envData = { ...envs[envKey] ?? { enabled: false, rules: [] } };
@@ -17487,7 +17484,7 @@ var Flag = class {
     envs[envKey] = envData;
     this.environments = envs;
   }
-  /** 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, defaultValue) {
     const envs = { ...this.environments };
     const envData = { ...envs[envKey] ?? { enabled: false, rules: [] } };
@@ -17495,7 +17492,7 @@ var Flag = class {
     envs[envKey] = envData;
     this.environments = envs;
   }
-  /** Clear all rules for a specific environment (sync local mutation). */
+  /** Clear all rules for a specific environment. Call `save()` to persist. */
   clearRules(envKey) {
     const envs = { ...this.environments };
     const envData = envs[envKey];
@@ -17505,9 +17502,9 @@ var Flag = class {
     }
   }
   /**
-   * 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) {
     return this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
@@ -18049,7 +18046,7 @@ var FlagsClient = class {
   // Runtime: initialize / disconnect / refresh
   // ------------------------------------------------------------------
   /**
-   * 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.
@@ -18064,7 +18061,7 @@ var FlagsClient = class {
     this._wsManager.on("flag_changed", this._handleFlagChanged);
     this._wsManager.on("flag_deleted", this._handleFlagDeleted);
   }
-  /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
+  /** Disconnect the flags runtime and release resources. */
   async disconnect() {
     if (this._wsManager !== null) {
       this._wsManager.off("flag_changed", this._handleFlagChanged);
@@ -18077,30 +18074,30 @@ var FlagsClient = class {
     this._initialized = false;
     this._environment = null;
   }
-  /** Re-fetch all flag definitions and clear cache. */
+  /** Refresh all flag definitions from the server. */
   async refresh() {
     await this._fetchAllFlags();
     this._cache.clear();
     this._fireChangeListenersAll("manual");
   }
-  /** Return the current WebSocket connection status. */
+  /** Return the current real-time connection status. */
   connectionStatus() {
     if (this._wsManager !== null) {
       return this._wsManager.connectionStatus;
     }
     return "disconnected";
   }
-  /** Return cache statistics. */
+  /** Return evaluation statistics. */
   stats() {
     return new FlagStats(this._cache.cacheHits, this._cache.cacheMisses);
   }
   // ------------------------------------------------------------------
-  // Runtime: change listeners (dual-mode)
+  // Runtime: change listeners
   // ------------------------------------------------------------------
   /**
    * 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, callback) {
@@ -18121,10 +18118,9 @@ var FlagsClient = class {
   // Runtime: context registration
   // ------------------------------------------------------------------
   /**
-   * 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) {
     if (Array.isArray(context)) {
@@ -18141,7 +18137,7 @@ var FlagsClient = class {
   // Runtime: Tier 1 evaluate
   // ------------------------------------------------------------------
   /**
-   * Tier 1 explicit evaluation — stateless, no provider or cache.
+   * Evaluate a flag with an explicit environment and context.
    */
   async evaluate(key, options) {
     const evalDict = contextsToEvalDict(options.context);
@@ -18384,27 +18380,27 @@ var Logger = class {
   /**
    * Persist this logger to the server.
    *
-   * POST if `id` is null (new), PUT if `id` is set (update).
+   * Creates if new, updates if existing.
    */
   async save() {
     const saved = await this._client._saveLogger(this);
     this._apply(saved);
   }
-  /** Set the base log level (sync local mutation). */
+  /** Set the base log level. Call `save()` to persist. */
   setLevel(level) {
     this.level = level;
   }
-  /** Clear the base log level (sync local mutation). */
+  /** Clear the base log level. Call `save()` to persist. */
   clearLevel() {
     this.level = null;
   }
-  /** Set an environment-specific log level (sync local mutation). */
+  /** Set an environment-specific log level. Call `save()` to persist. */
   setEnvironmentLevel(env, level) {
     const envs = { ...this.environments };
     envs[env] = { ...envs[env] ?? {}, level };
     this.environments = envs;
   }
-  /** Clear an environment-specific log level (sync local mutation). */
+  /** Clear an environment-specific log level. Call `save()` to persist. */
   clearEnvironmentLevel(env) {
     const envs = { ...this.environments };
     if (envs[env]) {
@@ -18414,7 +18410,7 @@ var Logger = class {
       this.environments = envs;
     }
   }
-  /** Clear all environment-specific log levels (sync local mutation). */
+  /** Clear all environment-specific log levels. Call `save()` to persist. */
   clearAllEnvironmentLevels() {
     this.environments = {};
   }
@@ -18469,27 +18465,27 @@ var LogGroup = class {
   /**
    * 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.
    */
   async save() {
     const saved = await this._client._saveLogGroup(this);
     this._apply(saved);
   }
-  /** Set the base log level (sync local mutation). */
+  /** Set the base log level. Call `save()` to persist. */
   setLevel(level) {
     this.level = level;
   }
-  /** Clear the base log level (sync local mutation). */
+  /** Clear the base log level. Call `save()` to persist. */
   clearLevel() {
     this.level = null;
   }
-  /** Set an environment-specific log level (sync local mutation). */
+  /** Set an environment-specific log level. Call `save()` to persist. */
   setEnvironmentLevel(env, level) {
     const envs = { ...this.environments };
     envs[env] = { ...envs[env] ?? {}, level };
     this.environments = envs;
   }
-  /** Clear an environment-specific log level (sync local mutation). */
+  /** Clear an environment-specific log level. Call `save()` to persist. */
   clearEnvironmentLevel(env) {
     const envs = { ...this.environments };
     if (envs[env]) {
@@ -18499,7 +18495,7 @@ var LogGroup = class {
       this.environments = envs;
     }
   }
-  /** Clear all environment-specific log levels (sync local mutation). */
+  /** Clear all environment-specific log levels. Call `save()` to persist. */
   clearAllEnvironmentLevels() {
     this.environments = {};
   }
@@ -18585,8 +18581,8 @@ var LoggingClient = class {
   /**
    * 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) {
     if (this._started) {
@@ -18813,17 +18809,9 @@ var LoggingClient = class {
   /**
    * 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()`.
    */
   async start() {
     if (this._started) return;
@@ -18864,12 +18852,12 @@ var LoggingClient = class {
     this._started = true;
   }
   // ------------------------------------------------------------------
-  // Runtime: change listeners (dual-mode)
+  // Runtime: change listeners
   // ------------------------------------------------------------------
   /**
    * 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, callback) {