@smplkit/sdk 3.0.83 → 3.0.85

package/dist/index.d.cts

@@ -579,19 +579,18 @@ declare class SharedWebSocket {
 }
 
 /**
- * LiveConfigProxy — live, dict-like, read-only configuration access.
+ * LiveConfigProxy — live, dict-like, read-only view of a config's resolved values.
+ *
+ * Returned by {@link ConfigClient.get} when called with a single argument.
+ * For typed access via an object literal or class instance, use
+ * {@link ConfigClient.bind} instead — bound objects stay live on the same
+ * WebSocket-driven cache, with no proxy indirection.
  */
 
 /**
- * A live, dict-like, read-only view of resolved config values.
- *
- * Returned by {@link ConfigClient.get}. Always reflects the latest
- * server-pushed state — every read sees current values.
+ * A live, dict-like, read-only view of a config's resolved values.
  *
- * Attribute access returns the current resolved value for the given item
- * key. If a *model* class was provided, the model is reconstructed from
- * the latest values on each access (so attribute access type-checks
- * against the model).
+ * Always reflects the latest server-pushed state — every read sees current values.
  *
  * Dict-like API: `proxy["key"]`, `key in proxy`, `Object.keys(proxy)`,
  * `proxy.values()`, `proxy.items()`, `proxy.get(key, default)`,
@@ -606,7 +605,7 @@ declare class SharedWebSocket {
  * @example
  * ```typescript
  * const cfg = await client.config.get("user-service");
- * console.log(cfg.database.host);   // resolved value
+ * console.log(cfg.database);        // resolved value
  * console.log(cfg["max_retries"]);  // subscript also works
  * for (const key of Object.keys(cfg)) console.log(key);
  *
@@ -614,14 +613,12 @@ declare class SharedWebSocket {
  * cfg.onChange("max_retries", (event) => console.log("retries changed"));
  * ```
  */
-declare class LiveConfigProxy<T = Record<string, unknown>> {
+declare class LiveConfigProxy {
     /** @internal */
     private readonly _client;
     /** @internal */
     private readonly _key;
-    /** @internal */
-    private readonly _model?;
-    constructor(client: ConfigClient, key: string, model?: new (data: any) => T);
+    constructor(client: ConfigClient, key: string);
     /** @internal */
     _currentValues(): Record<string, unknown>;
     /** Dict method: list of resolved item keys. */
@@ -632,32 +629,10 @@ declare class LiveConfigProxy<T = Record<string, unknown>> {
     items(): Array<[string, unknown]>;
     /** Dict method: get a value by key, returning `defaultValue` if absent. */
     get<V = unknown>(key: string, defaultValue?: V): V | unknown;
-    /** @internal */
-    private _registerItem;
-    /** Read a BOOLEAN item, registering the declaration on first call. */
-    getBool(key: string, defaultValue: boolean, options?: {
-        description?: string;
-    }): boolean;
-    /** Read a NUMBER item as int, registering the declaration on first call. */
-    getInt(key: string, defaultValue: number, options?: {
-        description?: string;
-    }): number;
-    /** Read a NUMBER item as float, registering the declaration on first call. */
-    getFloat(key: string, defaultValue: number, options?: {
-        description?: string;
-    }): number;
-    /** Read a STRING item, registering the declaration on first call. */
-    getString(key: string, defaultValue: string, options?: {
-        description?: string;
-    }): string;
-    /** Read a JSON item, registering the declaration on first call. */
-    getJson<V = unknown>(key: string, defaultValue: V, options?: {
-        description?: string;
-    }): V;
     /**
      * Register a change listener scoped to this config.
      *
-     * Three forms:
+     * Two forms:
      * - `proxy.onChange(callback)` — fires on any change to this config.
      * - `proxy.onChange("itemKey", callback)` — fires only when `itemKey` changes.
      *
@@ -2008,7 +1983,7 @@ declare class Environment {
      * environment. Unmanaged environments are view-only — existing values
      * render for comparison but no new values can be set. Managed
      * environments count toward the account's `platform.managed_environments`
-     * quota.
+     * quota. `production` is always managed and cannot be demoted.
      */
     managed: boolean;
     /** When the environment was created. */
@@ -3605,9 +3580,10 @@ declare class ConfigChangeEvent {
 /**
  * Runtime client for the smplkit Config service.
  *
- * Obtained via `SmplClient.config`. Provides live config values, change
- * listeners, and lazy initialization. Management/CRUD lives on
- * `SmplClient.manage.config` (or use a standalone {@link SmplManagementClient}).
+ * Obtained via `SmplClient.config`. Provides {@link bind} (the declarative
+ * path), {@link get} (lookup), change listeners, and lazy initialization.
+ * Management/CRUD lives on `SmplClient.manage.config` (or use a standalone
+ * {@link SmplManagementClient}).
  */
 declare class ConfigClient {
     /** @internal */
@@ -3633,55 +3609,84 @@ declare class ConfigClient {
      * without a full re-list. Mirrors Python's `_raw_config_cache`. */
     private _configStore;
     /** Cache of LiveConfigProxy instances by config id — ensures repeat
-     * `get_or_create(id)` (or `get(id)` after discovery) returns the same
-     * handle so callers can reference it as a parent via direct ref.
-     * Mirrors Python's `_proxies`. */
+     * `get(id)` calls return the same handle. */
     private _proxies;
+    /** Bound targets (plain objects or class instances) keyed by config
+     * id. WebSocket dispatch mutates these in place when values change. */
+    private _bindings;
     private _initialized;
     private _listeners;
     /** @internal */
     constructor(apiKey: string, timeout?: number, baseUrl?: string, extraHeaders?: Record<string, string>);
     /**
-     * Return a live, dict-like view of the resolved values for *id*.
+     * Bind an object to a config id; return the same object back, live.
+     *
+     * Declarative, code-first API. The object's keys are the schema; its
+     * values are the in-code defaults. On first boot:
      *
-     * Without `model`, returns a {@link LiveConfigProxy} that behaves like a
-     * `Record<string, unknown>` (`proxy["key"]`, iteration, `proxy.items()`,
-     * `Object.keys(proxy)`) and updates automatically as the server pushes
-     * changes.
+     * 1. Every leaf (recursively, through nested plain objects) is
+     *    registered with the server as a config item, with its value as
+     *    the in-code default and a type inferred from `typeof value`.
+     * 2. After the SDK's cache is populated, any server-side overrides for
+     *    this config are applied to the bound object in place.
      *
-     * With `model`, the return value type-checks as `model` — attribute
-     * access (`cfg.database.host`) walks a model rebuilt from the current
-     * values on each read, so the customer sees the model's type signature
-     * in their IDE while still tracking live data.
+     * On every WebSocket-delivered change thereafter the bound object is
+     * mutated in place — readers of `obj.foo` and `obj["foo"]` always see
+     * the current resolved value. The returned object is the same one you
+     * passed in (referential identity preserved).
      *
-     * Mirrors Python's `client.config.get(id)` / `client.config.get(id, ModelCls)`.
-     * There is no `subscribe()` — it was unified into `get()`.
+     * Idempotent. Repeated calls with the same id return the originally-
+     * bound object; the new `config` argument is ignored.
+     *
+     * **Plain object literals vs. class instances.** Plain object literals
+     * (e.g., `{ a: 1, b: { c: 2 } }`) are the recommended input shape —
+     * their keys are the explicit override set, and omitted keys inherit
+     * from `parent`. Class instances are also accepted, but every
+     * enumerable property is registered as an explicit override (there is
+     * no JS equivalent of Python's `model_fields_set`); to get omit-to-
+     * inherit semantics, use a plain object literal.
+     *
+     * @param id - The config id to register under.
+     * @param config - A plain object literal (recommended) or class
+     *   instance carrying the in-code defaults.
+     * @param options - Optional `parent`: another object previously
+     *   returned from a {@link bind} call. Activates parent-chain
+     *   inheritance for keys the caller omitted.
+     * @returns The same `config` object, registered and live.
+     * @throws TypeError if `config` is not an object.
+     * @throws Error if `parent` was not previously bound via {@link bind}.
      */
-    get<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
+    bind<T extends object>(id: string, config: T, options?: {
+        parent?: object | null;
+    }): Promise<T>;
     /**
-     * Declare a configuration from code; return a live, dict-like view.
+     * Read a config (full) or a single value within a config.
      *
-     * Idempotent. Repeated calls with the same `id` return the same
-     * {@link LiveConfigProxy} instance. The first call queues a discovery
-     * payload (the config and any items declared via typed getters on the
-     * returned handle) for upload to `POST /api/v1/configs/bulk` on next
-     * flush. If the config already exists server-side, `managed=true`
-     * configs are left untouched; `managed=false` configs receive the
-     * SDK's items via source-row upsert per ADR-024 §2.9.
+     * Three forms dispatched by argument count:
      *
-     * Unlike {@link get}, this method does NOT raise `NotFoundError` when
-     * the id is absent from the cache — discovery handles that case.
+     * - `get(id)` — returns a {@link LiveConfigProxy}, a live dict-like
+     *   view. Throws {@link SmplkitNotFoundError} if the config is missing.
+     *   No registration.
+     * - `get(id, key)` — returns the resolved value of `key` within `id`.
+     *   Throws {@link SmplkitNotFoundError} if either the config or the key
+     *   is missing. No registration.
+     * - `get(id, key, defaultValue)` — returns the resolved value, falling
+     *   back to `defaultValue` if either is missing. Never throws. Also
+     *   **registers** the config (if new) and the key (with `defaultValue`
+     *   as its default value) for code-first console observability.
      *
-     * Mirrors Python's `client.config.get_or_create(id, ...)`.
+     * For typed access via a Pydantic-style declarative API, use
+     * {@link bind} instead.
      */
-    getOrCreate<T = Record<string, unknown>>(id: string, options?: {
-        parent?: string | LiveConfigProxy<any> | null;
-        name?: string;
-        description?: string;
-        model?: new (data: any) => T;
-    }): Promise<LiveConfigProxy<T>>;
+    get(id: string): Promise<LiveConfigProxy>;
+    get(id: string, key: string): Promise<unknown>;
+    get<V>(id: string, key: string, defaultValue: V): Promise<V | unknown>;
+    /** @internal — return the config_id this object was bound under, or null. */
+    private _configIdFor;
+    /** @internal — apply current cached values to a freshly-bound target. */
+    private _syncTargetFromCache;
     /** @internal — return (and cache) the canonical proxy for a config id. */
-    _cachedProxy<T>(id: string, model?: new (data: any) => T): LiveConfigProxy<T>;
+    _cachedProxy(id: string): LiveConfigProxy;
     /** @internal — queue a config declaration with the management buffer. */
     _observeConfigDeclaration(configId: string, parent: string | null, name: string | null, description: string | null): void;
     /** @internal — queue a config item declaration with the management buffer. */
@@ -3704,17 +3709,14 @@ declare class ConfigClient {
      * (set via `_resolveManagement`) so runtime + management share one HTTP
      * client; falls back to a direct GET when running without `SmplClient`
      * bootstrap (e.g. unit tests that construct `ConfigClient` directly).
-     *
-     * Pages through the server until a short page (less than the requested
-     * size) is returned — accounts with more than 1000 configs would
-     * otherwise silently lose everything past page one.
      */
     private _listConfigs;
     /**
      * Eagerly initialize the config subclient — fetch all configs, resolve
      * environment-scoped values into the local cache, and subscribe to the
      * shared WebSocket for live updates. Idempotent. Called automatically
-     * on first `client.config.get(...)` if not invoked manually.
+     * on first `client.config.get(...)` / `client.config.bind(...)` if not
+     * invoked manually.
      */
     start(): Promise<void>;
     /** @internal */
@@ -4161,9 +4163,17 @@ declare class PinoAdapter implements LoggingAdapter {
 /** A single error object from a JSON:API error response. */
 interface ApiErrorDetail {
     status?: string;
+    /**
+     * Application-specific machine-readable error code (e.g.
+     * ``environment_unmanaged``). Per JSON:API §7 and ADR-014, the server
+     * sets this on every error so callers can branch without string-matching.
+     */
+    code?: string;
     title?: string;
     detail?: string;
     source?: Record<string, unknown>;
+    /** Additional structured context (e.g. ``{environment: "staging"}``). */
+    meta?: Record<string, unknown>;
 }
 /** Base exception for all smplkit SDK errors. */
 declare class SmplError extends Error {

package/dist/index.d.ts

@@ -579,19 +579,18 @@ declare class SharedWebSocket {
 }
 
 /**
- * LiveConfigProxy — live, dict-like, read-only configuration access.
+ * LiveConfigProxy — live, dict-like, read-only view of a config's resolved values.
+ *
+ * Returned by {@link ConfigClient.get} when called with a single argument.
+ * For typed access via an object literal or class instance, use
+ * {@link ConfigClient.bind} instead — bound objects stay live on the same
+ * WebSocket-driven cache, with no proxy indirection.
  */
 
 /**
- * A live, dict-like, read-only view of resolved config values.
- *
- * Returned by {@link ConfigClient.get}. Always reflects the latest
- * server-pushed state — every read sees current values.
+ * A live, dict-like, read-only view of a config's resolved values.
  *
- * Attribute access returns the current resolved value for the given item
- * key. If a *model* class was provided, the model is reconstructed from
- * the latest values on each access (so attribute access type-checks
- * against the model).
+ * Always reflects the latest server-pushed state — every read sees current values.
  *
  * Dict-like API: `proxy["key"]`, `key in proxy`, `Object.keys(proxy)`,
  * `proxy.values()`, `proxy.items()`, `proxy.get(key, default)`,
@@ -606,7 +605,7 @@ declare class SharedWebSocket {
  * @example
  * ```typescript
  * const cfg = await client.config.get("user-service");
- * console.log(cfg.database.host);   // resolved value
+ * console.log(cfg.database);        // resolved value
  * console.log(cfg["max_retries"]);  // subscript also works
  * for (const key of Object.keys(cfg)) console.log(key);
  *
@@ -614,14 +613,12 @@ declare class SharedWebSocket {
  * cfg.onChange("max_retries", (event) => console.log("retries changed"));
  * ```
  */
-declare class LiveConfigProxy<T = Record<string, unknown>> {
+declare class LiveConfigProxy {
     /** @internal */
     private readonly _client;
     /** @internal */
     private readonly _key;
-    /** @internal */
-    private readonly _model?;
-    constructor(client: ConfigClient, key: string, model?: new (data: any) => T);
+    constructor(client: ConfigClient, key: string);
     /** @internal */
     _currentValues(): Record<string, unknown>;
     /** Dict method: list of resolved item keys. */
@@ -632,32 +629,10 @@ declare class LiveConfigProxy<T = Record<string, unknown>> {
     items(): Array<[string, unknown]>;
     /** Dict method: get a value by key, returning `defaultValue` if absent. */
     get<V = unknown>(key: string, defaultValue?: V): V | unknown;
-    /** @internal */
-    private _registerItem;
-    /** Read a BOOLEAN item, registering the declaration on first call. */
-    getBool(key: string, defaultValue: boolean, options?: {
-        description?: string;
-    }): boolean;
-    /** Read a NUMBER item as int, registering the declaration on first call. */
-    getInt(key: string, defaultValue: number, options?: {
-        description?: string;
-    }): number;
-    /** Read a NUMBER item as float, registering the declaration on first call. */
-    getFloat(key: string, defaultValue: number, options?: {
-        description?: string;
-    }): number;
-    /** Read a STRING item, registering the declaration on first call. */
-    getString(key: string, defaultValue: string, options?: {
-        description?: string;
-    }): string;
-    /** Read a JSON item, registering the declaration on first call. */
-    getJson<V = unknown>(key: string, defaultValue: V, options?: {
-        description?: string;
-    }): V;
     /**
      * Register a change listener scoped to this config.
      *
-     * Three forms:
+     * Two forms:
      * - `proxy.onChange(callback)` — fires on any change to this config.
      * - `proxy.onChange("itemKey", callback)` — fires only when `itemKey` changes.
      *
@@ -2008,7 +1983,7 @@ declare class Environment {
      * environment. Unmanaged environments are view-only — existing values
      * render for comparison but no new values can be set. Managed
      * environments count toward the account's `platform.managed_environments`
-     * quota.
+     * quota. `production` is always managed and cannot be demoted.
      */
     managed: boolean;
     /** When the environment was created. */
@@ -3605,9 +3580,10 @@ declare class ConfigChangeEvent {
 /**
  * Runtime client for the smplkit Config service.
  *
- * Obtained via `SmplClient.config`. Provides live config values, change
- * listeners, and lazy initialization. Management/CRUD lives on
- * `SmplClient.manage.config` (or use a standalone {@link SmplManagementClient}).
+ * Obtained via `SmplClient.config`. Provides {@link bind} (the declarative
+ * path), {@link get} (lookup), change listeners, and lazy initialization.
+ * Management/CRUD lives on `SmplClient.manage.config` (or use a standalone
+ * {@link SmplManagementClient}).
  */
 declare class ConfigClient {
     /** @internal */
@@ -3633,55 +3609,84 @@ declare class ConfigClient {
      * without a full re-list. Mirrors Python's `_raw_config_cache`. */
     private _configStore;
     /** Cache of LiveConfigProxy instances by config id — ensures repeat
-     * `get_or_create(id)` (or `get(id)` after discovery) returns the same
-     * handle so callers can reference it as a parent via direct ref.
-     * Mirrors Python's `_proxies`. */
+     * `get(id)` calls return the same handle. */
     private _proxies;
+    /** Bound targets (plain objects or class instances) keyed by config
+     * id. WebSocket dispatch mutates these in place when values change. */
+    private _bindings;
     private _initialized;
     private _listeners;
     /** @internal */
     constructor(apiKey: string, timeout?: number, baseUrl?: string, extraHeaders?: Record<string, string>);
     /**
-     * Return a live, dict-like view of the resolved values for *id*.
+     * Bind an object to a config id; return the same object back, live.
+     *
+     * Declarative, code-first API. The object's keys are the schema; its
+     * values are the in-code defaults. On first boot:
      *
-     * Without `model`, returns a {@link LiveConfigProxy} that behaves like a
-     * `Record<string, unknown>` (`proxy["key"]`, iteration, `proxy.items()`,
-     * `Object.keys(proxy)`) and updates automatically as the server pushes
-     * changes.
+     * 1. Every leaf (recursively, through nested plain objects) is
+     *    registered with the server as a config item, with its value as
+     *    the in-code default and a type inferred from `typeof value`.
+     * 2. After the SDK's cache is populated, any server-side overrides for
+     *    this config are applied to the bound object in place.
      *
-     * With `model`, the return value type-checks as `model` — attribute
-     * access (`cfg.database.host`) walks a model rebuilt from the current
-     * values on each read, so the customer sees the model's type signature
-     * in their IDE while still tracking live data.
+     * On every WebSocket-delivered change thereafter the bound object is
+     * mutated in place — readers of `obj.foo` and `obj["foo"]` always see
+     * the current resolved value. The returned object is the same one you
+     * passed in (referential identity preserved).
      *
-     * Mirrors Python's `client.config.get(id)` / `client.config.get(id, ModelCls)`.
-     * There is no `subscribe()` — it was unified into `get()`.
+     * Idempotent. Repeated calls with the same id return the originally-
+     * bound object; the new `config` argument is ignored.
+     *
+     * **Plain object literals vs. class instances.** Plain object literals
+     * (e.g., `{ a: 1, b: { c: 2 } }`) are the recommended input shape —
+     * their keys are the explicit override set, and omitted keys inherit
+     * from `parent`. Class instances are also accepted, but every
+     * enumerable property is registered as an explicit override (there is
+     * no JS equivalent of Python's `model_fields_set`); to get omit-to-
+     * inherit semantics, use a plain object literal.
+     *
+     * @param id - The config id to register under.
+     * @param config - A plain object literal (recommended) or class
+     *   instance carrying the in-code defaults.
+     * @param options - Optional `parent`: another object previously
+     *   returned from a {@link bind} call. Activates parent-chain
+     *   inheritance for keys the caller omitted.
+     * @returns The same `config` object, registered and live.
+     * @throws TypeError if `config` is not an object.
+     * @throws Error if `parent` was not previously bound via {@link bind}.
      */
-    get<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
+    bind<T extends object>(id: string, config: T, options?: {
+        parent?: object | null;
+    }): Promise<T>;
     /**
-     * Declare a configuration from code; return a live, dict-like view.
+     * Read a config (full) or a single value within a config.
      *
-     * Idempotent. Repeated calls with the same `id` return the same
-     * {@link LiveConfigProxy} instance. The first call queues a discovery
-     * payload (the config and any items declared via typed getters on the
-     * returned handle) for upload to `POST /api/v1/configs/bulk` on next
-     * flush. If the config already exists server-side, `managed=true`
-     * configs are left untouched; `managed=false` configs receive the
-     * SDK's items via source-row upsert per ADR-024 §2.9.
+     * Three forms dispatched by argument count:
      *
-     * Unlike {@link get}, this method does NOT raise `NotFoundError` when
-     * the id is absent from the cache — discovery handles that case.
+     * - `get(id)` — returns a {@link LiveConfigProxy}, a live dict-like
+     *   view. Throws {@link SmplkitNotFoundError} if the config is missing.
+     *   No registration.
+     * - `get(id, key)` — returns the resolved value of `key` within `id`.
+     *   Throws {@link SmplkitNotFoundError} if either the config or the key
+     *   is missing. No registration.
+     * - `get(id, key, defaultValue)` — returns the resolved value, falling
+     *   back to `defaultValue` if either is missing. Never throws. Also
+     *   **registers** the config (if new) and the key (with `defaultValue`
+     *   as its default value) for code-first console observability.
      *
-     * Mirrors Python's `client.config.get_or_create(id, ...)`.
+     * For typed access via a Pydantic-style declarative API, use
+     * {@link bind} instead.
      */
-    getOrCreate<T = Record<string, unknown>>(id: string, options?: {
-        parent?: string | LiveConfigProxy<any> | null;
-        name?: string;
-        description?: string;
-        model?: new (data: any) => T;
-    }): Promise<LiveConfigProxy<T>>;
+    get(id: string): Promise<LiveConfigProxy>;
+    get(id: string, key: string): Promise<unknown>;
+    get<V>(id: string, key: string, defaultValue: V): Promise<V | unknown>;
+    /** @internal — return the config_id this object was bound under, or null. */
+    private _configIdFor;
+    /** @internal — apply current cached values to a freshly-bound target. */
+    private _syncTargetFromCache;
     /** @internal — return (and cache) the canonical proxy for a config id. */
-    _cachedProxy<T>(id: string, model?: new (data: any) => T): LiveConfigProxy<T>;
+    _cachedProxy(id: string): LiveConfigProxy;
     /** @internal — queue a config declaration with the management buffer. */
     _observeConfigDeclaration(configId: string, parent: string | null, name: string | null, description: string | null): void;
     /** @internal — queue a config item declaration with the management buffer. */
@@ -3704,17 +3709,14 @@ declare class ConfigClient {
      * (set via `_resolveManagement`) so runtime + management share one HTTP
      * client; falls back to a direct GET when running without `SmplClient`
      * bootstrap (e.g. unit tests that construct `ConfigClient` directly).
-     *
-     * Pages through the server until a short page (less than the requested
-     * size) is returned — accounts with more than 1000 configs would
-     * otherwise silently lose everything past page one.
      */
     private _listConfigs;
     /**
      * Eagerly initialize the config subclient — fetch all configs, resolve
      * environment-scoped values into the local cache, and subscribe to the
      * shared WebSocket for live updates. Idempotent. Called automatically
-     * on first `client.config.get(...)` if not invoked manually.
+     * on first `client.config.get(...)` / `client.config.bind(...)` if not
+     * invoked manually.
      */
     start(): Promise<void>;
     /** @internal */
@@ -4161,9 +4163,17 @@ declare class PinoAdapter implements LoggingAdapter {
 /** A single error object from a JSON:API error response. */
 interface ApiErrorDetail {
     status?: string;
+    /**
+     * Application-specific machine-readable error code (e.g.
+     * ``environment_unmanaged``). Per JSON:API §7 and ADR-014, the server
+     * sets this on every error so callers can branch without string-matching.
+     */
+    code?: string;
     title?: string;
     detail?: string;
     source?: Record<string, unknown>;
+    /** Additional structured context (e.g. ``{environment: "staging"}``). */
+    meta?: Record<string, unknown>;
 }
 /** Base exception for all smplkit SDK errors. */
 declare class SmplError extends Error {