@smplkit/sdk 1.1.10 → 1.2.1

package/dist/index.d.ts

@@ -1,178 +1,48 @@
 /**
- * Deep-merge resolution algorithm for config inheritance chains.
+ * Shared WebSocket connection to the app service event gateway.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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
  */
-
-/** @internal Options for constructing a ConfigRuntime. */
-interface ConfigRuntimeOptions {
-    configKey: string;
-    configId: string;
-    environment: string;
-    chain: ChainConfig[];
-    apiKey: string;
-    baseUrl: string;
-    fetchChain: (() => Promise<ChainConfig[]>) | null;
-}
+type EventCallback = (data: Record<string, any>) => void;
 /**
- * Runtime configuration handle for a specific environment.
+ * Manages a single WebSocket connection to the app service event gateway.
  *
- * 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.
+ * Shared across config and flags modules for efficient multiplexing.
  */
-declare class ConfigRuntime {
-    private _cache;
-    private _chain;
-    private _fetchCount;
-    private _lastFetchAt;
+declare class SharedWebSocket {
+    private readonly _appBaseUrl;
+    private readonly _apiKey;
+    private _listeners;
+    private _connectionStatus;
     private _closed;
-    private _wsStatus;
     private _ws;
     private _reconnectTimer;
     private _backoffIndex;
-    private _listeners;
-    private readonly _configId;
-    private readonly _environment;
-    private readonly _apiKey;
-    private readonly _baseUrl;
-    private readonly _fetchChain;
-    /** @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.
-     *
-     * Shuts down the WebSocket and cancels any pending reconnect timer.
-     * Safe to call multiple times.
-     */
-    close(): Promise<void>;
-    /**
-     * Async dispose support for `await using` (TypeScript 5.2+).
-     */
-    [Symbol.asyncDispose](): Promise<void>;
+    constructor(appBaseUrl: string, apiKey: string);
+    /** Register a listener for a specific event type. */
+    on(eventName: string, callback: EventCallback): void;
+    /** Unregister a listener for a specific event type. */
+    off(eventName: string, callback: EventCallback): void;
+    private _dispatch;
+    get connectionStatus(): string;
+    /** Start the WebSocket connection. */
+    start(): void;
+    /** Stop the WebSocket connection. */
+    stop(): void;
     private _buildWsUrl;
-    private _connectWebSocket;
+    private _connect;
     private _scheduleReconnect;
-    private _handleMessage;
-    private _applyChanges;
-    private _diffAndFire;
-    private _fireListeners;
 }
 
 /**
@@ -182,7 +52,6 @@ declare class ConfigRuntime {
  * management-plane operations (`update`, `setValues`, `setValue`) as well
  * as the {@link connect} entry point for runtime value resolution.
  */
-
 /**
  * Internal type used by {@link ConfigClient}.  Not part of the public API.
  * @internal
@@ -239,6 +108,7 @@ declare class Config {
         }): Promise<Config>;
         readonly _apiKey: string;
         readonly _baseUrl: string;
+        _getSharedWs?: () => SharedWebSocket;
     }, fields: {
         id: string;
         key: string;
@@ -288,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. */
@@ -342,14 +190,6 @@ interface GetConfigOptions {
     id?: string;
 }
 
-/**
- * ConfigClient — management-plane operations for configs.
- *
- * Uses the generated OpenAPI types (`src/generated/config.d.ts`) via
- * `openapi-fetch` for all HTTP calls, keeping the client layer fully
- * type-safe without hand-coded request/response shapes.
- */
-
 /**
  * Client for the smplkit Config API (management plane).
  *
@@ -365,6 +205,15 @@ declare class ConfigClient {
     readonly _baseUrl: string;
     /** @internal */
     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);
     /**
@@ -392,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.
      *
@@ -403,6 +269,388 @@ declare class ConfigClient {
     private _getByKey;
 }
 
+/**
+ * Flag and ContextType resource models returned by the management API.
+ */
+
+/**
+ * A flag resource returned by {@link FlagsClient} management methods.
+ *
+ * Provides `update()` for partial updates and `addRule()` for
+ * conveniently appending a rule to an environment.
+ */
+declare class Flag {
+    /** UUID of the flag. */
+    id: string;
+    /** Unique key within the account. */
+    key: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Value type: BOOLEAN, STRING, NUMERIC, or JSON. */
+    type: string;
+    /** Flag-level default value. */
+    default: unknown;
+    /** Closed set of possible values. */
+    values: Array<{
+        name: string;
+        value: unknown;
+    }>;
+    /** Optional description. */
+    description: string | null;
+    /** Per-environment configuration. */
+    environments: Record<string, any>;
+    /** When the flag was created. */
+    createdAt: string | null;
+    /** When the flag was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    private readonly _client;
+    /** @internal */
+    constructor(client: FlagsClient, fields: {
+        id: string;
+        key: string;
+        name: string;
+        type: string;
+        default: unknown;
+        values: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        description: string | null;
+        environments: Record<string, any>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /**
+     * Update this flag's attributes on the server.
+     *
+     * Only provided fields are changed; others retain their current values.
+     */
+    update(options: {
+        environments?: Record<string, any>;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        default?: unknown;
+        description?: string;
+        name?: string;
+    }): Promise<void>;
+    /**
+     * Add a rule to a specific environment.
+     *
+     * The built rule must include an `environment` key (set via
+     * `Rule(...).environment("env_key")`).  Re-fetches current state
+     * first to avoid stale data.
+     */
+    addRule(builtRule: Record<string, any>): Promise<void>;
+    /** @internal */
+    _apply(other: Flag): void;
+    toString(): string;
+}
+/** A context type resource returned by management API methods. */
+declare class ContextType {
+    /** UUID. */
+    id: string;
+    /** Unique key within the account. */
+    key: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Known attributes. */
+    attributes: Record<string, any>;
+    constructor(fields: {
+        id: string;
+        key: string;
+        name: string;
+        attributes: Record<string, any>;
+    });
+    toString(): string;
+}
+
+/**
+ * Public types for the Flags SDK: FlagType, Context, Rule.
+ */
+/** The value type of a flag. */
+type FlagType = "BOOLEAN" | "STRING" | "NUMERIC" | "JSON";
+/**
+ * A typed evaluation context entity.
+ *
+ * Represents a single entity (user, account, device, etc.) in the
+ * evaluation context.  The *type* and *key* identify the entity;
+ * *attributes* carry the data that JSON Logic rules target.
+ *
+ * @example
+ * ```typescript
+ * new Context("user", "user-123", { plan: "enterprise", firstName: "Alice" })
+ * new Context("user", "user-123", { plan: "enterprise" }, { name: "Alice Smith" })
+ * ```
+ */
+declare class Context {
+    readonly type: string;
+    readonly key: string;
+    readonly name: string | null;
+    readonly attributes: Record<string, unknown>;
+    constructor(type: string, key: string, attributes?: Record<string, unknown>, options?: {
+        name?: string;
+    });
+    toString(): string;
+}
+/**
+ * Fluent builder for JSON Logic rule dicts.
+ *
+ * @example
+ * ```typescript
+ * new Rule("Enable for enterprise users")
+ *     .when("user.plan", "==", "enterprise")
+ *     .when("account.region", "==", "us")
+ *     .serve(true)
+ *     .build()
+ * ```
+ *
+ * Multiple `.when()` calls are AND'd.  `.environment()` tags the
+ * built dict with an environment key for use with `Flag.addRule()`.
+ */
+declare class Rule {
+    private _description;
+    private _conditions;
+    private _value;
+    private _environment;
+    constructor(description: string);
+    /** Tag this rule with an environment key (used by `addRule`). */
+    environment(envKey: string): Rule;
+    /** Add a condition.  Multiple calls are AND'd. */
+    when(variable: string, op: string, value: any): Rule;
+    /** Set the value returned when this rule matches. */
+    serve(value: any): Rule;
+    /** Finalize and return the rule as a plain object. */
+    build(): Record<string, any>;
+}
+
+/**
+ * FlagsClient — management + prescriptive runtime for Smpl Flags.
+ *
+ * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
+ * `openapi-fetch` for all HTTP calls. Context type management and
+ * context registration use direct HTTP via the Transport class since
+ * these endpoints are on the flags service but not in the generated spec.
+ */
+
+/** Describes a flag definition change. */
+declare class FlagChangeEvent {
+    readonly key: string;
+    readonly source: string;
+    constructor(key: string, source: string);
+}
+/** Cache statistics for the flags runtime. */
+declare class FlagStats {
+    readonly cacheHits: number;
+    readonly cacheMisses: number;
+    constructor(cacheHits: number, cacheMisses: number);
+}
+/** @internal */
+declare class FlagHandleBase {
+    /** @internal */ readonly _namespace: FlagsClient;
+    /** @internal */ readonly _key: string;
+    /** @internal */ readonly _default: any;
+    /** @internal */ _listeners: Array<(event: FlagChangeEvent) => void>;
+    constructor(namespace: FlagsClient, key: string, defaultValue: any);
+    get key(): string;
+    get default(): any;
+    get(options?: {
+        context?: Context[];
+    }): any;
+    /** Register a flag-specific change listener. Works as a decorator. */
+    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+}
+/** Typed handle for a boolean flag. */
+declare class BoolFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): boolean;
+}
+/** Typed handle for a string flag. */
+declare class StringFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): string;
+}
+/** Typed handle for a numeric flag. */
+declare class NumberFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): number;
+}
+/** Typed handle for a JSON flag. */
+declare class JsonFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): Record<string, any>;
+}
+/**
+ * Client for the smplkit Flags API — management plane + prescriptive runtime.
+ *
+ * Obtained via `SmplClient.flags`.
+ */
+declare class FlagsClient {
+    /** @internal */
+    readonly _apiKey: string;
+    /** @internal */
+    readonly _baseUrl: string;
+    /** @internal */
+    private readonly _http;
+    /** @internal */
+    private readonly _transport;
+    private _environment;
+    private _flagStore;
+    private _connected;
+    private _cache;
+    private _contextProvider;
+    private _contextBuffer;
+    private _handles;
+    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. */
+    create(key: string, options: {
+        name: string;
+        type: FlagType;
+        default: unknown;
+        description?: string;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+    }): Promise<Flag>;
+    /** Fetch a flag by UUID. */
+    get(flagId: string): Promise<Flag>;
+    /** List all flags. */
+    list(): Promise<Flag[]>;
+    /** Delete a flag by UUID. */
+    delete(flagId: string): Promise<void>;
+    /**
+     * Internal: PUT a full flag update.
+     * Called by {@link Flag} instance methods.
+     * @internal
+     */
+    _updateFlag(options: {
+        flag: Flag;
+        environments?: Record<string, any>;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        default?: unknown;
+        description?: string;
+        name?: string;
+    }): Promise<Flag>;
+    /** Create a context type. */
+    createContextType(key: string, options: {
+        name: string;
+    }): Promise<ContextType>;
+    /** Update a context type (merge attributes). */
+    updateContextType(ctId: string, options: {
+        attributes: Record<string, any>;
+    }): Promise<ContextType>;
+    /** List all context types. */
+    listContextTypes(): Promise<ContextType[]>;
+    /** Delete a context type. */
+    deleteContextType(ctId: string): Promise<void>;
+    /** List context instances filtered by context type key. */
+    listContexts(options: {
+        contextTypeKey: string;
+    }): Promise<any[]>;
+    /** Declare a boolean flag handle. */
+    boolFlag(key: string, defaultValue: boolean): BoolFlagHandle;
+    /** Declare a string flag handle. */
+    stringFlag(key: string, defaultValue: string): StringFlagHandle;
+    /** Declare a numeric flag handle. */
+    numberFlag(key: string, defaultValue: number): NumberFlagHandle;
+    /** Declare a JSON flag handle. */
+    jsonFlag(key: string, defaultValue: Record<string, any>): JsonFlagHandle;
+    /**
+     * Register a context provider function.
+     *
+     * Called on every `handle.get()` to supply the current evaluation
+     * context. Can also be used as a decorator:
+     *
+     * ```typescript
+     * client.flags.setContextProvider(() => [
+     *   new Context("user", userId, { plan: userPlan }),
+     * ]);
+     * ```
+     */
+    setContextProvider(fn: () => Context[]): void;
+    /**
+     * Register a context provider — decorator-style alias.
+     *
+     * ```typescript
+     * const provider = client.flags.contextProvider(() => [...]);
+     * ```
+     */
+    contextProvider(fn: () => Context[]): () => Context[];
+    /**
+     * Connect to an environment: fetch flag definitions, register on
+     * shared WebSocket, enable local evaluation.
+     * @internal — called by SmplClient.connect().
+     */
+    _connectInternal(environment: string): Promise<void>;
+    /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
+    disconnect(): Promise<void>;
+    /** Re-fetch all flag definitions and clear cache. */
+    refresh(): Promise<void>;
+    /** Return the current WebSocket connection status. */
+    connectionStatus(): string;
+    /** Return cache statistics. */
+    stats(): FlagStats;
+    /** Register a global change listener that fires for any flag change. */
+    onChangeAny(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    /**
+     * Register a global change listener — decorator-style alias.
+     *
+     * ```typescript
+     * const listener = client.flags.onChange((event) => { ... });
+     * ```
+     */
+    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    /**
+     * Explicitly register context(s) for background batch registration.
+     *
+     * Accepts a single Context or an array. Fire-and-forget — never
+     * blocks. Works before `connect()` is called.
+     */
+    register(context: Context | Context[]): void;
+    /** Flush pending context registrations to the server. */
+    flushContexts(): Promise<void>;
+    /**
+     * Tier 1 explicit evaluation — stateless, no provider or cache.
+     *
+     * Useful for scripts, one-off jobs, and infrastructure code.
+     */
+    evaluate(key: string, options: {
+        environment: string;
+        context: Context[];
+    }): Promise<any>;
+    /** @internal */
+    _evaluateHandle(key: string, defaultValue: any, context: Context[] | null): any;
+    private _handleFlagChanged;
+    private _handleFlagDeleted;
+    private _fetchAllFlags;
+    private _fetchFlagsList;
+    private _fireChangeListeners;
+    private _fireChangeListenersAll;
+    private _flushContexts;
+    private _resourceToModel;
+    private _resourceToPlainDict;
+    private _parseContextType;
+}
+
 /**
  * Top-level SDK client — SmplClient.
  *
@@ -418,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
@@ -431,14 +690,208 @@ 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 {
     /** Client for config management-plane operations. */
     readonly config: ConfigClient;
+    /** Client for flags management and runtime operations. */
+    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;
 }
 
 /**
@@ -472,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 { Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, type CreateConfigOptions, type GetConfigOptions, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError };
+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 };