@smplkit/sdk 1.2.0 → 1.2.2

package/dist/index.d.ts

@@ -46,174 +46,12 @@ declare class SharedWebSocket {
 }
 
 /**
- * Deep-merge resolution algorithm for config inheritance chains.
+ * Config resource — management-plane model with runtime connect support.
  *
- * 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.
+ * 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.
  */
-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;
-}
-
 /**
  * Internal type used by {@link ConfigClient}.  Not part of the public API.
  * @internal
@@ -320,37 +158,15 @@ declare class Config {
      * @param environment - Target environment, or omit for base values.
      */
     setValue(key: string, value: unknown, environment?: string): Promise<void>;
-    /**
-     * Connect to this config for runtime value resolution.
-     *
-     * Eagerly fetches this config and its full parent chain, resolves values
-     * for the given environment via deep merge, and returns a
-     * {@link ConfigRuntime} with a fully populated local cache.
-     *
-     * A background WebSocket connection is started for real-time updates.
-     * If the WebSocket fails to connect, the runtime operates in cache-only
-     * mode and reconnects automatically.
-     *
-     * Supports both `await` and `await using` (TypeScript 5.2+)::
-     *
-     * ```typescript
-     * // Simple await
-     * const runtime = await config.connect("production");
-     * try { ... } finally { await runtime.close(); }
-     *
-     * // await using (auto-close)
-     * await using runtime = await config.connect("production");
-     * ```
-     *
-     * @param environment - The environment to resolve for (e.g. `"production"`).
-     * @param options.timeout - Milliseconds to wait for the initial fetch.
-     */
-    connect(environment: string, options?: ConnectOptions): Promise<ConfigRuntime>;
     /**
      * Walk the parent chain and return config data objects, child-to-root.
      * @internal
      */
-    private _buildChain;
+    _buildChain(_timeout?: unknown): Promise<Array<{
+        id: string;
+        items: Record<string, unknown>;
+        environments: Record<string, unknown>;
+    }>>;
     toString(): string;
 }
 /** Options for creating a new config. */
@@ -391,6 +207,13 @@ declare class ConfigClient {
     private readonly _http;
     /** @internal — returns the shared WebSocket for real-time updates. */
     _getSharedWs?: () => SharedWebSocket;
+    /** @internal — set by SmplClient after construction. */
+    _parent: {
+        readonly _environment: string;
+        readonly _service: string | null;
+    } | null;
+    private _configCache;
+    private _connected;
     /** @internal */
     constructor(apiKey: string, timeout?: number);
     /**
@@ -418,6 +241,23 @@ declare class ConfigClient {
      * @throws {SmplConflictError} If the config has child configs.
      */
     delete(configId: string): Promise<void>;
+    /**
+     * Fetch all configs, resolve values for the environment, and cache.
+     * @internal — called by SmplClient.connect().
+     */
+    _connectInternal(environment: string): Promise<void>;
+    /**
+     * Read a resolved config value (prescriptive access).
+     *
+     * Requires {@link SmplClient.connect} to have been called.
+     *
+     * @param configKey - The config key to look up.
+     * @param itemKey - Optional specific item key. If omitted, returns all values.
+     * @param defaultValue - Default value if the key is missing.
+     *
+     * @throws {SmplNotConnectedError} If connect() has not been called.
+     */
+    getValue(configKey: string, itemKey?: string, defaultValue?: unknown): unknown;
     /**
      * Internal: PUT a full config update and return the updated model.
      *
@@ -670,6 +510,11 @@ declare class FlagsClient {
     private _globalListeners;
     private _wsManager;
     private readonly _ensureWs;
+    /** @internal — set by SmplClient after construction. */
+    _parent: {
+        readonly _environment: string;
+        readonly _service: string | null;
+    } | null;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
     /** Create a flag. */
@@ -753,10 +598,9 @@ declare class FlagsClient {
     /**
      * Connect to an environment: fetch flag definitions, register on
      * shared WebSocket, enable local evaluation.
+     * @internal — called by SmplClient.connect().
      */
-    connect(environment: string, _options?: {
-        timeout?: number;
-    }): Promise<void>;
+    _connectInternal(environment: string): Promise<void>;
     /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
     disconnect(): Promise<void>;
     /** Re-fetch all flag definitions and clear cache. */
@@ -822,6 +666,17 @@ interface SmplClientOptions {
      * environment variable or the `~/.smplkit` configuration file.
      */
     apiKey?: string;
+    /**
+     * The environment to connect to (e.g. `"production"`, `"staging"`).
+     * When omitted, resolved from the `SMPLKIT_ENVIRONMENT` environment variable.
+     */
+    environment?: string;
+    /**
+     * Optional service name. When set, the SDK automatically registers
+     * the service as a context instance and includes it in flag
+     * evaluation context.
+     */
+    service?: string;
     /**
      * Request timeout in milliseconds.
      * @default 30000
@@ -835,8 +690,8 @@ interface SmplClientOptions {
  * ```typescript
  * import { SmplClient } from "@smplkit/sdk";
  *
- * const client = new SmplClient({ apiKey: "sk_api_..." });
- * const cfg = await client.config.get({ key: "common" });
+ * const client = new SmplClient({ apiKey: "sk_api_...", environment: "production" });
+ * await client.connect();
  * ```
  */
 declare class SmplClient {
@@ -846,13 +701,199 @@ declare class SmplClient {
     readonly flags: FlagsClient;
     private _wsManager;
     private readonly _apiKey;
+    /** @internal */
+    readonly _environment: string;
+    /** @internal */
+    readonly _service: string | null;
+    private _connected;
+    private readonly _timeout;
     constructor(options?: SmplClientOptions);
+    /**
+     * Connect to the smplkit platform.
+     *
+     * Fetches initial flag and config data, opens the shared WebSocket,
+     * and registers the service as a context instance (if provided).
+     *
+     * This method is idempotent — calling it multiple times is safe.
+     */
+    connect(): Promise<void>;
+    /** @internal */
+    private _registerServiceContext;
     /** Lazily create and start the shared WebSocket. @internal */
     private _ensureWs;
     /** Close the shared WebSocket and release resources. */
     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.
  *
@@ -884,9 +925,13 @@ declare class SmplNotFoundError extends SmplError {
 declare class SmplConflictError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string);
 }
+/** Raised when a method requiring connect() is called before connecting. */
+declare class SmplNotConnectedError extends SmplError {
+    constructor(message: string);
+}
 /** Raised when the server rejects a request due to validation errors (HTTP 422). */
 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, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+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 };