@smplkit/sdk 1.1.9 → 1.2.0

package/dist/index.d.ts

@@ -1,3 +1,50 @@
+/**
+ * Shared WebSocket connection to the app service event gateway.
+ *
+ * A single {@link SharedWebSocket} instance is shared across all product
+ * modules (config, flags) within one {@link SmplClient}.  Product modules
+ * register listeners for specific event types; the shared connection
+ * dispatches incoming events to the appropriate listeners.
+ *
+ * Protocol:
+ * - Connect to `wss://app.smplkit.com/api/ws/v1/events?api_key={key}`
+ * - Receive `{"type": "connected"}` on success
+ * - Receive events: `{"event": "config_changed", ...}`, `{"event": "flag_changed", ...}`
+ * - No subscribe message — the API key determines the account
+ * - Heartbeat: server sends `ping`, client responds with `pong`
+ * - Reconnect with exponential backoff
+ */
+type EventCallback = (data: Record<string, any>) => void;
+/**
+ * Manages a single WebSocket connection to the app service event gateway.
+ *
+ * Shared across config and flags modules for efficient multiplexing.
+ */
+declare class SharedWebSocket {
+    private readonly _appBaseUrl;
+    private readonly _apiKey;
+    private _listeners;
+    private _connectionStatus;
+    private _closed;
+    private _ws;
+    private _reconnectTimer;
+    private _backoffIndex;
+    constructor(appBaseUrl: string, apiKey: string);
+    /** Register a listener for a specific event type. */
+    on(eventName: string, callback: EventCallback): void;
+    /** Unregister a listener for a specific event type. */
+    off(eventName: string, callback: EventCallback): void;
+    private _dispatch;
+    get connectionStatus(): string;
+    /** Start the WebSocket connection. */
+    start(): void;
+    /** Stop the WebSocket connection. */
+    stop(): void;
+    private _buildWsUrl;
+    private _connect;
+    private _scheduleReconnect;
+}
+
 /**
  * Deep-merge resolution algorithm for config inheritance chains.
  *
@@ -74,6 +121,7 @@ interface ConfigRuntimeOptions {
     apiKey: string;
     baseUrl: string;
     fetchChain: (() => Promise<ChainConfig[]>) | null;
+    sharedWs?: SharedWebSocket | null;
 }
 /**
  * Runtime configuration handle for a specific environment.
@@ -89,16 +137,10 @@ declare class ConfigRuntime {
     private _fetchCount;
     private _lastFetchAt;
     private _closed;
-    private _wsStatus;
-    private _ws;
-    private _reconnectTimer;
-    private _backoffIndex;
     private _listeners;
-    private readonly _configId;
     private readonly _environment;
-    private readonly _apiKey;
-    private readonly _baseUrl;
     private readonly _fetchChain;
+    private _sharedWs;
     /** @internal */
     constructor(options: ConfigRuntimeOptions);
     /**
@@ -158,31 +200,20 @@ declare class ConfigRuntime {
     /**
      * Close the runtime connection.
      *
-     * Shuts down the WebSocket and cancels any pending reconnect timer.
-     * Safe to call multiple times.
+     * Unregisters from the shared WebSocket. Safe to call multiple times.
      */
     close(): Promise<void>;
     /**
      * Async dispose support for `await using` (TypeScript 5.2+).
      */
     [Symbol.asyncDispose](): Promise<void>;
-    private _buildWsUrl;
-    private _connectWebSocket;
-    private _scheduleReconnect;
-    private _handleMessage;
+    private _handleConfigChanged;
+    private _handleConfigDeleted;
     private _applyChanges;
     private _diffAndFire;
     private _fireListeners;
 }
 
-/**
- * Config resource — management-plane model with runtime connect support.
- *
- * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations (`update`, `setValues`, `setValue`) as well
- * as the {@link connect} entry point for runtime value resolution.
- */
-
 /**
  * Internal type used by {@link ConfigClient}.  Not part of the public API.
  * @internal
@@ -239,6 +270,7 @@ declare class Config {
         }): Promise<Config>;
         readonly _apiKey: string;
         readonly _baseUrl: string;
+        _getSharedWs?: () => SharedWebSocket;
     }, fields: {
         id: string;
         key: string;
@@ -342,14 +374,6 @@ interface GetConfigOptions {
     id?: string;
 }
 
-/**
- * ConfigClient — management-plane operations for configs.
- *
- * Uses the generated OpenAPI types (`src/generated/config.d.ts`) via
- * `openapi-fetch` for all HTTP calls, keeping the client layer fully
- * type-safe without hand-coded request/response shapes.
- */
-
 /**
  * Client for the smplkit Config API (management plane).
  *
@@ -365,6 +389,8 @@ declare class ConfigClient {
     readonly _baseUrl: string;
     /** @internal */
     private readonly _http;
+    /** @internal — returns the shared WebSocket for real-time updates. */
+    _getSharedWs?: () => SharedWebSocket;
     /** @internal */
     constructor(apiKey: string, timeout?: number);
     /**
@@ -403,6 +429,384 @@ declare class ConfigClient {
     private _getByKey;
 }
 
+/**
+ * Flag and ContextType resource models returned by the management API.
+ */
+
+/**
+ * A flag resource returned by {@link FlagsClient} management methods.
+ *
+ * Provides `update()` for partial updates and `addRule()` for
+ * conveniently appending a rule to an environment.
+ */
+declare class Flag {
+    /** UUID of the flag. */
+    id: string;
+    /** Unique key within the account. */
+    key: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Value type: BOOLEAN, STRING, NUMERIC, or JSON. */
+    type: string;
+    /** Flag-level default value. */
+    default: unknown;
+    /** Closed set of possible values. */
+    values: Array<{
+        name: string;
+        value: unknown;
+    }>;
+    /** Optional description. */
+    description: string | null;
+    /** Per-environment configuration. */
+    environments: Record<string, any>;
+    /** When the flag was created. */
+    createdAt: string | null;
+    /** When the flag was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    private readonly _client;
+    /** @internal */
+    constructor(client: FlagsClient, fields: {
+        id: string;
+        key: string;
+        name: string;
+        type: string;
+        default: unknown;
+        values: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        description: string | null;
+        environments: Record<string, any>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /**
+     * Update this flag's attributes on the server.
+     *
+     * Only provided fields are changed; others retain their current values.
+     */
+    update(options: {
+        environments?: Record<string, any>;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        default?: unknown;
+        description?: string;
+        name?: string;
+    }): Promise<void>;
+    /**
+     * Add a rule to a specific environment.
+     *
+     * The built rule must include an `environment` key (set via
+     * `Rule(...).environment("env_key")`).  Re-fetches current state
+     * first to avoid stale data.
+     */
+    addRule(builtRule: Record<string, any>): Promise<void>;
+    /** @internal */
+    _apply(other: Flag): void;
+    toString(): string;
+}
+/** A context type resource returned by management API methods. */
+declare class ContextType {
+    /** UUID. */
+    id: string;
+    /** Unique key within the account. */
+    key: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Known attributes. */
+    attributes: Record<string, any>;
+    constructor(fields: {
+        id: string;
+        key: string;
+        name: string;
+        attributes: Record<string, any>;
+    });
+    toString(): string;
+}
+
+/**
+ * Public types for the Flags SDK: FlagType, Context, Rule.
+ */
+/** The value type of a flag. */
+type FlagType = "BOOLEAN" | "STRING" | "NUMERIC" | "JSON";
+/**
+ * A typed evaluation context entity.
+ *
+ * Represents a single entity (user, account, device, etc.) in the
+ * evaluation context.  The *type* and *key* identify the entity;
+ * *attributes* carry the data that JSON Logic rules target.
+ *
+ * @example
+ * ```typescript
+ * new Context("user", "user-123", { plan: "enterprise", firstName: "Alice" })
+ * new Context("user", "user-123", { plan: "enterprise" }, { name: "Alice Smith" })
+ * ```
+ */
+declare class Context {
+    readonly type: string;
+    readonly key: string;
+    readonly name: string | null;
+    readonly attributes: Record<string, unknown>;
+    constructor(type: string, key: string, attributes?: Record<string, unknown>, options?: {
+        name?: string;
+    });
+    toString(): string;
+}
+/**
+ * Fluent builder for JSON Logic rule dicts.
+ *
+ * @example
+ * ```typescript
+ * new Rule("Enable for enterprise users")
+ *     .when("user.plan", "==", "enterprise")
+ *     .when("account.region", "==", "us")
+ *     .serve(true)
+ *     .build()
+ * ```
+ *
+ * Multiple `.when()` calls are AND'd.  `.environment()` tags the
+ * built dict with an environment key for use with `Flag.addRule()`.
+ */
+declare class Rule {
+    private _description;
+    private _conditions;
+    private _value;
+    private _environment;
+    constructor(description: string);
+    /** Tag this rule with an environment key (used by `addRule`). */
+    environment(envKey: string): Rule;
+    /** Add a condition.  Multiple calls are AND'd. */
+    when(variable: string, op: string, value: any): Rule;
+    /** Set the value returned when this rule matches. */
+    serve(value: any): Rule;
+    /** Finalize and return the rule as a plain object. */
+    build(): Record<string, any>;
+}
+
+/**
+ * FlagsClient — management + prescriptive runtime for Smpl Flags.
+ *
+ * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
+ * `openapi-fetch` for all HTTP calls. Context type management and
+ * context registration use direct HTTP via the Transport class since
+ * these endpoints are on the flags service but not in the generated spec.
+ */
+
+/** Describes a flag definition change. */
+declare class FlagChangeEvent {
+    readonly key: string;
+    readonly source: string;
+    constructor(key: string, source: string);
+}
+/** Cache statistics for the flags runtime. */
+declare class FlagStats {
+    readonly cacheHits: number;
+    readonly cacheMisses: number;
+    constructor(cacheHits: number, cacheMisses: number);
+}
+/** @internal */
+declare class FlagHandleBase {
+    /** @internal */ readonly _namespace: FlagsClient;
+    /** @internal */ readonly _key: string;
+    /** @internal */ readonly _default: any;
+    /** @internal */ _listeners: Array<(event: FlagChangeEvent) => void>;
+    constructor(namespace: FlagsClient, key: string, defaultValue: any);
+    get key(): string;
+    get default(): any;
+    get(options?: {
+        context?: Context[];
+    }): any;
+    /** Register a flag-specific change listener. Works as a decorator. */
+    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+}
+/** Typed handle for a boolean flag. */
+declare class BoolFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): boolean;
+}
+/** Typed handle for a string flag. */
+declare class StringFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): string;
+}
+/** Typed handle for a numeric flag. */
+declare class NumberFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): number;
+}
+/** Typed handle for a JSON flag. */
+declare class JsonFlagHandle extends FlagHandleBase {
+    get(options?: {
+        context?: Context[];
+    }): Record<string, any>;
+}
+/**
+ * Client for the smplkit Flags API — management plane + prescriptive runtime.
+ *
+ * Obtained via `SmplClient.flags`.
+ */
+declare class FlagsClient {
+    /** @internal */
+    readonly _apiKey: string;
+    /** @internal */
+    readonly _baseUrl: string;
+    /** @internal */
+    private readonly _http;
+    /** @internal */
+    private readonly _transport;
+    private _environment;
+    private _flagStore;
+    private _connected;
+    private _cache;
+    private _contextProvider;
+    private _contextBuffer;
+    private _handles;
+    private _globalListeners;
+    private _wsManager;
+    private readonly _ensureWs;
+    /** @internal */
+    constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
+    /** Create a flag. */
+    create(key: string, options: {
+        name: string;
+        type: FlagType;
+        default: unknown;
+        description?: string;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+    }): Promise<Flag>;
+    /** Fetch a flag by UUID. */
+    get(flagId: string): Promise<Flag>;
+    /** List all flags. */
+    list(): Promise<Flag[]>;
+    /** Delete a flag by UUID. */
+    delete(flagId: string): Promise<void>;
+    /**
+     * Internal: PUT a full flag update.
+     * Called by {@link Flag} instance methods.
+     * @internal
+     */
+    _updateFlag(options: {
+        flag: Flag;
+        environments?: Record<string, any>;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+        default?: unknown;
+        description?: string;
+        name?: string;
+    }): Promise<Flag>;
+    /** Create a context type. */
+    createContextType(key: string, options: {
+        name: string;
+    }): Promise<ContextType>;
+    /** Update a context type (merge attributes). */
+    updateContextType(ctId: string, options: {
+        attributes: Record<string, any>;
+    }): Promise<ContextType>;
+    /** List all context types. */
+    listContextTypes(): Promise<ContextType[]>;
+    /** Delete a context type. */
+    deleteContextType(ctId: string): Promise<void>;
+    /** List context instances filtered by context type key. */
+    listContexts(options: {
+        contextTypeKey: string;
+    }): Promise<any[]>;
+    /** Declare a boolean flag handle. */
+    boolFlag(key: string, defaultValue: boolean): BoolFlagHandle;
+    /** Declare a string flag handle. */
+    stringFlag(key: string, defaultValue: string): StringFlagHandle;
+    /** Declare a numeric flag handle. */
+    numberFlag(key: string, defaultValue: number): NumberFlagHandle;
+    /** Declare a JSON flag handle. */
+    jsonFlag(key: string, defaultValue: Record<string, any>): JsonFlagHandle;
+    /**
+     * Register a context provider function.
+     *
+     * Called on every `handle.get()` to supply the current evaluation
+     * context. Can also be used as a decorator:
+     *
+     * ```typescript
+     * client.flags.setContextProvider(() => [
+     *   new Context("user", userId, { plan: userPlan }),
+     * ]);
+     * ```
+     */
+    setContextProvider(fn: () => Context[]): void;
+    /**
+     * Register a context provider — decorator-style alias.
+     *
+     * ```typescript
+     * const provider = client.flags.contextProvider(() => [...]);
+     * ```
+     */
+    contextProvider(fn: () => Context[]): () => Context[];
+    /**
+     * Connect to an environment: fetch flag definitions, register on
+     * shared WebSocket, enable local evaluation.
+     */
+    connect(environment: string, _options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
+    disconnect(): Promise<void>;
+    /** Re-fetch all flag definitions and clear cache. */
+    refresh(): Promise<void>;
+    /** Return the current WebSocket connection status. */
+    connectionStatus(): string;
+    /** Return cache statistics. */
+    stats(): FlagStats;
+    /** Register a global change listener that fires for any flag change. */
+    onChangeAny(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    /**
+     * Register a global change listener — decorator-style alias.
+     *
+     * ```typescript
+     * const listener = client.flags.onChange((event) => { ... });
+     * ```
+     */
+    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    /**
+     * Explicitly register context(s) for background batch registration.
+     *
+     * Accepts a single Context or an array. Fire-and-forget — never
+     * blocks. Works before `connect()` 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.
+     *
+     * Useful for scripts, one-off jobs, and infrastructure code.
+     */
+    evaluate(key: string, options: {
+        environment: string;
+        context: Context[];
+    }): Promise<any>;
+    /** @internal */
+    _evaluateHandle(key: string, defaultValue: any, context: Context[] | null): any;
+    private _handleFlagChanged;
+    private _handleFlagDeleted;
+    private _fetchAllFlags;
+    private _fetchFlagsList;
+    private _fireChangeListeners;
+    private _fireChangeListenersAll;
+    private _flushContexts;
+    private _resourceToModel;
+    private _resourceToPlainDict;
+    private _parseContextType;
+}
+
 /**
  * Top-level SDK client — SmplClient.
  *
@@ -438,7 +842,15 @@ interface SmplClientOptions {
 declare class SmplClient {
     /** Client for config management-plane operations. */
     readonly config: ConfigClient;
+    /** Client for flags management and runtime operations. */
+    readonly flags: FlagsClient;
+    private _wsManager;
+    private readonly _apiKey;
     constructor(options?: SmplClientOptions);
+    /** Lazily create and start the shared WebSocket. @internal */
+    private _ensureWs;
+    /** Close the shared WebSocket and release resources. */
+    close(): void;
 }
 
 /**
@@ -477,4 +889,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string);
 }
 
-export { Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, type CreateConfigOptions, type GetConfigOptions, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError };
+export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, ConfigRuntime, type ConfigStats, type ConnectOptions, type ConnectionStatus, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };