@smplkit/sdk 1.3.12 → 1.3.14

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import createClient3 from "openapi-fetch";
+import createClient4 from "openapi-fetch";
 
 // src/config/client.ts
 import createClient from "openapi-fetch";
@@ -62,13 +62,6 @@ var SmplConflictError = class extends SmplError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
-var SmplNotConnectedError = class extends SmplError {
-  constructor(message) {
-    super(message);
-    this.name = "SmplNotConnectedError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
 var SmplValidationError = class extends SmplError {
   constructor(message, statusCode, responseBody, errors) {
     super(message, statusCode ?? 422, responseBody, errors);
@@ -148,9 +141,9 @@ function resolveChain(chain, environment) {
 
 // src/config/types.ts
 var Config = class {
-  /** UUID of the config. */
+  /** UUID of the config, or `null` if unsaved. */
   id;
-  /** Human-readable key (e.g. `"user_service"`). */
+  /** Human-readable key (e.g. `"user-service"`). */
   key;
   /** Display name. */
   name;
@@ -170,10 +163,7 @@ var Config = class {
   createdAt;
   /** When the config was last updated, or null if unavailable. */
   updatedAt;
-  /**
-   * Internal reference to the parent client.
-   * @internal
-   */
+  /** @internal */
   _client;
   /** @internal */
   constructor(client, fields) {
@@ -189,100 +179,31 @@ var Config = class {
     this.updatedAt = fields.updatedAt;
   }
   /**
-   * 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).
-   */
-  async update(options) {
-    const updated = await this._client._updateConfig({
-      configId: this.id,
-      name: options.name ?? this.name,
-      key: this.key,
-      description: options.description !== void 0 ? options.description : this.description,
-      parent: this.parent,
-      items: options.items ?? this.items,
-      environments: options.environments ?? this.environments
-    });
-    this.name = updated.name;
-    this.description = updated.description;
-    this.items = updated.items;
-    this.environments = updated.environments;
-    this.updatedAt = updated.updatedAt;
-  }
-  /**
-   * 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.
-   */
-  async setValues(values, environment) {
-    let newItems;
-    let newEnvs;
-    if (environment === void 0) {
-      newItems = values;
-      newEnvs = this.environments;
-    } else {
-      newItems = this.items;
-      const existingEntry = typeof this.environments[environment] === "object" && this.environments[environment] !== null ? { ...this.environments[environment] } : {};
-      existingEntry.values = values;
-      newEnvs = { ...this.environments, [environment]: existingEntry };
-    }
-    const updated = await this._client._updateConfig({
-      configId: this.id,
-      name: this.name,
-      key: this.key,
-      description: this.description,
-      parent: this.parent,
-      items: newItems,
-      environments: newEnvs
-    });
-    this.items = updated.items;
-    this.environments = updated.environments;
-    this.updatedAt = updated.updatedAt;
-  }
-  /**
-   * Set a single key within base or environment-specific values.
+   * Persist this config to the server.
    *
-   * Merges the key into existing values rather than replacing all values.
-   *
-   * @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.
    */
-  async setValue(key, value, environment) {
-    if (environment === void 0) {
-      const merged = { ...this.items, [key]: value };
-      await this.setValues(merged);
+  async save() {
+    if (this.id === null) {
+      const created = await this._client._createConfig(this);
+      this._apply(created);
     } else {
-      const envEntry = typeof this.environments[environment] === "object" && this.environments[environment] !== null ? this.environments[environment] : {};
-      const existing = {
-        ...typeof envEntry.values === "object" && envEntry.values !== null ? envEntry.values : {}
-      };
-      existing[key] = value;
-      await this.setValues(existing, environment);
+      const updated = await this._client._updateConfig(this);
+      this._apply(updated);
     }
   }
   /**
    * Walk the parent chain and return config data objects, child-to-root.
    * @internal
    */
-  async _buildChain(_timeout) {
-    const chain = [{ id: this.id, items: this.items, environments: this.environments }];
+  async _buildChain() {
+    const chain = [{ id: this.id ?? "", items: this.items, environments: this.environments }];
     let parentId = this.parent;
     while (parentId !== null) {
-      const parentConfig = await this._client.get({ id: parentId });
+      const parentConfig = await this._client._getById(parentId);
       chain.push({
-        id: parentConfig.id,
+        id: parentConfig.id ?? "",
         items: parentConfig.items,
         environments: parentConfig.environments
       });
@@ -290,11 +211,82 @@ var Config = class {
     }
     return chain;
   }
+  /** @internal — copy all fields from another Config instance. */
+  _apply(other) {
+    this.id = other.id;
+    this.key = other.key;
+    this.name = other.name;
+    this.description = other.description;
+    this.parent = other.parent;
+    this.items = other.items;
+    this.environments = other.environments;
+    this.createdAt = other.createdAt;
+    this.updatedAt = other.updatedAt;
+  }
   toString() {
     return `Config(id=${this.id}, key=${this.key}, name=${this.name})`;
   }
 };
 
+// src/config/proxy.ts
+var LiveConfigProxy = class {
+  /** @internal */
+  _client;
+  /** @internal */
+  _key;
+  /** @internal */
+  _model;
+  constructor(client, key, model) {
+    this._client = client;
+    this._key = key;
+    this._model = model;
+    return new Proxy(this, {
+      get(target, prop, receiver) {
+        if (typeof prop === "symbol" || prop === "constructor" || prop === "toJSON") {
+          return Reflect.get(target, prop, receiver);
+        }
+        const values = target._currentValues();
+        if (target._model) {
+          const instance = new target._model(values);
+          return instance[prop];
+        }
+        return values[prop];
+      },
+      has(target, prop) {
+        if (typeof prop === "symbol") return Reflect.has(target, prop);
+        const values = target._currentValues();
+        return prop in values;
+      },
+      ownKeys(target) {
+        const values = target._currentValues();
+        return Object.keys(values);
+      },
+      getOwnPropertyDescriptor(target, prop) {
+        if (typeof prop === "symbol") return Reflect.getOwnPropertyDescriptor(target, prop);
+        const values = target._currentValues();
+        if (prop in values) {
+          return {
+            configurable: true,
+            enumerable: true,
+            value: values[prop],
+            writable: false
+          };
+        }
+        return void 0;
+      }
+    });
+  }
+  /** @internal */
+  _currentValues() {
+    return this._client._getCachedConfig(this._key) ?? {};
+  }
+};
+
+// src/helpers.ts
+function keyToDisplayName(key) {
+  return key.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
 // src/config/client.ts
 var BASE_URL = "https://config.smplkit.com";
 function extractItemValues(items) {
@@ -324,7 +316,7 @@ function extractEnvironments(environments) {
 function resourceToConfig(resource, client) {
   const attrs = resource.attributes;
   return new Config(client, {
-    id: resource.id ?? "",
+    id: resource.id ?? null,
     key: attrs.key ?? "",
     name: attrs.name,
     description: attrs.description ?? null,
@@ -333,8 +325,8 @@ function resourceToConfig(resource, client) {
     environments: extractEnvironments(
       attrs.environments
     ),
-    createdAt: attrs.created_at ? new Date(attrs.created_at) : null,
-    updatedAt: attrs.updated_at ? new Date(attrs.updated_at) : null
+    createdAt: attrs.created_at ?? null,
+    updatedAt: attrs.updated_at ?? null
   });
 }
 async function checkError(response, _context) {
@@ -401,7 +393,7 @@ function buildRequestBody(options) {
   };
 }
 var ConfigClient = class {
-  /** @internal — used by Config instances for reconnecting and WebSocket auth. */
+  /** @internal */
   _apiKey;
   /** @internal */
   _baseUrl = BASE_URL;
@@ -412,7 +404,7 @@ var ConfigClient = class {
   /** @internal — set by SmplClient after construction. */
   _parent = null;
   _configCache = {};
-  _connected = false;
+  _initialized = false;
   _listeners = [];
   /** @internal */
   constructor(apiKey, timeout) {
@@ -424,7 +416,6 @@ var ConfigClient = class {
         Authorization: `Bearer ${apiKey}`,
         Accept: "application/json"
       },
-      // openapi-fetch custom fetch receives a pre-built Request object
       fetch: async (request) => {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), ms);
@@ -441,23 +432,31 @@ var ConfigClient = class {
       }
     });
   }
-  /**
-   * Fetch a single config by key or UUID.
-   *
-   * Exactly one of `key` or `id` must be provided.
-   *
-   * @throws {SmplNotFoundError} If no matching config exists.
-   */
-  async get(options) {
-    const { key, id } = options;
-    if (key === void 0 === (id === void 0)) {
-      throw new Error("Exactly one of 'key' or 'id' must be provided.");
-    }
-    return id !== void 0 ? this._getById(id) : this._getByKey(key);
+  // ------------------------------------------------------------------
+  // Management: factory method
+  // ------------------------------------------------------------------
+  /** Create an unsaved config. Call `.save()` to persist. */
+  new(key, options) {
+    return new Config(this, {
+      id: null,
+      key,
+      name: options?.name ?? keyToDisplayName(key),
+      description: options?.description ?? null,
+      parent: options?.parent ?? null,
+      items: {},
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
   }
-  /**
-   * List all configs for the account.
-   */
+  // ------------------------------------------------------------------
+  // Management: CRUD
+  // ------------------------------------------------------------------
+  /** Fetch a config by key. */
+  async get(key) {
+    return this._getByKey(key);
+  }
+  /** List all configs. */
   async list() {
     let data;
     try {
@@ -470,18 +469,31 @@ var ConfigClient = class {
     if (!data) return [];
     return data.data.map((r) => resourceToConfig(r, this));
   }
-  /**
-   * Create a new config.
-   *
-   * @throws {SmplValidationError} If the server rejects the request.
-   */
-  async create(options) {
+  /** Delete a config by key. */
+  async delete(key) {
+    const config = await this.get(key);
+    try {
+      const result = await this._http.DELETE("/api/v1/configs/{id}", {
+        params: { path: { id: config.id } }
+      });
+      if (result.error !== void 0 && result.response.status !== 204)
+        await checkError(result.response, `Failed to delete config '${key}'`);
+    } catch (err) {
+      wrapFetchError(err);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Management: internal save methods (called by Config.save())
+  // ------------------------------------------------------------------
+  /** @internal — POST a new config. */
+  async _createConfig(config) {
     const body = buildRequestBody({
-      name: options.name,
-      key: options.key,
-      description: options.description,
-      parent: options.parent,
-      items: options.items
+      name: config.name,
+      key: config.key,
+      description: config.description,
+      parent: config.parent,
+      items: config.items,
+      environments: config.environments
     });
     let data;
     try {
@@ -494,98 +506,124 @@ var ConfigClient = class {
     if (!data || !data.data) throw new SmplValidationError("Failed to create config");
     return resourceToConfig(data.data, this);
   }
-  /**
-   * Delete a config by UUID.
-   *
-   * @throws {SmplNotFoundError} If the config does not exist.
-   * @throws {SmplConflictError} If the config has child configs.
-   */
-  async delete(configId) {
+  /** @internal — PUT a config update. */
+  async _updateConfig(config) {
+    const body = buildRequestBody({
+      id: config.id,
+      name: config.name,
+      key: config.key,
+      description: config.description,
+      parent: config.parent,
+      items: config.items,
+      environments: config.environments
+    });
+    let data;
     try {
-      const result = await this._http.DELETE("/api/v1/configs/{id}", {
-        params: { path: { id: configId } }
+      const result = await this._http.PUT("/api/v1/configs/{id}", {
+        params: { path: { id: config.id } },
+        body
       });
-      if (result.error !== void 0 && result.response.status !== 204)
-        await checkError(result.response, `Failed to delete config ${configId}`);
+      if (result.error !== void 0)
+        await checkError(result.response, `Failed to update config ${config.id}`);
+      data = result.data;
     } catch (err) {
       wrapFetchError(err);
     }
+    if (!data || !data.data) throw new SmplValidationError(`Failed to update config ${config.id}`);
+    return resourceToConfig(data.data, this);
   }
-  /**
-   * Fetch all configs, resolve values for the environment, and cache.
-   * @internal — called by SmplClient.connect().
-   */
-  async _connectInternal(environment) {
-    const configs = await this.list();
-    const cache = {};
-    for (const cfg of configs) {
-      const chain = await cfg._buildChain(this._http);
-      cache[cfg.key] = resolveChain(chain, environment);
+  /** @internal — fetch a config by UUID. */
+  async _getById(configId) {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/configs/{id}", {
+        params: { path: { id: configId } }
+      });
+      if (result.error !== void 0)
+        await checkError(result.response, `Config ${configId} not found`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
     }
-    this._configCache = cache;
-    this._connected = true;
+    if (!data || !data.data) throw new SmplNotFoundError(`Config ${configId} not found`);
+    return resourceToConfig(data.data, this);
   }
+  // ------------------------------------------------------------------
+  // Runtime: resolve and subscribe
+  // ------------------------------------------------------------------
   /**
-   * Read a resolved config value (prescriptive access).
+   * Resolve a config's values for the current environment.
    *
-   * Requires {@link SmplClient.connect} to have been called.
+   * Returns a flat dict of resolved key-value pairs, walking the
+   * parent chain and applying environment overrides.
    *
-   * @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.
-   *
-   * @throws {SmplNotConnectedError} If connect() has not been called.
+   * Optionally pass a model class to map the resolved values.
    */
-  getValue(configKey, itemKey, defaultValue) {
-    if (!this._connected) {
-      throw new SmplNotConnectedError("SmplClient is not connected. Call client.connect() first.");
-    }
-    const resolved = this._configCache[configKey];
-    if (resolved === void 0) {
-      return defaultValue ?? null;
+  async resolve(key, model) {
+    await this._ensureInitialized();
+    const values = this._configCache[key];
+    if (values === void 0) {
+      throw new SmplNotFoundError(`Config with key '${key}' not found in cache`);
     }
-    if (itemKey === void 0) {
-      return { ...resolved };
+    if (model) {
+      return new model(values);
     }
-    return itemKey in resolved ? resolved[itemKey] : defaultValue ?? null;
-  }
-  /**
-   * Return a config value as a string, or `defaultValue` if absent or not a string.
-   *
-   * @throws {SmplNotConnectedError} If connect() has not been called.
-   */
-  getString(configKey, itemKey, defaultValue = null) {
-    const value = this.getValue(configKey, itemKey);
-    return typeof value === "string" ? value : defaultValue;
+    return values;
   }
   /**
-   * 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, itemKey, defaultValue = null) {
-    const value = this.getValue(configKey, itemKey);
-    return typeof value === "number" ? value : defaultValue;
+  async subscribe(key, model) {
+    await this._ensureInitialized();
+    if (!(key in this._configCache)) {
+      throw new SmplNotFoundError(`Config with key '${key}' not found in cache`);
+    }
+    return new LiveConfigProxy(this, key, model);
   }
+  // ------------------------------------------------------------------
+  // Runtime: change listeners (3-level overloads)
+  // ------------------------------------------------------------------
   /**
-   * 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, itemKey, defaultValue = null) {
-    const value = this.getValue(configKey, itemKey);
-    return typeof value === "boolean" ? value : defaultValue;
+  onChange(callbackOrConfigKey, callbackOrItemKey, callback) {
+    if (typeof callbackOrConfigKey === "function") {
+      this._listeners.push({
+        callback: callbackOrConfigKey,
+        configKey: null,
+        itemKey: null
+      });
+    } else if (typeof callbackOrItemKey === "function") {
+      this._listeners.push({
+        callback: callbackOrItemKey,
+        configKey: callbackOrConfigKey,
+        itemKey: null
+      });
+    } else if (typeof callbackOrItemKey === "string" && callback) {
+      this._listeners.push({
+        callback,
+        configKey: callbackOrConfigKey,
+        itemKey: callbackOrItemKey
+      });
+    }
   }
+  // ------------------------------------------------------------------
+  // Runtime: refresh
+  // ------------------------------------------------------------------
   /**
    * 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.
    */
   async refresh() {
-    if (!this._connected) {
-      throw new SmplNotConnectedError("SmplClient is not connected. Call client.connect() first.");
+    if (!this._initialized) {
+      throw new SmplError("Config not initialized. Call resolve() or subscribe() first.");
     }
     const environment = this._parent?._environment;
     if (!environment) {
@@ -594,27 +632,62 @@ var ConfigClient = class {
     const configs = await this.list();
     const newCache = {};
     for (const cfg of configs) {
-      const chain = await cfg._buildChain(this._http);
+      const chain = await cfg._buildChain();
       newCache[cfg.key] = resolveChain(chain, environment);
     }
     const oldCache = this._configCache;
     this._configCache = newCache;
     this._diffAndFire(oldCache, newCache, "manual");
   }
-  /**
-   * 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, options) {
-    this._listeners.push({
-      callback,
-      configKey: options?.configKey ?? null,
-      itemKey: options?.itemKey ?? null
-    });
+  // ------------------------------------------------------------------
+  // Runtime: lazy initialization
+  // ------------------------------------------------------------------
+  /** @internal */
+  async _ensureInitialized() {
+    if (this._initialized) return;
+    const environment = this._parent?._environment;
+    if (!environment) {
+      throw new SmplError("No environment set. Ensure SmplClient is configured.");
+    }
+    const configs = await this.list();
+    const cache = {};
+    for (const cfg of configs) {
+      const chain = await cfg._buildChain();
+      cache[cfg.key] = resolveChain(chain, environment);
+    }
+    this._configCache = cache;
+    this._initialized = true;
+    if (this._getSharedWs) {
+      const ws = this._getSharedWs();
+      ws.on("config_changed", this._handleConfigChanged);
+    }
+  }
+  /** @internal — called by SmplClient for backward compat. */
+  async _connectInternal(environment) {
+    if (this._initialized) return;
+    const configs = await this.list();
+    const cache = {};
+    for (const cfg of configs) {
+      const chain = await cfg._buildChain();
+      cache[cfg.key] = resolveChain(chain, environment);
+    }
+    this._configCache = cache;
+    this._initialized = true;
   }
+  /** @internal — get resolved config from cache. Used by LiveConfigProxy. */
+  _getCachedConfig(key) {
+    return this._configCache[key];
+  }
+  // ------------------------------------------------------------------
+  // Internal: WebSocket handler
+  // ------------------------------------------------------------------
+  _handleConfigChanged = (_data) => {
+    void this.refresh().catch(() => {
+    });
+  };
+  // ------------------------------------------------------------------
+  // Internal: change detection
+  // ------------------------------------------------------------------
   /** @internal */
   _diffAndFire(oldCache, newCache, source) {
     const allConfigKeys = /* @__PURE__ */ new Set([...Object.keys(oldCache), ...Object.keys(newCache)]);
@@ -645,54 +718,9 @@ var ConfigClient = class {
       }
     }
   }
-  /**
-   * Internal: PUT a full config update and return the updated model.
-   *
-   * Called by {@link Config} instance methods.
-   * @internal
-   */
-  async _updateConfig(payload) {
-    const body = buildRequestBody({
-      id: payload.configId,
-      name: payload.name,
-      key: payload.key,
-      description: payload.description,
-      parent: payload.parent,
-      items: payload.items,
-      environments: payload.environments
-    });
-    let data;
-    try {
-      const result = await this._http.PUT("/api/v1/configs/{id}", {
-        params: { path: { id: payload.configId } },
-        body
-      });
-      if (result.error !== void 0)
-        await checkError(result.response, `Failed to update config ${payload.configId}`);
-      data = result.data;
-    } catch (err) {
-      wrapFetchError(err);
-    }
-    if (!data || !data.data)
-      throw new SmplValidationError(`Failed to update config ${payload.configId}`);
-    return resourceToConfig(data.data, this);
-  }
-  // ---- Private helpers ----
-  async _getById(configId) {
-    let data;
-    try {
-      const result = await this._http.GET("/api/v1/configs/{id}", {
-        params: { path: { id: configId } }
-      });
-      if (result.error !== void 0)
-        await checkError(result.response, `Config ${configId} not found`);
-      data = result.data;
-    } catch (err) {
-      wrapFetchError(err);
-    }
-    if (!data || !data.data) throw new SmplNotFoundError(`Config ${configId} not found`);
-    return resourceToConfig(data.data, this);
-  }
+  // ------------------------------------------------------------------
+  // Internal: fetch by key
+  // ------------------------------------------------------------------
   async _getByKey(key) {
     let data;
     try {
@@ -717,7 +745,7 @@ import createClient2 from "openapi-fetch";
 
 // src/flags/models.ts
 var Flag = class {
-  /** UUID of the flag. */
+  /** UUID of the flag, or `null` if unsaved. */
   id;
   /** Unique key within the account. */
   key;
@@ -754,37 +782,35 @@ var Flag = class {
     this.updatedAt = fields.updatedAt;
   }
   /**
-   * Update this flag's attributes on the server.
+   * Persist this flag to the server.
    *
-   * Only provided fields are changed; others retain their current values.
+   * POST if `id` is null (new flag), PUT if `id` is set (update).
+   * Updates this instance in-place with the server response.
    */
-  async update(options) {
-    const updated = await this._client._updateFlag({
-      flag: this,
-      environments: options.environments,
-      values: options.values,
-      default: options.default,
-      description: options.description,
-      name: options.name
-    });
-    this._apply(updated);
+  async save() {
+    if (this.id === null) {
+      const created = await this._client._createFlag(this);
+      this._apply(created);
+    } else {
+      const updated = await this._client._updateFlag(this);
+      this._apply(updated);
+    }
   }
   /**
-   * Add a rule to a specific environment.
+   * Add a rule to a specific environment (sync local mutation).
    *
    * The built rule must include an `environment` key (set via
-   * `Rule(...).environment("env_key")`).  Re-fetches current state
-   * first to avoid stale data.
+   * `Rule(...).environment("env_key")`). No HTTP call is made.
+   *
+   * @returns `this` for chaining.
    */
-  async addRule(builtRule) {
+  addRule(builtRule) {
     const envKey = builtRule.environment;
     if (!envKey) {
       throw new Error(
         `Built rule must include 'environment' key. Use new Rule(...).environment("env_key").when(...).serve(...).build()`
       );
     }
-    const current = await this._client.get(this.id);
-    this._apply(current);
     const envs = { ...this.environments };
     const envData = { ...envs[envKey] ?? { enabled: true, rules: [] } };
     const rules = [...envData.rules ?? []];
@@ -792,13 +818,43 @@ var Flag = class {
     rules.push(ruleCopy);
     envData.rules = rules;
     envs[envKey] = envData;
-    const updated = await this._client._updateFlag({
-      flag: this,
-      environments: envs
-    });
-    this._apply(updated);
+    this.environments = envs;
+    return this;
   }
-  /** @internal */
+  /** Enable or disable a flag in a specific environment (sync local mutation). */
+  setEnvironmentEnabled(envKey, enabled) {
+    const envs = { ...this.environments };
+    const envData = { ...envs[envKey] ?? { enabled: false, rules: [] } };
+    envData.enabled = enabled;
+    envs[envKey] = envData;
+    this.environments = envs;
+  }
+  /** Set the default value for a specific environment (sync local mutation). */
+  setEnvironmentDefault(envKey, defaultValue) {
+    const envs = { ...this.environments };
+    const envData = { ...envs[envKey] ?? { enabled: false, rules: [] } };
+    envData.default = defaultValue;
+    envs[envKey] = envData;
+    this.environments = envs;
+  }
+  /** Clear all rules for a specific environment (sync local mutation). */
+  clearRules(envKey) {
+    const envs = { ...this.environments };
+    const envData = envs[envKey];
+    if (envData) {
+      envs[envKey] = { ...envData, rules: [] };
+      this.environments = envs;
+    }
+  }
+  /**
+   * Evaluate the flag locally (sync, no HTTP).
+   *
+   * Requires `initialize()` to have been called.
+   */
+  get(options) {
+    return this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
+  }
+  /** @internal — copy all fields from another Flag instance. */
   _apply(other) {
     this.id = other.id;
     this.key = other.key;
@@ -815,36 +871,53 @@ var Flag = class {
     return `Flag(key=${this.key}, type=${this.type}, default=${this.default})`;
   }
 };
-var ContextType = class {
-  /** UUID. */
-  id;
-  /** Unique key within the account. */
-  key;
-  /** Human-readable display name. */
-  name;
-  /** Known attributes. */
-  attributes;
-  constructor(fields) {
-    this.id = fields.id;
-    this.key = fields.key;
-    this.name = fields.name;
-    this.attributes = fields.attributes;
+var BooleanFlag = class extends Flag {
+  get(options) {
+    const value = this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
+    if (typeof value === "boolean") {
+      return value;
+    }
+    return this.default;
   }
-  toString() {
-    return `ContextType(key=${this.key}, name=${this.name})`;
+};
+var StringFlag = class extends Flag {
+  get(options) {
+    const value = this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
+    if (typeof value === "string") {
+      return value;
+    }
+    return this.default;
   }
 };
-
-// src/flags/client.ts
-import jsonLogic from "json-logic-js";
-var FLAGS_BASE_URL = "https://flags.smplkit.com";
-var APP_BASE_URL = "https://app.smplkit.com";
-var CACHE_MAX_SIZE = 1e4;
-var CONTEXT_REGISTRATION_LRU_SIZE = 1e4;
-var CONTEXT_BATCH_FLUSH_SIZE = 100;
-async function checkError2(response, _context) {
-  const body = await response.text().catch(() => "");
-  throwForStatus(response.status, body);
+var NumberFlag = class extends Flag {
+  get(options) {
+    const value = this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
+    if (typeof value === "number") {
+      return value;
+    }
+    return this.default;
+  }
+};
+var JsonFlag = class extends Flag {
+  get(options) {
+    const value = this._client._evaluateHandle(this.key, this.default, options?.context ?? null);
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value;
+    }
+    return this.default;
+  }
+};
+
+// src/flags/client.ts
+import jsonLogic from "json-logic-js";
+var FLAGS_BASE_URL = "https://flags.smplkit.com";
+var APP_BASE_URL = "https://app.smplkit.com";
+var CACHE_MAX_SIZE = 1e4;
+var CONTEXT_REGISTRATION_LRU_SIZE = 1e4;
+var CONTEXT_BATCH_FLUSH_SIZE = 100;
+async function checkError2(response, _context) {
+  const body = await response.text().catch(() => "");
+  throwForStatus(response.status, body);
 }
 function wrapFetchError2(err) {
   if (err instanceof SmplNotFoundError || err instanceof SmplConflictError || err instanceof SmplValidationError || err instanceof SmplError) {
@@ -960,88 +1033,6 @@ var FlagStats = class {
     this.cacheMisses = cacheMisses;
   }
 };
-var FlagHandleBase = class {
-  /** @internal */
-  _namespace;
-  /** @internal */
-  _key;
-  /** @internal */
-  _default;
-  /** @internal */
-  _listeners = [];
-  constructor(namespace, key, defaultValue) {
-    this._namespace = namespace;
-    this._key = key;
-    this._default = defaultValue;
-  }
-  get key() {
-    return this._key;
-  }
-  get default() {
-    return this._default;
-  }
-  /* v8 ignore next 3 — overridden by all exported subclasses */
-  get(options) {
-    return this._namespace._evaluateHandle(this._key, this._default, options?.context ?? null);
-  }
-  /** Register a flag-specific change listener. Works as a decorator. */
-  onChange(callback) {
-    this._listeners.push(callback);
-    return callback;
-  }
-};
-var BoolFlagHandle = class extends FlagHandleBase {
-  get(options) {
-    const value = this._namespace._evaluateHandle(
-      this._key,
-      this._default,
-      options?.context ?? null
-    );
-    if (typeof value === "boolean") {
-      return value;
-    }
-    return this._default;
-  }
-};
-var StringFlagHandle = class extends FlagHandleBase {
-  get(options) {
-    const value = this._namespace._evaluateHandle(
-      this._key,
-      this._default,
-      options?.context ?? null
-    );
-    if (typeof value === "string") {
-      return value;
-    }
-    return this._default;
-  }
-};
-var NumberFlagHandle = class extends FlagHandleBase {
-  get(options) {
-    const value = this._namespace._evaluateHandle(
-      this._key,
-      this._default,
-      options?.context ?? null
-    );
-    if (typeof value === "number") {
-      return value;
-    }
-    return this._default;
-  }
-};
-var JsonFlagHandle = class extends FlagHandleBase {
-  get(options) {
-    const value = this._namespace._evaluateHandle(
-      this._key,
-      this._default,
-      options?.context ?? null
-    );
-    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-      return value;
-    }
-    return this._default;
-  }
-};
 var ContextRegistrationBuffer = class {
   _seen = /* @__PURE__ */ new Map();
   _pending = [];
@@ -1085,13 +1076,14 @@ var FlagsClient = class {
   // Runtime state
   _environment = null;
   _flagStore = {};
-  _connected = false;
+  _initialized = false;
   _cache = new ResolutionCache();
   _contextProvider = null;
   _contextBuffer = new ContextRegistrationBuffer();
   _handles = {};
   _globalListeners = [];
-  // Shared WebSocket (set during connect)
+  _keyListeners = /* @__PURE__ */ new Map();
+  // Shared WebSocket (set during initialize)
   _wsManager = null;
   _ensureWs;
   /** @internal — set by SmplClient after construction. */
@@ -1133,55 +1125,91 @@ var FlagsClient = class {
     });
   }
   // ------------------------------------------------------------------
-  // Management methods
+  // Management: factory methods (return unsaved flags)
   // ------------------------------------------------------------------
-  /** Create a flag. */
-  async create(key, options) {
-    let values = options.values;
-    if (values === void 0 && options.type === "BOOLEAN") {
-      values = [
+  /** Create an unsaved boolean flag. Call `.save()` to persist. */
+  newBooleanFlag(key, options) {
+    return new BooleanFlag(this, {
+      id: null,
+      key,
+      name: options.name ?? keyToDisplayName(key),
+      type: "BOOLEAN",
+      default: options.default,
+      values: [
         { name: "True", value: true },
         { name: "False", value: false }
-      ];
-    }
-    const body = {
-      data: {
-        type: "flag",
-        attributes: {
-          key,
-          name: options.name,
-          description: options.description ?? "",
-          type: options.type,
-          default: options.default,
-          values: values ?? []
-        }
-      }
-    };
-    let data;
-    try {
-      const result = await this._http.POST("/api/v1/flags", { body });
-      if (result.error !== void 0) await checkError2(result.response, "Failed to create flag");
-      data = result.data;
-    } catch (err) {
-      wrapFetchError2(err);
-    }
-    if (!data || !data.data) throw new SmplValidationError("Failed to create flag");
-    return this._resourceToModel(data.data);
+      ],
+      description: options.description ?? null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
+  }
+  /** Create an unsaved string flag. Call `.save()` to persist. */
+  newStringFlag(key, options) {
+    return new StringFlag(this, {
+      id: null,
+      key,
+      name: options.name ?? keyToDisplayName(key),
+      type: "STRING",
+      default: options.default,
+      values: options.values ?? [],
+      description: options.description ?? null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
   }
-  /** Fetch a flag by UUID. */
-  async get(flagId) {
+  /** Create an unsaved number flag. Call `.save()` to persist. */
+  newNumberFlag(key, options) {
+    return new NumberFlag(this, {
+      id: null,
+      key,
+      name: options.name ?? keyToDisplayName(key),
+      type: "NUMERIC",
+      default: options.default,
+      values: options.values ?? [],
+      description: options.description ?? null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
+  }
+  /** Create an unsaved JSON flag. Call `.save()` to persist. */
+  newJsonFlag(key, options) {
+    return new JsonFlag(this, {
+      id: null,
+      key,
+      name: options.name ?? keyToDisplayName(key),
+      type: "JSON",
+      default: options.default,
+      values: options.values ?? [],
+      description: options.description ?? null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
+  }
+  // ------------------------------------------------------------------
+  // Management: CRUD
+  // ------------------------------------------------------------------
+  /** Fetch a flag by key. */
+  async get(key) {
     let data;
     try {
-      const result = await this._http.GET("/api/v1/flags/{id}", {
-        params: { path: { id: flagId } }
+      const result = await this._http.GET("/api/v1/flags", {
+        params: { query: { "filter[key]": key } }
       });
-      if (result.error !== void 0) await checkError2(result.response, `Flag ${flagId} not found`);
+      if (result.error !== void 0)
+        await checkError2(result.response, `Flag with key '${key}' not found`);
       data = result.data;
     } catch (err) {
       wrapFetchError2(err);
     }
-    if (!data || !data.data) throw new SmplNotFoundError(`Flag ${flagId} not found`);
-    return this._resourceToModel(data.data);
+    if (!data || !data.data || data.data.length === 0) {
+      throw new SmplNotFoundError(`Flag with key '${key}' not found`);
+    }
+    return this._resourceToModel(data.data[0]);
   }
   /** List all flags. */
   async list() {
@@ -1196,161 +1224,148 @@ var FlagsClient = class {
     if (!data) return [];
     return data.data.map((r) => this._resourceToModel(r));
   }
-  /** Delete a flag by UUID. */
-  async delete(flagId) {
+  /** Delete a flag by key. */
+  async delete(key) {
+    const flag = await this.get(key);
     try {
       const result = await this._http.DELETE("/api/v1/flags/{id}", {
-        params: { path: { id: flagId } }
+        params: { path: { id: flag.id } }
       });
       if (result.error !== void 0 && result.response.status !== 204)
-        await checkError2(result.response, `Failed to delete flag ${flagId}`);
+        await checkError2(result.response, `Failed to delete flag '${key}'`);
     } catch (err) {
       wrapFetchError2(err);
     }
   }
-  /**
-   * Internal: PUT a full flag update.
-   * Called by {@link Flag} instance methods.
-   * @internal
-   */
-  async _updateFlag(options) {
-    const { flag } = options;
+  // ------------------------------------------------------------------
+  // Management: internal save methods (called by Flag.save())
+  // ------------------------------------------------------------------
+  /** @internal — POST a new flag. */
+  async _createFlag(flag) {
     const body = {
       data: {
         type: "flag",
         attributes: {
           key: flag.key,
-          name: options.name !== void 0 ? options.name : flag.name,
+          name: flag.name,
+          description: flag.description ?? "",
           type: flag.type,
-          default: options.default !== void 0 ? options.default : flag.default,
-          values: options.values !== void 0 ? options.values : flag.values,
-          description: options.description !== void 0 ? options.description : flag.description ?? "",
-          ...options.environments !== void 0 ? { environments: options.environments } : flag.environments && Object.keys(flag.environments).length > 0 ? { environments: flag.environments } : {}
+          default: flag.default,
+          values: flag.values,
+          ...Object.keys(flag.environments).length > 0 ? { environments: flag.environments } : {}
         }
       }
     };
     let data;
     try {
-      const result = await this._http.PUT("/api/v1/flags/{id}", {
-        params: { path: { id: flag.id } },
-        body
-      });
-      if (result.error !== void 0)
-        await checkError2(result.response, `Failed to update flag ${flag.id}`);
+      const result = await this._http.POST("/api/v1/flags", { body });
+      if (result.error !== void 0) await checkError2(result.response, "Failed to create flag");
       data = result.data;
     } catch (err) {
       wrapFetchError2(err);
     }
-    if (!data || !data.data) throw new SmplValidationError(`Failed to update flag ${flag.id}`);
+    if (!data || !data.data) throw new SmplValidationError("Failed to create flag");
     return this._resourceToModel(data.data);
   }
-  // ------------------------------------------------------------------
-  // Context type management (via generated app client)
-  // ------------------------------------------------------------------
-  /** Create a context type. */
-  async createContextType(key, options) {
-    let data;
-    try {
-      const result = await this._appHttp.POST("/api/v1/context_types", {
-        body: {
-          data: { type: "context_type", attributes: { key, name: options.name } }
+  /** @internal — PUT a flag update. */
+  async _updateFlag(flag) {
+    const body = {
+      data: {
+        type: "flag",
+        attributes: {
+          key: flag.key,
+          name: flag.name,
+          type: flag.type,
+          default: flag.default,
+          values: flag.values,
+          description: flag.description ?? "",
+          ...Object.keys(flag.environments).length > 0 ? { environments: flag.environments } : {}
         }
-      });
-      if (result.error !== void 0)
-        await checkError2(result.response, "Failed to create context type");
-      data = result.data;
-    } catch (err) {
-      wrapFetchError2(err);
-    }
-    if (!data || !data.data) throw new SmplValidationError("Failed to create context type");
-    return this._parseContextType(data.data);
-  }
-  /** Update a context type (merge attributes). */
-  async updateContextType(ctId, options) {
+      }
+    };
     let data;
     try {
-      const result = await this._appHttp.PUT("/api/v1/context_types/{id}", {
-        params: { path: { id: ctId } },
-        body: {
-          data: {
-            type: "context_type",
-            attributes: { key: options.key, name: options.name, attributes: options.attributes }
-          }
-        }
+      const result = await this._http.PUT("/api/v1/flags/{id}", {
+        params: { path: { id: flag.id } },
+        body
       });
       if (result.error !== void 0)
-        await checkError2(result.response, `Failed to update context type ${ctId}`);
-      data = result.data;
-    } catch (err) {
-      wrapFetchError2(err);
-    }
-    if (!data || !data.data) throw new SmplValidationError(`Failed to update context type ${ctId}`);
-    return this._parseContextType(data.data);
-  }
-  /** List all context types. */
-  async listContextTypes() {
-    let data;
-    try {
-      const result = await this._appHttp.GET("/api/v1/context_types");
-      if (result.error !== void 0)
-        await checkError2(result.response, "Failed to list context types");
-      data = result.data;
-    } catch (err) {
-      wrapFetchError2(err);
-    }
-    if (!data || !data.data) throw new SmplValidationError("Failed to list context types");
-    return data.data.map((item) => this._parseContextType(item));
-  }
-  /** Delete a context type. */
-  async deleteContextType(ctId) {
-    try {
-      const result = await this._appHttp.DELETE("/api/v1/context_types/{id}", {
-        params: { path: { id: ctId } }
-      });
-      if (result.error !== void 0 && result.response.status !== 204)
-        await checkError2(result.response, `Failed to delete context type ${ctId}`);
-    } catch (err) {
-      wrapFetchError2(err);
-    }
-  }
-  /** List context instances filtered by context type key. */
-  async listContexts(options) {
-    let data;
-    try {
-      const result = await this._appHttp.GET("/api/v1/contexts", {
-        params: { query: { "filter[context_type_id]": options.contextTypeKey } }
-      });
-      if (result.error !== void 0) await checkError2(result.response, "Failed to list contexts");
+        await checkError2(result.response, `Failed to update flag ${flag.id}`);
       data = result.data;
     } catch (err) {
       wrapFetchError2(err);
     }
-    return data?.data ?? [];
+    if (!data || !data.data) throw new SmplValidationError(`Failed to update flag ${flag.id}`);
+    return this._resourceToModel(data.data);
   }
   // ------------------------------------------------------------------
   // Runtime: typed flag handles
   // ------------------------------------------------------------------
-  /** Declare a boolean flag handle. */
-  boolFlag(key, defaultValue) {
-    const handle = new BoolFlagHandle(this, key, defaultValue);
+  /** Declare a boolean flag handle for runtime evaluation. */
+  booleanFlag(key, defaultValue) {
+    const handle = new BooleanFlag(this, {
+      id: null,
+      key,
+      name: key,
+      type: "BOOLEAN",
+      default: defaultValue,
+      values: [],
+      description: null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
     this._handles[key] = handle;
     return handle;
   }
-  /** Declare a string flag handle. */
+  /** Declare a string flag handle for runtime evaluation. */
   stringFlag(key, defaultValue) {
-    const handle = new StringFlagHandle(this, key, defaultValue);
+    const handle = new StringFlag(this, {
+      id: null,
+      key,
+      name: key,
+      type: "STRING",
+      default: defaultValue,
+      values: [],
+      description: null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
     this._handles[key] = handle;
     return handle;
   }
-  /** Declare a numeric flag handle. */
+  /** Declare a numeric flag handle for runtime evaluation. */
   numberFlag(key, defaultValue) {
-    const handle = new NumberFlagHandle(this, key, defaultValue);
+    const handle = new NumberFlag(this, {
+      id: null,
+      key,
+      name: key,
+      type: "NUMERIC",
+      default: defaultValue,
+      values: [],
+      description: null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
     this._handles[key] = handle;
     return handle;
   }
-  /** Declare a JSON flag handle. */
+  /** Declare a JSON flag handle for runtime evaluation. */
   jsonFlag(key, defaultValue) {
-    const handle = new JsonFlagHandle(this, key, defaultValue);
+    const handle = new JsonFlag(this, {
+      id: null,
+      key,
+      name: key,
+      type: "JSON",
+      default: defaultValue,
+      values: [],
+      description: null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
     this._handles[key] = handle;
     return handle;
   }
@@ -1360,41 +1375,32 @@ var FlagsClient = class {
   /**
    * 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) {
     this._contextProvider = fn;
   }
   /**
    * Register a context provider — decorator-style alias.
-   *
-   * ```typescript
-   * const provider = client.flags.contextProvider(() => [...]);
-   * ```
    */
   contextProvider(fn) {
     this._contextProvider = fn;
     return fn;
   }
   // ------------------------------------------------------------------
-  // Runtime: connect / disconnect / refresh
+  // Runtime: initialize / disconnect / refresh
   // ------------------------------------------------------------------
   /**
-   * 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.
    */
-  async _connectInternal(environment) {
-    this._environment = environment;
+  async initialize() {
+    if (this._initialized) return;
+    this._environment = this._parent?._environment ?? null;
     await this._fetchAllFlags();
-    this._connected = true;
+    this._initialized = true;
     this._cache.clear();
     this._wsManager = this._ensureWs();
     this._wsManager.on("flag_changed", this._handleFlagChanged);
@@ -1410,7 +1416,7 @@ var FlagsClient = class {
     await this._flushContexts();
     this._flagStore = {};
     this._cache.clear();
-    this._connected = false;
+    this._initialized = false;
     this._environment = null;
   }
   /** Re-fetch all flag definitions and clear cache. */
@@ -1431,22 +1437,27 @@ var FlagsClient = class {
     return new FlagStats(this._cache.cacheHits, this._cache.cacheMisses);
   }
   // ------------------------------------------------------------------
-  // Runtime: change listeners
+  // Runtime: change listeners (dual-mode)
   // ------------------------------------------------------------------
-  /** Register a global change listener that fires for any flag change. */
-  onChangeAny(callback) {
-    this._globalListeners.push(callback);
-    return callback;
-  }
   /**
-   * 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) {
-    return this.onChangeAny(callback);
+  onChange(callbackOrKey, callback) {
+    if (typeof callbackOrKey === "function") {
+      this._globalListeners.push(callbackOrKey);
+    } else {
+      const key = callbackOrKey;
+      if (!callback) {
+        throw new SmplError("onChange(key, callback) requires a callback function.");
+      }
+      if (!this._keyListeners.has(key)) {
+        this._keyListeners.set(key, []);
+      }
+      this._keyListeners.get(key).push(callback);
+    }
   }
   // ------------------------------------------------------------------
   // Runtime: context registration
@@ -1455,7 +1466,7 @@ var FlagsClient = class {
    * 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) {
     if (Array.isArray(context)) {
@@ -1473,8 +1484,6 @@ var FlagsClient = class {
   // ------------------------------------------------------------------
   /**
    * Tier 1 explicit evaluation — stateless, no provider or cache.
-   *
-   * Useful for scripts, one-off jobs, and infrastructure code.
    */
   async evaluate(key, options) {
     const evalDict = contextsToEvalDict(options.context);
@@ -1482,7 +1491,7 @@ var FlagsClient = class {
       evalDict["service"] = { key: this._parent._service };
     }
     let flagDef = null;
-    if (this._connected && key in this._flagStore) {
+    if (this._initialized && key in this._flagStore) {
       flagDef = this._flagStore[key];
     } else {
       const flags = await this._fetchFlagsList();
@@ -1503,8 +1512,8 @@ var FlagsClient = class {
   // ------------------------------------------------------------------
   /** @internal */
   _evaluateHandle(key, defaultValue, context) {
-    if (!this._connected) {
-      throw new SmplNotConnectedError("SmplClient is not connected. Call client.connect() first.");
+    if (!this._initialized) {
+      throw new SmplError("Flags not initialized. Call await client.flags.initialize() first.");
     }
     let evalDict;
     if (context !== null) {
@@ -1541,6 +1550,19 @@ var FlagsClient = class {
     return value;
   }
   // ------------------------------------------------------------------
+  // Internal: _connectInternal (called by SmplClient for backward compat)
+  // ------------------------------------------------------------------
+  /** @internal — called by SmplClient constructor / lazy init. */
+  async _connectInternal(environment) {
+    this._environment = environment;
+    await this._fetchAllFlags();
+    this._initialized = true;
+    this._cache.clear();
+    this._wsManager = this._ensureWs();
+    this._wsManager.on("flag_changed", this._handleFlagChanged);
+    this._wsManager.on("flag_deleted", this._handleFlagDeleted);
+  }
+  // ------------------------------------------------------------------
   // Internal: event handlers (called by SharedWebSocket)
   // ------------------------------------------------------------------
   _handleFlagChanged = (data) => {
@@ -1592,9 +1614,9 @@ var FlagsClient = class {
         } catch {
         }
       }
-      const handle = this._handles[flagKey];
-      if (handle) {
-        for (const cb of handle._listeners) {
+      const keyCallbacks = this._keyListeners.get(flagKey);
+      if (keyCallbacks) {
+        for (const cb of keyCallbacks) {
           try {
             cb(event);
           } catch {
@@ -1630,10 +1652,11 @@ var FlagsClient = class {
   // ------------------------------------------------------------------
   // Internal: model conversion
   // ------------------------------------------------------------------
+  /** @internal */
   _resourceToModel(resource) {
     const attrs = resource.attributes;
     return new Flag(this, {
-      id: resource.id ?? "",
+      id: resource.id ?? null,
       key: attrs.key,
       name: attrs.name,
       type: attrs.type,
@@ -1657,13 +1680,567 @@ var FlagsClient = class {
       environments: attrs.environments ?? {}
     };
   }
-  _parseContextType(data) {
-    const attrs = data.attributes ?? {};
-    return new ContextType({
-      id: data.id ?? "",
+};
+
+// src/logging/client.ts
+import createClient3 from "openapi-fetch";
+
+// src/logging/models.ts
+var Logger = class {
+  /** UUID of the logger, or `null` if unsaved. */
+  id;
+  /** Unique key (dot-separated hierarchy). */
+  key;
+  /** Human-readable display name. */
+  name;
+  /** Base log level, or null if inherited. */
+  level;
+  /** UUID of the parent log group, or null. */
+  group;
+  /** Whether this logger is managed by the platform. */
+  managed;
+  /** Observed sources (services that report this logger). */
+  sources;
+  /** Per-environment level overrides. */
+  environments;
+  /** When the logger was created. */
+  createdAt;
+  /** When the logger was last updated. */
+  updatedAt;
+  /** @internal */
+  _client;
+  /** @internal */
+  constructor(client, fields) {
+    this._client = client;
+    this.id = fields.id;
+    this.key = fields.key;
+    this.name = fields.name;
+    this.level = fields.level;
+    this.group = fields.group;
+    this.managed = fields.managed;
+    this.sources = fields.sources;
+    this.environments = fields.environments;
+    this.createdAt = fields.createdAt;
+    this.updatedAt = fields.updatedAt;
+  }
+  /**
+   * Persist this logger to the server.
+   *
+   * POST if `id` is null (new), PUT if `id` is set (update).
+   */
+  async save() {
+    const saved = await this._client._saveLogger(this);
+    this._apply(saved);
+  }
+  /** Set the base log level (sync local mutation). */
+  setLevel(level) {
+    this.level = level;
+  }
+  /** Clear the base log level (sync local mutation). */
+  clearLevel() {
+    this.level = null;
+  }
+  /** Set an environment-specific log level (sync local mutation). */
+  setEnvironmentLevel(env, level) {
+    const envs = { ...this.environments };
+    envs[env] = { ...envs[env] ?? {}, level };
+    this.environments = envs;
+  }
+  /** Clear an environment-specific log level (sync local mutation). */
+  clearEnvironmentLevel(env) {
+    const envs = { ...this.environments };
+    if (envs[env]) {
+      const entry = { ...envs[env] };
+      delete entry.level;
+      envs[env] = entry;
+      this.environments = envs;
+    }
+  }
+  /** Clear all environment-specific log levels (sync local mutation). */
+  clearAllEnvironmentLevels() {
+    this.environments = {};
+  }
+  /** @internal — copy all fields from another Logger instance. */
+  _apply(other) {
+    this.id = other.id;
+    this.key = other.key;
+    this.name = other.name;
+    this.level = other.level;
+    this.group = other.group;
+    this.managed = other.managed;
+    this.sources = other.sources;
+    this.environments = other.environments;
+    this.createdAt = other.createdAt;
+    this.updatedAt = other.updatedAt;
+  }
+  toString() {
+    return `Logger(key=${this.key}, level=${this.level})`;
+  }
+};
+var LogGroup = class {
+  /** UUID of the log group, or `null` if unsaved. */
+  id;
+  /** Unique key. */
+  key;
+  /** Human-readable display name. */
+  name;
+  /** Base log level, or null if inherited. */
+  level;
+  /** UUID of the parent log group, or null. */
+  group;
+  /** Per-environment level overrides. */
+  environments;
+  /** When the log group was created. */
+  createdAt;
+  /** When the log group was last updated. */
+  updatedAt;
+  /** @internal */
+  _client;
+  /** @internal */
+  constructor(client, fields) {
+    this._client = client;
+    this.id = fields.id;
+    this.key = fields.key;
+    this.name = fields.name;
+    this.level = fields.level;
+    this.group = fields.group;
+    this.environments = fields.environments;
+    this.createdAt = fields.createdAt;
+    this.updatedAt = fields.updatedAt;
+  }
+  /**
+   * Persist this log group to the server.
+   *
+   * POST if `id` is null (new), PUT if `id` is set (update).
+   */
+  async save() {
+    const saved = await this._client._saveLogGroup(this);
+    this._apply(saved);
+  }
+  /** Set the base log level (sync local mutation). */
+  setLevel(level) {
+    this.level = level;
+  }
+  /** Clear the base log level (sync local mutation). */
+  clearLevel() {
+    this.level = null;
+  }
+  /** Set an environment-specific log level (sync local mutation). */
+  setEnvironmentLevel(env, level) {
+    const envs = { ...this.environments };
+    envs[env] = { ...envs[env] ?? {}, level };
+    this.environments = envs;
+  }
+  /** Clear an environment-specific log level (sync local mutation). */
+  clearEnvironmentLevel(env) {
+    const envs = { ...this.environments };
+    if (envs[env]) {
+      const entry = { ...envs[env] };
+      delete entry.level;
+      envs[env] = entry;
+      this.environments = envs;
+    }
+  }
+  /** Clear all environment-specific log levels (sync local mutation). */
+  clearAllEnvironmentLevels() {
+    this.environments = {};
+  }
+  /** @internal — copy all fields from another LogGroup instance. */
+  _apply(other) {
+    this.id = other.id;
+    this.key = other.key;
+    this.name = other.name;
+    this.level = other.level;
+    this.group = other.group;
+    this.environments = other.environments;
+    this.createdAt = other.createdAt;
+    this.updatedAt = other.updatedAt;
+  }
+  toString() {
+    return `LogGroup(key=${this.key}, level=${this.level})`;
+  }
+};
+
+// src/logging/client.ts
+var LOGGING_BASE_URL = "https://logging.smplkit.com";
+async function checkError3(response, _context) {
+  const body = await response.text().catch(() => "");
+  throwForStatus(response.status, body);
+}
+function wrapFetchError3(err) {
+  if (err instanceof SmplNotFoundError || err instanceof SmplConflictError || err instanceof SmplValidationError || err instanceof SmplError) {
+    throw err;
+  }
+  if (err instanceof TypeError) {
+    throw new SmplConnectionError(`Network error: ${err.message}`);
+  }
+  throw new SmplConnectionError(
+    `Request failed: ${err instanceof Error ? err.message : String(err)}`
+  );
+}
+var LoggingClient = class {
+  /** @internal */
+  _apiKey;
+  /** @internal */
+  _baseUrl = LOGGING_BASE_URL;
+  /** @internal */
+  _http;
+  /** @internal — set by SmplClient after construction. */
+  _parent = null;
+  _ensureWs;
+  _wsManager = null;
+  _started = false;
+  _globalListeners = [];
+  _keyListeners = /* @__PURE__ */ new Map();
+  /** @internal */
+  constructor(apiKey, ensureWs, timeout) {
+    this._apiKey = apiKey;
+    this._ensureWs = ensureWs;
+    const ms = timeout ?? 3e4;
+    this._http = createClient3({
+      baseUrl: LOGGING_BASE_URL,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      },
+      fetch: async (request) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), ms);
+        try {
+          return await fetch(new Request(request, { signal: controller.signal }));
+        } catch (err) {
+          if (err instanceof DOMException && err.name === "AbortError") {
+            throw new SmplTimeoutError(`Request timed out after ${ms}ms`);
+          }
+          throw err;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+    });
+  }
+  // ------------------------------------------------------------------
+  // Management: Logger factory
+  // ------------------------------------------------------------------
+  /** Create an unsaved logger. Call `.save()` to persist. */
+  new(key, options) {
+    return new Logger(this, {
+      id: null,
+      key,
+      name: options?.name ?? keyToDisplayName(key),
+      level: null,
+      group: null,
+      managed: options?.managed ?? false,
+      sources: [],
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
+  }
+  // ------------------------------------------------------------------
+  // Management: Logger CRUD
+  // ------------------------------------------------------------------
+  /** Fetch a logger by key. */
+  async get(key) {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/loggers", {
+        params: { query: { "filter[key]": key } }
+      });
+      if (result.error !== void 0)
+        await checkError3(result.response, `Logger with key '${key}' not found`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError3(err);
+    }
+    if (!data || !data.data || data.data.length === 0) {
+      throw new SmplNotFoundError(`Logger with key '${key}' not found`);
+    }
+    return this._loggerToModel(data.data[0]);
+  }
+  /** List all loggers. */
+  async list() {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/loggers", {});
+      if (result.error !== void 0) await checkError3(result.response, "Failed to list loggers");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError3(err);
+    }
+    if (!data) return [];
+    return data.data.map((r) => this._loggerToModel(r));
+  }
+  /** Delete a logger by key. */
+  async delete(key) {
+    const logger = await this.get(key);
+    try {
+      const result = await this._http.DELETE("/api/v1/loggers/{id}", {
+        params: { path: { id: logger.id } }
+      });
+      if (result.error !== void 0 && result.response.status !== 204)
+        await checkError3(result.response, `Failed to delete logger '${key}'`);
+    } catch (err) {
+      wrapFetchError3(err);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Management: LogGroup factory
+  // ------------------------------------------------------------------
+  /** Create an unsaved log group. Call `.save()` to persist. */
+  newGroup(key, options) {
+    return new LogGroup(this, {
+      id: null,
+      key,
+      name: options?.name ?? keyToDisplayName(key),
+      level: null,
+      group: options?.group ?? null,
+      environments: {},
+      createdAt: null,
+      updatedAt: null
+    });
+  }
+  // ------------------------------------------------------------------
+  // Management: LogGroup CRUD
+  // ------------------------------------------------------------------
+  /** Fetch a log group by key. */
+  async getGroup(key) {
+    const groups = await this.listGroups();
+    const match = groups.find((g) => g.key === key);
+    if (!match) {
+      throw new SmplNotFoundError(`LogGroup with key '${key}' not found`);
+    }
+    return match;
+  }
+  /** List all log groups. */
+  async listGroups() {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/log_groups", {});
+      if (result.error !== void 0)
+        await checkError3(result.response, "Failed to list log groups");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError3(err);
+    }
+    if (!data) return [];
+    return data.data.map((r) => this._groupToModel(r));
+  }
+  /** Delete a log group by key. */
+  async deleteGroup(key) {
+    const group = await this.getGroup(key);
+    try {
+      const result = await this._http.DELETE("/api/v1/log_groups/{id}", {
+        params: { path: { id: group.id } }
+      });
+      if (result.error !== void 0 && result.response.status !== 204)
+        await checkError3(result.response, `Failed to delete log group '${key}'`);
+    } catch (err) {
+      wrapFetchError3(err);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Management: internal save methods
+  // ------------------------------------------------------------------
+  /** @internal — POST or PUT a logger. */
+  async _saveLogger(logger) {
+    const body = {
+      data: {
+        type: "logger",
+        attributes: {
+          key: logger.key,
+          name: logger.name,
+          level: logger.level,
+          group: logger.group,
+          managed: logger.managed,
+          environments: logger.environments
+        }
+      }
+    };
+    if (logger.id === null) {
+      let data;
+      try {
+        const result = await this._http.POST("/api/v1/loggers", { body });
+        if (result.error !== void 0)
+          await checkError3(result.response, "Failed to create logger");
+        data = result.data;
+      } catch (err) {
+        wrapFetchError3(err);
+      }
+      if (!data || !data.data) throw new SmplValidationError("Failed to create logger");
+      return this._loggerToModel(data.data);
+    } else {
+      let data;
+      try {
+        const result = await this._http.PUT("/api/v1/loggers/{id}", {
+          params: { path: { id: logger.id } },
+          body
+        });
+        if (result.error !== void 0)
+          await checkError3(result.response, `Failed to update logger ${logger.id}`);
+        data = result.data;
+      } catch (err) {
+        wrapFetchError3(err);
+      }
+      if (!data || !data.data)
+        throw new SmplValidationError(`Failed to update logger ${logger.id}`);
+      return this._loggerToModel(data.data);
+    }
+  }
+  /** @internal — POST or PUT a log group. */
+  async _saveLogGroup(group) {
+    const body = {
+      data: {
+        type: "log_group",
+        attributes: {
+          key: group.key,
+          name: group.name,
+          level: group.level,
+          group: group.group,
+          environments: group.environments
+        }
+      }
+    };
+    if (group.id === null) {
+      let data;
+      try {
+        const result = await this._http.POST("/api/v1/log_groups", { body });
+        if (result.error !== void 0)
+          await checkError3(result.response, "Failed to create log group");
+        data = result.data;
+      } catch (err) {
+        wrapFetchError3(err);
+      }
+      if (!data || !data.data) throw new SmplValidationError("Failed to create log group");
+      return this._groupToModel(data.data);
+    } else {
+      let data;
+      try {
+        const result = await this._http.PUT("/api/v1/log_groups/{id}", {
+          params: { path: { id: group.id } },
+          body
+        });
+        if (result.error !== void 0)
+          await checkError3(result.response, `Failed to update log group ${group.id}`);
+        data = result.data;
+      } catch (err) {
+        wrapFetchError3(err);
+      }
+      if (!data || !data.data)
+        throw new SmplValidationError(`Failed to update log group ${group.id}`);
+      return this._groupToModel(data.data);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Runtime: start (scaffolded)
+  // ------------------------------------------------------------------
+  /**
+   * 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().
+   */
+  async start() {
+    if (this._started) return;
+    this._wsManager = this._ensureWs();
+    this._wsManager.on("logger_changed", this._handleLoggerChanged);
+    this._started = true;
+  }
+  // ------------------------------------------------------------------
+  // Runtime: change listeners (dual-mode)
+  // ------------------------------------------------------------------
+  /**
+   * Register a change listener.
+   *
+   * - `onChange(callback)` — fires for any logger change (global).
+   * - `onChange(key, callback)` — fires only for the specified logger key.
+   */
+  onChange(callbackOrKey, callback) {
+    if (typeof callbackOrKey === "function") {
+      this._globalListeners.push(callbackOrKey);
+    } else {
+      const key = callbackOrKey;
+      if (!callback) {
+        throw new SmplError("onChange(key, callback) requires a callback function.");
+      }
+      if (!this._keyListeners.has(key)) {
+        this._keyListeners.set(key, []);
+      }
+      this._keyListeners.get(key).push(callback);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Internal: close
+  // ------------------------------------------------------------------
+  /** @internal */
+  _close() {
+    if (this._wsManager !== null) {
+      this._wsManager.off("logger_changed", this._handleLoggerChanged);
+      this._wsManager = null;
+    }
+    this._started = false;
+  }
+  // ------------------------------------------------------------------
+  // Internal: WebSocket handler
+  // ------------------------------------------------------------------
+  _handleLoggerChanged = (data) => {
+    const key = data.key;
+    if (key) {
+      const level = data.level ?? null;
+      const event = {
+        key,
+        level,
+        source: "websocket"
+      };
+      for (const cb of this._globalListeners) {
+        try {
+          cb(event);
+        } catch {
+        }
+      }
+      const keyCallbacks = this._keyListeners.get(key);
+      if (keyCallbacks) {
+        for (const cb of keyCallbacks) {
+          try {
+            cb(event);
+          } catch {
+          }
+        }
+      }
+    }
+  };
+  // ------------------------------------------------------------------
+  // Internal: model conversion
+  // ------------------------------------------------------------------
+  _loggerToModel(resource) {
+    const attrs = resource.attributes;
+    return new Logger(this, {
+      id: resource.id ?? null,
       key: attrs.key ?? "",
-      name: attrs.name ?? "",
-      attributes: attrs.attributes ?? {}
+      name: attrs.name,
+      level: attrs.level ?? null,
+      group: attrs.group ?? null,
+      managed: attrs.managed ?? false,
+      sources: attrs.sources ?? [],
+      environments: attrs.environments ?? {},
+      createdAt: attrs.created_at ?? null,
+      updatedAt: attrs.updated_at ?? null
+    });
+  }
+  _groupToModel(resource) {
+    const attrs = resource.attributes;
+    return new LogGroup(this, {
+      id: resource.id ?? null,
+      key: attrs.key ?? "",
+      name: attrs.name,
+      level: attrs.level ?? null,
+      group: attrs.group ?? null,
+      environments: attrs.environments ?? {},
+      createdAt: attrs.created_at ?? null,
+      updatedAt: attrs.updated_at ?? null
     });
   }
 };
@@ -1879,17 +2456,18 @@ var APP_BASE_URL2 = "https://app.smplkit.com";
 var NO_ENVIRONMENT_MESSAGE = "No environment provided. Set one of:\n  1. Pass environment to the constructor\n  2. Set the SMPLKIT_ENVIRONMENT environment variable";
 var NO_SERVICE_MESSAGE = "No service provided. Set one of:\n  1. Pass service in options\n  2. Set the SMPLKIT_SERVICE environment variable";
 var SmplClient = class {
-  /** Client for config management-plane operations. */
+  /** Client for config management and runtime. */
   config;
-  /** Client for flags management and runtime operations. */
+  /** Client for flags management and runtime. */
   flags;
+  /** Client for logging management and runtime. */
+  logging;
   _wsManager = null;
   _apiKey;
   /** @internal */
   _environment;
   /** @internal */
   _service;
-  _connected = false;
   _timeout;
   _appHttp;
   constructor(options = {}) {
@@ -1906,48 +2484,21 @@ var SmplClient = class {
     const apiKey = resolveApiKey(options.apiKey, environment);
     this._apiKey = apiKey;
     this._timeout = options.timeout ?? 3e4;
-    const ms = this._timeout;
-    this._appHttp = createClient3({
+    this._appHttp = createClient4({
       baseUrl: APP_BASE_URL2,
       headers: {
         Authorization: `Bearer ${apiKey}`,
         Accept: "application/json"
-      },
-      fetch: async (request) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), ms);
-        try {
-          return await fetch(new Request(request, { signal: controller.signal }));
-        } catch (err) {
-          if (err instanceof DOMException && err.name === "AbortError") {
-            throw new SmplTimeoutError(`Request timed out after ${ms}ms`);
-          }
-          throw err;
-        } finally {
-          clearTimeout(timer);
-        }
       }
     });
     this.config = new ConfigClient(apiKey, this._timeout);
     this.flags = new FlagsClient(apiKey, () => this._ensureWs(), this._timeout);
+    this.logging = new LoggingClient(apiKey, () => this._ensureWs(), this._timeout);
     this.config._getSharedWs = () => this._ensureWs();
     this.flags._parent = this;
     this.config._parent = this;
-  }
-  /**
-   * 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.
-   */
-  async connect() {
-    if (this._connected) return;
-    await this._registerServiceContext();
-    await this.flags._connectInternal(this._environment);
-    await this.config._connectInternal(this._environment);
-    this._connected = true;
+    this.logging._parent = this;
+    void this._registerServiceContext();
   }
   /** @internal */
   async _registerServiceContext() {
@@ -1976,6 +2527,7 @@ var SmplClient = class {
   }
   /** Close the shared WebSocket and release resources. */
   close() {
+    this.logging._close();
     if (this._wsManager !== null) {
       this._wsManager.stop();
       this._wsManager = null;
@@ -2047,28 +2599,43 @@ var Rule = class {
     return result;
   }
 };
+
+// src/logging/types.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2["TRACE"] = "TRACE";
+  LogLevel2["DEBUG"] = "DEBUG";
+  LogLevel2["INFO"] = "INFO";
+  LogLevel2["WARN"] = "WARN";
+  LogLevel2["ERROR"] = "ERROR";
+  LogLevel2["FATAL"] = "FATAL";
+  LogLevel2["SILENT"] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
 export {
-  BoolFlagHandle,
+  BooleanFlag,
   Config,
   ConfigClient,
   Context,
-  ContextType,
   Flag,
   FlagChangeEvent,
   FlagStats,
   FlagsClient,
-  JsonFlagHandle,
-  NumberFlagHandle,
+  JsonFlag,
+  LiveConfigProxy,
+  LogGroup,
+  LogLevel,
+  Logger,
+  LoggingClient,
+  NumberFlag,
   Rule,
   SharedWebSocket,
   SmplClient,
   SmplConflictError,
   SmplConnectionError,
   SmplError,
-  SmplNotConnectedError,
   SmplNotFoundError,
   SmplTimeoutError,
   SmplValidationError,
-  StringFlagHandle
+  StringFlag
 };
 //# sourceMappingURL=index.js.map