@replanejs/sdk 0.5.6

package/dist/index.cjs

@@ -0,0 +1,565 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var src_exports = {};
+__export(src_exports, {
+  ReplaneError: () => ReplaneError,
+  createInMemoryReplaneClient: () => createInMemoryReplaneClient,
+  createReplaneClient: () => createReplaneClient
+});
+module.exports = __toCommonJS(src_exports);
+const SUPPORTED_REPLICATION_STREAM_RECORD_TYPES = Object.keys({
+  config_change: true,
+  init: true
+});
+function fnv1a32(input) {
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(input);
+  let hash = 2166136261 >>> 0;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash >>> 0;
+}
+function fnv1a32ToUnit(input) {
+  const h = fnv1a32(input);
+  return h / 2 ** 32;
+}
+function evaluateOverrides(baseValue, overrides, context, logger) {
+  for (const override of overrides) {
+    let overrideResult = "matched";
+    const results = override.conditions.map((c) => evaluateCondition(c, context, logger));
+    if (results.some((r) => r === "not_matched")) {
+      overrideResult = "not_matched";
+    } else if (results.some((r) => r === "unknown")) {
+      overrideResult = "unknown";
+    }
+    if (overrideResult === "matched") {
+      return override.value;
+    }
+  }
+  return baseValue;
+}
+function evaluateCondition(condition, context, logger) {
+  const operator = condition.operator;
+  if (operator === "and") {
+    const results = condition.conditions.map((c) => evaluateCondition(c, context, logger));
+    if (results.some((r) => r === "not_matched")) return "not_matched";
+    if (results.some((r) => r === "unknown")) return "unknown";
+    return "matched";
+  }
+  if (operator === "or") {
+    const results = condition.conditions.map((c) => evaluateCondition(c, context, logger));
+    if (results.some((r) => r === "matched")) return "matched";
+    if (results.some((r) => r === "unknown")) return "unknown";
+    return "not_matched";
+  }
+  if (operator === "not") {
+    const result = evaluateCondition(condition.condition, context, logger);
+    if (result === "matched") return "not_matched";
+    if (result === "not_matched") return "matched";
+    return "unknown";
+  }
+  if (operator === "segmentation") {
+    const contextValue2 = context[condition.property];
+    if (contextValue2 === void 0 || contextValue2 === null) {
+      return "unknown";
+    }
+    const hashInput = String(contextValue2) + condition.seed;
+    const unitValue = fnv1a32ToUnit(hashInput);
+    return unitValue >= condition.fromPercentage / 100 && unitValue < condition.toPercentage / 100 ? "matched" : "not_matched";
+  }
+  const property = condition.property;
+  const contextValue = context[property];
+  const expectedValue = condition.value;
+  if (contextValue === void 0) {
+    return "unknown";
+  }
+  const castedValue = castToContextType(expectedValue, contextValue);
+  switch (operator) {
+    case "equals":
+      return contextValue === castedValue ? "matched" : "not_matched";
+    case "in":
+      if (!Array.isArray(castedValue)) return "unknown";
+      return castedValue.includes(contextValue) ? "matched" : "not_matched";
+    case "not_in":
+      if (!Array.isArray(castedValue)) return "unknown";
+      return !castedValue.includes(contextValue) ? "matched" : "not_matched";
+    case "less_than":
+      if (typeof contextValue === "number" && typeof castedValue === "number") {
+        return contextValue < castedValue ? "matched" : "not_matched";
+      }
+      if (typeof contextValue === "string" && typeof castedValue === "string") {
+        return contextValue < castedValue ? "matched" : "not_matched";
+      }
+      return "not_matched";
+    case "less_than_or_equal":
+      if (typeof contextValue === "number" && typeof castedValue === "number") {
+        return contextValue <= castedValue ? "matched" : "not_matched";
+      }
+      if (typeof contextValue === "string" && typeof castedValue === "string") {
+        return contextValue <= castedValue ? "matched" : "not_matched";
+      }
+      return "not_matched";
+    case "greater_than":
+      if (typeof contextValue === "number" && typeof castedValue === "number") {
+        return contextValue > castedValue ? "matched" : "not_matched";
+      }
+      if (typeof contextValue === "string" && typeof castedValue === "string") {
+        return contextValue > castedValue ? "matched" : "not_matched";
+      }
+      return "not_matched";
+    case "greater_than_or_equal":
+      if (typeof contextValue === "number" && typeof castedValue === "number") {
+        return contextValue >= castedValue ? "matched" : "not_matched";
+      }
+      if (typeof contextValue === "string" && typeof castedValue === "string") {
+        return contextValue >= castedValue ? "matched" : "not_matched";
+      }
+      return "not_matched";
+    default:
+      warnNever(operator, logger, `Unexpected operator: ${operator}`);
+      return "unknown";
+  }
+}
+function warnNever(value, logger, message) {
+  logger.warn(message, { value });
+}
+function castToContextType(expectedValue, contextValue) {
+  if (typeof contextValue === "number") {
+    if (typeof expectedValue === "string") {
+      const num = Number(expectedValue);
+      return isNaN(num) ? expectedValue : num;
+    }
+    return expectedValue;
+  }
+  if (typeof contextValue === "boolean") {
+    if (typeof expectedValue === "string") {
+      if (expectedValue === "true") return true;
+      if (expectedValue === "false") return false;
+    }
+    if (typeof expectedValue === "number") {
+      return expectedValue !== 0;
+    }
+    return expectedValue;
+  }
+  if (typeof contextValue === "string") {
+    if (typeof expectedValue === "number" || typeof expectedValue === "boolean") {
+      return String(expectedValue);
+    }
+    return expectedValue;
+  }
+  return expectedValue;
+}
+async function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryDelay(averageDelay) {
+  const jitter = averageDelay / 5;
+  const delayMs = averageDelay + Math.random() * jitter - jitter / 2;
+  await delay(delayMs);
+}
+class ReplaneRemoteStorage {
+  closeController = new AbortController();
+  // never throws
+  async *startReplicationStream(options) {
+    const { signal, cleanUpSignals } = combineAbortSignals([
+      this.closeController.signal,
+      options.signal
+    ]);
+    try {
+      let failedAttempts = 0;
+      while (!signal.aborted) {
+        try {
+          for await (const event of this.startReplicationStreamImpl({
+            ...options,
+            signal,
+            onConnect: () => {
+              failedAttempts = 0;
+            }
+          })) {
+            yield event;
+          }
+        } catch (error) {
+          failedAttempts++;
+          const retryDelayMs = Math.min(options.retryDelayMs * 2 ** (failedAttempts - 1), 1e4);
+          if (!signal.aborted) {
+            options.logger.error(
+              `Failed to fetch project events, retrying in ${retryDelayMs}ms...`,
+              error
+            );
+            await retryDelay(retryDelayMs);
+          }
+        }
+      }
+    } finally {
+      cleanUpSignals();
+    }
+  }
+  async *startReplicationStreamImpl(options) {
+    const rawEvents = fetchSse({
+      fetchFn: options.fetchFn,
+      headers: {
+        Authorization: this.getAuthHeader(options),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(options.getBody()),
+      timeoutMs: options.requestTimeoutMs,
+      method: "POST",
+      signal: options.signal,
+      url: this.getApiEndpoint(`/sdk/v1/replication/stream`, options),
+      onConnect: options.onConnect
+    });
+    for await (const rawEvent of rawEvents) {
+      const event = JSON.parse(rawEvent);
+      if (typeof event === "object" && event !== null && "type" in event && typeof event.type === "string" && SUPPORTED_REPLICATION_STREAM_RECORD_TYPES.includes(event.type)) {
+        yield event;
+      }
+    }
+  }
+  close() {
+    this.closeController.abort();
+  }
+  getAuthHeader(options) {
+    return `Bearer ${options.sdkKey}`;
+  }
+  getApiEndpoint(path, options) {
+    return `${options.baseUrl}/api${path}`;
+  }
+}
+var ReplaneErrorCode = /* @__PURE__ */ ((ReplaneErrorCode2) => {
+  ReplaneErrorCode2["NotFound"] = "not_found";
+  ReplaneErrorCode2["Timeout"] = "timeout";
+  ReplaneErrorCode2["NetworkError"] = "network_error";
+  ReplaneErrorCode2["AuthError"] = "auth_error";
+  ReplaneErrorCode2["Forbidden"] = "forbidden";
+  ReplaneErrorCode2["ServerError"] = "server_error";
+  ReplaneErrorCode2["ClientError"] = "client_error";
+  ReplaneErrorCode2["Closed"] = "closed";
+  ReplaneErrorCode2["NotInitialized"] = "not_initialized";
+  ReplaneErrorCode2["Unknown"] = "unknown";
+  return ReplaneErrorCode2;
+})(ReplaneErrorCode || {});
+class ReplaneError extends Error {
+  code;
+  constructor(params) {
+    super(params.message, { cause: params.cause });
+    this.name = "ReplaneError";
+    this.code = params.code;
+  }
+}
+async function createReplaneClient(sdkOptions) {
+  const storage = new ReplaneRemoteStorage();
+  return await _createReplaneClient(toFinalOptions(sdkOptions), storage);
+}
+function createInMemoryReplaneClient(initialData) {
+  return {
+    getConfig: (configName) => {
+      const config = initialData[configName];
+      if (config === void 0) {
+        throw new ReplaneError({
+          message: `Config not found: ${String(configName)}`,
+          code: "not_found" /* NotFound */
+        });
+      }
+      return config;
+    },
+    close: () => {
+    }
+  };
+}
+async function _createReplaneClient(sdkOptions, storage) {
+  if (!sdkOptions.sdkKey) throw new Error("SDK key is required");
+  let configs = new Map(
+    sdkOptions.fallbacks.map((config) => [config.name, config])
+  );
+  const clientReady = new Deferred();
+  (async () => {
+    try {
+      const replicationStream = storage.startReplicationStream({
+        ...sdkOptions,
+        getBody: () => ({
+          currentConfigs: [...configs.values()].map((config) => ({
+            name: config.name,
+            overrides: config.overrides,
+            version: config.version,
+            value: config.value
+          })),
+          requiredConfigs: sdkOptions.requiredConfigs
+        })
+      });
+      for await (const event of replicationStream) {
+        if (event.type === "init") {
+          configs = new Map(event.configs.map((config) => [config.name, config]));
+          clientReady.resolve();
+        } else if (event.type === "config_change") {
+          configs.set(event.configName, {
+            name: event.configName,
+            overrides: event.overrides,
+            version: event.version,
+            value: event.value
+          });
+        } else {
+          warnNever(event, sdkOptions.logger, "Replane: unknown event type in event stream");
+        }
+      }
+    } catch (error) {
+      sdkOptions.logger.error("Replane: error initializing client:", error);
+      clientReady.reject(error);
+    }
+  })();
+  function getConfig(configName, getConfigOptions = {}) {
+    const config = configs.get(String(configName));
+    if (config === void 0) {
+      throw new ReplaneError({
+        message: `Config not found: ${String(configName)}`,
+        code: "not_found" /* NotFound */
+      });
+    }
+    try {
+      return evaluateOverrides(
+        config.value,
+        config.overrides,
+        { ...sdkOptions.context, ...getConfigOptions?.context ?? {} },
+        sdkOptions.logger
+      );
+    } catch (error) {
+      sdkOptions.logger.error(
+        `Replane: error evaluating overrides for config ${String(configName)}:`,
+        error
+      );
+      return config.value;
+    }
+  }
+  const close = () => storage.close();
+  const initializationTimeoutId = setTimeout(() => {
+    if (sdkOptions.fallbacks.length === 0) {
+      close();
+      clientReady.reject(
+        new ReplaneError({
+          message: "Replane client initialization timed out",
+          code: "timeout" /* Timeout */
+        })
+      );
+      return;
+    }
+    const missingRequiredConfigs = [];
+    for (const requiredConfigName of sdkOptions.requiredConfigs) {
+      if (!configs.has(requiredConfigName)) {
+        missingRequiredConfigs.push(requiredConfigName);
+      }
+    }
+    if (missingRequiredConfigs.length > 0) {
+      close();
+      clientReady.reject(
+        new ReplaneError({
+          message: `Required configs are missing: ${missingRequiredConfigs.join(", ")}`,
+          code: "not_found" /* NotFound */
+        })
+      );
+      return;
+    }
+    clientReady.resolve();
+  }, sdkOptions.sdkInitializationTimeoutMs);
+  clientReady.promise.then(() => clearTimeout(initializationTimeoutId));
+  await clientReady.promise;
+  return {
+    getConfig,
+    close
+  };
+}
+function toFinalOptions(defaults) {
+  return {
+    sdkKey: defaults.sdkKey,
+    baseUrl: defaults.baseUrl.replace(/\/+$/, ""),
+    fetchFn: defaults.fetchFn ?? // some browsers require binding the fetch function to window
+    globalThis.fetch.bind(globalThis),
+    requestTimeoutMs: defaults.requestTimeoutMs ?? 2e3,
+    sdkInitializationTimeoutMs: defaults.sdkInitializationTimeoutMs ?? 5e3,
+    logger: defaults.logger ?? console,
+    retryDelayMs: defaults.retryDelayMs ?? 200,
+    context: {
+      ...defaults.context ?? {}
+    },
+    requiredConfigs: Array.isArray(defaults.required) ? defaults.required.map((name) => String(name)) : Object.entries(defaults.required ?? {}).filter(([_, value]) => value !== void 0).map(([name]) => name),
+    fallbacks: Object.entries(defaults.fallbacks ?? {}).filter(([_, value]) => value !== void 0).map(([name, value]) => ({
+      name,
+      overrides: [],
+      version: -1,
+      value
+    }))
+  };
+}
+async function fetchWithTimeout(input, init, timeoutMs, fetchFn) {
+  if (!fetchFn) {
+    throw new Error("Global fetch is not available. Provide options.fetchFn.");
+  }
+  if (!timeoutMs) return fetchFn(input, init);
+  const timeoutController = new AbortController();
+  const t = setTimeout(() => timeoutController.abort(), timeoutMs);
+  const { signal } = combineAbortSignals([init.signal, timeoutController.signal]);
+  try {
+    return await fetchFn(input, {
+      ...init,
+      signal
+    });
+  } finally {
+    clearTimeout(t);
+  }
+}
+const SSE_DATA_PREFIX = "data:";
+async function* fetchSse(params) {
+  const abortController = new AbortController();
+  const { signal, cleanUpSignals } = params.signal ? combineAbortSignals([params.signal, abortController.signal]) : { signal: abortController.signal, cleanUpSignals: () => {
+  } };
+  try {
+    const res = await fetchWithTimeout(
+      params.url,
+      {
+        method: params.method ?? "GET",
+        headers: { Accept: "text/event-stream", ...params.headers ?? {} },
+        body: params.body,
+        signal
+      },
+      params.timeoutMs,
+      params.fetchFn
+    );
+    await ensureSuccessfulResponse(res, `SSE ${params.url}`);
+    const responseContentType = res.headers.get("content-type") ?? "";
+    if (!responseContentType.includes("text/event-stream")) {
+      throw new ReplaneError({
+        message: `Expected text/event-stream, got "${responseContentType}"`,
+        code: "server_error" /* ServerError */
+      });
+    }
+    if (!res.body) {
+      throw new ReplaneError({
+        message: `Failed to fetch SSE ${params.url}: body is empty`,
+        code: "unknown" /* Unknown */
+      });
+    }
+    if (params.onConnect) {
+      params.onConnect();
+    }
+    const decoded = res.body.pipeThrough(new TextDecoderStream());
+    const reader = decoded.getReader();
+    let buffer = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += value;
+        const frames = buffer.split(/\r?\n\r?\n/);
+        buffer = frames.pop() ?? "";
+        for (const frame of frames) {
+          const dataLines = [];
+          for (const rawLine of frame.split(/\r?\n/)) {
+            if (!rawLine) continue;
+            if (rawLine.startsWith(":")) continue;
+            if (rawLine.startsWith(SSE_DATA_PREFIX)) {
+              const line = rawLine.slice(SSE_DATA_PREFIX.length).replace(/^\s/, "");
+              dataLines.push(line);
+            }
+          }
+          if (dataLines.length) {
+            const payload = dataLines.join("\n");
+            yield payload;
+          }
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+      }
+      abortController.abort();
+    }
+  } finally {
+    cleanUpSignals();
+  }
+}
+async function ensureSuccessfulResponse(response, message) {
+  if (response.status === 404) {
+    throw new ReplaneError({
+      message: `Not found: ${message}`,
+      code: "not_found" /* NotFound */
+    });
+  }
+  if (response.status === 401) {
+    throw new ReplaneError({
+      message: `Unauthorized access: ${message}`,
+      code: "auth_error" /* AuthError */
+    });
+  }
+  if (response.status === 403) {
+    throw new ReplaneError({
+      message: `Forbidden access: ${message}`,
+      code: "forbidden" /* Forbidden */
+    });
+  }
+  if (!response.ok) {
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      body = "<unable to read response body>";
+    }
+    const code = response.status >= 500 ? "server_error" /* ServerError */ : response.status >= 400 ? "client_error" /* ClientError */ : "unknown" /* Unknown */;
+    throw new ReplaneError({
+      message: `Fetch response isn't successful (${message}): ${response.status} ${response.statusText} - ${body}`,
+      code
+    });
+  }
+}
+function combineAbortSignals(signals) {
+  const controller = new AbortController();
+  const onAbort = () => {
+    controller.abort();
+    cleanUpSignals();
+  };
+  const cleanUpSignals = () => {
+    for (const s of signals) {
+      s?.removeEventListener("abort", onAbort);
+    }
+  };
+  for (const s of signals) {
+    s?.addEventListener("abort", onAbort, { once: true });
+  }
+  if (signals.some((s) => s?.aborted)) {
+    onAbort();
+  }
+  return { signal: controller.signal, cleanUpSignals };
+}
+class Deferred {
+  promise;
+  resolve;
+  reject;
+  constructor() {
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ReplaneError,
+  createInMemoryReplaneClient,
+  createReplaneClient
+});

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+//#region src/index.d.ts
+type Configs = object;
+type ReplaneContext = Record<string, unknown>;
+interface ReplaneClientOptions<T extends Configs> {
+  /**
+   * Base URL of the Replane API (no trailing slash).
+   */
+  baseUrl: string;
+  /**
+   * Project SDK key for authorization.
+   */
+  sdkKey: string;
+  /**
+   * Custom fetch implementation (useful for tests / polyfills).
+   */
+  fetchFn?: typeof fetch;
+  /**
+   * Optional timeout in ms for the request.
+   * @default 2000
+   */
+  requestTimeoutMs?: number;
+  /**
+   * Optional timeout in ms for the SDK initialization.
+   * @default 5000
+   */
+  sdkInitializationTimeoutMs?: number;
+  /**
+   * Delay between retries in ms.
+   * @default 100
+   */
+  retryDelayMs?: number;
+  /**
+   * Optional logger (defaults to console).
+   */
+  logger?: ReplaneLogger;
+  /**
+   * Default context for all config evaluations.
+   * Can be overridden per-request in `client.watchConfig()` and `watcher.getValue()`.
+   */
+  context?: ReplaneContext;
+  /**
+   * Required configs for the client.
+   * If a config is not present, the client will throw an error during initialization.
+   * @example
+   * {
+   *   required: {
+   *     config1: true,
+   *     config2: true,
+   *     config3: false,
+   *   },
+   * }
+   *
+   * @example
+   * {
+   *   required: ["config1", "config2", "config3"],
+   * }
+   */
+  required?: { [K in keyof T]: boolean } | Array<keyof T>;
+  /**
+   * Fallback configs to use if the initial request to fetch configs fails.
+   * @example
+   * {
+   *   fallbacks: {
+   *     config1: "value1",
+   *     config2: 42,
+   *   },
+   * }
+   */
+  fallbacks?: { [K in keyof T]: T[K] };
+}
+interface ReplaneLogger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+interface GetConfigOptions {
+  /**
+   * Context for override evaluation (merged with client-level context).
+   */
+  context?: ReplaneContext;
+}
+interface ConfigWatcher<T> {
+  /** Current config value (or fallback if not found). */
+  getValue(context?: ReplaneContext): T;
+  /** Stop watching for changes. */
+  close(): void;
+}
+interface ReplaneClient<T extends Configs> {
+  /** Get a config by its name. */
+  getConfig<K extends keyof T>(configName: K, options?: GetConfigOptions): T[K];
+  /** Close the client and clean up resources. */
+  close(): void;
+}
+declare class ReplaneError extends Error {
+  code: string;
+  constructor(params: {
+    message: string;
+    code: string;
+    cause?: unknown;
+  });
+}
+/**
+ * Create a Replane client bound to an SDK key.
+ * Usage:
+ *   const client = await createReplaneClient({ sdkKey: 'your-sdk-key', baseUrl: 'https://app.replane.dev' })
+ *   const value = client.getConfig('my-config')
+ */
+declare function createReplaneClient<T extends Configs = Record<string, unknown>>(sdkOptions: ReplaneClientOptions<T>): Promise<ReplaneClient<T>>;
+/**
+ * Create a Replane client that uses in-memory storage.
+ * Usage:
+ *   const client = createInMemoryReplaneClient({ 'my-config': 123 })
+ *   const value = client.getConfig('my-config') // 123
+ */
+declare function createInMemoryReplaneClient<T extends Configs = Record<string, unknown>>(initialData: T): ReplaneClient<T>;
+//#endregion
+export { ConfigWatcher, GetConfigOptions, ReplaneClient, ReplaneClientOptions, ReplaneContext, ReplaneError, ReplaneLogger, createInMemoryReplaneClient, createReplaneClient };