@smplkit/sdk 1.3.12 → 1.3.14

package/dist/index.d.ts

@@ -46,36 +46,19 @@ declare class SharedWebSocket {
 }
 
 /**
- * Config resource — management-plane model.
- *
- * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations (`update`, `setValues`, `setValue`).
- * Prescriptive value access is via `client.config.getValue()` after
- * `client.connect()`.
- */
-/**
- * Internal type used by {@link ConfigClient}.  Not part of the public API.
- * @internal
+ * Config resource — active-record model with save() pattern.
  */
-interface ConfigUpdatePayload {
-    configId: string;
-    name: string;
-    key: string | null;
-    description: string | null;
-    parent: string | null;
-    items: Record<string, unknown>;
-    environments: Record<string, unknown>;
-}
+
 /**
- * A configuration resource fetched from the smplkit Config service.
+ * A configuration resource managed by the smplkit platform.
  *
- * Instances are returned by {@link ConfigClient} methods and provide
- * management-plane operations (update, setValues, setValue).
+ * Management: mutate properties directly and call `save()` to persist.
+ * POST if `id` is null (new), PUT if `id` is set (update).
  */
 declare class Config {
-    /** UUID of the config. */
-    id: string;
-    /** Human-readable key (e.g. `"user_service"`). */
+    /** UUID of the config, or `null` if unsaved. */
+    id: string | null;
+    /** Human-readable key (e.g. `"user-service"`). */
     key: string;
     /** Display name. */
     name: string;
@@ -92,102 +75,75 @@ declare class Config {
      */
     environments: Record<string, unknown>;
     /** When the config was created, or null if unavailable. */
-    createdAt: Date | null;
+    createdAt: string | null;
     /** When the config was last updated, or null if unavailable. */
-    updatedAt: Date | null;
-    /**
-     * Internal reference to the parent client.
-     * @internal
-     */
-    private readonly _client;
+    updatedAt: string | null;
     /** @internal */
-    constructor(client: {
-        _updateConfig(payload: ConfigUpdatePayload): Promise<Config>;
-        get(options: {
-            id: string;
-        }): Promise<Config>;
-        readonly _apiKey: string;
-        readonly _baseUrl: string;
-        _getSharedWs?: () => SharedWebSocket;
-    }, fields: {
-        id: string;
+    readonly _client: ConfigClient;
+    /** @internal */
+    constructor(client: ConfigClient, fields: {
+        id: string | null;
         key: string;
         name: string;
         description: string | null;
         parent: string | null;
         items: Record<string, unknown>;
         environments: Record<string, unknown>;
-        createdAt: Date | null;
-        updatedAt: Date | null;
+        createdAt: string | null;
+        updatedAt: string | null;
     });
     /**
-     * Update this config's attributes on the server.
-     *
-     * Builds the request from current attribute values, overriding with any
-     * provided options. Updates local attributes in place on success.
-     *
-     * @param options.name - New display name.
-     * @param options.description - New description (pass empty string to clear).
-     * @param options.items - New base values (replaces entirely).
-     * @param options.environments - New environments dict (replaces entirely).
-     */
-    update(options: {
-        name?: string;
-        description?: string;
-        items?: Record<string, unknown>;
-        environments?: Record<string, unknown>;
-    }): Promise<void>;
-    /**
-     * Replace base or environment-specific values.
-     *
-     * When `environment` is provided, replaces that environment's `values`
-     * sub-dict (other environments are preserved). When omitted, replaces
-     * the base `items`.
-     *
-     * @param values - The complete set of values to set.
-     * @param environment - Target environment, or omit for base values.
-     */
-    setValues(values: Record<string, unknown>, environment?: string): Promise<void>;
-    /**
-     * Set a single key within base or environment-specific values.
-     *
-     * Merges the key into existing values rather than replacing all values.
+     * Persist this config to the server.
      *
-     * @param key - The config key to set.
-     * @param value - The value to assign.
-     * @param environment - Target environment, or omit for base values.
+     * POST if `id` is null (new config), PUT if `id` is set (update).
+     * Updates this instance in-place with the server response.
      */
-    setValue(key: string, value: unknown, environment?: string): Promise<void>;
+    save(): Promise<void>;
     /**
      * Walk the parent chain and return config data objects, child-to-root.
      * @internal
      */
-    _buildChain(_timeout?: unknown): Promise<Array<{
+    _buildChain(): Promise<Array<{
         id: string;
         items: Record<string, unknown>;
         environments: Record<string, unknown>;
     }>>;
+    /** @internal — copy all fields from another Config instance. */
+    _apply(other: Config): void;
     toString(): string;
 }
-/** Options for creating a new config. */
-interface CreateConfigOptions {
-    /** Display name for the config. */
-    name: string;
-    /** Human-readable key. Auto-generated by the server if omitted. */
-    key?: string;
-    /** Optional description. */
-    description?: string;
-    /** Parent config UUID. Defaults to the account's `common` config if omitted. */
-    parent?: string;
-    /** Initial base values. */
-    items?: Record<string, unknown>;
-}
-/** Options for fetching a single config. Exactly one of `key` or `id` must be provided. */
-interface GetConfigOptions {
-    /** Fetch by human-readable key. */
-    key?: string;
-    /** Fetch by UUID. */
-    id?: string;
+
+/**
+ * LiveConfigProxy — ES6 Proxy-based 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.
+ */
+
+/**
+ * A live proxy that auto-updates when the underlying config changes.
+ *
+ * Access properties directly — each read re-resolves from the cache.
+ *
+ * @example
+ * ```typescript
+ * const proxy = await client.config.subscribe("user-service");
+ * console.log(proxy.timeout);  // reads from live cache
+ * // ... later, after a WebSocket update ...
+ * console.log(proxy.timeout);  // reads the updated value
+ * ```
+ */
+declare class LiveConfigProxy<T = Record<string, unknown>> {
+    /** @internal */
+    private readonly _client;
+    /** @internal */
+    private readonly _key;
+    /** @internal */
+    private readonly _model?;
+    constructor(client: ConfigClient, key: string, model?: new (data: any) => T);
+    /** @internal */
+    _currentValues(): Record<string, unknown>;
 }
 
 /** Describes a single config value change detected on refresh. */
@@ -204,15 +160,12 @@ interface ConfigChangeEvent {
     source: "websocket" | "manual";
 }
 /**
- * Client for the smplkit Config API (management plane).
- *
- * All methods are async and return `Promise<T>`. Network and server
- * errors are mapped to typed SDK exceptions.
+ * Client for the smplkit Config API — management plane + runtime.
  *
  * Obtained via `SmplClient.config`.
  */
 declare class ConfigClient {
-    /** @internal — used by Config instances for reconnecting and WebSocket auth. */
+    /** @internal */
     readonly _apiKey: string;
     /** @internal */
     readonly _baseUrl: string;
@@ -226,205 +179,287 @@ declare class ConfigClient {
         readonly _service: string | null;
     } | null;
     private _configCache;
-    private _connected;
+    private _initialized;
     private _listeners;
     /** @internal */
     constructor(apiKey: string, timeout?: number);
-    /**
-     * Fetch a single config by key or UUID.
-     *
-     * Exactly one of `key` or `id` must be provided.
-     *
-     * @throws {SmplNotFoundError} If no matching config exists.
-     */
-    get(options: GetConfigOptions): Promise<Config>;
-    /**
-     * List all configs for the account.
-     */
+    /** Create an unsaved config. Call `.save()` to persist. */
+    new(key: string, options?: {
+        name?: string;
+        description?: string;
+        parent?: string;
+    }): Config;
+    /** Fetch a config by key. */
+    get(key: string): Promise<Config>;
+    /** List all configs. */
     list(): Promise<Config[]>;
+    /** Delete a config by key. */
+    delete(key: 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>;
     /**
-     * Create a new config.
-     *
-     * @throws {SmplValidationError} If the server rejects the request.
-     */
-    create(options: CreateConfigOptions): Promise<Config>;
-    /**
-     * Delete a config by UUID.
-     *
-     * @throws {SmplNotFoundError} If the config does not exist.
-     * @throws {SmplConflictError} If the config has child configs.
-     */
-    delete(configId: string): Promise<void>;
-    /**
-     * Fetch all configs, resolve values for the environment, and cache.
-     * @internal — called by SmplClient.connect().
-     */
-    _connectInternal(environment: string): Promise<void>;
-    /**
-     * Read a resolved config value (prescriptive access).
-     *
-     * Requires {@link SmplClient.connect} to have been called.
-     *
-     * @param configKey - The config key to look up.
-     * @param itemKey - Optional specific item key. If omitted, returns all values.
-     * @param defaultValue - Default value if the key is missing.
+     * Resolve a config's values for the current environment.
      *
-     * @throws {SmplNotConnectedError} If connect() has not been called.
-     */
-    getValue(configKey: string, itemKey?: string, defaultValue?: unknown): unknown;
-    /**
-     * Return a config value as a string, or `defaultValue` if absent or not a string.
+     * Returns a flat dict of resolved key-value pairs, walking the
+     * parent chain and applying environment overrides.
      *
-     * @throws {SmplNotConnectedError} If connect() has not been called.
+     * Optionally pass a model class to map the resolved values.
      */
-    getString(configKey: string, itemKey: string, defaultValue?: string | null): string | null;
+    resolve<T = Record<string, unknown>>(key: string, model?: new (data: any) => T): Promise<T>;
     /**
-     * Return a config value as a number, or `defaultValue` if absent or not a number.
+     * Subscribe to a config's values — returns a live proxy that
+     * auto-updates when the underlying config changes.
      *
-     * @throws {SmplNotConnectedError} If connect() has not been called.
+     * Optionally pass a model class to map the resolved values.
      */
-    getInt(configKey: string, itemKey: string, defaultValue?: number | null): number | null;
+    subscribe<T = Record<string, unknown>>(key: string, model?: new (data: any) => T): Promise<LiveConfigProxy<T>>;
     /**
-     * Return a config value as a boolean, or `defaultValue` if absent or not a boolean.
+     * Register a change listener.
      *
-     * @throws {SmplNotConnectedError} If connect() has not been called.
+     * - `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.
      */
-    getBool(configKey: string, itemKey: string, defaultValue?: boolean | null): boolean | null;
+    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.
-     *
-     * Fires change listeners for any values that differ from the previous cache.
-     *
-     * @throws {SmplNotConnectedError} If connect() has not been called.
+     * Fires change listeners for any values that differ.
      */
     refresh(): Promise<void>;
-    /**
-     * Register a listener that fires when a config value changes (on refresh).
-     *
-     * @param callback - Called with a {@link ConfigChangeEvent} on each change.
-     * @param options.configKey - If provided, only fire for changes to this config.
-     * @param options.itemKey - If provided, only fire for changes to this item key.
-     */
-    onChange(callback: (event: ConfigChangeEvent) => void, options?: {
-        configKey?: string;
-        itemKey?: string;
-    }): void;
+    /** @internal */
+    private _ensureInitialized;
+    /** @internal — called by SmplClient for backward compat. */
+    _connectInternal(environment: string): Promise<void>;
+    /** @internal — get resolved config from cache. Used by LiveConfigProxy. */
+    _getCachedConfig(key: string): Record<string, unknown> | undefined;
+    private _handleConfigChanged;
     /** @internal */
     private _diffAndFire;
-    /**
-     * Internal: PUT a full config update and return the updated model.
-     *
-     * Called by {@link Config} instance methods.
-     * @internal
-     */
-    _updateConfig(payload: ConfigUpdatePayload): Promise<Config>;
-    private _getById;
     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<{
+interface components {
+    schemas: {
+        /**
+         * Flag
+         * @example {
+         *       "created_at": "2026-03-27T10:00:00Z",
+         *       "default": false,
+         *       "description": "Enable dark mode for the application UI",
+         *       "environments": {
+         *         "production": {
+         *           "default": false,
+         *           "enabled": true,
+         *           "rules": [
+         *             {
+         *               "description": "Beta users get dark mode",
+         *               "logic": {
+         *                 "attribute": "beta",
+         *                 "op": "eq",
+         *                 "value": true
+         *               },
+         *               "value": true
+         *             }
+         *           ]
+         *         },
+         *         "staging": {
+         *           "default": true,
+         *           "enabled": true,
+         *           "rules": []
+         *         }
+         *       },
+         *       "key": "dark_mode",
+         *       "name": "Dark Mode",
+         *       "type": "BOOLEAN",
+         *       "updated_at": "2026-03-27T10:00:00Z",
+         *       "values": [
+         *         {
+         *           "name": "on",
+         *           "value": true
+         *         },
+         *         {
+         *           "name": "off",
+         *           "value": false
+         *         }
+         *       ]
+         *     }
+         */
+        Flag: {
+            /**
+             * Key
+             * @description Unique key within account
+             */
+            key: string;
+            /**
+             * Name
+             * @description Human-readable display name
+             */
             name: string;
+            /**
+             * Description
+             * @default
+             */
+            description: string;
+            /**
+             * Type
+             * @description Value type: STRING, BOOLEAN, NUMERIC, or JSON
+             */
+            type: string;
+            /**
+             * Default
+             * @description Default value; must reference a value in the values array
+             */
+            default: unknown;
+            /**
+             * Values
+             * @description Closed set of possible values
+             */
+            values: components["schemas"]["FlagValue"][];
+            /** Environments */
+            environments?: {
+                [key: string]: components["schemas"]["FlagEnvironment"];
+            };
+            /** Created At */
+            readonly created_at?: string | null;
+            /** Updated At */
+            readonly updated_at?: string | null;
+        };
+        /** FlagEnvironment */
+        FlagEnvironment: {
+            /**
+             * Enabled
+             * @default false
+             */
+            enabled: boolean;
+            /** Default */
+            default?: unknown | null;
+            /** Rules */
+            rules?: components["schemas"]["FlagRule"][];
+        };
+        /** FlagListResponse */
+        FlagListResponse: {
+            /** Data */
+            data: components["schemas"]["FlagResource"][];
+        };
+        /**
+         * FlagResource
+         * @example {
+         *       "attributes": {
+         *         "created_at": "2026-03-27T10:00:00Z",
+         *         "default": false,
+         *         "description": "Enable dark mode for the application UI",
+         *         "environments": {
+         *           "production": {
+         *             "default": false,
+         *             "enabled": true,
+         *             "rules": [
+         *               {
+         *                 "description": "Beta users get dark mode",
+         *                 "logic": {
+         *                   "attribute": "beta",
+         *                   "op": "eq",
+         *                   "value": true
+         *                 },
+         *                 "value": true
+         *               }
+         *             ]
+         *           }
+         *         },
+         *         "key": "dark_mode",
+         *         "name": "Dark Mode",
+         *         "type": "BOOLEAN",
+         *         "updated_at": "2026-03-27T10:00:00Z",
+         *         "values": [
+         *           {
+         *             "name": "on",
+         *             "value": true
+         *           },
+         *           {
+         *             "name": "off",
+         *             "value": false
+         *           }
+         *         ]
+         *       },
+         *       "id": "550e8400-e29b-41d4-a716-446655440000",
+         *       "type": "flag"
+         *     }
+         */
+        FlagResource: {
+            /** Id */
+            id?: string | null;
+            /**
+             * Type
+             * @constant
+             */
+            type: "flag";
+            attributes: components["schemas"]["Flag"];
+        };
+        /** FlagResponse */
+        FlagResponse: {
+            data: components["schemas"]["FlagResource"];
+        };
+        /** FlagRule */
+        FlagRule: {
+            /** Description */
+            description?: string | null;
+            /** Logic */
+            logic: {
+                [key: string]: unknown;
+            };
+            /** Value */
             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<{
+        };
+        /** FlagValue */
+        FlagValue: {
+            /** Name */
             name: string;
+            /** Value */
             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;
+        };
+        /** HTTPValidationError */
+        HTTPValidationError: {
+            /** Detail */
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        /** Resource[Flag] */
+        Resource_Flag_: {
+            /** Id */
+            id?: string | null;
+            /**
+             * Type
+             * @default
+             */
+            type: string;
+            attributes: components["schemas"]["Flag"];
+        };
+        /** Response[Flag] */
+        Response_Flag_: {
+            data: components["schemas"]["Resource_Flag_"];
+        };
+        /** ValidationError */
+        ValidationError: {
+            /** Location */
+            loc: (string | number)[];
+            /** Message */
+            msg: string;
+            /** Error Type */
+            type: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
 }
 
 /**
- * Public types for the Flags SDK: FlagType, Context, Rule.
+ * Public types for the Flags SDK: Context, Rule.
  */
-/** The value type of a flag. */
-type FlagType = "BOOLEAN" | "STRING" | "NUMERIC" | "JSON";
 /**
  * A typed evaluation context entity.
  *
@@ -480,65 +515,141 @@ declare class Rule {
 }
 
 /**
- * FlagsClient — management + prescriptive runtime for Smpl Flags.
+ * Unified Flag hierarchy — management model + runtime handle.
  *
- * Uses the generated OpenAPI types (`src/generated/flags.d.ts`) via
- * `openapi-fetch` for all flag HTTP calls. Context type management and
- * context registration use the generated app service types
- * (`src/generated/app.d.ts`) via a separate `openapi-fetch` client.
+ * A single {@link Flag} class replaces the old separate Flag + FlagHandle
+ * classes. Typed subclasses ({@link BooleanFlag}, {@link StringFlag},
+ * {@link NumberFlag}, {@link JsonFlag}) override `get()` for type safety.
  */
 
-/** 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;
+/**
+ * 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.
+ */
+declare class Flag {
+    /** UUID of the flag, or `null` if unsaved. */
+    id: string | null;
+    /** 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 */
+    readonly _client: FlagsClient;
+    /** @internal */
+    constructor(client: FlagsClient, fields: {
+        id: string | null;
+        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;
+    });
+    /**
+     * Persist this flag to the server.
+     *
+     * POST if `id` is null (new flag), PUT if `id` is set (update).
+     * Updates this instance in-place with the server response.
+     */
+    save(): Promise<void>;
+    /**
+     * Add a rule to a specific environment (sync local mutation).
+     *
+     * The built rule must include an `environment` key (set via
+     * `Rule(...).environment("env_key")`). No HTTP call is made.
+     *
+     * @returns `this` for chaining.
+     */
+    addRule(builtRule: Record<string, any>): Flag;
+    /** Enable or disable a flag in a specific environment (sync local mutation). */
+    setEnvironmentEnabled(envKey: string, enabled: boolean): void;
+    /** Set the default value for a specific environment (sync local mutation). */
+    setEnvironmentDefault(envKey: string, defaultValue: unknown): void;
+    /** Clear all rules for a specific environment (sync local mutation). */
+    clearRules(envKey: string): void;
+    /**
+     * Evaluate the flag locally (sync, no HTTP).
+     *
+     * Requires `initialize()` to have been called.
+     */
     get(options?: {
         context?: Context[];
-    }): any;
-    /** Register a flag-specific change listener. Works as a decorator. */
-    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    }): unknown;
+    /** @internal — copy all fields from another Flag instance. */
+    _apply(other: Flag): void;
+    toString(): string;
 }
-/** Typed handle for a boolean flag. */
-declare class BoolFlagHandle extends FlagHandleBase {
+/** Typed flag that returns `boolean` from `get()`. */
+declare class BooleanFlag extends Flag {
     get(options?: {
         context?: Context[];
     }): boolean;
 }
-/** Typed handle for a string flag. */
-declare class StringFlagHandle extends FlagHandleBase {
+/** Typed flag that returns `string` from `get()`. */
+declare class StringFlag extends Flag {
     get(options?: {
         context?: Context[];
     }): string;
 }
-/** Typed handle for a numeric flag. */
-declare class NumberFlagHandle extends FlagHandleBase {
+/** Typed flag that returns `number` from `get()`. */
+declare class NumberFlag extends Flag {
     get(options?: {
         context?: Context[];
     }): number;
 }
-/** Typed handle for a JSON flag. */
-declare class JsonFlagHandle extends FlagHandleBase {
+/** Typed flag that returns `Record<string, any>` from `get()`. */
+declare class JsonFlag extends Flag {
     get(options?: {
         context?: Context[];
     }): 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 flag HTTP calls. Context registration uses
+ * the generated app service types (`src/generated/app.d.ts`).
+ */
+
+type FlagResource = components["schemas"]["FlagResource"];
+/** 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);
+}
 /**
  * Client for the smplkit Flags API — management plane + prescriptive runtime.
  *
@@ -555,12 +666,13 @@ declare class FlagsClient {
     private readonly _appHttp;
     private _environment;
     private _flagStore;
-    private _connected;
+    private _initialized;
     private _cache;
     private _contextProvider;
     private _contextBuffer;
     private _handles;
     private _globalListeners;
+    private _keyListeners;
     private _wsManager;
     private readonly _ensureWs;
     /** @internal — set by SmplClient after construction. */
@@ -570,92 +682,77 @@ declare class FlagsClient {
     } | null;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
-    /** Create a flag. */
-    create(key: string, options: {
-        name: string;
-        type: FlagType;
-        default: unknown;
+    /** Create an unsaved boolean flag. Call `.save()` to persist. */
+    newBooleanFlag(key: string, options: {
+        default: boolean;
+        name?: string;
+        description?: string;
+    }): BooleanFlag;
+    /** Create an unsaved string flag. Call `.save()` to persist. */
+    newStringFlag(key: string, options: {
+        default: string;
+        name?: string;
         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>;
+    }): StringFlag;
+    /** Create an unsaved number flag. Call `.save()` to persist. */
+    newNumberFlag(key: string, options: {
+        default: number;
+        name?: string;
+        description?: string;
         values?: Array<{
             name: string;
             value: unknown;
         }>;
-        default?: unknown;
-        description?: string;
+    }): NumberFlag;
+    /** Create an unsaved JSON flag. Call `.save()` to persist. */
+    newJsonFlag(key: string, options: {
+        default: Record<string, any>;
         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: {
-        key: string;
-        name: string;
-        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;
+        description?: string;
+        values?: Array<{
+            name: string;
+            value: unknown;
+        }>;
+    }): JsonFlag;
+    /** Fetch a flag by key. */
+    get(key: string): Promise<Flag>;
+    /** List all flags. */
+    list(): Promise<Flag[]>;
+    /** Delete a flag by key. */
+    delete(key: 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;
+    /** Declare a string flag handle for runtime evaluation. */
+    stringFlag(key: string, defaultValue: string): StringFlag;
+    /** Declare a numeric flag handle for runtime evaluation. */
+    numberFlag(key: string, defaultValue: number): NumberFlag;
+    /** Declare a JSON flag handle for runtime evaluation. */
+    jsonFlag(key: string, defaultValue: Record<string, any>): JsonFlag;
     /**
      * 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 }),
-     * ]);
-     * ```
+     * Called on every `handle.get()` to supply the current evaluation context.
      */
     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.
-     * @internal — called by SmplClient.connect().
+     * Initialize the flags runtime: fetch definitions and wire WebSocket.
+     *
+     * Idempotent — safe to call multiple times. Must be called (and awaited)
+     * before using `.get()` on flag handles.
      */
-    _connectInternal(environment: string): Promise<void>;
+    initialize(): Promise<void>;
     /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
     disconnect(): Promise<void>;
     /** Re-fetch all flag definitions and clear cache. */
@@ -664,29 +761,24 @@ declare class FlagsClient {
     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.
+     * Register a change listener.
      *
-     * ```typescript
-     * const listener = client.flags.onChange((event) => { ... });
-     * ```
+     * - `onChange(callback)` — fires for any flag change (global).
+     * - `onChange(key, callback)` — fires only for the specified flag key.
      */
-    onChange(callback: (event: FlagChangeEvent) => void): (event: FlagChangeEvent) => void;
+    onChange(callbackOrKey: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): 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.
+     * 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.
-     *
-     * Useful for scripts, one-off jobs, and infrastructure code.
      */
     evaluate(key: string, options: {
         environment: string;
@@ -694,6 +786,8 @@ declare class FlagsClient {
     }): Promise<any>;
     /** @internal */
     _evaluateHandle(key: string, defaultValue: any, context: Context[] | null): any;
+    /** @internal — called by SmplClient constructor / lazy init. */
+    _connectInternal(environment: string): Promise<void>;
     private _handleFlagChanged;
     private _handleFlagDeleted;
     private _fetchAllFlags;
@@ -701,16 +795,243 @@ declare class FlagsClient {
     private _fireChangeListeners;
     private _fireChangeListenersAll;
     private _flushContexts;
-    private _resourceToModel;
+    /** @internal */
+    _resourceToModel(resource: FlagResource): Flag;
     private _resourceToPlainDict;
-    private _parseContextType;
+}
+
+/**
+ * Public types for the Logging SDK.
+ */
+/** Log level values matching the smplkit platform. */
+declare enum LogLevel {
+    TRACE = "TRACE",
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    FATAL = "FATAL",
+    SILENT = "SILENT"
+}
+/** Describes a logger configuration change. */
+interface LoggerChangeEvent {
+    /** The logger key that changed. */
+    key: string;
+    /** The new effective log level, or null if removed. */
+    level: LogLevel | null;
+    /** How the change was delivered. */
+    source: string;
+}
+
+/**
+ * Logger and LogGroup active-record models for the Logging SDK.
+ */
+
+/**
+ * A logger resource managed by the smplkit platform.
+ *
+ * Management: mutate properties and call `save()` to persist.
+ * Convenience methods (`setLevel`, `setEnvironmentLevel`, etc.) are
+ * sync local mutations — no HTTP until `save()`.
+ */
+declare class Logger {
+    /** UUID of the logger, or `null` if unsaved. */
+    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. */
+    group: string | null;
+    /** Whether this logger is managed by the platform. */
+    managed: boolean;
+    /** Observed sources (services that report this logger). */
+    sources: Array<Record<string, any>>;
+    /** Per-environment level overrides. */
+    environments: Record<string, any>;
+    /** When the logger was created. */
+    createdAt: string | null;
+    /** When the logger was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    readonly _client: LoggingClient;
+    /** @internal */
+    constructor(client: LoggingClient, fields: {
+        id: string | null;
+        key: string;
+        name: string;
+        level: string | null;
+        group: string | null;
+        managed: boolean;
+        sources: Array<Record<string, any>>;
+        environments: Record<string, any>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /**
+     * Persist this logger to the server.
+     *
+     * POST if `id` is null (new), PUT if `id` is set (update).
+     */
+    save(): Promise<void>;
+    /** Set the base log level (sync local mutation). */
+    setLevel(level: LogLevel): void;
+    /** Clear the base log level (sync local mutation). */
+    clearLevel(): void;
+    /** Set an environment-specific log level (sync local mutation). */
+    setEnvironmentLevel(env: string, level: LogLevel): void;
+    /** Clear an environment-specific log level (sync local mutation). */
+    clearEnvironmentLevel(env: string): void;
+    /** Clear all environment-specific log levels (sync local mutation). */
+    clearAllEnvironmentLevels(): void;
+    /** @internal — copy all fields from another Logger instance. */
+    _apply(other: Logger): void;
+    toString(): string;
+}
+/**
+ * A log group resource for organizing loggers.
+ *
+ * Management: mutate properties and call `save()` to persist.
+ */
+declare class LogGroup {
+    /** UUID of the log group, 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. */
+    group: string | null;
+    /** Per-environment level overrides. */
+    environments: Record<string, any>;
+    /** When the log group was created. */
+    createdAt: string | null;
+    /** When the log group was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    readonly _client: LoggingClient;
+    /** @internal */
+    constructor(client: LoggingClient, fields: {
+        id: string | null;
+        key: string;
+        name: string;
+        level: string | null;
+        group: string | null;
+        environments: Record<string, any>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /**
+     * Persist this log group to the server.
+     *
+     * POST if `id` is null (new), PUT if `id` is set (update).
+     */
+    save(): Promise<void>;
+    /** Set the base log level (sync local mutation). */
+    setLevel(level: LogLevel): void;
+    /** Clear the base log level (sync local mutation). */
+    clearLevel(): void;
+    /** Set an environment-specific log level (sync local mutation). */
+    setEnvironmentLevel(env: string, level: LogLevel): void;
+    /** Clear an environment-specific log level (sync local mutation). */
+    clearEnvironmentLevel(env: string): void;
+    /** Clear all environment-specific log levels (sync local mutation). */
+    clearAllEnvironmentLevels(): void;
+    /** @internal — copy all fields from another LogGroup instance. */
+    _apply(other: LogGroup): void;
+    toString(): string;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * Client for the smplkit Logging API — management plane + scaffolded runtime.
+ *
+ * Obtained via `SmplClient.logging`.
+ */
+declare class LoggingClient {
+    /** @internal */
+    readonly _apiKey: string;
+    /** @internal */
+    readonly _baseUrl: string;
+    /** @internal */
+    private readonly _http;
+    /** @internal — set by SmplClient after construction. */
+    _parent: {
+        readonly _environment: string;
+        readonly _service: string | null;
+    } | null;
+    private readonly _ensureWs;
+    private _wsManager;
+    private _started;
+    private _globalListeners;
+    private _keyListeners;
+    /** @internal */
+    constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
+    /** Create an unsaved logger. Call `.save()` to persist. */
+    new(key: string, options?: {
+        name?: string;
+        managed?: boolean;
+    }): Logger;
+    /** Fetch a logger by key. */
+    get(key: string): Promise<Logger>;
+    /** List all loggers. */
+    list(): Promise<Logger[]>;
+    /** Delete a logger by key. */
+    delete(key: string): Promise<void>;
+    /** Create an unsaved log group. Call `.save()` to persist. */
+    newGroup(key: string, options?: {
+        name?: string;
+        group?: string;
+    }): LogGroup;
+    /** Fetch a log group by key. */
+    getGroup(key: string): Promise<LogGroup>;
+    /** List all log groups. */
+    listGroups(): Promise<LogGroup[]>;
+    /** Delete a log group by key. */
+    deleteGroup(key: string): Promise<void>;
+    /** @internal — POST or PUT a logger. */
+    _saveLogger(logger: Logger): Promise<Logger>;
+    /** @internal — POST or PUT a log group. */
+    _saveLogGroup(group: LogGroup): Promise<LogGroup>;
+    /**
+     * Start the logging runtime.
+     *
+     * Fetches existing loggers/groups and wires WebSocket listeners for
+     * live updates. Idempotent — safe to call multiple times.
+     *
+     * Note: Node.js auto-discovery (equivalent to Python's logging module
+     * monkey-patching) is deferred. Management methods work without start().
+     */
+    start(): Promise<void>;
+    /**
+     * Register a change listener.
+     *
+     * - `onChange(callback)` — fires for any logger change (global).
+     * - `onChange(key, callback)` — fires only for the specified logger key.
+     */
+    onChange(callbackOrKey: string | ((event: LoggerChangeEvent) => void), callback?: (event: LoggerChangeEvent) => void): void;
+    /** @internal */
+    _close(): void;
+    private _handleLoggerChanged;
+    private _loggerToModel;
+    private _groupToModel;
 }
 
 /**
  * Top-level SDK client — SmplClient.
  *
  * The main entry point for the smplkit TypeScript SDK. Provides access
- * to sub-clients for each API domain (config, flags, logging, etc.).
+ * to sub-clients for each API domain (config, flags, logging).
  */
 
 /** Configuration options for the {@link SmplClient}. */
@@ -745,34 +1066,37 @@ interface SmplClientOptions {
  * ```typescript
  * import { SmplClient } from "@smplkit/sdk";
  *
- * const client = new SmplClient({ apiKey: "sk_api_...", environment: "production" });
- * await client.connect();
+ * const client = new SmplClient({
+ *   apiKey: "sk_api_...",
+ *   environment: "production",
+ *   service: "my-service",
+ * });
+ *
+ * // Flags runtime
+ * await client.flags.initialize();
+ * const flag = client.flags.booleanFlag("checkout-v2", false);
+ * console.log(flag.get());
+ *
+ * // Config runtime
+ * const values = await client.config.resolve("user-service");
  * ```
  */
 declare class SmplClient {
-    /** Client for config management-plane operations. */
+    /** Client for config management and runtime. */
     readonly config: ConfigClient;
-    /** Client for flags management and runtime operations. */
+    /** Client for flags management and runtime. */
     readonly flags: FlagsClient;
+    /** Client for logging management and runtime. */
+    readonly logging: LoggingClient;
     private _wsManager;
     private readonly _apiKey;
     /** @internal */
     readonly _environment: string;
     /** @internal */
     readonly _service: string;
-    private _connected;
     private readonly _timeout;
     private readonly _appHttp;
     constructor(options?: SmplClientOptions);
-    /**
-     * Connect to the smplkit platform.
-     *
-     * Fetches initial flag and config data, opens the shared WebSocket,
-     * and registers the service as a context instance (if provided).
-     *
-     * This method is idempotent — calling it multiple times is safe.
-     */
-    connect(): Promise<void>;
     /** @internal */
     private _registerServiceContext;
     /** Lazily create and start the shared WebSocket. @internal */
@@ -822,13 +1146,9 @@ declare class SmplNotFoundError extends SmplError {
 declare class SmplConflictError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
-/** Raised when a method requiring connect() is called before connecting. */
-declare class SmplNotConnectedError extends SmplError {
-    constructor(message: string);
-}
 /** Raised when the server rejects a request due to validation errors (HTTP 422). */
 declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { type ApiErrorObject, BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, LoggingClient, NumberFlag, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag };