@smplkit/sdk 1.3.22 → 1.3.23

package/dist/index.d.cts

@@ -53,7 +53,7 @@ declare class SharedWebSocket {
  * A configuration resource managed by the smplkit platform.
  *
  * Management: mutate properties directly and call `save()` to persist.
- * POST if `id` is null (new), PUT if `id` is set (update).
+ * Creates if new, updates if existing.
  */
 declare class Config {
     /** UUID of the config, or `null` if unsaved. */
@@ -70,8 +70,7 @@ declare class Config {
     items: Record<string, unknown>;
     /**
      * Per-environment overrides.
-     * Stored as `{ env_name: { values: { key: value } } }` — values are
-     * unwrapped from the server's `{ value: raw }` wrapper.
+     * Structured as `{ env_name: { values: { key: value } } }`.
      */
     environments: Record<string, unknown>;
     /** When the config was created, or null if unavailable. */
@@ -95,7 +94,7 @@ declare class Config {
     /**
      * Persist this config to the server.
      *
-     * POST if `id` is null (new config), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
@@ -118,17 +117,17 @@ declare class Config {
 }
 
 /**
- * LiveConfigProxy — ES6 Proxy-based live configuration access.
+ * LiveConfigProxy — live configuration access.
  *
- * Property reads are delegated to the latest resolved values in the
- * ConfigClient cache. When the cache updates via WebSocket, subsequent
- * reads automatically reflect the new values.
+ * Property reads always return the latest resolved values. When the
+ * underlying config changes, subsequent reads automatically reflect
+ * the new values.
  */
 
 /**
  * A live proxy that auto-updates when the underlying config changes.
  *
- * Access properties directly — each read re-resolves from the cache.
+ * Access properties directly — each read returns the latest resolved value.
  *
  * @example
  * ```typescript
@@ -208,8 +207,8 @@ declare class ConfigClient {
     /**
      * Resolve a config's values for the current environment.
      *
-     * Returns a flat dict of resolved key-value pairs, walking the
-     * parent chain and applying environment overrides.
+     * Returns a flat dict of resolved key-value pairs with inherited
+     * values and environment overrides applied.
      *
      * Optionally pass a model class to map the resolved values.
      */
@@ -230,7 +229,7 @@ declare class ConfigClient {
      */
     onChange(callbackOrConfigKey: string | ((event: ConfigChangeEvent) => void), callbackOrItemKey?: string | ((event: ConfigChangeEvent) => void), callback?: (event: ConfigChangeEvent) => void): void;
     /**
-     * Re-fetch all configs, re-resolve values, and update the cache.
+     * Re-fetch all configs and re-resolve values.
      * Fires change listeners for any values that differ.
      */
     refresh(): Promise<void>;
@@ -529,8 +528,8 @@ declare class Rule {
 /**
  * A flag resource that doubles as a runtime handle.
  *
- * Management: call `save()` to persist (POST if new, PUT if existing).
- * Runtime: call `get()` for local JSON Logic evaluation.
+ * Management: call `save()` to persist (creates if new, updates if existing).
+ * Runtime: call `get()` to evaluate the flag locally.
  */
 declare class Flag {
     /** UUID of the flag, or `null` if unsaved. */
@@ -577,7 +576,7 @@ declare class Flag {
     /**
      * Persist this flag to the server.
      *
-     * POST if `id` is null (new flag), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
@@ -597,7 +596,7 @@ declare class Flag {
     /** Clear all rules for a specific environment (sync local mutation). */
     clearRules(envKey: string): void;
     /**
-     * Evaluate the flag locally (sync, no HTTP).
+     * Evaluate the flag locally.
      *
      * Requires `initialize()` to have been called.
      */
@@ -635,10 +634,6 @@ declare class JsonFlag extends Flag {
 
 /**
  * FlagsClient — management + prescriptive runtime for Smpl Flags.
- *
- * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
- * `openapi-fetch` for all flag HTTP calls. Context registration uses
- * the generated app service types (`src/generated/app.d.ts`).
  */
 
 type FlagResource = components["schemas"]["FlagResource"];
@@ -773,16 +768,18 @@ declare class FlagsClient {
      */
     onChange(callbackOrKey: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
     /**
-     * Explicitly register context(s) for background batch registration.
+     * Register context(s) with the server.
      *
-     * Accepts a single Context or an array. Fire-and-forget — never
-     * blocks. Works before `initialize()` is called.
+     * Accepts a single Context or an array. Registration is asynchronous
+     * and never blocks. Works before `initialize()` is called.
      */
     register(context: Context | Context[]): void;
     /** Flush pending context registrations to the server. */
     flushContexts(): Promise<void>;
     /**
-     * Tier 1 explicit evaluation — stateless, no provider or cache.
+     * Evaluate a flag with an explicit environment and context.
+     *
+     * Stateless — does not use the context provider or cached results.
      */
     evaluate(key: string, options: {
         environment: string;
@@ -877,7 +874,7 @@ declare class Logger {
     /**
      * Persist this logger to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
     /** Set the base log level (sync local mutation). */
@@ -932,7 +929,7 @@ declare class LogGroup {
     /**
      * Persist this log group to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
     /** Set the base log level (sync local mutation). */
@@ -953,11 +950,8 @@ declare class LogGroup {
 /**
  * Contract for pluggable logging framework integration.
  *
- * Adapters bridge the smplkit logging runtime to a specific logging framework.
- * The core LoggingClient delegates all framework-specific work through this interface.
- *
- * Adapters are NOT responsible for: key normalization, caching, bulk registration,
- * level resolution, or WebSocket handling. Those remain in the core client.
+ * Adapters bridge the smplkit logging runtime to a specific logging
+ * framework (e.g., Winston, Pino).
  */
 interface LoggingAdapter {
     /** Human-readable adapter name for diagnostics (e.g., 'winston'). */
@@ -988,9 +982,6 @@ interface LoggingAdapter {
 
 /**
  * LoggingClient — management plane + scaffolded runtime for Smpl Logging.
- *
- * Uses the generated OpenAPI types (`src/generated/logging.d.ts`) via
- * `openapi-fetch` for all HTTP calls.
  */
 
 /**
@@ -1055,14 +1046,9 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * Performs the full runtime pipeline:
-     *   1. Auto-load adapters (if none registered explicitly)
-     *   2. Discover existing loggers from each adapter
-     *   3. Install hooks on each adapter for new logger creation
-     *   4. Bulk-register discovered loggers with the server
-     *   5. Fetch all loggers and groups from the server
-     *   6. Resolve levels and apply to adapters
-     *   7. Wire WebSocket for live updates
+     * Discovers loggers from registered adapters, syncs them with the
+     * server, applies server-side log levels, and subscribes to live
+     * level updates.
      *
      * Idempotent — safe to call multiple times.
      * Management methods work without start().
@@ -1169,10 +1155,9 @@ declare class SmplClient {
 /**
  * Winston logging framework adapter.
  *
- * Bridges the smplkit logging runtime to winston's logger container.
- * Discovers loggers via `winston.loggers` (the Container), hooks into
- * new logger creation by monkey-patching `Container.add()`, and applies
- * levels by setting `logger.level` on the winston logger instance.
+ * Integrates the smplkit logging runtime with Winston. Discovers
+ * existing loggers, tracks new logger creation, and applies
+ * server-managed log levels.
  */
 
 interface WinstonAdapterConfig {
@@ -1199,10 +1184,8 @@ declare class WinstonAdapter implements LoggingAdapter {
 /**
  * Pino logging framework adapter.
  *
- * Pino has no global logger registry. This adapter builds its own internal
- * registry by monkey-patching the pino module's default export and the
- * `child()` method on created loggers. Logger instances are tracked via
- * WeakRef to avoid memory leaks.
+ * Integrates the smplkit logging runtime with Pino. Tracks logger
+ * instances (including child loggers) for discovery and level control.
  */
 
 interface PinoAdapterConfig {

package/dist/index.d.ts

@@ -53,7 +53,7 @@ declare class SharedWebSocket {
  * A configuration resource managed by the smplkit platform.
  *
  * Management: mutate properties directly and call `save()` to persist.
- * POST if `id` is null (new), PUT if `id` is set (update).
+ * Creates if new, updates if existing.
  */
 declare class Config {
     /** UUID of the config, or `null` if unsaved. */
@@ -70,8 +70,7 @@ declare class Config {
     items: Record<string, unknown>;
     /**
      * Per-environment overrides.
-     * Stored as `{ env_name: { values: { key: value } } }` — values are
-     * unwrapped from the server's `{ value: raw }` wrapper.
+     * Structured as `{ env_name: { values: { key: value } } }`.
      */
     environments: Record<string, unknown>;
     /** When the config was created, or null if unavailable. */
@@ -95,7 +94,7 @@ declare class Config {
     /**
      * Persist this config to the server.
      *
-     * POST if `id` is null (new config), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
@@ -118,17 +117,17 @@ declare class Config {
 }
 
 /**
- * LiveConfigProxy — ES6 Proxy-based live configuration access.
+ * LiveConfigProxy — live configuration access.
  *
- * Property reads are delegated to the latest resolved values in the
- * ConfigClient cache. When the cache updates via WebSocket, subsequent
- * reads automatically reflect the new values.
+ * Property reads always return the latest resolved values. When the
+ * underlying config changes, subsequent reads automatically reflect
+ * the new values.
  */
 
 /**
  * A live proxy that auto-updates when the underlying config changes.
  *
- * Access properties directly — each read re-resolves from the cache.
+ * Access properties directly — each read returns the latest resolved value.
  *
  * @example
  * ```typescript
@@ -208,8 +207,8 @@ declare class ConfigClient {
     /**
      * Resolve a config's values for the current environment.
      *
-     * Returns a flat dict of resolved key-value pairs, walking the
-     * parent chain and applying environment overrides.
+     * Returns a flat dict of resolved key-value pairs with inherited
+     * values and environment overrides applied.
      *
      * Optionally pass a model class to map the resolved values.
      */
@@ -230,7 +229,7 @@ declare class ConfigClient {
      */
     onChange(callbackOrConfigKey: string | ((event: ConfigChangeEvent) => void), callbackOrItemKey?: string | ((event: ConfigChangeEvent) => void), callback?: (event: ConfigChangeEvent) => void): void;
     /**
-     * Re-fetch all configs, re-resolve values, and update the cache.
+     * Re-fetch all configs and re-resolve values.
      * Fires change listeners for any values that differ.
      */
     refresh(): Promise<void>;
@@ -529,8 +528,8 @@ declare class Rule {
 /**
  * A flag resource that doubles as a runtime handle.
  *
- * Management: call `save()` to persist (POST if new, PUT if existing).
- * Runtime: call `get()` for local JSON Logic evaluation.
+ * Management: call `save()` to persist (creates if new, updates if existing).
+ * Runtime: call `get()` to evaluate the flag locally.
  */
 declare class Flag {
     /** UUID of the flag, or `null` if unsaved. */
@@ -577,7 +576,7 @@ declare class Flag {
     /**
      * Persist this flag to the server.
      *
-     * POST if `id` is null (new flag), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      * Updates this instance in-place with the server response.
      */
     save(): Promise<void>;
@@ -597,7 +596,7 @@ declare class Flag {
     /** Clear all rules for a specific environment (sync local mutation). */
     clearRules(envKey: string): void;
     /**
-     * Evaluate the flag locally (sync, no HTTP).
+     * Evaluate the flag locally.
      *
      * Requires `initialize()` to have been called.
      */
@@ -635,10 +634,6 @@ declare class JsonFlag extends Flag {
 
 /**
  * FlagsClient — management + prescriptive runtime for Smpl Flags.
- *
- * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
- * `openapi-fetch` for all flag HTTP calls. Context registration uses
- * the generated app service types (`src/generated/app.d.ts`).
  */
 
 type FlagResource = components["schemas"]["FlagResource"];
@@ -773,16 +768,18 @@ declare class FlagsClient {
      */
     onChange(callbackOrKey: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
     /**
-     * Explicitly register context(s) for background batch registration.
+     * Register context(s) with the server.
      *
-     * Accepts a single Context or an array. Fire-and-forget — never
-     * blocks. Works before `initialize()` is called.
+     * Accepts a single Context or an array. Registration is asynchronous
+     * and never blocks. Works before `initialize()` is called.
      */
     register(context: Context | Context[]): void;
     /** Flush pending context registrations to the server. */
     flushContexts(): Promise<void>;
     /**
-     * Tier 1 explicit evaluation — stateless, no provider or cache.
+     * Evaluate a flag with an explicit environment and context.
+     *
+     * Stateless — does not use the context provider or cached results.
      */
     evaluate(key: string, options: {
         environment: string;
@@ -877,7 +874,7 @@ declare class Logger {
     /**
      * Persist this logger to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
     /** Set the base log level (sync local mutation). */
@@ -932,7 +929,7 @@ declare class LogGroup {
     /**
      * Persist this log group to the server.
      *
-     * POST if `id` is null (new), PUT if `id` is set (update).
+     * Creates if new, updates if existing.
      */
     save(): Promise<void>;
     /** Set the base log level (sync local mutation). */
@@ -953,11 +950,8 @@ declare class LogGroup {
 /**
  * Contract for pluggable logging framework integration.
  *
- * Adapters bridge the smplkit logging runtime to a specific logging framework.
- * The core LoggingClient delegates all framework-specific work through this interface.
- *
- * Adapters are NOT responsible for: key normalization, caching, bulk registration,
- * level resolution, or WebSocket handling. Those remain in the core client.
+ * Adapters bridge the smplkit logging runtime to a specific logging
+ * framework (e.g., Winston, Pino).
  */
 interface LoggingAdapter {
     /** Human-readable adapter name for diagnostics (e.g., 'winston'). */
@@ -988,9 +982,6 @@ interface LoggingAdapter {
 
 /**
  * LoggingClient — management plane + scaffolded runtime for Smpl Logging.
- *
- * Uses the generated OpenAPI types (`src/generated/logging.d.ts`) via
- * `openapi-fetch` for all HTTP calls.
  */
 
 /**
@@ -1055,14 +1046,9 @@ declare class LoggingClient {
     /**
      * Start the logging runtime.
      *
-     * Performs the full runtime pipeline:
-     *   1. Auto-load adapters (if none registered explicitly)
-     *   2. Discover existing loggers from each adapter
-     *   3. Install hooks on each adapter for new logger creation
-     *   4. Bulk-register discovered loggers with the server
-     *   5. Fetch all loggers and groups from the server
-     *   6. Resolve levels and apply to adapters
-     *   7. Wire WebSocket for live updates
+     * Discovers loggers from registered adapters, syncs them with the
+     * server, applies server-side log levels, and subscribes to live
+     * level updates.
      *
      * Idempotent — safe to call multiple times.
      * Management methods work without start().
@@ -1169,10 +1155,9 @@ declare class SmplClient {
 /**
  * Winston logging framework adapter.
  *
- * Bridges the smplkit logging runtime to winston's logger container.
- * Discovers loggers via `winston.loggers` (the Container), hooks into
- * new logger creation by monkey-patching `Container.add()`, and applies
- * levels by setting `logger.level` on the winston logger instance.
+ * Integrates the smplkit logging runtime with Winston. Discovers
+ * existing loggers, tracks new logger creation, and applies
+ * server-managed log levels.
  */
 
 interface WinstonAdapterConfig {
@@ -1199,10 +1184,8 @@ declare class WinstonAdapter implements LoggingAdapter {
 /**
  * Pino logging framework adapter.
  *
- * Pino has no global logger registry. This adapter builds its own internal
- * registry by monkey-patching the pino module's default export and the
- * `child()` method on created loggers. Logger instances are tracked via
- * WeakRef to avoid memory leaks.
+ * Integrates the smplkit logging runtime with Pino. Tracks logger
+ * instances (including child loggers) for discovery and level control.
  */
 
 interface PinoAdapterConfig {

package/dist/index.js

@@ -16770,8 +16770,7 @@ var Config = class {
   items;
   /**
    * Per-environment overrides.
-   * Stored as `{ env_name: { values: { key: value } } }` — values are
-   * unwrapped from the server's `{ value: raw }` wrapper.
+   * Structured as `{ env_name: { values: { key: value } } }`.
    */
   environments;
   /** When the config was created, or null if unavailable. */
@@ -16796,7 +16795,7 @@ var Config = class {
   /**
    * Persist this config to the server.
    *
-   * POST if `id` is null (new config), PUT if `id` is set (update).
+   * Creates if new, updates if existing.
    * Updates this instance in-place with the server response.
    */
   async save() {
@@ -17174,8 +17173,8 @@ var ConfigClient = class {
   /**
    * Resolve a config's values for the current environment.
    *
-   * Returns a flat dict of resolved key-value pairs, walking the
-   * parent chain and applying environment overrides.
+   * Returns a flat dict of resolved key-value pairs with inherited
+   * values and environment overrides applied.
    *
    * Optionally pass a model class to map the resolved values.
    */
@@ -17238,7 +17237,7 @@ var ConfigClient = class {
   // Runtime: refresh
   // ------------------------------------------------------------------
   /**
-   * Re-fetch all configs, re-resolve values, and update the cache.
+   * Re-fetch all configs and re-resolve values.
    * Fires change listeners for any values that differ.
    */
   async refresh() {
@@ -17404,7 +17403,7 @@ var Flag = class {
   /**
    * Persist this flag to the server.
    *
-   * POST if `id` is null (new flag), PUT if `id` is set (update).
+   * Creates if new, updates if existing.
    * Updates this instance in-place with the server response.
    */
   async save() {
@@ -17467,7 +17466,7 @@ var Flag = class {
     }
   }
   /**
-   * Evaluate the flag locally (sync, no HTTP).
+   * Evaluate the flag locally.
    *
    * Requires `initialize()` to have been called.
    */
@@ -18083,10 +18082,10 @@ var FlagsClient = class {
   // Runtime: context registration
   // ------------------------------------------------------------------
   /**
-   * Explicitly register context(s) for background batch registration.
+   * Register context(s) with the server.
    *
-   * Accepts a single Context or an array. Fire-and-forget — never
-   * blocks. Works before `initialize()` is called.
+   * Accepts a single Context or an array. Registration is asynchronous
+   * and never blocks. Works before `initialize()` is called.
    */
   register(context) {
     if (Array.isArray(context)) {
@@ -18103,7 +18102,9 @@ var FlagsClient = class {
   // Runtime: Tier 1 evaluate
   // ------------------------------------------------------------------
   /**
-   * Tier 1 explicit evaluation — stateless, no provider or cache.
+   * Evaluate a flag with an explicit environment and context.
+   *
+   * Stateless — does not use the context provider or cached results.
    */
   async evaluate(key, options) {
     const evalDict = contextsToEvalDict(options.context);
@@ -18346,7 +18347,7 @@ var Logger = class {
   /**
    * Persist this logger to the server.
    *
-   * POST if `id` is null (new), PUT if `id` is set (update).
+   * Creates if new, updates if existing.
    */
   async save() {
     const saved = await this._client._saveLogger(this);
@@ -18431,7 +18432,7 @@ var LogGroup = class {
   /**
    * Persist this log group to the server.
    *
-   * POST if `id` is null (new), PUT if `id` is set (update).
+   * Creates if new, updates if existing.
    */
   async save() {
     const saved = await this._client._saveLogGroup(this);
@@ -18775,14 +18776,9 @@ var LoggingClient = class {
   /**
    * Start the logging runtime.
    *
-   * Performs the full runtime pipeline:
-   *   1. Auto-load adapters (if none registered explicitly)
-   *   2. Discover existing loggers from each adapter
-   *   3. Install hooks on each adapter for new logger creation
-   *   4. Bulk-register discovered loggers with the server
-   *   5. Fetch all loggers and groups from the server
-   *   6. Resolve levels and apply to adapters
-   *   7. Wire WebSocket for live updates
+   * Discovers loggers from registered adapters, syncs them with the
+   * server, applies server-side log levels, and subscribes to live
+   * level updates.
    *
    * Idempotent — safe to call multiple times.
    * Management methods work without start().