@smplkit/sdk 3.0.78 → 3.0.79

package/dist/index.cjs

@@ -17511,7 +17511,20 @@ var LiveConfigProxy = class {
     this._client = client;
     this._key = key;
     this._model = model;
-    const ownMethods = /* @__PURE__ */ new Set(["keys", "values", "items", "get", "onChange", "_currentValues"]);
+    const ownMethods = /* @__PURE__ */ new Set([
+      "keys",
+      "values",
+      "items",
+      "get",
+      "onChange",
+      "getBool",
+      "getInt",
+      "getFloat",
+      "getString",
+      "getJson",
+      "_currentValues",
+      "_registerItem"
+    ]);
     return new Proxy(this, {
       get(target, prop, receiver) {
         if (typeof prop === "symbol" || prop === "constructor" || prop === "toJSON") {
@@ -17528,7 +17541,10 @@ var LiveConfigProxy = class {
         }
         return values[prop];
       },
-      set(_target, prop, _value) {
+      set(target, prop, value, receiver) {
+        if (typeof prop === "string" && prop.startsWith("_")) {
+          return Reflect.set(target, prop, value, receiver);
+        }
         throw new Error(
           `LiveConfigProxy is read-only; cannot set ${JSON.stringify(String(prop))}. Mutate config values via client.manage.config.*`
         );
@@ -17583,6 +17599,74 @@ 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);
@@ -17693,6 +17777,11 @@ var ConfigClient = class {
    * cache for everyone (including descendants that inherit from it)
    * 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`. */
+  _proxies = {};
   _initialized = false;
   _listeners = [];
   /** @internal */
@@ -17752,7 +17841,65 @@ var ConfigClient = class {
     if (metrics) {
       metrics.record("config.resolutions", 1, "resolutions", { config: id });
     }
-    return new LiveConfigProxy(this, id, model);
+    return this._cachedProxy(id, model);
+  }
+  /**
+   * 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 — return (and cache) the canonical proxy for a config id. */
+  _cachedProxy(id, model) {
+    let proxy = this._proxies[id];
+    if (!proxy) {
+      proxy = new LiveConfigProxy(this, id, model);
+      this._proxies[id] = proxy;
+    } else if (model !== void 0 && proxy._model === void 0) {
+      proxy._model = model;
+    }
+    return proxy;
+  }
+  /** @internal — queue a config declaration with the management buffer. */
+  _observeConfigDeclaration(configId, parent, name, description) {
+    const manage = this._resolveManagement?.();
+    if (!manage) return;
+    manage.config.registerConfig(configId, {
+      service: this._parent?._service ?? null,
+      environment: this._parent?._environment ?? "",
+      parent,
+      name,
+      description
+    });
+  }
+  /** @internal — queue a config item declaration with the management buffer. */
+  _observeItemDeclaration(configId, itemKey, itemType, defaultValue, description) {
+    const manage = this._resolveManagement?.();
+    if (!manage) return;
+    manage.config.registerConfigItem(
+      configId,
+      itemKey,
+      itemType,
+      defaultValue,
+      description ?? null
+    );
   }
   // ------------------------------------------------------------------
   // Runtime: change listeners (3-level overloads)
@@ -17875,6 +18022,17 @@ var ConfigClient = class {
     if (!environment) {
       throw new SmplError("No environment set. Ensure SmplClient is configured.");
     }
+    const manage = this._resolveManagement?.();
+    if (manage) {
+      try {
+        await manage.config.flush();
+      } catch (err) {
+        debug(
+          "config",
+          `pre-start discovery flush failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
     const configs = await this._listConfigs();
     const cache = {};
     const store = {};
@@ -18828,11 +18986,99 @@ function resourceToConfig2(resource, client) {
     updatedAt: attrs.updated_at ?? null
   });
 }
+var CONFIG_REGISTRATION_FLUSH_SIZE = 50;
+var ConfigRegistrationBuffer = class {
+  _pending = /* @__PURE__ */ new Map();
+  _meta = /* @__PURE__ */ new Map();
+  _sentItems = /* @__PURE__ */ new Set();
+  declare(configId, meta) {
+    if (this._meta.has(configId)) return;
+    this._meta.set(configId, meta);
+    this._pending.set(configId, this._buildEntry(configId, {}));
+  }
+  addItem(configId, itemKey, itemType, defaultValue, description) {
+    if (!this._meta.has(configId)) return;
+    const sentKey = `${configId}::${itemKey}`;
+    if (this._sentItems.has(sentKey)) return;
+    let entry = this._pending.get(configId);
+    if (!entry) {
+      entry = this._buildEntry(configId, {});
+      this._pending.set(configId, entry);
+    }
+    if (itemKey in entry.items) return;
+    const def = { value: defaultValue, type: itemType };
+    if (description !== null) def.description = description;
+    entry.items[itemKey] = def;
+  }
+  _buildEntry(configId, items) {
+    const meta = this._meta.get(configId);
+    const entry = { id: configId, items };
+    if (meta.service !== null) entry.service = meta.service;
+    if (meta.environment !== null) entry.environment = meta.environment;
+    if (meta.parent !== null) entry.parent = meta.parent;
+    if (meta.name !== null) entry.name = meta.name;
+    if (meta.description !== null) entry.description = meta.description;
+    return entry;
+  }
+  /** Destructive drain — records sent items so they aren't re-queued. */
+  drain() {
+    const batch = Array.from(this._pending.values());
+    for (const entry of batch) {
+      for (const itemKey of Object.keys(entry.items)) {
+        this._sentItems.add(`${entry.id}::${itemKey}`);
+      }
+    }
+    this._pending.clear();
+    return batch;
+  }
+  get pendingCount() {
+    return this._pending.size;
+  }
+};
 var ManagementConfigClient = class {
   /** @internal */
   constructor(_http) {
     this._http = _http;
   }
+  /** @internal */
+  _buffer = new ConfigRegistrationBuffer();
+  /** @internal — queue a configuration declaration for bulk-discovery upload. */
+  registerConfig(configId, meta) {
+    this._buffer.declare(configId, {
+      service: meta.service,
+      environment: meta.environment,
+      parent: meta.parent ?? null,
+      name: meta.name ?? null,
+      description: meta.description ?? null
+    });
+    if (this._buffer.pendingCount >= CONFIG_REGISTRATION_FLUSH_SIZE) {
+      void this.flush();
+    }
+  }
+  /** @internal — queue a config item declaration. */
+  registerConfigItem(configId, itemKey, itemType, defaultValue, description) {
+    this._buffer.addItem(configId, itemKey, itemType, defaultValue, description);
+    if (this._buffer.pendingCount >= CONFIG_REGISTRATION_FLUSH_SIZE) {
+      void this.flush();
+    }
+  }
+  /** Send any pending config declarations to `POST /api/v1/configs/bulk`. */
+  async flush() {
+    const batch = this._buffer.drain();
+    if (batch.length === 0) return;
+    try {
+      const result = await this._http.POST("/api/v1/configs/bulk", {
+        body: { configs: batch }
+      });
+      if (!result.response.ok) {
+      }
+    } catch {
+    }
+  }
+  /** Number of pending config declarations awaiting flush. */
+  get pendingCount() {
+    return this._buffer.pendingCount;
+  }
   /** Construct an unsaved {@link Config}. Call `.save()` to persist. */
   new(id, options = {}) {
     const parent = options.parent;
@@ -21094,6 +21340,7 @@ var SmplManagementClient = class {
       await this.contexts.flush();
       await this.flags.flush();
       await this.loggers.flush();
+      await this.config.flush();
     } catch {
     }
   }