@smplkit/sdk 1.3.26 → 1.3.28

package/dist/index.d.cts

@@ -1,6 +1,43 @@
+/**
+ * Internal SDK telemetry engine.
+ *
+ * Accumulates usage metrics in memory and periodically flushes them to the
+ * app service via `POST /api/v1/metrics/bulk`.  This module is entirely
+ * private — nothing here is exported or documented for customers.
+ *
+ * @internal
+ */
+/** @internal */
+declare class MetricsReporter {
+    private readonly _apiKey;
+    private readonly _environment;
+    private readonly _service;
+    private readonly _flushInterval;
+    private _counters;
+    private _gauges;
+    private _timer;
+    private _closed;
+    constructor(options: {
+        apiKey: string;
+        environment: string;
+        service: string;
+        flushInterval?: number;
+    });
+    record(name: string, value?: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    recordGauge(name: string, value: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    flush(): void;
+    close(): void;
+    private _mergeDimensions;
+    private _maybeStartTimer;
+    private _flush;
+    private _buildPayload;
+    private _entry;
+}
+
 /**
  * Shared WebSocket connection for real-time event delivery.
  */
+
 type EventCallback = (data: Record<string, any>) => void;
 /**
  * Manages a WebSocket connection for real-time event delivery.
@@ -8,13 +45,14 @@ type EventCallback = (data: Record<string, any>) => void;
 declare class SharedWebSocket {
     private readonly _appBaseUrl;
     private readonly _apiKey;
+    private readonly _metrics;
     private _listeners;
     private _connectionStatus;
     private _closed;
     private _ws;
     private _reconnectTimer;
     private _backoffIndex;
-    constructor(appBaseUrl: string, apiKey: string);
+    constructor(appBaseUrl: string, apiKey: string, metrics?: MetricsReporter | null);
     /** Register a listener for a specific event type. */
     on(eventName: string, callback: EventCallback): void;
     /** Unregister a listener for a specific event type. */
@@ -41,15 +79,13 @@ declare class SharedWebSocket {
  * Creates if new, updates if existing.
  */
 declare class Config {
-    /** UUID of the config, or `null` if unsaved. */
+    /** Unique identifier (slug, e.g. `"user-service"`). */
     id: string | null;
-    /** Human-readable key (e.g. `"user-service"`). */
-    key: string;
     /** Display name. */
     name: string;
     /** Optional description. */
     description: string | null;
-    /** Parent config UUID, or null if this is a root config. */
+    /** Parent config id (slug), or null if this is a root config. */
     parent: string | null;
     /** Base key-value pairs. */
     items: Record<string, unknown>;
@@ -67,7 +103,6 @@ declare class Config {
     /** @internal */
     constructor(client: ConfigClient, fields: {
         id: string | null;
-        key: string;
         name: string;
         description: string | null;
         parent: string | null;
@@ -130,8 +165,8 @@ declare class LiveConfigProxy<T = Record<string, unknown>> {
 
 /** Describes a single config value change detected on refresh. */
 interface ConfigChangeEvent {
-    /** The config key that changed. */
-    configKey: string;
+    /** The config id that changed. */
+    configId: string;
     /** The item key within the config that changed. */
     itemKey: string;
     /** The previous value (null if the key was absent). */
@@ -159,6 +194,7 @@ declare class ConfigClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private _configCache;
     private _initialized;
@@ -166,45 +202,45 @@ declare class ConfigClient {
     /** @internal */
     constructor(apiKey: string, timeout?: number);
     /** Create an unsaved config. Call `.save()` to persist. */
-    new(key: string, options?: {
+    new(id: string, options?: {
         name?: string;
         description?: string;
         parent?: string;
     }): Config;
-    /** Fetch a config by key. */
-    get(key: string): Promise<Config>;
+    /** Fetch a config by id. */
+    get(id: string): Promise<Config>;
     /** List all configs. */
     list(): Promise<Config[]>;
-    /** Delete a config by key. */
-    delete(key: string): Promise<void>;
+    /** Delete a config by id. */
+    delete(id: string): Promise<void>;
     /** @internal — POST a new config. */
     _createConfig(config: Config): Promise<Config>;
     /** @internal — PUT a config update. */
     _updateConfig(config: Config): Promise<Config>;
-    /** @internal — fetch a config by UUID. */
-    _getById(configId: string): Promise<Config>;
+    /** @internal — fetch a config by id. */
+    _getById(id: string): Promise<Config>;
     /**
      * Resolve a config's values for the current environment.
      *
      * Returns the resolved key-value pairs for the given config.
      * Optionally pass a model class to map the resolved values.
      */
-    resolve<T = Record<string, unknown>>(key: string, model?: new (data: any) => T): Promise<T>;
+    resolve<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<T>;
     /**
      * Subscribe to a config's values. Returns a proxy whose properties
      * always reflect the latest resolved values.
      *
      * Optionally pass a model class to map the resolved values.
      */
-    subscribe<T = Record<string, unknown>>(key: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
+    subscribe<T = Record<string, unknown>>(id: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
     /**
      * Register a change listener.
      *
      * - `onChange(callback)` — fires for any config change (global).
-     * - `onChange(configKey, callback)` — fires for changes to a specific config.
-     * - `onChange(configKey, itemKey, callback)` — fires for a specific item.
+     * - `onChange(configId, callback)` — fires for changes to a specific config.
+     * - `onChange(configId, itemKey, callback)` — fires for a specific item.
      */
-    onChange(callbackOrConfigKey: string | ((event: ConfigChangeEvent) => void), callbackOrItemKey?: string | ((event: ConfigChangeEvent) => void), callback?: (event: ConfigChangeEvent) => void): void;
+    onChange(callbackOrConfigId: string | ((event: ConfigChangeEvent) => void), callbackOrItemKey?: string | ((event: ConfigChangeEvent) => void), callback?: (event: ConfigChangeEvent) => void): void;
     /**
      * Refresh all config values from the server.
      * Fires change listeners for any values that changed.
@@ -219,7 +255,6 @@ declare class ConfigClient {
     private _handleConfigChanged;
     /** @internal */
     private _diffAndFire;
-    private _getByKey;
 }
 
 interface components {
@@ -252,7 +287,6 @@ interface components {
          *           "rules": []
          *         }
          *       },
-         *       "key": "dark_mode",
          *       "name": "Dark Mode",
          *       "type": "BOOLEAN",
          *       "updated_at": "2026-03-27T10:00:00Z",
@@ -269,11 +303,8 @@ interface components {
          *     }
          */
         Flag: {
-            /**
-             * Key
-             * @description Unique key within account
-             */
-            key: string;
+            /** Id */
+            id?: string | null;
             /**
              * Name
              * @description Human-readable display name
@@ -349,7 +380,6 @@ interface components {
          *             ]
          *           }
          *         },
-         *         "key": "dark_mode",
          *         "name": "Dark Mode",
          *         "type": "BOOLEAN",
          *         "updated_at": "2026-03-27T10:00:00Z",
@@ -364,7 +394,7 @@ interface components {
          *           }
          *         ]
          *       },
-         *       "id": "550e8400-e29b-41d4-a716-446655440000",
+         *       "id": "dark_mode",
          *       "type": "flag"
          *     }
          */
@@ -503,10 +533,8 @@ declare class Rule {
  * Call `save()` to persist changes. Call `get()` to evaluate the flag.
  */
 declare class Flag {
-    /** UUID of the flag, or `null` if unsaved. */
+    /** Unique identifier (slug) within the account. */
     id: string | null;
-    /** Unique key within the account. */
-    key: string;
     /** Human-readable display name. */
     name: string;
     /** Value type: BOOLEAN, STRING, NUMERIC, or JSON. */
@@ -531,7 +559,6 @@ declare class Flag {
     /** @internal */
     constructor(client: FlagsClient, fields: {
         id: string | null;
-        key: string;
         name: string;
         type: string;
         default: unknown;
@@ -610,9 +637,9 @@ declare class JsonFlag extends Flag {
 type FlagResource = components["schemas"]["FlagResource"];
 /** Describes a flag definition change. */
 declare class FlagChangeEvent {
-    readonly key: string;
+    readonly id: string;
     readonly source: string;
-    constructor(key: string, source: string);
+    constructor(id: string, source: string);
 }
 /** Evaluation statistics for the flags runtime. */
 declare class FlagStats {
@@ -649,17 +676,18 @@ declare class FlagsClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
     /** Create an unsaved boolean flag. Call `.save()` to persist. */
-    newBooleanFlag(key: string, options: {
+    newBooleanFlag(id: string, options: {
         default: boolean;
         name?: string;
         description?: string;
     }): BooleanFlag;
     /** Create an unsaved string flag. Call `.save()` to persist. */
-    newStringFlag(key: string, options: {
+    newStringFlag(id: string, options: {
         default: string;
         name?: string;
         description?: string;
@@ -669,7 +697,7 @@ declare class FlagsClient {
         }>;
     }): StringFlag;
     /** Create an unsaved number flag. Call `.save()` to persist. */
-    newNumberFlag(key: string, options: {
+    newNumberFlag(id: string, options: {
         default: number;
         name?: string;
         description?: string;
@@ -679,7 +707,7 @@ declare class FlagsClient {
         }>;
     }): NumberFlag;
     /** Create an unsaved JSON flag. Call `.save()` to persist. */
-    newJsonFlag(key: string, options: {
+    newJsonFlag(id: string, options: {
         default: Record<string, any>;
         name?: string;
         description?: string;
@@ -688,24 +716,24 @@ declare class FlagsClient {
             value: unknown;
         }>;
     }): JsonFlag;
-    /** Fetch a flag by key. */
-    get(key: string): Promise<Flag>;
+    /** Fetch a flag by id. */
+    get(id: string): Promise<Flag>;
     /** List all flags. */
     list(): Promise<Flag[]>;
-    /** Delete a flag by key. */
-    delete(key: string): Promise<void>;
+    /** Delete a flag by id. */
+    delete(id: string): Promise<void>;
     /** @internal — POST a new flag. */
     _createFlag(flag: Flag): Promise<Flag>;
     /** @internal — PUT a flag update. */
     _updateFlag(flag: Flag): Promise<Flag>;
     /** Declare a boolean flag handle for runtime evaluation. */
-    booleanFlag(key: string, defaultValue: boolean): BooleanFlag;
+    booleanFlag(id: string, defaultValue: boolean): BooleanFlag;
     /** Declare a string flag handle for runtime evaluation. */
-    stringFlag(key: string, defaultValue: string): StringFlag;
+    stringFlag(id: string, defaultValue: string): StringFlag;
     /** Declare a numeric flag handle for runtime evaluation. */
-    numberFlag(key: string, defaultValue: number): NumberFlag;
+    numberFlag(id: string, defaultValue: number): NumberFlag;
     /** Declare a JSON flag handle for runtime evaluation. */
-    jsonFlag(key: string, defaultValue: Record<string, any>): JsonFlag;
+    jsonFlag(id: string, defaultValue: Record<string, any>): JsonFlag;
     /**
      * Register a context provider function.
      *
@@ -735,9 +763,9 @@ declare class FlagsClient {
      * Register a change listener.
      *
      * - `onChange(callback)` — fires for any flag change.
-     * - `onChange(key, callback)` — fires only for the specified flag key.
+     * - `onChange(id, callback)` — fires only for the specified flag id.
      */
-    onChange(callbackOrKey: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
+    onChange(callbackOrId: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
     /**
      * Register context(s) with the server.
      *
@@ -749,7 +777,7 @@ declare class FlagsClient {
     /**
      * Evaluate a flag with an explicit environment and context.
      */
-    evaluate(key: string, options: {
+    evaluate(id: string, options: {
         environment: string;
         context: Context[];
     }): Promise<any>;
@@ -784,8 +812,8 @@ declare enum LogLevel {
 }
 /** Describes a logger configuration change. */
 interface LoggerChangeEvent {
-    /** The logger key that changed. */
-    key: string;
+    /** The logger id that changed. */
+    id: string;
     /** The new effective log level, or null if removed. */
     level: LogLevel | null;
     /** How the change was delivered. */
@@ -802,15 +830,13 @@ interface LoggerChangeEvent {
  * Mutate properties or use convenience methods, then call `save()` to persist.
  */
 declare class Logger {
-    /** UUID of the logger, or `null` if unsaved. */
+    /** Unique identifier (dot-separated hierarchy, e.g. `"sqlalchemy.engine"`). */
     id: string | null;
-    /** Unique key (dot-separated hierarchy). */
-    key: string;
     /** Human-readable display name. */
     name: string;
     /** Base log level, or null if inherited. */
     level: string | null;
-    /** UUID of the parent log group, or null. */
+    /** Id of the parent log group, or null. */
     group: string | null;
     /** Whether this logger is managed by the platform. */
     managed: boolean;
@@ -827,7 +853,6 @@ declare class Logger {
     /** @internal */
     constructor(client: LoggingClient, fields: {
         id: string | null;
-        key: string;
         name: string;
         level: string | null;
         group: string | null;
@@ -863,15 +888,13 @@ declare class Logger {
  * Management: mutate properties and call `save()` to persist.
  */
 declare class LogGroup {
-    /** UUID of the log group, or `null` if unsaved. */
+    /** Unique identifier (slug), or `null` if unsaved. */
     id: string | null;
-    /** Unique key. */
-    key: string;
     /** Human-readable display name. */
     name: string;
     /** Base log level, or null if inherited. */
     level: string | null;
-    /** UUID of the parent log group, or null. */
+    /** Id of the parent log group, or null. */
     group: string | null;
     /** Per-environment level overrides. */
     environments: Record<string, any>;
@@ -884,7 +907,6 @@ declare class LogGroup {
     /** @internal */
     constructor(client: LoggingClient, fields: {
         id: string | null;
-        key: string;
         name: string;
         level: string | null;
         group: string | null;
@@ -962,6 +984,7 @@ declare class LoggingClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private readonly _ensureWs;
     private _wsManager;
@@ -980,27 +1003,27 @@ declare class LoggingClient {
      */
     registerAdapter(adapter: LoggingAdapter): void;
     /** Create an unsaved logger. Call `.save()` to persist. */
-    new(key: string, options?: {
+    new(id: string, options?: {
         name?: string;
         managed?: boolean;
     }): Logger;
-    /** Fetch a logger by key. */
-    get(key: string): Promise<Logger>;
+    /** Fetch a logger by id. */
+    get(id: string): Promise<Logger>;
     /** List all loggers. */
     list(): Promise<Logger[]>;
-    /** Delete a logger by key. */
-    delete(key: string): Promise<void>;
+    /** Delete a logger by id. */
+    delete(id: string): Promise<void>;
     /** Create an unsaved log group. Call `.save()` to persist. */
-    newGroup(key: string, options?: {
+    newGroup(id: string, options?: {
         name?: string;
         group?: string;
     }): LogGroup;
-    /** Fetch a log group by key. */
-    getGroup(key: string): Promise<LogGroup>;
+    /** Fetch a log group by id. */
+    getGroup(id: string): Promise<LogGroup>;
     /** List all log groups. */
     listGroups(): Promise<LogGroup[]>;
-    /** Delete a log group by key. */
-    deleteGroup(key: string): Promise<void>;
+    /** Delete a log group by id. */
+    deleteGroup(id: string): Promise<void>;
     /** @internal — POST or PUT a logger. */
     _saveLogger(logger: Logger): Promise<Logger>;
     /** @internal — POST or PUT a log group. */
@@ -1017,9 +1040,9 @@ declare class LoggingClient {
      * Register a change listener.
      *
      * - `onChange(callback)` — fires for any logger change.
-     * - `onChange(key, callback)` — fires only for the specified logger key.
+     * - `onChange(id, callback)` — fires only for the specified logger id.
      */
-    onChange(callbackOrKey: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
+    onChange(callbackOrId: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
     /** @internal */
     _close(): void;
     /** Auto-load built-in adapters by attempting to require each framework. */
@@ -1064,6 +1087,12 @@ interface SmplClientOptions {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Disable SDK telemetry reporting.
+     * When `true`, no usage metrics are collected or sent.
+     * @default false
+     */
+    disableTelemetry?: boolean;
 }
 /**
  * Entry point for the smplkit TypeScript SDK.
@@ -1100,6 +1129,8 @@ declare class SmplClient {
     readonly _environment: string;
     /** @internal */
     readonly _service: string;
+    /** @internal */
+    readonly _metrics: MetricsReporter | null;
     private readonly _timeout;
     private readonly _appHttp;
     constructor(options?: SmplClientOptions);