@smplkit/sdk 1.1.10 → 1.2.1

package/dist/index.js

@@ -1,7 +1,3 @@
-import {
-  ConfigRuntime
-} from "./chunk-RF6LYU4V.js";
-
 // src/config/client.ts
 import createClient from "openapi-fetch";
 
@@ -47,6 +43,13 @@ 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) {
     super(message, statusCode ?? 422, responseBody);
@@ -55,6 +58,34 @@ var SmplValidationError = class extends SmplError {
   }
 };
 
+// src/config/resolve.ts
+function deepMerge(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (key in result && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key]) && typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[key] = deepMerge(
+        result[key],
+        value
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function resolveChain(chain, environment) {
+  let accumulated = {};
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const config = chain[i];
+    const baseValues = config.items ?? {};
+    const envEntry = (config.environments ?? {})[environment];
+    const envValues = envEntry !== null && envEntry !== void 0 && typeof envEntry === "object" && !Array.isArray(envEntry) ? envEntry.values ?? {} : {};
+    const configResolved = deepMerge(baseValues, envValues);
+    accumulated = deepMerge(accumulated, configResolved);
+  }
+  return accumulated;
+}
+
 // src/config/types.ts
 var Config = class {
   /** UUID of the config. */
@@ -181,45 +212,6 @@ var Config = class {
       await this.setValues(existing, environment);
     }
   }
-  /**
-   * Connect to this config for runtime value resolution.
-   *
-   * Eagerly fetches this config and its full parent chain, resolves values
-   * for the given environment via deep merge, and returns a
-   * {@link ConfigRuntime} with a fully populated local cache.
-   *
-   * A background WebSocket connection is started for real-time updates.
-   * If the WebSocket fails to connect, the runtime operates in cache-only
-   * mode and reconnects automatically.
-   *
-   * Supports both `await` and `await using` (TypeScript 5.2+)::
-   *
-   * ```typescript
-   * // Simple await
-   * const runtime = await config.connect("production");
-   * try { ... } finally { await runtime.close(); }
-   *
-   * // await using (auto-close)
-   * await using runtime = await config.connect("production");
-   * ```
-   *
-   * @param environment - The environment to resolve for (e.g. `"production"`).
-   * @param options.timeout - Milliseconds to wait for the initial fetch.
-   */
-  async connect(environment, options) {
-    const { ConfigRuntime: ConfigRuntime2 } = await import("./runtime-FT745HBO.js");
-    const timeout = options?.timeout ?? 3e4;
-    const chain = await this._buildChain(timeout);
-    return new ConfigRuntime2({
-      configKey: this.key,
-      configId: this.id,
-      environment,
-      chain,
-      apiKey: this._client._apiKey,
-      baseUrl: this._client._baseUrl,
-      fetchChain: () => this._buildChain(timeout)
-    });
-  }
   /**
    * Walk the parent chain and return config data objects, child-to-root.
    * @internal
@@ -364,6 +356,12 @@ var ConfigClient = class {
   _baseUrl = BASE_URL;
   /** @internal */
   _http;
+  /** @internal — returns the shared WebSocket for real-time updates. */
+  _getSharedWs;
+  /** @internal — set by SmplClient after construction. */
+  _parent = null;
+  _configCache = {};
+  _connected = false;
   /** @internal */
   constructor(apiKey, timeout) {
     this._apiKey = apiKey;
@@ -461,6 +459,44 @@ var ConfigClient = class {
       wrapFetchError(err);
     }
   }
+  /**
+   * 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);
+    }
+    this._configCache = cache;
+    this._connected = true;
+  }
+  /**
+   * 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.
+   *
+   * @throws {SmplNotConnectedError} If connect() has not been called.
+   */
+  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;
+    }
+    if (itemKey === void 0) {
+      return { ...resolved };
+    }
+    return itemKey in resolved ? resolved[itemKey] : defaultValue ?? null;
+  }
   /**
    * Internal: PUT a full config update and return the updated model.
    *
@@ -528,58 +564,1607 @@ var ConfigClient = class {
   }
 };
 
-// src/resolve.ts
-import { readFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-var NO_API_KEY_MESSAGE = "No API key provided. Set one of:\n  1. Pass apiKey to the constructor\n  2. Set the SMPLKIT_API_KEY environment variable\n  3. Create a ~/.smplkit file with:\n     [default]\n     api_key = your_key_here";
-function resolveApiKey(explicit) {
-  if (explicit) return explicit;
-  const envVal = process.env.SMPLKIT_API_KEY;
-  if (envVal) return envVal;
-  const configPath = join(homedir(), ".smplkit");
-  try {
-    const content = readFileSync(configPath, "utf-8");
-    let inDefaultSection = false;
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      if (trimmed === "" || trimmed.startsWith("#")) continue;
-      if (trimmed.startsWith("[")) {
-        inDefaultSection = trimmed.toLowerCase() === "[default]";
-        continue;
+// src/flags/client.ts
+import createClient2 from "openapi-fetch";
+
+// src/auth.ts
+function buildAuthHeader(apiKey) {
+  return `Bearer ${apiKey}`;
+}
+
+// src/transport.ts
+var SDK_VERSION = "0.0.0";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var Transport = class {
+  apiKey;
+  timeout;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Send a GET request.
+   *
+   * @param url - Fully-qualified URL (e.g. `https://config.smplkit.com/api/v1/configs`).
+   * @param params - Optional query parameters.
+   * @returns Parsed JSON response body.
+   */
+  async get(url, params) {
+    return this.request("GET", url, void 0, params);
+  }
+  /**
+   * Send a POST request with a JSON body.
+   *
+   * @param url - Fully-qualified URL.
+   * @param body - JSON-serializable request body.
+   * @returns Parsed JSON response body.
+   */
+  async post(url, body) {
+    return this.request("POST", url, body);
+  }
+  /**
+   * Send a PUT request with a JSON body.
+   *
+   * @param url - Fully-qualified URL.
+   * @param body - JSON-serializable request body.
+   * @returns Parsed JSON response body.
+   */
+  async put(url, body) {
+    return this.request("PUT", url, body);
+  }
+  /**
+   * Send a DELETE request.
+   *
+   * @param url - Fully-qualified URL.
+   * @returns Parsed JSON response body (empty object for 204 responses).
+   */
+  async delete(url) {
+    return this.request("DELETE", url);
+  }
+  /**
+   * Core request method. Handles headers, timeouts, and error mapping.
+   */
+  async request(method, url, body, params) {
+    if (params) {
+      const searchParams = new URLSearchParams(params);
+      url += `?${searchParams.toString()}`;
+    }
+    const headers = {
+      Authorization: buildAuthHeader(this.apiKey),
+      "User-Agent": `smplkit-typescript-sdk/${SDK_VERSION}`,
+      Accept: "application/vnd.api+json"
+    };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/vnd.api+json";
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new SmplTimeoutError(`Request timed out after ${this.timeout}ms`);
       }
-      if (inDefaultSection && trimmed.startsWith("api_key")) {
-        const eqIndex = trimmed.indexOf("=");
-        if (eqIndex !== -1) {
-          const value = trimmed.slice(eqIndex + 1).trim();
-          if (value) return value;
-        }
+      if (error instanceof TypeError) {
+        throw new SmplConnectionError(`Network error: ${error.message}`);
       }
+      throw new SmplConnectionError(
+        `Request failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (response.status === 204) {
+      return {};
+    }
+    const responseText = await response.text();
+    if (!response.ok) {
+      this.throwForStatus(response.status, responseText);
+    }
+    try {
+      return JSON.parse(responseText);
+    } catch {
+      throw new SmplError(`Invalid JSON response: ${responseText}`, response.status, responseText);
     }
-  } catch {
   }
-  throw new SmplError(NO_API_KEY_MESSAGE);
-}
+  /**
+   * Map HTTP error status codes to typed SDK exceptions.
+   *
+   * @throws {SmplNotFoundError} On 404.
+   * @throws {SmplConflictError} On 409.
+   * @throws {SmplValidationError} On 422.
+   * @throws {SmplError} On any other non-2xx status.
+   */
+  throwForStatus(status, body) {
+    switch (status) {
+      case 404:
+        throw new SmplNotFoundError(body, 404, body);
+      case 409:
+        throw new SmplConflictError(body, 409, body);
+      case 422:
+        throw new SmplValidationError(body, 422, body);
+      default:
+        throw new SmplError(`HTTP ${status}: ${body}`, status, body);
+    }
+  }
+};
 
-// src/client.ts
-var SmplClient = class {
-  /** Client for config management-plane operations. */
-  config;
-  constructor(options = {}) {
-    const apiKey = resolveApiKey(options.apiKey);
-    this.config = new ConfigClient(apiKey, options.timeout);
+// src/flags/models.ts
+var Flag = class {
+  /** UUID of the flag. */
+  id;
+  /** Unique key within the account. */
+  key;
+  /** Human-readable display name. */
+  name;
+  /** Value type: BOOLEAN, STRING, NUMERIC, or JSON. */
+  type;
+  /** Flag-level default value. */
+  default;
+  /** Closed set of possible values. */
+  values;
+  /** Optional description. */
+  description;
+  /** Per-environment configuration. */
+  environments;
+  /** When the flag was created. */
+  createdAt;
+  /** When the flag 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.type = fields.type;
+    this.default = fields.default;
+    this.values = fields.values;
+    this.description = fields.description;
+    this.environments = fields.environments;
+    this.createdAt = fields.createdAt;
+    this.updatedAt = fields.updatedAt;
+  }
+  /**
+   * Update this flag's attributes on the server.
+   *
+   * Only provided fields are changed; others retain their current values.
+   */
+  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);
+  }
+  /**
+   * 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.
+   */
+  async 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 ?? []];
+    const { environment: _env, ...ruleCopy } = builtRule;
+    rules.push(ruleCopy);
+    envData.rules = rules;
+    envs[envKey] = envData;
+    const updated = await this._client._updateFlag({
+      flag: this,
+      environments: envs
+    });
+    this._apply(updated);
+  }
+  /** @internal */
+  _apply(other) {
+    this.id = other.id;
+    this.key = other.key;
+    this.name = other.name;
+    this.type = other.type;
+    this.default = other.default;
+    this.values = other.values;
+    this.description = other.description;
+    this.environments = other.environments;
+    this.createdAt = other.createdAt;
+    this.updatedAt = other.updatedAt;
+  }
+  toString() {
+    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;
+  }
+  toString() {
+    return `ContextType(key=${this.key}, name=${this.name})`;
+  }
+};
+
+// 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(() => "");
+  switch (response.status) {
+    case 404:
+      throw new SmplNotFoundError(body || context, 404, body);
+    case 409:
+      throw new SmplConflictError(body || context, 409, body);
+    case 422:
+      throw new SmplValidationError(body || context, 422, body);
+    default:
+      throw new SmplError(`HTTP ${response.status}: ${body}`, response.status, body);
+  }
+}
+function wrapFetchError2(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)}`
+  );
+}
+function contextsToEvalDict(contexts) {
+  const result = {};
+  for (const ctx of contexts) {
+    result[ctx.type] = { key: ctx.key, ...ctx.attributes };
+  }
+  return result;
+}
+function sortedStringify(obj) {
+  if (obj === null || obj === void 0) return "null";
+  if (typeof obj !== "object") return JSON.stringify(obj);
+  if (Array.isArray(obj)) return "[" + obj.map(sortedStringify).join(",") + "]";
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + sortedStringify(obj[k])).join(",") + "}";
+}
+function hashContext(evalDict) {
+  const serialized = sortedStringify(evalDict);
+  let hash = 0;
+  for (let i = 0; i < serialized.length; i++) {
+    const chr = serialized.charCodeAt(i);
+    hash = (hash << 5) - hash + chr | 0;
+  }
+  return hash.toString(36);
+}
+function evaluateFlag(flagDef, environment, evalDict) {
+  const flagDefault = flagDef.default;
+  const environments = flagDef.environments ?? {};
+  if (environment === null || !(environment in environments)) {
+    return flagDefault;
+  }
+  const envConfig = environments[environment];
+  const envDefault = envConfig.default;
+  const fallback = envDefault !== void 0 && envDefault !== null ? envDefault : flagDefault;
+  if (!envConfig.enabled) {
+    return fallback;
+  }
+  const rules = envConfig.rules ?? [];
+  for (const rule of rules) {
+    const logic = rule.logic;
+    if (!logic || Object.keys(logic).length === 0) {
+      continue;
+    }
+    try {
+      const result = jsonLogic.apply(logic, evalDict);
+      if (result) {
+        return rule.value;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return fallback;
+}
+var FlagChangeEvent = class {
+  key;
+  source;
+  constructor(key, source) {
+    this.key = key;
+    this.source = source;
+  }
+};
+var ResolutionCache = class {
+  _maxSize;
+  _cache = /* @__PURE__ */ new Map();
+  cacheHits = 0;
+  cacheMisses = 0;
+  constructor(maxSize = CACHE_MAX_SIZE) {
+    this._maxSize = maxSize;
+  }
+  get(cacheKey) {
+    if (this._cache.has(cacheKey)) {
+      const value = this._cache.get(cacheKey);
+      this._cache.delete(cacheKey);
+      this._cache.set(cacheKey, value);
+      this.cacheHits++;
+      return [true, value];
+    }
+    this.cacheMisses++;
+    return [false, null];
+  }
+  put(cacheKey, value) {
+    if (this._cache.has(cacheKey)) {
+      this._cache.delete(cacheKey);
+    }
+    this._cache.set(cacheKey, value);
+    if (this._cache.size > this._maxSize) {
+      const firstKey = this._cache.keys().next().value;
+      if (firstKey !== void 0) {
+        this._cache.delete(firstKey);
+      }
+    }
+  }
+  clear() {
+    this._cache.clear();
+  }
+};
+var FlagStats = class {
+  cacheHits;
+  cacheMisses;
+  constructor(cacheHits, cacheMisses) {
+    this.cacheHits = cacheHits;
+    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 = [];
+  observe(contexts) {
+    for (const ctx of contexts) {
+      const cacheKey = `${ctx.type}:${ctx.key}`;
+      if (!this._seen.has(cacheKey)) {
+        if (this._seen.size >= CONTEXT_REGISTRATION_LRU_SIZE) {
+          const firstKey = this._seen.keys().next().value;
+          if (firstKey !== void 0) {
+            this._seen.delete(firstKey);
+          }
+        }
+        this._seen.set(cacheKey, ctx.attributes);
+        this._pending.push({
+          id: `${ctx.type}:${ctx.key}`,
+          name: ctx.name ?? ctx.key,
+          attributes: { ...ctx.attributes }
+        });
+      }
+    }
+  }
+  drain() {
+    const batch = this._pending;
+    this._pending = [];
+    return batch;
+  }
+  get pendingCount() {
+    return this._pending.length;
+  }
+};
+var FlagsClient = class {
+  /** @internal */
+  _apiKey;
+  /** @internal */
+  _baseUrl = FLAGS_BASE_URL;
+  /** @internal */
+  _http;
+  /** @internal */
+  _transport;
+  // Runtime state
+  _environment = null;
+  _flagStore = {};
+  _connected = false;
+  _cache = new ResolutionCache();
+  _contextProvider = null;
+  _contextBuffer = new ContextRegistrationBuffer();
+  _handles = {};
+  _globalListeners = [];
+  // Shared WebSocket (set during connect)
+  _wsManager = null;
+  _ensureWs;
+  /** @internal — set by SmplClient after construction. */
+  _parent = null;
+  /** @internal */
+  constructor(apiKey, ensureWs, timeout) {
+    this._apiKey = apiKey;
+    this._ensureWs = ensureWs;
+    const ms = timeout ?? 3e4;
+    this._http = createClient2({
+      baseUrl: FLAGS_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);
+        }
+      }
+    });
+    this._transport = new Transport({ apiKey, timeout: ms });
+  }
+  // ------------------------------------------------------------------
+  // Management methods
+  // ------------------------------------------------------------------
+  /** Create a flag. */
+  async create(key, options) {
+    let values = options.values;
+    if (values === void 0 && options.type === "BOOLEAN") {
+      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);
+  }
+  /** Fetch a flag by UUID. */
+  async get(flagId) {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/flags/{id}", {
+        params: { path: { id: flagId } }
+      });
+      if (result.error !== void 0) await checkError2(result.response, `Flag ${flagId} 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);
+  }
+  /** List all flags. */
+  async list() {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/flags", {});
+      if (result.error !== void 0) await checkError2(result.response, "Failed to list flags");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError2(err);
+    }
+    if (!data) return [];
+    return data.data.map((r) => this._resourceToModel(r));
+  }
+  /** Delete a flag by UUID. */
+  async delete(flagId) {
+    try {
+      const result = await this._http.DELETE("/api/v1/flags/{id}", {
+        params: { path: { id: flagId } }
+      });
+      if (result.error !== void 0 && result.response.status !== 204)
+        await checkError2(result.response, `Failed to delete flag ${flagId}`);
+    } catch (err) {
+      wrapFetchError2(err);
+    }
+  }
+  /**
+   * Internal: PUT a full flag update.
+   * Called by {@link Flag} instance methods.
+   * @internal
+   */
+  async _updateFlag(options) {
+    const { flag } = options;
+    const body = {
+      data: {
+        type: "flag",
+        attributes: {
+          key: flag.key,
+          name: options.name !== void 0 ? options.name : flag.name,
+          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 } : {}
+        }
+      }
+    };
+    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}`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError2(err);
+    }
+    if (!data || !data.data) throw new SmplValidationError(`Failed to update flag ${flag.id}`);
+    return this._resourceToModel(data.data);
+  }
+  // ------------------------------------------------------------------
+  // Context type management (direct HTTP — not in generated spec)
+  // ------------------------------------------------------------------
+  /** Create a context type. */
+  async createContextType(key, options) {
+    const resp = await this._transport.post(`${APP_BASE_URL}/api/v1/context_types`, {
+      data: { type: "context_type", attributes: { key, name: options.name } }
+    });
+    const data = resp.data ?? {};
+    return this._parseContextType(data);
+  }
+  /** Update a context type (merge attributes). */
+  async updateContextType(ctId, options) {
+    const resp = await this._transport.put(`${APP_BASE_URL}/api/v1/context_types/${ctId}`, {
+      data: { type: "context_type", attributes: { attributes: options.attributes } }
+    });
+    const data = resp.data ?? {};
+    return this._parseContextType(data);
+  }
+  /** List all context types. */
+  async listContextTypes() {
+    const resp = await this._transport.get(`${APP_BASE_URL}/api/v1/context_types`);
+    const items = resp.data ?? [];
+    return items.map((item) => this._parseContextType(item));
+  }
+  /** Delete a context type. */
+  async deleteContextType(ctId) {
+    await this._transport.delete(`${APP_BASE_URL}/api/v1/context_types/${ctId}`);
+  }
+  /** List context instances filtered by context type key. */
+  async listContexts(options) {
+    const resp = await this._transport.get(`${APP_BASE_URL}/api/v1/contexts`, {
+      "filter[context_type]": options.contextTypeKey
+    });
+    return resp.data ?? [];
+  }
+  // ------------------------------------------------------------------
+  // Runtime: typed flag handles
+  // ------------------------------------------------------------------
+  /** Declare a boolean flag handle. */
+  boolFlag(key, defaultValue) {
+    const handle = new BoolFlagHandle(this, key, defaultValue);
+    this._handles[key] = handle;
+    return handle;
+  }
+  /** Declare a string flag handle. */
+  stringFlag(key, defaultValue) {
+    const handle = new StringFlagHandle(this, key, defaultValue);
+    this._handles[key] = handle;
+    return handle;
+  }
+  /** Declare a numeric flag handle. */
+  numberFlag(key, defaultValue) {
+    const handle = new NumberFlagHandle(this, key, defaultValue);
+    this._handles[key] = handle;
+    return handle;
+  }
+  /** Declare a JSON flag handle. */
+  jsonFlag(key, defaultValue) {
+    const handle = new JsonFlagHandle(this, key, defaultValue);
+    this._handles[key] = handle;
+    return handle;
+  }
+  // ------------------------------------------------------------------
+  // Runtime: context provider
+  // ------------------------------------------------------------------
+  /**
+   * Register a context provider function.
+   *
+   * Called on every `handle.get()` to supply the current evaluation
+   * context. Can also be used as a decorator:
+   *
+   * ```typescript
+   * client.flags.setContextProvider(() => [
+   *   new Context("user", userId, { plan: userPlan }),
+   * ]);
+   * ```
+   */
+  setContextProvider(fn) {
+    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
+  // ------------------------------------------------------------------
+  /**
+   * Connect to an environment: fetch flag definitions, register on
+   * shared WebSocket, enable local evaluation.
+   * @internal — called by SmplClient.connect().
+   */
+  async _connectInternal(environment) {
+    this._environment = environment;
+    await this._fetchAllFlags();
+    this._connected = true;
+    this._cache.clear();
+    this._wsManager = this._ensureWs();
+    this._wsManager.on("flag_changed", this._handleFlagChanged);
+    this._wsManager.on("flag_deleted", this._handleFlagDeleted);
+  }
+  /** Disconnect: unregister from WebSocket, flush contexts, clear state. */
+  async disconnect() {
+    if (this._wsManager !== null) {
+      this._wsManager.off("flag_changed", this._handleFlagChanged);
+      this._wsManager.off("flag_deleted", this._handleFlagDeleted);
+      this._wsManager = null;
+    }
+    await this._flushContexts();
+    this._flagStore = {};
+    this._cache.clear();
+    this._connected = false;
+    this._environment = null;
+  }
+  /** Re-fetch all flag definitions and clear cache. */
+  async refresh() {
+    await this._fetchAllFlags();
+    this._cache.clear();
+    this._fireChangeListenersAll("manual");
+  }
+  /** Return the current WebSocket connection status. */
+  connectionStatus() {
+    if (this._wsManager !== null) {
+      return this._wsManager.connectionStatus;
+    }
+    return "disconnected";
+  }
+  /** Return cache statistics. */
+  stats() {
+    return new FlagStats(this._cache.cacheHits, this._cache.cacheMisses);
+  }
+  // ------------------------------------------------------------------
+  // Runtime: change listeners
+  // ------------------------------------------------------------------
+  /** 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.
+   *
+   * ```typescript
+   * const listener = client.flags.onChange((event) => { ... });
+   * ```
+   */
+  onChange(callback) {
+    return this.onChangeAny(callback);
+  }
+  // ------------------------------------------------------------------
+  // Runtime: context registration
+  // ------------------------------------------------------------------
+  /**
+   * Explicitly register context(s) for background batch registration.
+   *
+   * Accepts a single Context or an array. Fire-and-forget — never
+   * blocks. Works before `connect()` is called.
+   */
+  register(context) {
+    if (Array.isArray(context)) {
+      this._contextBuffer.observe(context);
+    } else {
+      this._contextBuffer.observe([context]);
+    }
+  }
+  /** Flush pending context registrations to the server. */
+  async flushContexts() {
+    await this._flushContexts();
+  }
+  // ------------------------------------------------------------------
+  // Runtime: Tier 1 evaluate
+  // ------------------------------------------------------------------
+  /**
+   * 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);
+    if (this._parent?._service && !("service" in evalDict)) {
+      evalDict["service"] = { key: this._parent._service };
+    }
+    let flagDef = null;
+    if (this._connected && key in this._flagStore) {
+      flagDef = this._flagStore[key];
+    } else {
+      const flags = await this._fetchFlagsList();
+      for (const f of flags) {
+        if (f.key === key) {
+          flagDef = f;
+          break;
+        }
+      }
+    }
+    if (flagDef === null) {
+      return null;
+    }
+    return evaluateFlag(flagDef, options.environment, evalDict);
+  }
+  // ------------------------------------------------------------------
+  // Internal: evaluation
+  // ------------------------------------------------------------------
+  /** @internal */
+  _evaluateHandle(key, defaultValue, context) {
+    if (!this._connected) {
+      throw new SmplNotConnectedError("SmplClient is not connected. Call client.connect() first.");
+    }
+    let evalDict;
+    if (context !== null) {
+      evalDict = contextsToEvalDict(context);
+    } else if (this._contextProvider !== null) {
+      const contexts = this._contextProvider();
+      evalDict = contextsToEvalDict(contexts);
+      this._contextBuffer.observe(contexts);
+      if (this._contextBuffer.pendingCount >= CONTEXT_BATCH_FLUSH_SIZE) {
+        void this._flushContexts();
+      }
+    } else {
+      evalDict = {};
+    }
+    if (this._parent?._service && !("service" in evalDict)) {
+      evalDict["service"] = { key: this._parent._service };
+    }
+    const ctxHash = hashContext(evalDict);
+    const cacheKey = `${key}:${ctxHash}`;
+    const [hit, cachedValue] = this._cache.get(cacheKey);
+    if (hit) {
+      return cachedValue;
+    }
+    const flagDef = this._flagStore[key];
+    if (flagDef === void 0) {
+      this._cache.put(cacheKey, defaultValue);
+      return defaultValue;
+    }
+    let value = evaluateFlag(flagDef, this._environment, evalDict);
+    if (value === null || value === void 0) {
+      value = defaultValue;
+    }
+    this._cache.put(cacheKey, value);
+    return value;
+  }
+  // ------------------------------------------------------------------
+  // Internal: event handlers (called by SharedWebSocket)
+  // ------------------------------------------------------------------
+  _handleFlagChanged = (data) => {
+    const flagKey = data.key;
+    void this._fetchAllFlags().then(() => {
+      this._cache.clear();
+      this._fireChangeListeners(flagKey ?? null, "websocket");
+    });
+  };
+  _handleFlagDeleted = (data) => {
+    const flagKey = data.key;
+    void this._fetchAllFlags().then(() => {
+      this._cache.clear();
+      this._fireChangeListeners(flagKey ?? null, "websocket");
+    });
+  };
+  // ------------------------------------------------------------------
+  // Internal: flag store
+  // ------------------------------------------------------------------
+  async _fetchAllFlags() {
+    const flags = await this._fetchFlagsList();
+    const store = {};
+    for (const f of flags) {
+      store[f.key] = f;
+    }
+    this._flagStore = store;
+  }
+  async _fetchFlagsList() {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/flags", {});
+      if (result.error !== void 0) await checkError2(result.response, "Failed to list flags");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError2(err);
+    }
+    if (!data) return [];
+    return data.data.map((r) => this._resourceToPlainDict(r));
+  }
+  // ------------------------------------------------------------------
+  // Internal: change listeners
+  // ------------------------------------------------------------------
+  _fireChangeListeners(flagKey, source) {
+    if (flagKey) {
+      const event = new FlagChangeEvent(flagKey, source);
+      for (const cb of this._globalListeners) {
+        try {
+          cb(event);
+        } catch {
+        }
+      }
+      const handle = this._handles[flagKey];
+      if (handle) {
+        for (const cb of handle._listeners) {
+          try {
+            cb(event);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  _fireChangeListenersAll(source) {
+    for (const flagKey of Object.keys(this._flagStore)) {
+      this._fireChangeListeners(flagKey, source);
+    }
+  }
+  // ------------------------------------------------------------------
+  // Internal: context flush
+  // ------------------------------------------------------------------
+  async _flushContexts() {
+    const batch = this._contextBuffer.drain();
+    if (batch.length === 0) return;
+    try {
+      await this._transport.put(`${APP_BASE_URL}/api/v1/contexts/bulk`, {
+        contexts: batch
+      });
+    } catch {
+    }
+  }
+  // ------------------------------------------------------------------
+  // Internal: model conversion
+  // ------------------------------------------------------------------
+  _resourceToModel(resource) {
+    const attrs = resource.attributes;
+    return new Flag(this, {
+      id: resource.id ?? "",
+      key: attrs.key,
+      name: attrs.name,
+      type: attrs.type,
+      default: attrs.default,
+      values: (attrs.values ?? []).map((v) => ({ name: v.name, value: v.value })),
+      description: attrs.description ?? null,
+      environments: attrs.environments ?? {},
+      createdAt: attrs.created_at ?? null,
+      updatedAt: attrs.updated_at ?? null
+    });
+  }
+  _resourceToPlainDict(resource) {
+    const attrs = resource.attributes;
+    return {
+      key: attrs.key,
+      name: attrs.name,
+      type: attrs.type,
+      default: attrs.default,
+      values: (attrs.values ?? []).map((v) => ({ name: v.name, value: v.value })),
+      description: attrs.description ?? null,
+      environments: attrs.environments ?? {}
+    };
+  }
+  _parseContextType(data) {
+    const attrs = data.attributes ?? {};
+    return new ContextType({
+      id: data.id ?? "",
+      key: attrs.key ?? "",
+      name: attrs.name ?? "",
+      attributes: attrs.attributes ?? {}
+    });
+  }
+};
+
+// src/ws.ts
+import WebSocket from "ws";
+var BACKOFF_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 32e3, 6e4];
+var SharedWebSocket = class {
+  _appBaseUrl;
+  _apiKey;
+  _listeners = /* @__PURE__ */ new Map();
+  _connectionStatus = "disconnected";
+  _closed = false;
+  _ws = null;
+  _reconnectTimer = null;
+  _backoffIndex = 0;
+  constructor(appBaseUrl, apiKey) {
+    this._appBaseUrl = appBaseUrl;
+    this._apiKey = apiKey;
+  }
+  // ------------------------------------------------------------------
+  // Listener registration
+  // ------------------------------------------------------------------
+  /** Register a listener for a specific event type. */
+  on(eventName, callback) {
+    if (!this._listeners.has(eventName)) {
+      this._listeners.set(eventName, []);
+    }
+    this._listeners.get(eventName).push(callback);
+  }
+  /** Unregister a listener for a specific event type. */
+  off(eventName, callback) {
+    const list = this._listeners.get(eventName);
+    if (list) {
+      const idx = list.indexOf(callback);
+      if (idx !== -1) {
+        list.splice(idx, 1);
+      }
+    }
+  }
+  _dispatch(eventName, data) {
+    const callbacks = this._listeners.get(eventName);
+    if (callbacks) {
+      for (const cb of [...callbacks]) {
+        try {
+          cb(data);
+        } catch {
+        }
+      }
+    }
+  }
+  // ------------------------------------------------------------------
+  // Connection status
+  // ------------------------------------------------------------------
+  get connectionStatus() {
+    return this._connectionStatus;
+  }
+  // ------------------------------------------------------------------
+  // Lifecycle
+  // ------------------------------------------------------------------
+  /** Start the WebSocket connection. */
+  start() {
+    this._closed = false;
+    this._connect();
+  }
+  /** Stop the WebSocket connection. */
+  stop() {
+    this._closed = true;
+    this._connectionStatus = "disconnected";
+    if (this._reconnectTimer !== null) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    if (this._ws !== null) {
+      this._ws.close();
+      this._ws = null;
+    }
+  }
+  // ------------------------------------------------------------------
+  // Connection internals
+  // ------------------------------------------------------------------
+  _buildWsUrl() {
+    let url = this._appBaseUrl;
+    if (url.startsWith("https://")) {
+      url = "wss://" + url.slice("https://".length);
+    } else if (url.startsWith("http://")) {
+      url = "ws://" + url.slice("http://".length);
+    } else {
+      url = "wss://" + url;
+    }
+    url = url.replace(/\/$/, "");
+    return `${url}/api/ws/v1/events?api_key=${this._apiKey}`;
+  }
+  _connect() {
+    if (this._closed) return;
+    this._connectionStatus = "connecting";
+    const wsUrl = this._buildWsUrl();
+    try {
+      const ws = new WebSocket(wsUrl);
+      this._ws = ws;
+      ws.on("open", () => {
+        if (this._closed) {
+          ws.close();
+          return;
+        }
+      });
+      ws.on("message", (data) => {
+        try {
+          const raw = String(data);
+          if (raw === "ping") {
+            ws.send("pong");
+            return;
+          }
+          const msg = JSON.parse(raw);
+          if (msg.type === "connected") {
+            this._backoffIndex = 0;
+            this._connectionStatus = "connected";
+            return;
+          }
+          if (msg.type === "error") {
+            return;
+          }
+          const eventName = msg.event;
+          if (eventName) {
+            this._dispatch(eventName, msg);
+          }
+        } catch {
+        }
+      });
+      ws.on("close", () => {
+        if (!this._closed) {
+          this._connectionStatus = "disconnected";
+          this._scheduleReconnect();
+        }
+      });
+      ws.on("error", () => {
+      });
+    } catch {
+      if (!this._closed) {
+        this._scheduleReconnect();
+      }
+    }
+  }
+  _scheduleReconnect() {
+    if (this._closed) return;
+    const delay = BACKOFF_MS[Math.min(this._backoffIndex, BACKOFF_MS.length - 1)];
+    this._backoffIndex++;
+    this._connectionStatus = "connecting";
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this._connect();
+    }, delay);
+  }
+};
+
+// src/resolve.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var NO_API_KEY_MESSAGE = "No API key provided. Set one of:\n  1. Pass apiKey to the constructor\n  2. Set the SMPLKIT_API_KEY environment variable\n  3. Create a ~/.smplkit file with:\n     [default]\n     api_key = your_key_here";
+function resolveApiKey(explicit) {
+  if (explicit) return explicit;
+  const envVal = process.env.SMPLKIT_API_KEY;
+  if (envVal) return envVal;
+  const configPath = join(homedir(), ".smplkit");
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    let inDefaultSection = false;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) continue;
+      if (trimmed.startsWith("[")) {
+        inDefaultSection = trimmed.toLowerCase() === "[default]";
+        continue;
+      }
+      if (inDefaultSection && trimmed.startsWith("api_key")) {
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex !== -1) {
+          const value = trimmed.slice(eqIndex + 1).trim();
+          if (value) return value;
+        }
+      }
+    }
+  } catch {
+  }
+  throw new SmplError(NO_API_KEY_MESSAGE);
+}
+
+// src/client.ts
+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 SmplClient = class {
+  /** Client for config management-plane operations. */
+  config;
+  /** Client for flags management and runtime operations. */
+  flags;
+  _wsManager = null;
+  _apiKey;
+  /** @internal */
+  _environment;
+  /** @internal */
+  _service;
+  _connected = false;
+  _timeout;
+  constructor(options = {}) {
+    const apiKey = resolveApiKey(options.apiKey);
+    this._apiKey = apiKey;
+    const environment = options.environment || process.env.SMPLKIT_ENVIRONMENT;
+    if (!environment) {
+      throw new SmplError(NO_ENVIRONMENT_MESSAGE);
+    }
+    this._environment = environment;
+    this._service = options.service || process.env.SMPLKIT_SERVICE || null;
+    this._timeout = options.timeout ?? 3e4;
+    this.config = new ConfigClient(apiKey, this._timeout);
+    this.flags = new FlagsClient(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;
+    if (this._service) {
+      await this._registerServiceContext();
+    }
+    await this.flags._connectInternal(this._environment);
+    await this.config._connectInternal(this._environment);
+    this._connected = true;
+  }
+  /** @internal */
+  async _registerServiceContext() {
+    try {
+      await fetch(`${APP_BASE_URL2}/api/v1/contexts/bulk`, {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${this._apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          contexts: [
+            {
+              type: "service",
+              key: this._service,
+              attributes: { name: this._service }
+            }
+          ]
+        })
+      });
+    } catch {
+    }
+  }
+  /** Lazily create and start the shared WebSocket. @internal */
+  _ensureWs() {
+    if (this._wsManager === null) {
+      this._wsManager = new SharedWebSocket(APP_BASE_URL2, this._apiKey);
+      this._wsManager.start();
+    }
+    return this._wsManager;
+  }
+  /** Close the shared WebSocket and release resources. */
+  close() {
+    if (this._wsManager !== null) {
+      this._wsManager.stop();
+      this._wsManager = null;
+    }
+  }
+};
+
+// src/config/runtime.ts
+var ConfigRuntime = class {
+  _cache;
+  _chain;
+  _fetchCount;
+  _lastFetchAt;
+  _closed = false;
+  _listeners = [];
+  _environment;
+  _fetchChain;
+  _sharedWs = null;
+  /** @internal */
+  constructor(options) {
+    this._environment = options.environment;
+    this._fetchChain = options.fetchChain;
+    this._chain = options.chain;
+    this._cache = resolveChain(options.chain, options.environment);
+    this._fetchCount = options.chain.length;
+    this._lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (options.sharedWs) {
+      this._sharedWs = options.sharedWs;
+      this._sharedWs.on("config_changed", this._handleConfigChanged);
+      this._sharedWs.on("config_deleted", this._handleConfigDeleted);
+    }
+  }
+  // ---- Value access (synchronous, local cache) ----
+  /**
+   * Return the resolved value for `key`, or `defaultValue` if absent.
+   *
+   * @param key - The config key to look up.
+   * @param defaultValue - Returned when the key is not present (default: null).
+   */
+  get(key, defaultValue = null) {
+    return key in this._cache ? this._cache[key] : defaultValue;
+  }
+  /**
+   * Return the value as a string, or `defaultValue` if absent or not a string.
+   */
+  getString(key, defaultValue = null) {
+    const value = this._cache[key];
+    return typeof value === "string" ? value : defaultValue;
+  }
+  /**
+   * Return the value as a number, or `defaultValue` if absent or not a number.
+   */
+  getInt(key, defaultValue = null) {
+    const value = this._cache[key];
+    return typeof value === "number" ? value : defaultValue;
+  }
+  /**
+   * Return the value as a boolean, or `defaultValue` if absent or not a boolean.
+   */
+  getBool(key, defaultValue = null) {
+    const value = this._cache[key];
+    return typeof value === "boolean" ? value : defaultValue;
+  }
+  /**
+   * Return whether `key` is present in the resolved configuration.
+   */
+  exists(key) {
+    return key in this._cache;
+  }
+  /**
+   * Return a shallow copy of the full resolved configuration.
+   */
+  getAll() {
+    return { ...this._cache };
+  }
+  // ---- Change listeners ----
+  /**
+   * Register a listener that fires when a config value changes.
+   *
+   * @param callback - Called with a {@link ConfigChangeEvent} on each change.
+   * @param options.key - If provided, the listener fires only for this key.
+   *   If omitted, the listener fires for all changes.
+   */
+  onChange(callback, options) {
+    this._listeners.push({
+      callback,
+      key: options?.key ?? null
+    });
+  }
+  // ---- Diagnostics ----
+  /**
+   * Return diagnostic statistics for this runtime.
+   */
+  stats() {
+    return {
+      fetchCount: this._fetchCount,
+      lastFetchAt: this._lastFetchAt
+    };
+  }
+  /**
+   * Return the current WebSocket connection status.
+   */
+  connectionStatus() {
+    if (this._sharedWs) {
+      return this._sharedWs.connectionStatus;
+    }
+    return "disconnected";
+  }
+  // ---- Lifecycle ----
+  /**
+   * Force a manual refresh of the cached configuration.
+   *
+   * Re-fetches the full config chain via HTTP, re-resolves values, updates
+   * the local cache, and fires listeners for any detected changes.
+   *
+   * @throws {Error} If no `fetchChain` function was provided on construction.
+   */
+  async refresh() {
+    if (!this._fetchChain) {
+      throw new Error("No fetchChain function provided; cannot refresh.");
+    }
+    const newChain = await this._fetchChain();
+    const oldCache = this._cache;
+    this._chain = newChain;
+    this._cache = resolveChain(newChain, this._environment);
+    this._fetchCount += newChain.length;
+    this._lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+    this._diffAndFire(oldCache, this._cache, "manual");
+  }
+  /**
+   * Close the runtime connection.
+   *
+   * Unregisters from the shared WebSocket. Safe to call multiple times.
+   */
+  async close() {
+    this._closed = true;
+    if (this._sharedWs !== null) {
+      this._sharedWs.off("config_changed", this._handleConfigChanged);
+      this._sharedWs.off("config_deleted", this._handleConfigDeleted);
+      this._sharedWs = null;
+    }
+  }
+  /**
+   * Async dispose support for `await using` (TypeScript 5.2+).
+   */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // ---- Shared WebSocket event handlers ----
+  _handleConfigChanged = (data) => {
+    if (this._closed) return;
+    const configId = data.config_id;
+    const changes = data.changes;
+    if (configId && changes) {
+      this._applyChanges(configId, changes);
+    } else if (this._fetchChain) {
+      void this._fetchChain().then((newChain) => {
+        const oldCache = this._cache;
+        this._chain = newChain;
+        this._cache = resolveChain(newChain, this._environment);
+        this._fetchCount += newChain.length;
+        this._lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+        this._diffAndFire(oldCache, this._cache, "websocket");
+      }).catch(() => {
+      });
+    }
+  };
+  _handleConfigDeleted = (_data) => {
+    this._closed = true;
+    void this.close();
+  };
+  _applyChanges(configId, changes) {
+    const chainEntry = this._chain.find((c) => c.id === configId);
+    if (!chainEntry) return;
+    for (const change of changes) {
+      const { key, new_value } = change;
+      const envEntry = chainEntry.environments[this._environment] !== void 0 && chainEntry.environments[this._environment] !== null ? chainEntry.environments[this._environment] : null;
+      const envValues = envEntry !== null && typeof envEntry === "object" ? envEntry.values ?? {} : null;
+      if (new_value === null || new_value === void 0) {
+        delete chainEntry.items[key];
+        if (envValues) delete envValues[key];
+      } else if (envValues && key in envValues) {
+        envValues[key] = new_value;
+      } else if (key in chainEntry.items) {
+        chainEntry.items[key] = new_value;
+      } else {
+        chainEntry.items[key] = new_value;
+      }
+    }
+    const oldCache = this._cache;
+    this._cache = resolveChain(this._chain, this._environment);
+    this._diffAndFire(oldCache, this._cache, "websocket");
+  }
+  _diffAndFire(oldCache, newCache, source) {
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldCache), ...Object.keys(newCache)]);
+    for (const key of allKeys) {
+      const oldVal = key in oldCache ? oldCache[key] : null;
+      const newVal = key in newCache ? newCache[key] : null;
+      if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+        const event = { key, oldValue: oldVal, newValue: newVal, source };
+        this._fireListeners(event);
+      }
+    }
+  }
+  _fireListeners(event) {
+    for (const listener of this._listeners) {
+      if (listener.key === null || listener.key === event.key) {
+        try {
+          listener.callback(event);
+        } catch {
+        }
+      }
+    }
+  }
+};
+
+// src/flags/types.ts
+var Context = class {
+  type;
+  key;
+  name;
+  attributes;
+  constructor(type, key, attributes, options) {
+    this.type = type;
+    this.key = key;
+    this.name = options?.name ?? null;
+    this.attributes = { ...attributes ?? {} };
+  }
+  toString() {
+    return `Context(type=${this.type}, key=${this.key}, name=${this.name})`;
+  }
+};
+var Rule = class {
+  _description;
+  _conditions = [];
+  _value = null;
+  _environment = null;
+  constructor(description) {
+    this._description = description;
+  }
+  /** Tag this rule with an environment key (used by `addRule`). */
+  environment(envKey) {
+    this._environment = envKey;
+    return this;
+  }
+  /** Add a condition.  Multiple calls are AND'd. */
+  when(variable, op, value) {
+    if (op === "contains") {
+      this._conditions.push({ in: [value, { var: variable }] });
+    } else {
+      this._conditions.push({ [op]: [{ var: variable }, value] });
+    }
+    return this;
+  }
+  /** Set the value returned when this rule matches. */
+  serve(value) {
+    this._value = value;
+    return this;
+  }
+  /** Finalize and return the rule as a plain object. */
+  build() {
+    let logic;
+    if (this._conditions.length === 1) {
+      logic = this._conditions[0];
+    } else if (this._conditions.length > 1) {
+      logic = { and: this._conditions };
+    } else {
+      logic = {};
+    }
+    const result = {
+      description: this._description,
+      logic,
+      value: this._value
+    };
+    if (this._environment !== null) {
+      result.environment = this._environment;
+    }
+    return result;
   }
 };
 export {
+  BoolFlagHandle,
   Config,
   ConfigClient,
   ConfigRuntime,
+  Context,
+  ContextType,
+  Flag,
+  FlagChangeEvent,
+  FlagStats,
+  FlagsClient,
+  JsonFlagHandle,
+  NumberFlagHandle,
+  Rule,
+  SharedWebSocket,
   SmplClient,
   SmplConflictError,
   SmplConnectionError,
   SmplError,
+  SmplNotConnectedError,
   SmplNotFoundError,
   SmplTimeoutError,
-  SmplValidationError
+  SmplValidationError,
+  StringFlagHandle
 };
 //# sourceMappingURL=index.js.map