@smplkit/sdk 3.0.84 → 3.0.85

package/dist/index.cjs

@@ -17486,47 +17486,15 @@ var Config = class {
 };
 
 // src/config/proxy.ts
-function _unflattenDotNotation(flat) {
-  const nested = {};
-  for (const [key, value] of Object.entries(flat)) {
-    const parts = key.split(".");
-    let current = nested;
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i];
-      if (current[part] === void 0 || typeof current[part] !== "object" || current[part] === null) {
-        current[part] = {};
-      }
-      current = current[part];
-    }
-    current[parts[parts.length - 1]] = value;
-  }
-  return nested;
-}
 var LiveConfigProxy = class {
   /** @internal */
   _client;
   /** @internal */
   _key;
-  /** @internal */
-  _model;
-  constructor(client, key, model) {
+  constructor(client, key) {
     this._client = client;
     this._key = key;
-    this._model = model;
-    const ownMethods = /* @__PURE__ */ new Set([
-      "keys",
-      "values",
-      "items",
-      "get",
-      "onChange",
-      "getBool",
-      "getInt",
-      "getFloat",
-      "getString",
-      "getJson",
-      "_currentValues",
-      "_registerItem"
-    ]);
+    const ownMethods = /* @__PURE__ */ new Set(["keys", "values", "items", "get", "onChange", "_currentValues"]);
     return new Proxy(this, {
       get(target, prop, receiver) {
         if (typeof prop === "symbol" || prop === "constructor" || prop === "toJSON") {
@@ -17536,17 +17504,9 @@ var LiveConfigProxy = class {
           return Reflect.get(target, prop, receiver);
         }
         const values = target._currentValues();
-        if (target._model) {
-          const nested = _unflattenDotNotation(values);
-          const instance = new target._model(nested);
-          return instance[prop];
-        }
         return values[prop];
       },
-      set(target, prop, value, receiver) {
-        if (typeof prop === "string" && prop.startsWith("_")) {
-          return Reflect.set(target, prop, value, receiver);
-        }
+      set(_target, prop) {
         throw new Error(
           `LiveConfigProxy is read-only; cannot set ${JSON.stringify(String(prop))}. Mutate config values via client.manage.config.*`
         );
@@ -17601,74 +17561,6 @@ var LiveConfigProxy = class {
     const values = this._currentValues();
     return key in values ? values[key] : defaultValue;
   }
-  // ------------------------------------------------------------------
-  // Typed getters (ADR-037 §2.13)
-  //
-  // Each registers the item (key, type, default, description) on first
-  // call within the process, then returns the resolved value. When the
-  // resolved value cannot be coerced to the getter's type — including
-  // the "not yet set on the server" case — the in-code default is
-  // returned and a structured warning is logged.
-  // ------------------------------------------------------------------
-  /** @internal */
-  _registerItem(itemKey, itemType, defaultValue, description) {
-    this._client._observeItemDeclaration(this._key, itemKey, itemType, defaultValue, description);
-  }
-  /** Read a BOOLEAN item, registering the declaration on first call. */
-  getBool(key, defaultValue, options = {}) {
-    this._registerItem(key, "BOOLEAN", defaultValue, options.description);
-    const values = this._currentValues();
-    if (!(key in values)) return defaultValue;
-    const value = values[key];
-    if (typeof value === "boolean") return value;
-    console.warn(
-      `[smplkit] config ${JSON.stringify(this._key)} item ${JSON.stringify(key)}: expected BOOLEAN, got ${typeof value}; returning default`
-    );
-    return defaultValue;
-  }
-  /** Read a NUMBER item as int, registering the declaration on first call. */
-  getInt(key, defaultValue, options = {}) {
-    this._registerItem(key, "NUMBER", defaultValue, options.description);
-    const values = this._currentValues();
-    if (!(key in values)) return defaultValue;
-    const value = values[key];
-    if (typeof value === "number" && Number.isInteger(value)) return value;
-    console.warn(
-      `[smplkit] config ${JSON.stringify(this._key)} item ${JSON.stringify(key)}: expected NUMBER (int), got ${typeof value}; returning default`
-    );
-    return defaultValue;
-  }
-  /** Read a NUMBER item as float, registering the declaration on first call. */
-  getFloat(key, defaultValue, options = {}) {
-    this._registerItem(key, "NUMBER", defaultValue, options.description);
-    const values = this._currentValues();
-    if (!(key in values)) return defaultValue;
-    const value = values[key];
-    if (typeof value === "number") return value;
-    console.warn(
-      `[smplkit] config ${JSON.stringify(this._key)} item ${JSON.stringify(key)}: expected NUMBER (float), got ${typeof value}; returning default`
-    );
-    return defaultValue;
-  }
-  /** Read a STRING item, registering the declaration on first call. */
-  getString(key, defaultValue, options = {}) {
-    this._registerItem(key, "STRING", defaultValue, options.description);
-    const values = this._currentValues();
-    if (!(key in values)) return defaultValue;
-    const value = values[key];
-    if (typeof value === "string") return value;
-    console.warn(
-      `[smplkit] config ${JSON.stringify(this._key)} item ${JSON.stringify(key)}: expected STRING, got ${typeof value}; returning default`
-    );
-    return defaultValue;
-  }
-  /** Read a JSON item, registering the declaration on first call. */
-  getJson(key, defaultValue, options = {}) {
-    this._registerItem(key, "JSON", defaultValue, options.description);
-    const values = this._currentValues();
-    if (!(key in values)) return defaultValue;
-    return values[key];
-  }
   onChange(callbackOrItemKey, callback) {
     if (typeof callbackOrItemKey === "function") {
       this._client.onChange(this._key, callbackOrItemKey);
@@ -17721,6 +17613,7 @@ var ConfigChangeEvent = class {
   }
 };
 var BASE_URL = "https://config.smplkit.com";
+var MISSING = /* @__PURE__ */ Symbol("smplkit.config.get.MISSING");
 function extractItemValues(items) {
   if (!items) return {};
   const result = {};
@@ -17760,6 +17653,40 @@ function resourceToConfig(resource) {
     updatedAt: attrs.updated_at ?? null
   });
 }
+function valueToItemType(value) {
+  if (typeof value === "boolean") return "BOOLEAN";
+  if (typeof value === "number") return "NUMBER";
+  if (typeof value === "string") return "STRING";
+  return "STRING";
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function iterObjectItems(obj, prefix = "") {
+  const out = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const flatKey = `${prefix}${key}`;
+    if (isPlainObject(value)) {
+      out.push(...iterObjectItems(value, `${flatKey}.`));
+      continue;
+    }
+    out.push([flatKey, valueToItemType(value), value]);
+  }
+  return out;
+}
+function applyChangeToTarget(target, dottedKey, value) {
+  const parts = dottedKey.split(".");
+  let current = target;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (current === null || typeof current !== "object" || !(part in current)) return;
+    current = current[part];
+  }
+  if (current === null || typeof current !== "object") return;
+  current[parts[parts.length - 1]] = value;
+}
 var ConfigClient = class {
   /** @internal */
   _apiKey;
@@ -17780,10 +17707,11 @@ var ConfigClient = class {
    * without a full re-list. Mirrors Python's `_raw_config_cache`. */
   _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. */
   _proxies = {};
+  /** Bound targets (plain objects or class instances) keyed by config
+   * id. WebSocket dispatch mutates these in place when values change. */
+  _bindings = /* @__PURE__ */ new Map();
   _initialized = false;
   _listeners = [];
   /** @internal */
@@ -17816,66 +17744,126 @@ var ConfigClient = class {
     });
   }
   // ------------------------------------------------------------------
-  // Runtime: resolve and subscribe
+  // Public API: bind, get
   // ------------------------------------------------------------------
   /**
-   * 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}.
    */
-  async get(id, model) {
+  async bind(id, config, options = {}) {
+    if (config === null || typeof config !== "object") {
+      throw new TypeError(`bind() requires an object; got ${typeof config}`);
+    }
+    const existing = this._bindings.get(id);
+    if (existing !== void 0) {
+      return existing;
+    }
+    let parentId = null;
+    if (options.parent !== void 0 && options.parent !== null) {
+      parentId = this._configIdFor(options.parent);
+      if (parentId === null) {
+        throw new Error(
+          "bind(): parent must be an object previously returned from client.config.bind(). Bind the parent first."
+        );
+      }
+    }
+    const ctor = config.constructor;
+    const className = typeof ctor === "function" && ctor !== Object && typeof ctor.name === "string" && ctor.name ? ctor.name : null;
+    this._observeConfigDeclaration(id, parentId, className, null);
+    for (const [itemKey, itemType, value] of iterObjectItems(config)) {
+      this._observeItemDeclaration(id, itemKey, itemType, value, void 0);
+    }
+    this._bindings.set(id, config);
+    await this._ensureInitialized();
+    this._syncTargetFromCache(config, id);
+    return config;
+  }
+  async get(id, key, defaultValue = MISSING) {
     await this._ensureInitialized();
+    if (key === void 0) {
+      if (!(id in this._configCache)) {
+        throw new SmplNotFoundError(`Config with id '${id}' not found in cache`);
+      }
+      const metrics = this._parent?._metrics;
+      if (metrics) {
+        metrics.record("config.resolutions", 1, "resolutions", { config: id });
+      }
+      return this._cachedProxy(id);
+    }
+    const hasDefault = defaultValue !== MISSING;
+    if (hasDefault) {
+      this._observeConfigDeclaration(id, null, null, null);
+      this._observeItemDeclaration(id, key, valueToItemType(defaultValue), defaultValue, void 0);
+    }
     if (!(id in this._configCache)) {
+      if (hasDefault) return defaultValue;
       throw new SmplNotFoundError(`Config with id '${id}' not found in cache`);
     }
-    const metrics = this._parent?._metrics;
-    if (metrics) {
-      metrics.record("config.resolutions", 1, "resolutions", { config: id });
+    const values = this._configCache[id];
+    if (!(key in values)) {
+      if (hasDefault) return defaultValue;
+      throw new SmplNotFoundError(`Config item '${key}' not found in config '${id}'`);
     }
-    return this._cachedProxy(id, model);
+    return values[key];
   }
-  /**
-   * Declare a configuration from code; return a live, dict-like view.
-   *
-   * 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.
-   *
-   * Unlike {@link get}, this method does NOT raise `NotFoundError` when
-   * the id is absent from the cache — discovery handles that case.
-   *
-   * Mirrors Python's `client.config.get_or_create(id, ...)`.
-   */
-  async getOrCreate(id, options = {}) {
-    const parent = options.parent;
-    const parentId = parent instanceof LiveConfigProxy ? parent._key : parent ?? null;
-    this._observeConfigDeclaration(id, parentId, options.name ?? null, options.description ?? null);
-    await this._ensureInitialized();
-    return this._cachedProxy(id, options.model);
+  // ------------------------------------------------------------------
+  // Internal: binding helpers
+  // ------------------------------------------------------------------
+  /** @internal — return the config_id this object was bound under, or null. */
+  _configIdFor(target) {
+    for (const [cid, bound] of this._bindings) {
+      if (bound === target) return cid;
+    }
+    return null;
+  }
+  /** @internal — apply current cached values to a freshly-bound target. */
+  _syncTargetFromCache(target, configId) {
+    const cache = this._configCache[configId];
+    if (!cache) return;
+    for (const [dottedKey, value] of Object.entries(cache)) {
+      applyChangeToTarget(target, dottedKey, value);
+    }
   }
   /** @internal — return (and cache) the canonical proxy for a config id. */
-  _cachedProxy(id, model) {
+  _cachedProxy(id) {
     let proxy = this._proxies[id];
     if (!proxy) {
-      proxy = new LiveConfigProxy(this, id, model);
+      proxy = new LiveConfigProxy(this, id);
       this._proxies[id] = proxy;
-    } else if (model !== void 0 && proxy._model === void 0) {
-      proxy._model = model;
     }
     return proxy;
   }
@@ -17943,7 +17931,7 @@ var ConfigClient = class {
    */
   async refresh() {
     if (!this._initialized) {
-      throw new SmplError("Config not initialized. Call get() first.");
+      throw new SmplError("Config not initialized. Call get() or bind() first.");
     }
     const environment = this._parent?._environment;
     if (!environment) {
@@ -17967,10 +17955,6 @@ var ConfigClient = class {
    * (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.
    */
   async _listConfigs() {
     const PAGE_SIZE = 1e3;
@@ -18012,7 +17996,8 @@ var ConfigClient = class {
    * 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.
    */
   async start() {
     return this._ensureInitialized();
@@ -18148,10 +18133,14 @@ var ConfigClient = class {
       const oldItems = oldCache[cfgKey] ?? {};
       const newItems = newCache[cfgKey] ?? {};
       const allItemKeys = /* @__PURE__ */ new Set([...Object.keys(oldItems), ...Object.keys(newItems)]);
+      const target = this._bindings.get(cfgKey);
       for (const iKey of allItemKeys) {
         const oldVal = iKey in oldItems ? oldItems[iKey] : null;
         const newVal = iKey in newItems ? newItems[iKey] : null;
         if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+          if (target !== void 0) {
+            applyChangeToTarget(target, iKey, newVal);
+          }
           const metrics = this._parent?._metrics;
           if (metrics) {
             metrics.record("config.changes", 1, "changes", { config: cfgKey });