@smplkit/sdk 3.0.1 → 3.0.3

package/dist/index.d.cts

@@ -1429,9 +1429,9 @@ declare class Config {
      */
     _buildChain(configs?: Config[]): Promise<Array<{
         id: string | null;
-        items: Record<string, Record<string, unknown>>;
+        items: Record<string, unknown>;
         environments: Record<string, {
-            values: Record<string, Record<string, unknown>>;
+            values: Record<string, unknown>;
         }>;
     }>>;
     toString(): string;
@@ -1549,6 +1549,13 @@ declare class FlagsClient {
      * before using `.get()` on flag handles.
      */
     initialize(): Promise<void>;
+    /**
+     * Synchronous teardown — clears the flag-flush interval and unsubscribes
+     * from WebSocket events. Called by `SmplClient.close()`. Does not flush
+     * pending context observations (use {@link disconnect} for that).
+     * @internal
+     */
+    _close(): void;
     /** Disconnect the flags runtime and release resources. */
     disconnect(): Promise<void>;
     /** Refresh all flag definitions from the server. */
@@ -2409,6 +2416,11 @@ declare class ConfigClient {
     /** @internal — resolves the management config sub-client used by lazy-init/refresh. */
     _resolveManagement?: () => SmplManagementClient;
     private _configCache;
+    /** Raw Config objects keyed by id, kept around so a single-config
+     * change (WS event) can refetch one config and rebuild the resolved
+     * cache for everyone (including descendants that inherit from it)
+     * without a full re-list. Mirrors Python's `_raw_config_cache`. */
+    private _configStore;
     private _initialized;
     private _listeners;
     /** @internal */
@@ -2464,12 +2476,10 @@ declare class ConfigClient {
     /** @internal — get resolved config from cache. Used by LiveConfigProxy. */
     _getCachedConfig(key: string): Record<string, unknown> | undefined;
     private _handleConfigChanged;
-    private _handleConfigDeleted;
-    private _handleConfigsChanged;
     /** Fetch a single config by key. Returns null if not found. @internal */
     private _fetchSingleConfig;
-    /** Resolve a config's values for an environment (no parent chain). @internal */
-    private _resolveConfigValues;
+    private _handleConfigDeleted;
+    private _handleConfigsChanged;
     /** @internal */
     private _diffAndFire;
 }
@@ -2565,8 +2575,32 @@ declare class LoggingClient {
      * `install()`.
      *
      * Mirrors Python's `client.logging.install()`. There is no `stop()`.
+     *
+     * Adapter coverage:
+     * - **winston**: pre-existing named loggers (`winston.loggers.*`) and the
+     *   default logger are auto-discovered.
+     * - **pino**: pino has no global registry, so only loggers created
+     *   through `pino()` / `logger.child()` *after* `install()` runs are
+     *   tracked. To bring pre-existing pino loggers under management, recreate
+     *   them after install or register them explicitly via
+     *   `client.manage.loggers.register([...])`.
+     *
+     * After the initial pass, call {@link refresh} to re-fetch managed levels
+     * from the server and re-apply them onto the native loggers (e.g. after
+     * suspecting drift, or to force a manual sync outside the WebSocket).
      */
     install(): Promise<void>;
+    /**
+     * Re-fetch logger and group levels from the server and re-apply them
+     * onto the registered adapters.
+     *
+     * Diff-based: change listeners only fire for loggers whose level
+     * actually changed (added, removed, or different level), with
+     * `source: "manual"`. Mirrors Python's `client.logging.refresh()`.
+     *
+     * @throws SmplError if `install()` has not been called.
+     */
+    refresh(): Promise<void>;
     /**
      * @deprecated Use {@link LoggingClient.install}. Retained as a backwards-
      * compatible alias.
@@ -2596,6 +2630,14 @@ declare class LoggingClient {
     private _handleGroupChanged;
     private _handleGroupDeleted;
     private _handleLoggersChanged;
+    /**
+     * Full refetch of loggers + log_groups, apply resolved levels to
+     * adapters, diff against local stores and fire change listeners
+     * (global once, per-key for each changed id). Shared between the
+     * `loggers_changed` WS handler and the public `refresh()` method.
+     * @internal
+     */
+    private _resolveAndFire;
     /** Fetch a single logger by key. Returns null if not found. @internal */
     private _fetchSingleLogger;
     /** Fetch a single log group by key. Returns null if not found. @internal */

package/dist/index.d.ts

@@ -1429,9 +1429,9 @@ declare class Config {
      */
     _buildChain(configs?: Config[]): Promise<Array<{
         id: string | null;
-        items: Record<string, Record<string, unknown>>;
+        items: Record<string, unknown>;
         environments: Record<string, {
-            values: Record<string, Record<string, unknown>>;
+            values: Record<string, unknown>;
         }>;
     }>>;
     toString(): string;
@@ -1549,6 +1549,13 @@ declare class FlagsClient {
      * before using `.get()` on flag handles.
      */
     initialize(): Promise<void>;
+    /**
+     * Synchronous teardown — clears the flag-flush interval and unsubscribes
+     * from WebSocket events. Called by `SmplClient.close()`. Does not flush
+     * pending context observations (use {@link disconnect} for that).
+     * @internal
+     */
+    _close(): void;
     /** Disconnect the flags runtime and release resources. */
     disconnect(): Promise<void>;
     /** Refresh all flag definitions from the server. */
@@ -2409,6 +2416,11 @@ declare class ConfigClient {
     /** @internal — resolves the management config sub-client used by lazy-init/refresh. */
     _resolveManagement?: () => SmplManagementClient;
     private _configCache;
+    /** Raw Config objects keyed by id, kept around so a single-config
+     * change (WS event) can refetch one config and rebuild the resolved
+     * cache for everyone (including descendants that inherit from it)
+     * without a full re-list. Mirrors Python's `_raw_config_cache`. */
+    private _configStore;
     private _initialized;
     private _listeners;
     /** @internal */
@@ -2464,12 +2476,10 @@ declare class ConfigClient {
     /** @internal — get resolved config from cache. Used by LiveConfigProxy. */
     _getCachedConfig(key: string): Record<string, unknown> | undefined;
     private _handleConfigChanged;
-    private _handleConfigDeleted;
-    private _handleConfigsChanged;
     /** Fetch a single config by key. Returns null if not found. @internal */
     private _fetchSingleConfig;
-    /** Resolve a config's values for an environment (no parent chain). @internal */
-    private _resolveConfigValues;
+    private _handleConfigDeleted;
+    private _handleConfigsChanged;
     /** @internal */
     private _diffAndFire;
 }
@@ -2565,8 +2575,32 @@ declare class LoggingClient {
      * `install()`.
      *
      * Mirrors Python's `client.logging.install()`. There is no `stop()`.
+     *
+     * Adapter coverage:
+     * - **winston**: pre-existing named loggers (`winston.loggers.*`) and the
+     *   default logger are auto-discovered.
+     * - **pino**: pino has no global registry, so only loggers created
+     *   through `pino()` / `logger.child()` *after* `install()` runs are
+     *   tracked. To bring pre-existing pino loggers under management, recreate
+     *   them after install or register them explicitly via
+     *   `client.manage.loggers.register([...])`.
+     *
+     * After the initial pass, call {@link refresh} to re-fetch managed levels
+     * from the server and re-apply them onto the native loggers (e.g. after
+     * suspecting drift, or to force a manual sync outside the WebSocket).
      */
     install(): Promise<void>;
+    /**
+     * Re-fetch logger and group levels from the server and re-apply them
+     * onto the registered adapters.
+     *
+     * Diff-based: change listeners only fire for loggers whose level
+     * actually changed (added, removed, or different level), with
+     * `source: "manual"`. Mirrors Python's `client.logging.refresh()`.
+     *
+     * @throws SmplError if `install()` has not been called.
+     */
+    refresh(): Promise<void>;
     /**
      * @deprecated Use {@link LoggingClient.install}. Retained as a backwards-
      * compatible alias.
@@ -2596,6 +2630,14 @@ declare class LoggingClient {
     private _handleGroupChanged;
     private _handleGroupDeleted;
     private _handleLoggersChanged;
+    /**
+     * Full refetch of loggers + log_groups, apply resolved levels to
+     * adapters, diff against local stores and fire change listeners
+     * (global once, per-key for each changed id). Shared between the
+     * `loggers_changed` WS handler and the public `refresh()` method.
+     * @internal
+     */
+    private _resolveAndFire;
     /** Fetch a single logger by key. Returns null if not found. @internal */
     private _fetchSingleLogger;
     /** Fetch a single log group by key. Returns null if not found. @internal */

package/dist/index.js

@@ -16838,6 +16838,13 @@ function environmentsToWire(environments) {
   }
   return out;
 }
+function environmentsForResolver(environments) {
+  const out = {};
+  for (const [envId, env] of Object.entries(environments)) {
+    out[envId] = { values: env.values };
+  }
+  return out;
+}
 var Config = class {
   id;
   name;
@@ -17027,8 +17034,8 @@ var Config = class {
     const chain = [
       {
         id: this.id,
-        items: this._itemsRaw,
-        environments: environmentsToWire(this._environments)
+        items: this.items,
+        environments: environmentsForResolver(this._environments)
       }
     ];
     let current = this;
@@ -17050,8 +17057,8 @@ var Config = class {
       }
       chain.push({
         id: parentConfig.id,
-        items: parentConfig._itemsRaw,
-        environments: environmentsToWire(parentConfig._environments)
+        items: parentConfig.items,
+        environments: environmentsForResolver(parentConfig._environments)
       });
       current = parentConfig;
     }
@@ -17063,6 +17070,22 @@ var Config = class {
 };
 
 // src/config/proxy.ts
+function _unflattenDotNotation(flat) {
+  const nested = {};
+  for (const [key, value] of Object.entries(flat)) {
+    const parts = key.split(".");
+    let current = nested;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (current[part] === void 0 || typeof current[part] !== "object" || current[part] === null) {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+  }
+  return nested;
+}
 var LiveConfigProxy = class {
   /** @internal */
   _client;
@@ -17085,7 +17108,8 @@ var LiveConfigProxy = class {
         }
         const values = target._currentValues();
         if (target._model) {
-          const instance = new target._model(values);
+          const nested = _unflattenDotNotation(values);
+          const instance = new target._model(nested);
           return instance[prop];
         }
         return values[prop];
@@ -17247,6 +17271,11 @@ var ConfigClient = class {
   /** @internal — resolves the management config sub-client used by lazy-init/refresh. */
   _resolveManagement;
   _configCache = {};
+  /** Raw Config objects keyed by id, kept around so a single-config
+   * change (WS event) can refetch one config and rebuild the resolved
+   * cache for everyone (including descendants that inherit from it)
+   * without a full re-list. Mirrors Python's `_raw_config_cache`. */
+  _configStore = {};
   _initialized = false;
   _listeners = [];
   /** @internal */
@@ -17355,12 +17384,15 @@ var ConfigClient = class {
     }
     const configs = await this._listConfigs();
     const newCache = {};
+    const newStore = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
       newCache[cfg.id] = resolveChain(chain, environment);
+      newStore[cfg.id] = cfg;
     }
     const oldCache = this._configCache;
     this._configCache = newCache;
+    this._configStore = newStore;
     this._diffAndFire(oldCache, newCache, "manual");
   }
   /**
@@ -17402,11 +17434,14 @@ var ConfigClient = class {
     }
     const configs = await this._listConfigs();
     const cache = {};
+    const store = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
       cache[cfg.id] = resolveChain(chain, environment);
+      store[cfg.id] = cfg;
     }
     this._configCache = cache;
+    this._configStore = store;
     this._initialized = true;
     if (this._getSharedWs) {
       const ws = this._getSharedWs();
@@ -17420,11 +17455,14 @@ var ConfigClient = class {
     if (this._initialized) return;
     const configs = await this._listConfigs();
     const cache = {};
+    const store = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
       cache[cfg.id] = resolveChain(chain, environment);
+      store[cfg.id] = cfg;
     }
     this._configCache = cache;
+    this._configStore = store;
     this._initialized = true;
   }
   /** @internal — get resolved config from cache. Used by LiveConfigProxy. */
@@ -17438,26 +17476,29 @@ var ConfigClient = class {
     debug("websocket", `config_changed event received: ${JSON.stringify(data)}`);
     const configKey = data.id;
     if (!configKey) return;
+    const environment = this._parent?._environment;
+    if (!environment) return;
     void this._fetchSingleConfig(configKey).then((newConfig) => {
-      const environment = this._parent?._environment;
-      if (!environment) return;
-      const oldValues = this._configCache[configKey];
-      let newValues;
-      if (newConfig !== null) {
-        newValues = this._resolveConfigValues(newConfig, environment);
-      } else {
-        newValues = {};
-      }
-      const oldJson = JSON.stringify(oldValues ?? {});
-      const newJson = JSON.stringify(newValues);
-      if (oldJson === newJson) return;
-      const oldCache = { ...this._configCache };
-      if (newConfig !== null) {
-        this._configCache[configKey] = newValues;
+      const newStore = { ...this._configStore };
+      if (newConfig === null) {
+        delete newStore[configKey];
       } else {
-        delete this._configCache[configKey];
-      }
-      this._diffAndFire(oldCache, this._configCache, "websocket");
+        newStore[configKey] = newConfig;
+      }
+      const allConfigs = Object.values(newStore);
+      return Promise.all(
+        allConfigs.map(async (cfg) => {
+          const chain = await cfg._buildChain(allConfigs);
+          return [cfg.id, resolveChain(chain, environment)];
+        })
+      ).then((entries) => ({ entries, newStore }));
+    }).then(({ entries, newStore }) => {
+      const newCache = {};
+      for (const [id, values] of entries) newCache[id] = values;
+      const oldCache = this._configCache;
+      this._configCache = newCache;
+      this._configStore = newStore;
+      this._diffAndFire(oldCache, newCache, "websocket");
     }).catch((err) => {
       debug(
         "websocket",
@@ -17465,6 +17506,20 @@ var ConfigClient = class {
       );
     });
   };
+  /** Fetch a single config by key. Returns null if not found. @internal */
+  async _fetchSingleConfig(key) {
+    debug("api", `GET /api/v1/configs/${key}`);
+    try {
+      const result = await this._http.GET("/api/v1/configs/{id}", {
+        params: { path: { id: key } }
+      });
+      if (!result.response.ok) return null;
+      if (!result.data?.data) return null;
+      return resourceToConfig(result.data.data);
+    } catch {
+      return null;
+    }
+  }
   _handleConfigDeleted = (data) => {
     debug("websocket", `config_deleted event received: ${JSON.stringify(data)}`);
     const configKey = data.id;
@@ -17483,27 +17538,6 @@ var ConfigClient = class {
   // ------------------------------------------------------------------
   // Internal: change detection
   // ------------------------------------------------------------------
-  /** Fetch a single config by key. Returns null if not found. @internal */
-  async _fetchSingleConfig(key) {
-    debug("api", `GET /api/v1/configs/${key}`);
-    try {
-      const result = await this._http.GET("/api/v1/configs/{id}", {
-        params: { path: { id: key } }
-      });
-      if (!result.response.ok) return null;
-      if (!result.data?.data) return null;
-      return resourceToConfig(result.data.data);
-    } catch {
-      return null;
-    }
-  }
-  /** Resolve a config's values for an environment (no parent chain). @internal */
-  _resolveConfigValues(config, environment) {
-    const base = config.items ?? {};
-    const envEntry = config.environments?.[environment];
-    if (!envEntry?.values) return { ...base };
-    return { ...base, ...envEntry.values };
-  }
   /** @internal */
   _diffAndFire(oldCache, newCache, source) {
     const allConfigKeys = /* @__PURE__ */ new Set([...Object.keys(oldCache), ...Object.keys(newCache)]);
@@ -20456,6 +20490,30 @@ var FlagsClient = class {
     this._flagFlushTimer = setInterval(() => {
       void this._flushFlags();
     }, FLAG_REGISTRATION_FLUSH_INTERVAL_MS);
+    if (typeof this._flagFlushTimer === "object" && "unref" in this._flagFlushTimer) {
+      this._flagFlushTimer.unref();
+    }
+  }
+  /**
+   * Synchronous teardown — clears the flag-flush interval and unsubscribes
+   * from WebSocket events. Called by `SmplClient.close()`. Does not flush
+   * pending context observations (use {@link disconnect} for that).
+   * @internal
+   */
+  _close() {
+    if (this._flagFlushTimer !== null) {
+      clearInterval(this._flagFlushTimer);
+      this._flagFlushTimer = null;
+    }
+    if (this._wsManager !== null) {
+      this._wsManager.off("flag_changed", this._handleFlagChanged);
+      this._wsManager.off("flag_deleted", this._handleFlagDeleted);
+      this._wsManager.off("flags_changed", this._handleFlagsChanged);
+      this._wsManager = null;
+    }
+    this._cache.clear();
+    this._initialized = false;
+    this._environment = null;
   }
   /** Disconnect the flags runtime and release resources. */
   async disconnect() {
@@ -20612,6 +20670,9 @@ var FlagsClient = class {
     this._flagFlushTimer = setInterval(() => {
       void this._flushFlags();
     }, FLAG_REGISTRATION_FLUSH_INTERVAL_MS);
+    if (typeof this._flagFlushTimer === "object" && "unref" in this._flagFlushTimer) {
+      this._flagFlushTimer.unref();
+    }
   }
   // ------------------------------------------------------------------
   // Internal: event handlers (called by SharedWebSocket)
@@ -20959,10 +21020,39 @@ var LoggingClient = class {
    * `install()`.
    *
    * Mirrors Python's `client.logging.install()`. There is no `stop()`.
+   *
+   * Adapter coverage:
+   * - **winston**: pre-existing named loggers (`winston.loggers.*`) and the
+   *   default logger are auto-discovered.
+   * - **pino**: pino has no global registry, so only loggers created
+   *   through `pino()` / `logger.child()` *after* `install()` runs are
+   *   tracked. To bring pre-existing pino loggers under management, recreate
+   *   them after install or register them explicitly via
+   *   `client.manage.loggers.register([...])`.
+   *
+   * After the initial pass, call {@link refresh} to re-fetch managed levels
+   * from the server and re-apply them onto the native loggers (e.g. after
+   * suspecting drift, or to force a manual sync outside the WebSocket).
    */
   async install() {
     return this._installInternal();
   }
+  /**
+   * Re-fetch logger and group levels from the server and re-apply them
+   * onto the registered adapters.
+   *
+   * Diff-based: change listeners only fire for loggers whose level
+   * actually changed (added, removed, or different level), with
+   * `source: "manual"`. Mirrors Python's `client.logging.refresh()`.
+   *
+   * @throws SmplError if `install()` has not been called.
+   */
+  async refresh() {
+    if (!this._started) {
+      throw new SmplError("Logging not installed. Call install() first.");
+    }
+    await this._resolveAndFire("manual");
+  }
   /**
    * @deprecated Use {@link LoggingClient.install}. Retained as a backwards-
    * compatible alias.
@@ -21035,6 +21125,9 @@ var LoggingClient = class {
     this._loggerFlushTimer = setInterval(() => {
       void this._flushLoggerBuffer();
     }, 3e4);
+    if (typeof this._loggerFlushTimer === "object" && "unref" in this._loggerFlushTimer) {
+      this._loggerFlushTimer.unref();
+    }
     this._started = true;
   }
   // ------------------------------------------------------------------
@@ -21306,63 +21399,75 @@ var LoggingClient = class {
   };
   _handleLoggersChanged = (_data) => {
     debug("websocket", `loggers_changed event received`);
-    void Promise.all([this._listLoggers(), this._listLogGroups()]).then(([serverLoggers, serverGroups]) => {
-      debug("resolution", `resolution pass (trigger: loggers_changed event)`);
-      const changedLoggerIds = /* @__PURE__ */ new Set();
-      const newLoggerKeys = new Set(serverLoggers.map((l) => l.id));
-      for (const logger of serverLoggers) {
-        const key = logger.id;
-        const oldLevel = this._loggerStore[key] ?? null;
-        const newLevel = logger.level ?? null;
-        if (oldLevel !== newLevel || !(key in this._loggerStore)) {
-          changedLoggerIds.add(key);
-          this._loggerStore[key] = newLevel;
-        }
-      }
-      for (const key of Object.keys(this._loggerStore)) {
-        if (!newLoggerKeys.has(key)) {
-          changedLoggerIds.add(key);
-          delete this._loggerStore[key];
-        }
-      }
-      for (const group of serverGroups) {
-        this._groupStore[group.id] = group.level ?? null;
-      }
-      this._applyLevels(serverLoggers);
-      if (changedLoggerIds.size === 0) return;
-      const [firstKey] = changedLoggerIds;
-      const firstLogger = serverLoggers.find((l) => l.id === firstKey);
-      const globalEvent = new LoggerChangeEvent({
-        id: firstKey,
-        level: firstLogger?.level ?? null,
-        source: "websocket"
-      });
-      for (const cb of this._globalListeners) {
-        try {
-          cb(globalEvent);
-        } catch {
-        }
+    void this._resolveAndFire("websocket").catch(() => {
+    });
+  };
+  /**
+   * Full refetch of loggers + log_groups, apply resolved levels to
+   * adapters, diff against local stores and fire change listeners
+   * (global once, per-key for each changed id). Shared between the
+   * `loggers_changed` WS handler and the public `refresh()` method.
+   * @internal
+   */
+  async _resolveAndFire(source) {
+    const [serverLoggers, serverGroups] = await Promise.all([
+      this._listLoggers(),
+      this._listLogGroups()
+    ]);
+    debug("resolution", `resolution pass (trigger: ${source})`);
+    const changedLoggerIds = /* @__PURE__ */ new Set();
+    const newLoggerKeys = new Set(serverLoggers.map((l) => l.id));
+    for (const logger of serverLoggers) {
+      const key = logger.id;
+      const oldLevel = this._loggerStore[key] ?? null;
+      const newLevel = logger.level ?? null;
+      if (oldLevel !== newLevel || !(key in this._loggerStore)) {
+        changedLoggerIds.add(key);
+        this._loggerStore[key] = newLevel;
+      }
+    }
+    for (const key of Object.keys(this._loggerStore)) {
+      if (!newLoggerKeys.has(key)) {
+        changedLoggerIds.add(key);
+        delete this._loggerStore[key];
+      }
+    }
+    for (const group of serverGroups) {
+      this._groupStore[group.id] = group.level ?? null;
+    }
+    this._applyLevels(serverLoggers);
+    if (changedLoggerIds.size === 0) return;
+    const [firstKey] = changedLoggerIds;
+    const firstLogger = serverLoggers.find((l) => l.id === firstKey);
+    const globalEvent = new LoggerChangeEvent({
+      id: firstKey,
+      level: firstLogger?.level ?? null,
+      source
+    });
+    for (const cb of this._globalListeners) {
+      try {
+        cb(globalEvent);
+      } catch {
       }
-      for (const key of changedLoggerIds) {
-        const keyCallbacks = this._keyListeners.get(key);
-        if (keyCallbacks) {
-          const l = serverLoggers.find((x) => x.id === key);
-          const keyEvent = new LoggerChangeEvent({
-            id: key,
-            level: l?.level ?? null,
-            source: "websocket"
-          });
-          for (const cb of keyCallbacks) {
-            try {
-              cb(keyEvent);
-            } catch {
-            }
+    }
+    for (const key of changedLoggerIds) {
+      const keyCallbacks = this._keyListeners.get(key);
+      if (keyCallbacks) {
+        const l = serverLoggers.find((x) => x.id === key);
+        const keyEvent = new LoggerChangeEvent({
+          id: key,
+          level: l?.level ?? null,
+          source
+        });
+        for (const cb of keyCallbacks) {
+          try {
+            cb(keyEvent);
+          } catch {
           }
         }
       }
-    }).catch(() => {
-    });
-  };
+    }
+  }
   // ------------------------------------------------------------------
   // Internal: single-resource fetchers
   // ------------------------------------------------------------------
@@ -21905,6 +22010,7 @@ var SmplClient = class {
     if (this._metrics !== null) {
       this._metrics.close();
     }
+    this.flags._close();
     this.logging._close();
     if (this._wsManager !== null) {
       this._wsManager.stop();