@replanejs/sdk 0.7.6 → 0.7.8

package/dist/index.cjs

@@ -1,42 +1,836 @@
-"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 });
+
+//#region src/error.ts
+/**
+* Error codes for ReplaneError
+*/
+let ReplaneErrorCode = /* @__PURE__ */ function(ReplaneErrorCode$1) {
+	ReplaneErrorCode$1["NotFound"] = "not_found";
+	ReplaneErrorCode$1["Timeout"] = "timeout";
+	ReplaneErrorCode$1["NetworkError"] = "network_error";
+	ReplaneErrorCode$1["AuthError"] = "auth_error";
+	ReplaneErrorCode$1["Forbidden"] = "forbidden";
+	ReplaneErrorCode$1["ServerError"] = "server_error";
+	ReplaneErrorCode$1["ClientError"] = "client_error";
+	ReplaneErrorCode$1["Closed"] = "closed";
+	ReplaneErrorCode$1["NotInitialized"] = "not_initialized";
+	ReplaneErrorCode$1["Unknown"] = "unknown";
+	return ReplaneErrorCode$1;
+}({});
+/**
+* Custom error class for Replane SDK errors
+*/
+var ReplaneError = class extends Error {
+	code;
+	constructor(params) {
+		super(params.message, { cause: params.cause });
+		this.name = "ReplaneError";
+		this.code = params.code;
+	}
 };
-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;
+
+//#endregion
+//#region src/utils.ts
+/**
+* Returns a promise that resolves after the specified delay
+*
+* @param ms - Delay in milliseconds
+*/
+async function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Returns a promise that resolves after a delay with jitter.
+* The actual delay is the average delay ± 10% (jitter = averageDelay/5).
+*
+* @param averageDelay - The average delay in milliseconds
+*/
+async function retryDelay(averageDelay) {
+	const jitter = averageDelay / 5;
+	const delayMs = averageDelay + Math.random() * jitter - jitter / 2;
+	await delay(delayMs);
+}
+/**
+* Combines multiple abort signals into one.
+* When any of the input signals is aborted, the combined signal will also be aborted.
+*
+* @param signals - Array of AbortSignal instances (can contain undefined/null)
+* @returns An object containing the combined signal and a cleanup function
+*/
+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
+	};
+}
+/**
+* A deferred promise that can be resolved or rejected from outside.
+* Useful for coordinating async operations.
+*/
+var Deferred = class {
+	promise;
+	resolve;
+	reject;
+	constructor() {
+		this.promise = new Promise((resolve, reject) => {
+			this.resolve = resolve;
+			this.reject = reject;
+		});
+	}
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var src_exports = {};
-__export(src_exports, {
-  ReplaneError: () => import_error.ReplaneError,
-  ReplaneErrorCode: () => import_error.ReplaneErrorCode,
-  clearSnapshotCache: () => import_snapshot.clearSnapshotCache,
-  createInMemoryReplaneClient: () => import_client.createInMemoryReplaneClient,
-  createReplaneClient: () => import_client.createReplaneClient,
-  getReplaneSnapshot: () => import_snapshot.getReplaneSnapshot,
-  restoreReplaneClient: () => import_client.restoreReplaneClient
-});
-module.exports = __toCommonJS(src_exports);
-var import_client = require("./client");
-var import_error = require("./error");
-var import_snapshot = require("./snapshot");
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ReplaneError,
-  ReplaneErrorCode,
-  clearSnapshotCache,
-  createInMemoryReplaneClient,
-  createReplaneClient,
-  getReplaneSnapshot,
-  restoreReplaneClient
+
+//#endregion
+//#region src/sse.ts
+const SSE_DATA_PREFIX = "data:";
+/**
+* Fetch with timeout support
+*/
+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);
+	}
+}
+/**
+* Ensures the response is successful, throwing ReplaneError if not
+*/
+async function ensureSuccessfulResponse(response, message) {
+	if (response.status === 404) throw new ReplaneError({
+		message: `Not found: ${message}`,
+		code: ReplaneErrorCode.NotFound
+	});
+	if (response.status === 401) throw new ReplaneError({
+		message: `Unauthorized access: ${message}`,
+		code: ReplaneErrorCode.AuthError
+	});
+	if (response.status === 403) throw new ReplaneError({
+		message: `Forbidden access: ${message}`,
+		code: ReplaneErrorCode.Forbidden
+	});
+	if (!response.ok) {
+		let body;
+		try {
+			body = await response.text();
+		} catch {
+			body = "<unable to read response body>";
+		}
+		const code = response.status >= 500 ? ReplaneErrorCode.ServerError : response.status >= 400 ? ReplaneErrorCode.ClientError : ReplaneErrorCode.Unknown;
+		throw new ReplaneError({
+			message: `Fetch response isn't successful (${message}): ${response.status} ${response.statusText} - ${body}`,
+			code
+		});
+	}
+}
+/**
+* Fetches a Server-Sent Events (SSE) stream and yields parsed events.
+*
+* @param params - Options for the SSE fetch
+* @yields SseEvent objects containing either data or comment events
+*/
+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: ReplaneErrorCode.ServerError
+		});
+		if (!res.body) throw new ReplaneError({
+			message: `Failed to fetch SSE ${params.url}: body is empty`,
+			code: ReplaneErrorCode.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 = [];
+					let comment = null;
+					for (const rawLine of frame.split(/\r?\n/)) {
+						if (!rawLine) continue;
+						if (rawLine.startsWith(":")) {
+							comment = rawLine.slice(1);
+							continue;
+						}
+						if (rawLine.startsWith(SSE_DATA_PREFIX)) {
+							const line = rawLine.slice(SSE_DATA_PREFIX.length).replace(/^\s/, "");
+							dataLines.push(line);
+						}
+					}
+					if (dataLines.length) {
+						const data = dataLines.join("\n");
+						yield {
+							type: "data",
+							data
+						};
+					} else if (comment !== null) yield {
+						type: "comment",
+						comment
+					};
+				}
+			}
+		} finally {
+			try {
+				await reader.cancel();
+			} catch {}
+			abortController.abort();
+		}
+	} finally {
+		cleanUpSignals();
+	}
+}
+
+//#endregion
+//#region src/storage.ts
+const SUPPORTED_REPLICATION_STREAM_RECORD_TYPES = Object.keys({
+	config_change: true,
+	init: true
 });
+/**
+* Remote storage implementation that connects to the Replane server
+* and streams config updates via SSE.
+*/
+var ReplaneRemoteStorage = class {
+	closeController = new AbortController();
+	/**
+	* Start a replication stream that yields config updates.
+	* This method never throws - it retries on failure with exponential backoff.
+	*/
+	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 inactivityAbortController = new AbortController();
+		const { signal: combinedSignal, cleanUpSignals } = options.signal ? combineAbortSignals([options.signal, inactivityAbortController.signal]) : {
+			signal: inactivityAbortController.signal,
+			cleanUpSignals: () => {}
+		};
+		let inactivityTimer = null;
+		const resetInactivityTimer = () => {
+			if (inactivityTimer) clearTimeout(inactivityTimer);
+			inactivityTimer = setTimeout(() => {
+				inactivityAbortController.abort();
+			}, options.inactivityTimeoutMs);
+		};
+		try {
+			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: combinedSignal,
+				url: this.getApiEndpoint(`/sdk/v1/replication/stream`, options),
+				onConnect: () => {
+					resetInactivityTimer();
+					options.onConnect?.();
+				}
+			});
+			for await (const sseEvent of rawEvents) {
+				resetInactivityTimer();
+				if (sseEvent.type === "comment") continue;
+				const event = JSON.parse(sseEvent.data);
+				if (typeof event === "object" && event !== null && "type" in event && typeof event.type === "string" && SUPPORTED_REPLICATION_STREAM_RECORD_TYPES.includes(event.type)) yield event;
+			}
+		} finally {
+			if (inactivityTimer) clearTimeout(inactivityTimer);
+			cleanUpSignals();
+		}
+	}
+	/**
+	* Close the storage and abort any active connections
+	*/
+	close() {
+		this.closeController.abort();
+	}
+	getAuthHeader(options) {
+		return `Bearer ${options.sdkKey}`;
+	}
+	getApiEndpoint(path, options) {
+		return `${options.baseUrl}/api${path}`;
+	}
+};
+
+//#endregion
+//#region src/hash.ts
+/**
+* FNV-1a 32-bit hash function
+*
+* FNV (Fowler–Noll–Vo) is a non-cryptographic hash function known for its
+* speed and good distribution. This implementation uses the FNV-1a variant
+* which XORs before multiplying for better avalanche characteristics.
+*
+* @param input - The string to hash
+* @returns A 32-bit unsigned integer hash value
+*/
+function fnv1a32(input) {
+	const encoder = new TextEncoder();
+	const bytes = encoder.encode(input);
+	let hash = 2166136261;
+	for (let i = 0; i < bytes.length; i++) {
+		hash ^= bytes[i];
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return hash >>> 0;
+}
+/**
+* Convert FNV-1a hash to [0, 1) for bucketing.
+*
+* This is useful for percentage-based segmentation where you need
+* to deterministically assign a value to a bucket based on a string input.
+*
+* @param input - The string to hash
+* @returns A number in the range [0, 1)
+*/
+function fnv1a32ToUnit(input) {
+	const h = fnv1a32(input);
+	return h / 2 ** 32;
+}
+
+//#endregion
+//#region src/evaluation.ts
+/**
+* Evaluate config overrides based on context.
+* Returns the first matching override's value, or the base value if no override matches.
+*
+* @param baseValue - The default value to return if no override matches
+* @param overrides - Array of overrides to evaluate
+* @param context - The context to evaluate conditions against
+* @param logger - Logger for warnings
+* @returns The evaluated value
+*/
+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;
+}
+/**
+* Evaluate a single condition against a context.
+*
+* @param condition - The condition to evaluate
+* @param context - The context to evaluate against
+* @param logger - Logger for warnings
+* @returns The evaluation result
+*/
+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 contextValue$1 = context[condition.property];
+		if (contextValue$1 === void 0 || contextValue$1 === null) return "unknown";
+		const hashInput = String(contextValue$1) + 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";
+	}
+}
+/**
+* Helper to warn about exhaustive check failures
+*/
+function warnNever(value, logger, message) {
+	logger.warn(message, { value });
+}
+/**
+* Cast expected value to match context value type.
+* This enables loose matching between different types (e.g., "25" matches 25).
+*
+* @param expectedValue - The value from the condition
+* @param contextValue - The value from the context
+* @returns The expected value cast to match the context value's type
+*/
+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;
+}
+
+//#endregion
+//#region src/client.ts
+/**
+* Creates the core client logic shared between createReplaneClient and restoreReplaneClient
+*/
+function createClientCore(options) {
+	const { initialConfigs, context, logger, storage, streamOptions, requiredConfigs } = options;
+	const configs = new Map(initialConfigs.map((config) => [config.name, config]));
+	const clientReady = new Deferred();
+	const configSubscriptions = new Map();
+	const clientSubscriptions = new Set();
+	function processConfigUpdates(updatedConfigs) {
+		for (const config of updatedConfigs) {
+			configs.set(config.name, {
+				name: config.name,
+				overrides: config.overrides,
+				value: config.value
+			});
+			for (const callback of clientSubscriptions) callback({
+				name: config.name,
+				value: config.value
+			});
+			for (const callback of configSubscriptions.get(config.name) ?? []) callback({
+				name: config.name,
+				value: config.value
+			});
+		}
+	}
+	async function startStreaming() {
+		if (!storage || !streamOptions) return;
+		try {
+			const replicationStream = storage.startReplicationStream({
+				...streamOptions,
+				getBody: () => ({
+					currentConfigs: [...configs.values()].map((config) => ({
+						name: config.name,
+						overrides: config.overrides,
+						value: config.value
+					})),
+					requiredConfigs
+				})
+			});
+			for await (const event of replicationStream) {
+				const updatedConfigs = event.type === "config_change" ? [event.config] : event.configs;
+				processConfigUpdates(updatedConfigs);
+				clientReady.resolve();
+			}
+		} catch (error) {
+			logger.error("Replane: error in SSE connection:", error);
+			clientReady.reject(error);
+			throw error;
+		}
+	}
+	function get(configName, getConfigOptions = {}) {
+		const config = configs.get(String(configName));
+		if (config === void 0) throw new ReplaneError({
+			message: `Config not found: ${String(configName)}`,
+			code: ReplaneErrorCode.NotFound
+		});
+		try {
+			return evaluateOverrides(config.value, config.overrides, {
+				...context,
+				...getConfigOptions?.context ?? {}
+			}, logger);
+		} catch (error) {
+			logger.error(`Replane: error evaluating overrides for config ${String(configName)}:`, error);
+			return config.value;
+		}
+	}
+	const subscribe = (callbackOrConfigName, callbackOrUndefined) => {
+		let configName = void 0;
+		let callback;
+		if (typeof callbackOrConfigName === "function") callback = callbackOrConfigName;
+		else {
+			configName = callbackOrConfigName;
+			if (callbackOrUndefined === void 0) throw new Error("callback is required when config name is provided");
+			callback = callbackOrUndefined;
+		}
+		const originalCallback = callback;
+		callback = (...args) => {
+			originalCallback(...args);
+		};
+		if (configName === void 0) {
+			clientSubscriptions.add(callback);
+			return () => {
+				clientSubscriptions.delete(callback);
+			};
+		}
+		if (!configSubscriptions.has(configName)) configSubscriptions.set(configName, new Set());
+		configSubscriptions.get(configName).add(callback);
+		return () => {
+			configSubscriptions.get(configName)?.delete(callback);
+			if (configSubscriptions.get(configName)?.size === 0) configSubscriptions.delete(configName);
+		};
+	};
+	const getSnapshot = () => ({
+		configs: [...configs.values()].map((config) => ({
+			name: config.name,
+			value: config.value,
+			overrides: config.overrides.map((override) => ({
+				name: override.name,
+				conditions: override.conditions,
+				value: override.value
+			}))
+		})),
+		context
+	});
+	const close = () => storage?.close();
+	const client = {
+		get,
+		subscribe,
+		getSnapshot,
+		close
+	};
+	return {
+		client,
+		configs,
+		startStreaming,
+		clientReady
+	};
+}
+/**
+* Create a Replane client bound to an SDK key.
+*
+* @example
+* ```typescript
+* const client = await createReplaneClient({
+*   sdkKey: 'your-sdk-key',
+*   baseUrl: 'https://app.replane.dev'
+* });
+* const value = client.get('my-config');
+* ```
+*/
+async function createReplaneClient(sdkOptions) {
+	const storage = new ReplaneRemoteStorage();
+	return await createReplaneClientInternal(toFinalOptions(sdkOptions), storage);
+}
+/**
+* Create a Replane client that uses in-memory storage.
+* Useful for testing or when you have static config values.
+*
+* @example
+* ```typescript
+* const client = createInMemoryReplaneClient({ 'my-config': 123 });
+* const value = client.get('my-config'); // 123
+* ```
+*/
+function createInMemoryReplaneClient(initialData) {
+	return {
+		get: (configName) => {
+			const config = initialData[configName];
+			if (config === void 0) throw new ReplaneError({
+				message: `Config not found: ${String(configName)}`,
+				code: ReplaneErrorCode.NotFound
+			});
+			return config;
+		},
+		subscribe: () => {
+			return () => {};
+		},
+		getSnapshot: () => ({ configs: Object.entries(initialData).map(([name, value]) => ({
+			name,
+			value,
+			overrides: []
+		})) }),
+		close: () => {}
+	};
+}
+/**
+* Restore a Replane client from a snapshot.
+* This is useful for SSR/hydration scenarios where the server has already fetched configs.
+*
+* @example
+* ```typescript
+* // On the server:
+* const serverClient = await createReplaneClient({ ... });
+* const snapshot = serverClient.getSnapshot();
+* // Pass snapshot to client via props/serialization
+*
+* // On the client:
+* const client = restoreReplaneClient({
+*   snapshot,
+*   connection: { sdkKey, baseUrl }
+* });
+* const value = client.get('my-config');
+* ```
+*/
+function restoreReplaneClient(options) {
+	const { snapshot, connection } = options;
+	const context = options.context ?? snapshot.context ?? {};
+	const logger = connection?.logger ?? console;
+	const initialConfigs = snapshot.configs.map((config) => ({
+		name: config.name,
+		value: config.value,
+		overrides: config.overrides
+	}));
+	let storage = null;
+	let streamOptions = null;
+	if (connection) {
+		storage = new ReplaneRemoteStorage();
+		streamOptions = {
+			sdkKey: connection.sdkKey,
+			baseUrl: connection.baseUrl.replace(/\/+$/, ""),
+			fetchFn: connection.fetchFn ?? globalThis.fetch.bind(globalThis),
+			requestTimeoutMs: connection.requestTimeoutMs ?? 2e3,
+			initializationTimeoutMs: 5e3,
+			inactivityTimeoutMs: connection.inactivityTimeoutMs ?? 3e4,
+			logger,
+			retryDelayMs: connection.retryDelayMs ?? 200,
+			context,
+			requiredConfigs: [],
+			fallbacks: []
+		};
+	}
+	const { client, startStreaming } = createClientCore({
+		initialConfigs,
+		context,
+		logger,
+		storage,
+		streamOptions,
+		requiredConfigs: []
+	});
+	if (storage && streamOptions) startStreaming().catch((error) => {
+		logger.error("Replane: error in restored client SSE connection:", error);
+	});
+	return client;
+}
+/**
+* Internal function to create a Replane client with the given options and storage
+*/
+async function createReplaneClientInternal(sdkOptions, storage) {
+	if (!sdkOptions.sdkKey) throw new Error("SDK key is required");
+	const { client, configs, startStreaming, clientReady } = createClientCore({
+		initialConfigs: sdkOptions.fallbacks,
+		context: sdkOptions.context,
+		logger: sdkOptions.logger,
+		storage,
+		streamOptions: sdkOptions,
+		requiredConfigs: sdkOptions.requiredConfigs
+	});
+	startStreaming().catch((error) => {
+		sdkOptions.logger.error("Replane: error initializing client:", error);
+	});
+	const initializationTimeoutId = setTimeout(() => {
+		if (sdkOptions.fallbacks.length === 0) {
+			client.close();
+			clientReady.reject(new ReplaneError({
+				message: "Replane client initialization timed out",
+				code: ReplaneErrorCode.Timeout
+			}));
+			return;
+		}
+		const missingRequiredConfigs = [];
+		for (const requiredConfigName of sdkOptions.requiredConfigs) if (!configs.has(requiredConfigName)) missingRequiredConfigs.push(requiredConfigName);
+		if (missingRequiredConfigs.length > 0) {
+			client.close();
+			clientReady.reject(new ReplaneError({
+				message: `Required configs are missing: ${missingRequiredConfigs.join(", ")}`,
+				code: ReplaneErrorCode.NotFound
+			}));
+			return;
+		}
+		clientReady.resolve();
+	}, sdkOptions.initializationTimeoutMs);
+	clientReady.promise.then(() => clearTimeout(initializationTimeoutId));
+	await clientReady.promise;
+	return client;
+}
+/**
+* Convert user options to final options with defaults
+*/
+function toFinalOptions(defaults) {
+	return {
+		sdkKey: defaults.sdkKey,
+		baseUrl: defaults.baseUrl.replace(/\/+$/, ""),
+		fetchFn: defaults.fetchFn ?? globalThis.fetch.bind(globalThis),
+		requestTimeoutMs: defaults.requestTimeoutMs ?? 2e3,
+		initializationTimeoutMs: defaults.initializationTimeoutMs ?? 5e3,
+		inactivityTimeoutMs: defaults.inactivityTimeoutMs ?? 3e4,
+		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
+		}))
+	};
+}
+
+//#endregion
+//#region src/snapshot.ts
+const clientCache = new Map();
+function getCacheKey(options) {
+	return `${options.baseUrl}:${options.sdkKey}`;
+}
+function setupCleanupTimeout(cacheKey, cacheTtlMs) {
+	return setTimeout(() => {
+		clientCache.delete(cacheKey);
+	}, cacheTtlMs);
+}
+/**
+* Creates a Replane client and returns a snapshot.
+* Useful for SSR/SSG scenarios where you need to fetch config once
+* and pass it to the client.
+*
+* @example
+* ```ts
+* const snapshot = await getReplaneSnapshot({
+*   baseUrl: process.env.REPLANE_BASE_URL!,
+*   sdkKey: process.env.REPLANE_SDK_KEY!,
+* });
+* ```
+*/
+async function getReplaneSnapshot(options) {
+	const { cacheTtlMs = 6e4,...clientOptions } = options;
+	const cacheKey = getCacheKey(clientOptions);
+	const cached = clientCache.get(cacheKey);
+	if (cached) {
+		clearTimeout(cached.timeoutId);
+		cached.timeoutId = setupCleanupTimeout(cacheKey, cacheTtlMs);
+		const client$1 = await cached.clientPromise;
+		return client$1.getSnapshot();
+	}
+	const clientPromise = createReplaneClient(clientOptions);
+	const entry = {
+		clientPromise,
+		timeoutId: setupCleanupTimeout(cacheKey, cacheTtlMs)
+	};
+	clientCache.set(cacheKey, entry);
+	const client = await clientPromise;
+	return client.getSnapshot();
+}
+/**
+* Clears the client cache used by getReplaneSnapshot.
+* Useful for testing or when you need to force re-initialization.
+*/
+async function clearSnapshotCache() {
+	const clientPromises = [...clientCache.values()].map((cached) => cached.clientPromise);
+	clientCache.clear();
+	for (const clientPromise of clientPromises) {
+		const client = await clientPromise;
+		client.close();
+	}
+}
+
+//#endregion
+exports.ReplaneError = ReplaneError;
+exports.ReplaneErrorCode = ReplaneErrorCode;
+exports.clearSnapshotCache = clearSnapshotCache;
+exports.createInMemoryReplaneClient = createInMemoryReplaneClient;
+exports.createReplaneClient = createReplaneClient;
+exports.getReplaneSnapshot = getReplaneSnapshot;
+exports.restoreReplaneClient = restoreReplaneClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replanejs/sdk",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Dynamic configuration SDK for browser and server environments (Node.js, Deno, Bun). Powered by Replane.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,6 @@
   "devDependencies": {
     "@types/node": "^22.15.17",
     "async-channel": "^0.2.0",
-    "esbuild": "^0.23.1",
     "tsdown": "^0.11.9",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
@@ -52,9 +51,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:esm && pnpm run build:cjs",
-    "build:esm": "tsdown",
-    "build:cjs": "esbuild src/index.ts --platform=node --format=cjs --outfile=dist/index.cjs",
+    "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"