@smplkit/sdk 1.2.2 → 1.2.4

package/dist/index.d.cts

@@ -46,11 +46,12 @@ declare class SharedWebSocket {
 }
 
 /**
- * Config resource — management-plane model with runtime connect support.
+ * Config resource — management-plane model.
  *
  * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations (`update`, `setValues`, `setValue`) as well
- * as the {@link connect} entry point for runtime value resolution.
+ * management-plane operations (`update`, `setValues`, `setValue`).
+ * Prescriptive value access is via `client.config.getValue()` after
+ * `client.connect()`.
  */
 /**
  * Internal type used by {@link ConfigClient}.  Not part of the public API.
@@ -69,8 +70,7 @@ interface ConfigUpdatePayload {
  * A configuration resource fetched from the smplkit Config service.
  *
  * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations as well as the {@link connect} entry point
- * for runtime value resolution.
+ * management-plane operations (update, setValues, setValue).
  */
 declare class Config {
     /** UUID of the config. */
@@ -190,6 +190,19 @@ interface GetConfigOptions {
     id?: string;
 }
 
+/** Describes a single config value change detected on refresh. */
+interface ConfigChangeEvent {
+    /** The config key that changed. */
+    configKey: string;
+    /** The item key within the config that changed. */
+    itemKey: string;
+    /** The previous value (null if the key was absent). */
+    oldValue: unknown;
+    /** The updated value (null if the key was removed). */
+    newValue: unknown;
+    /** How the change was delivered. */
+    source: "websocket" | "manual";
+}
 /**
  * Client for the smplkit Config API (management plane).
  *
@@ -214,6 +227,7 @@ declare class ConfigClient {
     } | null;
     private _configCache;
     private _connected;
+    private _listeners;
     /** @internal */
     constructor(apiKey: string, timeout?: number);
     /**
@@ -258,6 +272,45 @@ declare class ConfigClient {
      * @throws {SmplNotConnectedError} If connect() has not been called.
      */
     getValue(configKey: string, itemKey?: string, defaultValue?: unknown): unknown;
+    /**
+     * Return a config value as a string, or `defaultValue` if absent or not a string.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getString(configKey: string, itemKey: string, defaultValue?: string | null): string | null;
+    /**
+     * Return a config value as a number, or `defaultValue` if absent or not a number.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getInt(configKey: string, itemKey: string, defaultValue?: number | null): number | null;
+    /**
+     * Return a config value as a boolean, or `defaultValue` if absent or not a boolean.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getBool(configKey: string, itemKey: string, defaultValue?: boolean | null): boolean | null;
+    /**
+     * Re-fetch all configs, re-resolve values, and update the cache.
+     *
+     * Fires change listeners for any values that differ from the previous cache.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Register a listener that fires when a config value changes (on refresh).
+     *
+     * @param callback - Called with a {@link ConfigChangeEvent} on each change.
+     * @param options.configKey - If provided, only fire for changes to this config.
+     * @param options.itemKey - If provided, only fire for changes to this item key.
+     */
+    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
+        configKey?: string;
+        itemKey?: string;
+    }): void;
+    /** @internal */
+    private _diffAndFire;
     /**
      * Internal: PUT a full config update and return the updated model.
      *
@@ -725,175 +778,6 @@ declare class SmplClient {
     close(): void;
 }
 
-/**
- * Deep-merge resolution algorithm for config inheritance chains.
- *
- * Mirrors the Python SDK's `_resolver.py` (ADR-024 §2.5–2.6).
- */
-/** A single entry in a config inheritance chain (child-to-root ordering). */
-interface ChainConfig {
-    /** Config UUID. */
-    id: string;
-    /** Base key-value pairs (unwrapped from typed item definitions). */
-    items: Record<string, unknown>;
-    /**
-     * Per-environment overrides.
-     * Each entry is `{ values: { key: value, ... } }` — values are already
-     * unwrapped from the server's `{ value: raw }` wrapper by the client layer.
-     */
-    environments: Record<string, unknown>;
-}
-
-/**
- * Types for the config runtime plane.
- */
-/** Describes a single value change pushed by the server or detected on refresh. */
-interface ConfigChangeEvent {
-    /** The config key that changed. */
-    key: string;
-    /** The previous value (null if the key was absent). */
-    oldValue: unknown;
-    /** The updated value (null if the key was removed). */
-    newValue: unknown;
-    /** How the change was delivered. */
-    source: "websocket" | "poll" | "manual";
-}
-/** Diagnostic statistics for a {@link ConfigRuntime} instance. */
-interface ConfigStats {
-    /**
-     * Total number of HTTP fetches performed, including the initial connect
-     * and any reconnection re-syncs or manual refreshes. Incremented by the
-     * chain length (number of configs fetched) on each fetch.
-     */
-    fetchCount: number;
-    /** ISO-8601 timestamp of the most recent fetch, or null if none yet. */
-    lastFetchAt: string | null;
-}
-/** WebSocket connection status. */
-type ConnectionStatus = "connected" | "connecting" | "disconnected";
-/** Options for {@link Config.connect}. */
-interface ConnectOptions {
-    /**
-     * Maximum milliseconds to wait for the initial fetch.
-     * @default 30000
-     */
-    timeout?: number;
-}
-
-/**
- * ConfigRuntime — runtime-plane value resolution with WebSocket updates.
- *
- * Holds a fully resolved local cache of config values for a specific
- * environment.  All value-access methods are synchronous (local reads);
- * only {@link refresh} and {@link close} are async.
- *
- * A background WebSocket connection is maintained for real-time updates.
- * If the WebSocket fails, the runtime operates in cache-only mode and
- * reconnects automatically with exponential backoff.
- */
-
-/** @internal Options for constructing a ConfigRuntime. */
-interface ConfigRuntimeOptions {
-    configKey: string;
-    configId: string;
-    environment: string;
-    chain: ChainConfig[];
-    apiKey: string;
-    baseUrl: string;
-    fetchChain: (() => Promise<ChainConfig[]>) | null;
-    sharedWs?: SharedWebSocket | null;
-}
-/**
- * Runtime configuration handle for a specific environment.
- *
- * Obtained by calling {@link Config.connect}.  All value-access methods
- * are synchronous and served entirely from a local in-process cache.
- * The cache is populated eagerly on construction and kept current via
- * a background WebSocket connection.
- */
-declare class ConfigRuntime {
-    private _cache;
-    private _chain;
-    private _fetchCount;
-    private _lastFetchAt;
-    private _closed;
-    private _listeners;
-    private readonly _environment;
-    private readonly _fetchChain;
-    private _sharedWs;
-    /** @internal */
-    constructor(options: ConfigRuntimeOptions);
-    /**
-     * Return the resolved value for `key`, or `defaultValue` if absent.
-     *
-     * @param key - The config key to look up.
-     * @param defaultValue - Returned when the key is not present (default: null).
-     */
-    get(key: string, defaultValue?: unknown): unknown;
-    /**
-     * Return the value as a string, or `defaultValue` if absent or not a string.
-     */
-    getString(key: string, defaultValue?: string | null): string | null;
-    /**
-     * Return the value as a number, or `defaultValue` if absent or not a number.
-     */
-    getInt(key: string, defaultValue?: number | null): number | null;
-    /**
-     * Return the value as a boolean, or `defaultValue` if absent or not a boolean.
-     */
-    getBool(key: string, defaultValue?: boolean | null): boolean | null;
-    /**
-     * Return whether `key` is present in the resolved configuration.
-     */
-    exists(key: string): boolean;
-    /**
-     * Return a shallow copy of the full resolved configuration.
-     */
-    getAll(): Record<string, unknown>;
-    /**
-     * Register a listener that fires when a config value changes.
-     *
-     * @param callback - Called with a {@link ConfigChangeEvent} on each change.
-     * @param options.key - If provided, the listener fires only for this key.
-     *   If omitted, the listener fires for all changes.
-     */
-    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
-        key?: string;
-    }): void;
-    /**
-     * Return diagnostic statistics for this runtime.
-     */
-    stats(): ConfigStats;
-    /**
-     * Return the current WebSocket connection status.
-     */
-    connectionStatus(): ConnectionStatus;
-    /**
-     * Force a manual refresh of the cached configuration.
-     *
-     * Re-fetches the full config chain via HTTP, re-resolves values, updates
-     * the local cache, and fires listeners for any detected changes.
-     *
-     * @throws {Error} If no `fetchChain` function was provided on construction.
-     */
-    refresh(): Promise<void>;
-    /**
-     * Close the runtime connection.
-     *
-     * Unregisters from the shared WebSocket. Safe to call multiple times.
-     */
-    close(): Promise<void>;
-    /**
-     * Async dispose support for `await using` (TypeScript 5.2+).
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    private _handleConfigChanged;
-    private _handleConfigDeleted;
-    private _applyChanges;
-    private _diffAndFire;
-    private _fireListeners;
-}
-
 /**
  * Structured SDK error types.
  *
@@ -934,4 +818,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string);
 }
 
-export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };

package/dist/index.d.ts

@@ -46,11 +46,12 @@ declare class SharedWebSocket {
 }
 
 /**
- * Config resource — management-plane model with runtime connect support.
+ * Config resource — management-plane model.
  *
  * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations (`update`, `setValues`, `setValue`) as well
- * as the {@link connect} entry point for runtime value resolution.
+ * management-plane operations (`update`, `setValues`, `setValue`).
+ * Prescriptive value access is via `client.config.getValue()` after
+ * `client.connect()`.
  */
 /**
  * Internal type used by {@link ConfigClient}.  Not part of the public API.
@@ -69,8 +70,7 @@ interface ConfigUpdatePayload {
  * A configuration resource fetched from the smplkit Config service.
  *
  * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations as well as the {@link connect} entry point
- * for runtime value resolution.
+ * management-plane operations (update, setValues, setValue).
  */
 declare class Config {
     /** UUID of the config. */
@@ -190,6 +190,19 @@ interface GetConfigOptions {
     id?: string;
 }
 
+/** Describes a single config value change detected on refresh. */
+interface ConfigChangeEvent {
+    /** The config key that changed. */
+    configKey: string;
+    /** The item key within the config that changed. */
+    itemKey: string;
+    /** The previous value (null if the key was absent). */
+    oldValue: unknown;
+    /** The updated value (null if the key was removed). */
+    newValue: unknown;
+    /** How the change was delivered. */
+    source: "websocket" | "manual";
+}
 /**
  * Client for the smplkit Config API (management plane).
  *
@@ -214,6 +227,7 @@ declare class ConfigClient {
     } | null;
     private _configCache;
     private _connected;
+    private _listeners;
     /** @internal */
     constructor(apiKey: string, timeout?: number);
     /**
@@ -258,6 +272,45 @@ declare class ConfigClient {
      * @throws {SmplNotConnectedError} If connect() has not been called.
      */
     getValue(configKey: string, itemKey?: string, defaultValue?: unknown): unknown;
+    /**
+     * Return a config value as a string, or `defaultValue` if absent or not a string.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getString(configKey: string, itemKey: string, defaultValue?: string | null): string | null;
+    /**
+     * Return a config value as a number, or `defaultValue` if absent or not a number.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getInt(configKey: string, itemKey: string, defaultValue?: number | null): number | null;
+    /**
+     * Return a config value as a boolean, or `defaultValue` if absent or not a boolean.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getBool(configKey: string, itemKey: string, defaultValue?: boolean | null): boolean | null;
+    /**
+     * Re-fetch all configs, re-resolve values, and update the cache.
+     *
+     * Fires change listeners for any values that differ from the previous cache.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Register a listener that fires when a config value changes (on refresh).
+     *
+     * @param callback - Called with a {@link ConfigChangeEvent} on each change.
+     * @param options.configKey - If provided, only fire for changes to this config.
+     * @param options.itemKey - If provided, only fire for changes to this item key.
+     */
+    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
+        configKey?: string;
+        itemKey?: string;
+    }): void;
+    /** @internal */
+    private _diffAndFire;
     /**
      * Internal: PUT a full config update and return the updated model.
      *
@@ -725,175 +778,6 @@ declare class SmplClient {
     close(): void;
 }
 
-/**
- * Deep-merge resolution algorithm for config inheritance chains.
- *
- * Mirrors the Python SDK's `_resolver.py` (ADR-024 §2.5–2.6).
- */
-/** A single entry in a config inheritance chain (child-to-root ordering). */
-interface ChainConfig {
-    /** Config UUID. */
-    id: string;
-    /** Base key-value pairs (unwrapped from typed item definitions). */
-    items: Record<string, unknown>;
-    /**
-     * Per-environment overrides.
-     * Each entry is `{ values: { key: value, ... } }` — values are already
-     * unwrapped from the server's `{ value: raw }` wrapper by the client layer.
-     */
-    environments: Record<string, unknown>;
-}
-
-/**
- * Types for the config runtime plane.
- */
-/** Describes a single value change pushed by the server or detected on refresh. */
-interface ConfigChangeEvent {
-    /** The config key that changed. */
-    key: string;
-    /** The previous value (null if the key was absent). */
-    oldValue: unknown;
-    /** The updated value (null if the key was removed). */
-    newValue: unknown;
-    /** How the change was delivered. */
-    source: "websocket" | "poll" | "manual";
-}
-/** Diagnostic statistics for a {@link ConfigRuntime} instance. */
-interface ConfigStats {
-    /**
-     * Total number of HTTP fetches performed, including the initial connect
-     * and any reconnection re-syncs or manual refreshes. Incremented by the
-     * chain length (number of configs fetched) on each fetch.
-     */
-    fetchCount: number;
-    /** ISO-8601 timestamp of the most recent fetch, or null if none yet. */
-    lastFetchAt: string | null;
-}
-/** WebSocket connection status. */
-type ConnectionStatus = "connected" | "connecting" | "disconnected";
-/** Options for {@link Config.connect}. */
-interface ConnectOptions {
-    /**
-     * Maximum milliseconds to wait for the initial fetch.
-     * @default 30000
-     */
-    timeout?: number;
-}
-
-/**
- * ConfigRuntime — runtime-plane value resolution with WebSocket updates.
- *
- * Holds a fully resolved local cache of config values for a specific
- * environment.  All value-access methods are synchronous (local reads);
- * only {@link refresh} and {@link close} are async.
- *
- * A background WebSocket connection is maintained for real-time updates.
- * If the WebSocket fails, the runtime operates in cache-only mode and
- * reconnects automatically with exponential backoff.
- */
-
-/** @internal Options for constructing a ConfigRuntime. */
-interface ConfigRuntimeOptions {
-    configKey: string;
-    configId: string;
-    environment: string;
-    chain: ChainConfig[];
-    apiKey: string;
-    baseUrl: string;
-    fetchChain: (() => Promise<ChainConfig[]>) | null;
-    sharedWs?: SharedWebSocket | null;
-}
-/**
- * Runtime configuration handle for a specific environment.
- *
- * Obtained by calling {@link Config.connect}.  All value-access methods
- * are synchronous and served entirely from a local in-process cache.
- * The cache is populated eagerly on construction and kept current via
- * a background WebSocket connection.
- */
-declare class ConfigRuntime {
-    private _cache;
-    private _chain;
-    private _fetchCount;
-    private _lastFetchAt;
-    private _closed;
-    private _listeners;
-    private readonly _environment;
-    private readonly _fetchChain;
-    private _sharedWs;
-    /** @internal */
-    constructor(options: ConfigRuntimeOptions);
-    /**
-     * Return the resolved value for `key`, or `defaultValue` if absent.
-     *
-     * @param key - The config key to look up.
-     * @param defaultValue - Returned when the key is not present (default: null).
-     */
-    get(key: string, defaultValue?: unknown): unknown;
-    /**
-     * Return the value as a string, or `defaultValue` if absent or not a string.
-     */
-    getString(key: string, defaultValue?: string | null): string | null;
-    /**
-     * Return the value as a number, or `defaultValue` if absent or not a number.
-     */
-    getInt(key: string, defaultValue?: number | null): number | null;
-    /**
-     * Return the value as a boolean, or `defaultValue` if absent or not a boolean.
-     */
-    getBool(key: string, defaultValue?: boolean | null): boolean | null;
-    /**
-     * Return whether `key` is present in the resolved configuration.
-     */
-    exists(key: string): boolean;
-    /**
-     * Return a shallow copy of the full resolved configuration.
-     */
-    getAll(): Record<string, unknown>;
-    /**
-     * Register a listener that fires when a config value changes.
-     *
-     * @param callback - Called with a {@link ConfigChangeEvent} on each change.
-     * @param options.key - If provided, the listener fires only for this key.
-     *   If omitted, the listener fires for all changes.
-     */
-    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
-        key?: string;
-    }): void;
-    /**
-     * Return diagnostic statistics for this runtime.
-     */
-    stats(): ConfigStats;
-    /**
-     * Return the current WebSocket connection status.
-     */
-    connectionStatus(): ConnectionStatus;
-    /**
-     * Force a manual refresh of the cached configuration.
-     *
-     * Re-fetches the full config chain via HTTP, re-resolves values, updates
-     * the local cache, and fires listeners for any detected changes.
-     *
-     * @throws {Error} If no `fetchChain` function was provided on construction.
-     */
-    refresh(): Promise<void>;
-    /**
-     * Close the runtime connection.
-     *
-     * Unregisters from the shared WebSocket. Safe to call multiple times.
-     */
-    close(): Promise<void>;
-    /**
-     * Async dispose support for `await using` (TypeScript 5.2+).
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    private _handleConfigChanged;
-    private _handleConfigDeleted;
-    private _applyChanges;
-    private _diffAndFire;
-    private _fireListeners;
-}
-
 /**
  * Structured SDK error types.
  *
@@ -934,4 +818,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string);
 }
 
-export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };