@smplkit/sdk 3.0.77 → 3.0.79

package/dist/index.d.cts

@@ -632,6 +632,28 @@ 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.
      *
@@ -2365,13 +2387,69 @@ declare class Config {
 }
 
 type ConfigHttp$1 = ReturnType<typeof createClient<___generated_config_d_ts.paths>>;
+interface ConfigBufferEntry {
+    id: string;
+    items: Record<string, {
+        value: unknown;
+        type: string;
+        description?: string;
+    }>;
+    service?: string;
+    environment?: string;
+    parent?: string;
+    name?: string;
+    description?: string;
+}
+interface ConfigBufferMeta {
+    service: string | null;
+    environment: string | null;
+    parent: string | null;
+    name: string | null;
+    description: string | null;
+}
+/**
+ * Buffer pending config declarations for bulk registration. @internal
+ *
+ * Configs differ from flags because each entry carries a nested `items`
+ * dict that grows incrementally as typed getters fire. We store per-config
+ * metadata permanently so post-flush deltas re-attribute correctly, and
+ * dedupe items per `(configId, itemKey)` so an already-sent item never
+ * re-sends. Mirrors Python's `_ConfigRegistrationBuffer`.
+ */
+declare class ConfigRegistrationBuffer {
+    private _pending;
+    private _meta;
+    private _sentItems;
+    declare(configId: string, meta: ConfigBufferMeta): void;
+    addItem(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description: string | null): void;
+    private _buildEntry;
+    /** Destructive drain — records sent items so they aren't re-queued. */
+    drain(): ConfigBufferEntry[];
+    get pendingCount(): number;
+}
 /**
- * `mgmt.config.*` — CRUD client for configs.
+ * `mgmt.config.*` — CRUD client for configs + bulk registration buffer.
  */
 declare class ManagementConfigClient {
     private readonly _http;
     /** @internal */
+    readonly _buffer: ConfigRegistrationBuffer;
+    /** @internal */
     constructor(_http: ConfigHttp$1);
+    /** @internal — queue a configuration declaration for bulk-discovery upload. */
+    registerConfig(configId: string, meta: {
+        service: string | null;
+        environment: string | null;
+        parent?: string | null;
+        name?: string | null;
+        description?: string | null;
+    }): void;
+    /** @internal — queue a config item declaration. */
+    registerConfigItem(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description: string | null): void;
+    /** Send any pending config declarations to `POST /api/v1/configs/bulk`. */
+    flush(): Promise<void>;
+    /** Number of pending config declarations awaiting flush. */
+    get pendingCount(): number;
     /** Construct an unsaved {@link Config}. Call `.save()` to persist. */
     new(id: string, options?: {
         name?: string;
@@ -3544,6 +3622,11 @@ declare class ConfigClient {
      * cache for everyone (including descendants that inherit from it)
      * 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`. */
+    private _proxies;
     private _initialized;
     private _listeners;
     /** @internal */
@@ -3565,6 +3648,34 @@ declare class ConfigClient {
      * There is no `subscribe()` — it was unified into `get()`.
      */
     get<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
+    /**
+     * 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, ...)`.
+     */
+    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>>;
+    /** @internal — return (and cache) the canonical proxy for a config id. */
+    _cachedProxy<T>(id: string, model?: new (data: any) => T): LiveConfigProxy<T>;
+    /** @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. */
+    _observeItemDeclaration(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description?: string): void;
     /**
      * Register a change listener.
      *

package/dist/index.d.ts

@@ -632,6 +632,28 @@ 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.
      *
@@ -2365,13 +2387,69 @@ declare class Config {
 }
 
 type ConfigHttp$1 = ReturnType<typeof createClient<___generated_config_d_ts.paths>>;
+interface ConfigBufferEntry {
+    id: string;
+    items: Record<string, {
+        value: unknown;
+        type: string;
+        description?: string;
+    }>;
+    service?: string;
+    environment?: string;
+    parent?: string;
+    name?: string;
+    description?: string;
+}
+interface ConfigBufferMeta {
+    service: string | null;
+    environment: string | null;
+    parent: string | null;
+    name: string | null;
+    description: string | null;
+}
+/**
+ * Buffer pending config declarations for bulk registration. @internal
+ *
+ * Configs differ from flags because each entry carries a nested `items`
+ * dict that grows incrementally as typed getters fire. We store per-config
+ * metadata permanently so post-flush deltas re-attribute correctly, and
+ * dedupe items per `(configId, itemKey)` so an already-sent item never
+ * re-sends. Mirrors Python's `_ConfigRegistrationBuffer`.
+ */
+declare class ConfigRegistrationBuffer {
+    private _pending;
+    private _meta;
+    private _sentItems;
+    declare(configId: string, meta: ConfigBufferMeta): void;
+    addItem(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description: string | null): void;
+    private _buildEntry;
+    /** Destructive drain — records sent items so they aren't re-queued. */
+    drain(): ConfigBufferEntry[];
+    get pendingCount(): number;
+}
 /**
- * `mgmt.config.*` — CRUD client for configs.
+ * `mgmt.config.*` — CRUD client for configs + bulk registration buffer.
  */
 declare class ManagementConfigClient {
     private readonly _http;
     /** @internal */
+    readonly _buffer: ConfigRegistrationBuffer;
+    /** @internal */
     constructor(_http: ConfigHttp$1);
+    /** @internal — queue a configuration declaration for bulk-discovery upload. */
+    registerConfig(configId: string, meta: {
+        service: string | null;
+        environment: string | null;
+        parent?: string | null;
+        name?: string | null;
+        description?: string | null;
+    }): void;
+    /** @internal — queue a config item declaration. */
+    registerConfigItem(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description: string | null): void;
+    /** Send any pending config declarations to `POST /api/v1/configs/bulk`. */
+    flush(): Promise<void>;
+    /** Number of pending config declarations awaiting flush. */
+    get pendingCount(): number;
     /** Construct an unsaved {@link Config}. Call `.save()` to persist. */
     new(id: string, options?: {
         name?: string;
@@ -3544,6 +3622,11 @@ declare class ConfigClient {
      * cache for everyone (including descendants that inherit from it)
      * 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`. */
+    private _proxies;
     private _initialized;
     private _listeners;
     /** @internal */
@@ -3565,6 +3648,34 @@ declare class ConfigClient {
      * There is no `subscribe()` — it was unified into `get()`.
      */
     get<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
+    /**
+     * 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, ...)`.
+     */
+    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>>;
+    /** @internal — return (and cache) the canonical proxy for a config id. */
+    _cachedProxy<T>(id: string, model?: new (data: any) => T): LiveConfigProxy<T>;
+    /** @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. */
+    _observeItemDeclaration(configId: string, itemKey: string, itemType: string, defaultValue: unknown, description?: string): void;
     /**
      * Register a change listener.
      *

package/dist/index.js

@@ -17441,7 +17441,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") {
@@ -17458,7 +17471,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.*`
         );
@@ -17513,6 +17529,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);
@@ -17623,6 +17707,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 */
@@ -17682,7 +17771,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)
@@ -17805,6 +17952,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 = {};
@@ -18758,11 +18916,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;
@@ -21024,6 +21270,7 @@ var SmplManagementClient = class {
       await this.contexts.flush();
       await this.flags.flush();
       await this.loggers.flush();
+      await this.config.flush();
     } catch {
     }
   }