@smplkit/sdk 1.1.9 → 1.2.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   ConfigRuntime
-} from "./chunk-RF6LYU4V.js";
+} from "./chunk-2VYY5OMH.js";
 
 // src/config/client.ts
 import createClient from "openapi-fetch";
@@ -207,7 +207,7 @@ var Config = class {
    * @param options.timeout - Milliseconds to wait for the initial fetch.
    */
   async connect(environment, options) {
-    const { ConfigRuntime: ConfigRuntime2 } = await import("./runtime-FT745HBO.js");
+    const { ConfigRuntime: ConfigRuntime2 } = await import("./runtime-MIIY5ZNG.js");
     const timeout = options?.timeout ?? 3e4;
     const chain = await this._buildChain(timeout);
     return new ConfigRuntime2({
@@ -217,7 +217,8 @@ var Config = class {
       chain,
       apiKey: this._client._apiKey,
       baseUrl: this._client._baseUrl,
-      fetchChain: () => this._buildChain(timeout)
+      fetchChain: () => this._buildChain(timeout),
+      sharedWs: this._client._getSharedWs ? this._client._getSharedWs() : null
     });
   }
   /**
@@ -364,6 +365,8 @@ var ConfigClient = class {
   _baseUrl = BASE_URL;
   /** @internal */
   _http;
+  /** @internal — returns the shared WebSocket for real-time updates. */
+  _getSharedWs;
   /** @internal */
   constructor(apiKey, timeout) {
     this._apiKey = apiKey;
@@ -528,6 +531,1181 @@ var ConfigClient = class {
   }
 };
 
+// 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 (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);
+    }
+  }
+  /**
+   * 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/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 */
+  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.
+   */
+  async connect(environment, _options) {
+    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);
+    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) {
+      return defaultValue;
+    }
+    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 = {};
+    }
+    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";
@@ -562,24 +1740,124 @@ function resolveApiKey(explicit) {
 }
 
 // src/client.ts
+var APP_BASE_URL2 = "https://app.smplkit.com";
 var SmplClient = class {
   /** Client for config management-plane operations. */
   config;
+  /** Client for flags management and runtime operations. */
+  flags;
+  _wsManager = null;
+  _apiKey;
   constructor(options = {}) {
     const apiKey = resolveApiKey(options.apiKey);
+    this._apiKey = apiKey;
     this.config = new ConfigClient(apiKey, options.timeout);
+    this.flags = new FlagsClient(apiKey, () => this._ensureWs(), options.timeout);
+    this.config._getSharedWs = () => this._ensureWs();
+  }
+  /** 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/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,
   SmplNotFoundError,
   SmplTimeoutError,
-  SmplValidationError
+  SmplValidationError,
+  StringFlagHandle
 };
 //# sourceMappingURL=index.js.map