@smplkit/sdk 1.2.0 → 1.2.2

package/dist/index.js

@@ -1,7 +1,3 @@
-import {
-  ConfigRuntime
-} from "./chunk-2VYY5OMH.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,46 +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-MIIY5ZNG.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),
-      sharedWs: this._client._getSharedWs ? this._client._getSharedWs() : null
-    });
-  }
   /**
    * Walk the parent chain and return config data objects, child-to-root.
    * @internal
@@ -367,6 +358,10 @@ var ConfigClient = class {
   _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;
@@ -464,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.
    *
@@ -1051,6 +1084,8 @@ var FlagsClient = class {
   // Shared WebSocket (set during connect)
   _wsManager = null;
   _ensureWs;
+  /** @internal — set by SmplClient after construction. */
+  _parent = null;
   /** @internal */
   constructor(apiKey, ensureWs, timeout) {
     this._apiKey = apiKey;
@@ -1289,8 +1324,9 @@ var FlagsClient = class {
   /**
    * Connect to an environment: fetch flag definitions, register on
    * shared WebSocket, enable local evaluation.
+   * @internal — called by SmplClient.connect().
    */
-  async connect(environment, _options) {
+  async _connectInternal(environment) {
     this._environment = environment;
     await this._fetchAllFlags();
     this._connected = true;
@@ -1377,6 +1413,9 @@ var FlagsClient = class {
    */
   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];
@@ -1400,7 +1439,7 @@ var FlagsClient = class {
   /** @internal */
   _evaluateHandle(key, defaultValue, context) {
     if (!this._connected) {
-      return defaultValue;
+      throw new SmplNotConnectedError("SmplClient is not connected. Call client.connect() first.");
     }
     let evalDict;
     if (context !== null) {
@@ -1415,6 +1454,9 @@ var FlagsClient = class {
     } 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);
@@ -1741,6 +1783,7 @@ function resolveApiKey(explicit) {
 
 // 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;
@@ -1748,12 +1791,66 @@ var SmplClient = class {
   flags;
   _wsManager = null;
   _apiKey;
+  /** @internal */
+  _environment;
+  /** @internal */
+  _service;
+  _connected = false;
+  _timeout;
   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);
+    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() {
@@ -1772,6 +1869,215 @@ var SmplClient = class {
   }
 };
 
+// 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;
@@ -1855,6 +2161,7 @@ export {
   SmplConflictError,
   SmplConnectionError,
   SmplError,
+  SmplNotConnectedError,
   SmplNotFoundError,
   SmplTimeoutError,
   SmplValidationError,