@smplkit/sdk 1.0.1 → 1.1.1

package/dist/index.d.cts

@@ -1,91 +1,214 @@
 /**
- * Internal HTTP client wrapper.
+ * Deep-merge resolution algorithm for config inheritance chains.
  *
- * Uses native `fetch` with `AbortController` for timeouts. Maps network
- * errors and HTTP status codes to typed SDK exceptions.
+ * 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. */
+    values: Record<string, unknown>;
+    /**
+     * Per-environment overrides.
+     * Each entry is `{ values: { key: value, ... } }` — the server wraps
+     * environment-specific values in a nested `values` key.
+     */
+    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.
  *
- * @internal This module is not part of the public API.
+ * 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.
  */
-/** Options for constructing a {@link Transport} instance. */
-interface TransportOptions {
-    /** The API key used for Bearer token authentication. */
+
+/** @internal Options for constructing a ConfigRuntime. */
+interface ConfigRuntimeOptions {
+    configKey: string;
+    configId: string;
+    environment: string;
+    chain: ChainConfig[];
     apiKey: string;
-    /** Base URL for all API requests. Must not have a trailing slash. */
     baseUrl: string;
-    /** Request timeout in milliseconds. Defaults to 30 000. */
-    timeout?: number;
+    fetchChain: (() => Promise<ChainConfig[]>) | null;
 }
-/** Parsed JSON response from the API. */
-type JsonBody = Record<string, any>;
 /**
- * Low-level HTTP transport that handles auth, timeouts, and error mapping.
+ * Runtime configuration handle for a specific environment.
  *
- * @internal
+ * 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 Transport {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly timeout;
-    constructor(options: TransportOptions);
+declare class ConfigRuntime {
+    private _cache;
+    private _chain;
+    private _fetchCount;
+    private _lastFetchAt;
+    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);
     /**
-     * Send a GET request.
+     * Return the resolved value for `key`, or `defaultValue` if absent.
      *
-     * @param path - URL path relative to `baseUrl` (e.g. `/api/v1/configs`).
-     * @param params - Optional query parameters.
-     * @returns Parsed JSON response body.
+     * @param key - The config key to look up.
+     * @param defaultValue - Returned when the key is not present (default: null).
      */
-    get(path: string, params?: Record<string, string>): Promise<JsonBody>;
+    get(key: string, defaultValue?: unknown): unknown;
     /**
-     * Send a POST request with a JSON body.
-     *
-     * @param path - URL path relative to `baseUrl`.
-     * @param body - JSON-serializable request body.
-     * @returns Parsed JSON response body.
+     * Return the value as a string, or `defaultValue` if absent or not a string.
      */
-    post(path: string, body: JsonBody): Promise<JsonBody>;
+    getString(key: string, defaultValue?: string | null): string | null;
     /**
-     * Send a PUT request with a JSON body.
-     *
-     * @param path - URL path relative to `baseUrl`.
-     * @param body - JSON-serializable request body.
-     * @returns Parsed JSON response body.
+     * Return the value as a number, or `defaultValue` if absent or not a number.
+     */
+    getNumber(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.
      */
-    put(path: string, body: JsonBody): Promise<JsonBody>;
+    getAll(): Record<string, unknown>;
     /**
-     * Send a DELETE request.
+     * Register a listener that fires when a config value changes.
      *
-     * @param path - URL path relative to `baseUrl`.
-     * @returns Parsed JSON response body (empty object for 204 responses).
+     * @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.
      */
-    delete(path: string): Promise<JsonBody>;
+    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
+        key?: string;
+    }): void;
     /**
-     * Core request method. Handles headers, timeouts, and error mapping.
+     * Return diagnostic statistics for this runtime.
      */
-    private request;
+    stats(): ConfigStats;
     /**
-     * Map HTTP error status codes to typed SDK exceptions.
+     * 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.
      *
-     * @throws {SmplNotFoundError} On 404.
-     * @throws {SmplConflictError} On 409.
-     * @throws {SmplValidationError} On 422.
-     * @throws {SmplError} On any other non-2xx status.
+     * Shuts down the WebSocket and cancels any pending reconnect timer.
+     * Safe to call multiple times.
      */
-    private throwForStatus;
+    close(): Promise<void>;
+    /**
+     * Async dispose support for `await using` (TypeScript 5.2+).
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private _buildWsUrl;
+    private _connectWebSocket;
+    private _scheduleReconnect;
+    private _handleMessage;
+    private _applyChanges;
+    private _diffAndFire;
+    private _fireListeners;
 }
 
 /**
- * Config resource types.
+ * Config resource — management-plane model with runtime connect support.
+ *
+ * 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.
+ */
+
+/**
+ * Internal type used by {@link ConfigClient}.  Not part of the public API.
+ * @internal
+ */
+interface ConfigUpdatePayload {
+    configId: string;
+    name: string;
+    key: string | null;
+    description: string | null;
+    parent: string | null;
+    values: Record<string, unknown>;
+    environments: Record<string, unknown>;
+}
+/**
+ * A configuration resource fetched from the smplkit Config service.
  *
- * These types represent the domain model for config resources after
- * unwrapping the JSON:API envelope.
+ * Instances are returned by {@link ConfigClient} methods and provide
+ * management-plane operations as well as the {@link connect} entry point
+ * for runtime value resolution.
  */
-/** A config resource as returned by the smplkit Config API. */
-interface Config {
+declare class Config {
     /** UUID of the config. */
     id: string;
     /** Human-readable key (e.g. `"user_service"`). */
     key: string;
-    /** Display name for the config. */
+    /** Display name. */
     name: string;
     /** Optional description. */
     description: string | null;
@@ -93,12 +216,110 @@ interface Config {
     parent: string | null;
     /** Base key-value pairs. */
     values: Record<string, unknown>;
-    /** Per-environment overrides, keyed by environment name. */
-    environments: Record<string, Record<string, unknown>>;
+    /**
+     * Per-environment overrides.
+     * Stored as `{ env_name: { values: { key: value } } }` to match the
+     * server's format.
+     */
+    environments: Record<string, unknown>;
     /** When the config was created, or null if unavailable. */
     createdAt: Date | null;
     /** When the config was last updated, or null if unavailable. */
     updatedAt: Date | null;
+    /**
+     * Internal reference to the parent client.
+     * @internal
+     */
+    private readonly _client;
+    /** @internal */
+    constructor(client: {
+        _updateConfig(payload: ConfigUpdatePayload): Promise<Config>;
+        get(options: {
+            id: string;
+        }): Promise<Config>;
+        readonly _apiKey: string;
+        readonly _baseUrl: string;
+    }, fields: {
+        id: string;
+        key: string;
+        name: string;
+        description: string | null;
+        parent: string | null;
+        values: Record<string, unknown>;
+        environments: Record<string, unknown>;
+        createdAt: Date | null;
+        updatedAt: Date | null;
+    });
+    /**
+     * Update this config's attributes on the server.
+     *
+     * Builds the request from current attribute values, overriding with any
+     * provided options. Updates local attributes in place on success.
+     *
+     * @param options.name - New display name.
+     * @param options.description - New description (pass empty string to clear).
+     * @param options.values - New base values (replaces entirely).
+     * @param options.environments - New environments dict (replaces entirely).
+     */
+    update(options: {
+        name?: string;
+        description?: string;
+        values?: Record<string, unknown>;
+        environments?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Replace base or environment-specific values.
+     *
+     * When `environment` is provided, replaces that environment's `values`
+     * sub-dict (other environments are preserved). When omitted, replaces
+     * the base `values`.
+     *
+     * @param values - The complete set of values to set.
+     * @param environment - Target environment, or omit for base values.
+     */
+    setValues(values: Record<string, unknown>, environment?: string): Promise<void>;
+    /**
+     * Set a single key within base or environment-specific values.
+     *
+     * Merges the key into existing values rather than replacing all values.
+     *
+     * @param key - The config key to set.
+     * @param value - The value to assign.
+     * @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;
+    toString(): string;
 }
 /** Options for creating a new config. */
 interface CreateConfigOptions {
@@ -108,7 +329,7 @@ interface CreateConfigOptions {
     key?: string;
     /** Optional description. */
     description?: string;
-    /** Parent config UUID. */
+    /** Parent config UUID. Defaults to the account's `common` config if omitted. */
     parent?: string;
     /** Initial base values. */
     values?: Record<string, unknown>;
@@ -124,65 +345,62 @@ interface GetConfigOptions {
 /**
  * ConfigClient — management-plane operations for configs.
  *
- * Provides CRUD operations on config resources. Obtained via
- * `SmplkitClient.config`.
+ * 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.
+ * Client for the smplkit Config API (management plane).
  *
  * All methods are async and return `Promise<T>`. Network and server
  * errors are mapped to typed SDK exceptions.
+ *
+ * Obtained via `SmplkitClient.config`.
  */
 declare class ConfigClient {
+    /** @internal — used by Config instances for reconnecting and WebSocket auth. */
+    readonly _apiKey: string;
+    /** @internal */
+    readonly _baseUrl: string;
     /** @internal */
-    private readonly transport;
+    private readonly _http;
     /** @internal */
-    constructor(transport: Transport);
+    constructor(apiKey: string, timeout?: number);
     /**
      * Fetch a single config by key or UUID.
      *
      * Exactly one of `key` or `id` must be provided.
      *
-     * @param options - Lookup options.
-     * @returns The matching config.
      * @throws {SmplNotFoundError} If no matching config exists.
-     * @throws {Error} If neither or both of `key` and `id` are provided.
      */
     get(options: GetConfigOptions): Promise<Config>;
     /**
      * List all configs for the account.
-     *
-     * @returns An array of config objects.
      */
     list(): Promise<Config[]>;
     /**
      * Create a new config.
      *
-     * @param options - Config creation options.
-     * @returns The created config.
      * @throws {SmplValidationError} If the server rejects the request.
      */
     create(options: CreateConfigOptions): Promise<Config>;
     /**
      * Delete a config by UUID.
      *
-     * @param configId - The UUID of the config to delete.
      * @throws {SmplNotFoundError} If the config does not exist.
-     * @throws {SmplConflictError} If the config has children.
+     * @throws {SmplConflictError} If the config has child configs.
      */
     delete(configId: string): Promise<void>;
-    /** Fetch a config by UUID. */
-    private getById;
-    /** Fetch a config by key using the list endpoint with a filter. */
-    private getByKey;
     /**
-     * Convert a JSON:API resource to a Config domain model.
+     * Internal: PUT a full config update and return the updated model.
+     *
+     * Called by {@link Config} instance methods.
      * @internal
      */
-    private resourceToModel;
-    /** Build a JSON:API request body for create operations. */
-    private buildRequestBody;
+    _updateConfig(payload: ConfigUpdatePayload): Promise<Config>;
+    private _getById;
+    private _getByKey;
 }
 
 /**
@@ -196,11 +414,6 @@ declare class ConfigClient {
 interface SmplkitClientOptions {
     /** API key for authenticating with the smplkit platform. */
     apiKey: string;
-    /**
-     * Base URL for all API requests.
-     * @default "https://config.smplkit.com"
-     */
-    baseUrl?: string;
     /**
      * Request timeout in milliseconds.
      * @default 30000
@@ -221,8 +434,6 @@ interface SmplkitClientOptions {
 declare class SmplkitClient {
     /** Client for config management-plane operations. */
     readonly config: ConfigClient;
-    /** @internal */
-    private readonly transport;
     constructor(options: SmplkitClientOptions);
 }
 
@@ -262,4 +473,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string);
 }
 
-export { type Config, ConfigClient, type CreateConfigOptions, type GetConfigOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, SmplkitClient, type SmplkitClientOptions };
+export { Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, type CreateConfigOptions, type GetConfigOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, SmplkitClient, type SmplkitClientOptions };