@configdirector/react-native-sdk 1.7.0 → 1.9.0

package/dist/{installedTestClient-LWv5ji8J.mjs → installedTestClient-BluKT8Qj.mjs}

@@ -89,6 +89,13 @@ var ConfigDirectorValidationError = class ConfigDirectorValidationError extends
 		Object.setPrototypeOf(this, ConfigDirectorValidationError.prototype);
 	}
 };
+var ConfigDirectorInitializationError = class ConfigDirectorInitializationError extends Error {
+	constructor(message) {
+		super(message);
+		_defineProperty(this, "name", "ConfigDirectorInitializationError");
+		Object.setPrototypeOf(this, ConfigDirectorInitializationError.prototype);
+	}
+};
 //#endregion
 //#region ../js-client-core/src/errors.ts
 const isFetchErrorFatal = (fetchError) => {
@@ -535,6 +542,187 @@ var StreamingTransport = class {
 	}
 };
 //#endregion
+//#region ../shared/src/native-values.ts
+const encodeNativeValue = (key, value) => {
+	if (key.trim().length == 0) throw new ConfigDirectorValidationError("Invalid config key. The key of a value cannot be empty.");
+	return encode(key, value);
+};
+const encode = (key, value) => {
+	switch (typeof value) {
+		case "boolean": return {
+			type: "boolean",
+			value: value ? "true" : "false"
+		};
+		case "number": return encodeNumber(key, value);
+		case "string": return {
+			type: "string",
+			value
+		};
+		case "object": if (value !== null) {
+			assertJsonContents(key, value, "");
+			return {
+				type: "json",
+				value: JSON.stringify(value)
+			};
+		}
+	}
+	throw new ConfigDirectorValidationError(`Invalid value for '${key}': ${describe(value)}. Use a boolean, a number, a string, a plain object, or an array.`);
+};
+const encodeNumber = (key, value) => {
+	if (!Number.isFinite(value)) throw new ConfigDirectorValidationError(`Invalid value for '${key}': ${describe(value)} is not a finite number.`);
+	if (Number.isInteger(value)) {
+		if (!Number.isSafeInteger(value)) throw new ConfigDirectorValidationError(`Invalid value for '${key}': ${value} is not a safe integer, so the SDK could not read it back exactly.`);
+		return {
+			type: "integer",
+			value: String(value)
+		};
+	}
+	return {
+		type: "float",
+		value: toPlainDecimal(value)
+	};
+};
+const toPlainDecimal = (value) => {
+	const text = String(value);
+	const exponentIndex = text.indexOf("e-");
+	if (exponentIndex < 0) return text;
+	const sign = text.startsWith("-") ? "-" : "";
+	const [integerDigits = "", fractionDigits = ""] = text.slice(sign.length, exponentIndex).split(".");
+	const leadingZeros = Number(text.slice(exponentIndex + 2)) - integerDigits.length;
+	return `${sign}0.${"0".repeat(leadingZeros)}${integerDigits}${fractionDigits}`;
+};
+const assertJsonContents = (key, value, path) => {
+	if (value === null || typeof value === "boolean" || typeof value === "string") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw invalidJsonContents(key, path, `${describe(value)} is not a finite number`);
+		return;
+	}
+	if (Array.isArray(value)) {
+		value.forEach((item, index) => assertJsonContents(key, item, `${path}[${index}]`));
+		return;
+	}
+	if (isPlainObject(value)) {
+		for (const [property, item] of Object.entries(value)) assertJsonContents(key, item, path ? `${path}.${property}` : property);
+		return;
+	}
+	throw invalidJsonContents(key, path, `${describe(value)} cannot be encoded as JSON`);
+};
+const invalidJsonContents = (key, path, problem) => new ConfigDirectorValidationError(`Invalid value for '${key}'${path ? ` at '${path}'` : ""}: ${problem}. JSON contents can hold booleans, finite numbers, strings, null, arrays, and plain objects.`);
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const describe = (value) => {
+	if (value === null) return "null";
+	if (typeof value === "function") return "a function";
+	if (typeof value === "object") {
+		var _value$constructor$na, _value$constructor;
+		return `a ${(_value$constructor$na = (_value$constructor = value.constructor) === null || _value$constructor === void 0 ? void 0 : _value$constructor.name) !== null && _value$constructor$na !== void 0 ? _value$constructor$na : "object"} instance`;
+	}
+	if (typeof value === "symbol") return "a symbol";
+	return String(value);
+};
+//#endregion
+//#region ../js-client-core/src/native-values.ts
+const nativeValueConfigState = (id, key, value, valueId) => {
+	const encoded = encodeNativeValue(key, value);
+	return {
+		id,
+		key,
+		type: encoded.type,
+		value: encoded.value,
+		valueId
+	};
+};
+//#endregion
+//#region ../js-client-core/src/OfflineTransport.ts
+const OFFLINE_ENVIRONMENT = {
+	environmentId: "offline",
+	projectId: "offline"
+};
+var OfflineTransport = class {
+	constructor(source) {
+		this.source = source;
+		_defineProperty(this, "emitter", new Emitter());
+		_defineProperty(this, "on", (name, handler) => this.emitter.on(name, handler));
+		_defineProperty(this, "off", (name, handler) => this.emitter.off(name, handler));
+	}
+	async connect() {
+		const configs = loadOfflineConfigs(this.source);
+		this.emitter.emit("configSetReceived", {
+			...OFFLINE_ENVIRONMENT,
+			kind: "full",
+			configs
+		});
+		return this;
+	}
+	clear() {
+		this.emitter.clear();
+	}
+	close() {}
+	dispose() {
+		this.clear();
+	}
+};
+const loadOfflineConfigs = (source) => {
+	switch (source.kind) {
+		case "in-code-defaults": return {};
+		case "values": return encodeOfflineValues(source.values);
+		case "rejected": throw new ConfigDirectorInitializationError(source.message);
+	}
+};
+const encodeOfflineValues = (values) => {
+	try {
+		return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, nativeValueConfigState(`offline:${key}`, key, value, void 0)]));
+	} catch (error) {
+		if (error instanceof ConfigDirectorValidationError) throw new ConfigDirectorInitializationError(`The offline values could not be loaded. ${error.message}`);
+		throw error;
+	}
+};
+//#endregion
+//#region ../shared/src/constants.ts
+const CLIENT_BASE_URL = "https://client-sdk-api.configdirector.com";
+//#endregion
+//#region ../js-client-core/src/connection-plan.ts
+const planConnection = (clientSdkKey, connection, urlFactory) => {
+	var _connection$mode;
+	if ((connection === null || connection === void 0 ? void 0 : connection.mode) === "offline") return {
+		kind: "stay-offline",
+		source: offlineSourceOf(connection)
+	};
+	const mode = (_connection$mode = connection === null || connection === void 0 ? void 0 : connection.mode) !== null && _connection$mode !== void 0 ? _connection$mode : "streaming";
+	if (!clientSdkKey || clientSdkKey.trim().length == 0) throw new ConfigDirectorValidationError("No client SDK key was provided, the client cannot be instantiated without a valid client SDK key");
+	if ((connection === null || connection === void 0 ? void 0 : connection.values) !== void 0) return {
+		kind: "stay-offline",
+		source: {
+			kind: "rejected",
+			message: `The connection option 'values' applies only when the connection mode is 'offline', but the mode is '${mode}'.`
+		}
+	};
+	return {
+		kind: "connect",
+		mode,
+		clientSdkKey,
+		baseUrl: baseUrlOf(connection === null || connection === void 0 ? void 0 : connection.url, urlFactory)
+	};
+};
+const baseUrlOf = (url, urlFactory) => {
+	if (!url) return CLIENT_BASE_URL;
+	try {
+		return urlFactory(url);
+	} catch (error) {
+		throw new ConfigDirectorValidationError(`Invalid base URL '${url}'. Parsing failed: ${error}`);
+	}
+};
+const offlineSourceOf = (connection) => {
+	if (connection.values !== void 0) return {
+		kind: "values",
+		values: connection.values
+	};
+	return { kind: "in-code-defaults" };
+};
+//#endregion
 //#region ../shared/src/value-parser.ts
 const getRequestedType = (defaultValue) => {
 	const baseType = typeof defaultValue;
@@ -758,12 +946,17 @@ const createDefaultLogger = (level, messageDecorator) => {
 	return new DefaultConsoleLogger(level !== null && level !== void 0 ? level : "warn", messageDecorator !== null && messageDecorator !== void 0 ? messageDecorator : new LogMessageDecorator());
 };
 //#endregion
+//#region ../js-client-core/src/telemetry/discarding.ts
+const discardingTelemetryClient = {
+	updateContext: async () => {},
+	evaluatedConfig: () => {},
+	recordInvalidContext: () => {},
+	close: async () => {}
+};
+//#endregion
 //#region ../shared/src/url.ts
 const defaultUrlFactory = (input, base) => new URL(input, base === null || base === void 0 ? void 0 : base.toString());
 //#endregion
-//#region ../shared/src/constants.ts
-const CLIENT_BASE_URL = "https://client-sdk-api.configdirector.com";
-//#endregion
 //#region ../shared/src/transport/pollingInterval.ts
 const resolvePollingInterval = (configuredSeconds, defaults) => {
 	if (configuredSeconds === void 0) return {
@@ -789,10 +982,34 @@ const generateInstanceId = () => {
 	});
 };
 //#endregion
+//#region ../js-client-core/src/browser-globals.ts
+const read = (readValue) => {
+	try {
+		return readValue(globalThis);
+	} catch {
+		return;
+	}
+};
+const readUserAgent = () => read((globals) => {
+	var _globals$navigator;
+	return (_globals$navigator = globals.navigator) === null || _globals$navigator === void 0 ? void 0 : _globals$navigator.userAgent;
+});
+const readHost = () => read((globals) => {
+	var _globals$location;
+	return (_globals$location = globals.location) === null || _globals$location === void 0 ? void 0 : _globals$location.host;
+});
+const localStorageIfAvailable = () => {
+	try {
+		var _localStorage;
+		return (_localStorage = globalThis.localStorage) !== null && _localStorage !== void 0 ? _localStorage : void 0;
+	} catch {
+		return;
+	}
+};
+//#endregion
 //#region ../js-client-core/src/client-session.ts
 const STORAGE_KEY = "configdirector-sdk:instance-id";
 const RECORD_VERSION = 1;
-const MAX_AGE_MS = 360 * 60 * 1e3;
 const STORAGE_DEADLINE_MS = 1e3;
 const CHECKSUM_SALT = "configdirector.instanceId.v1";
 const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -809,14 +1026,6 @@ const checksumFor = (id, createdAt) => {
 	const low = fnv1a(payload, 2166136261);
 	return fnv1a(`${low}|${payload}`, 16777619).toString(16).padStart(8, "0") + low.toString(16).padStart(8, "0");
 };
-const localStorageIfAvailable = () => {
-	try {
-		var _localStorage;
-		return (_localStorage = globalThis.localStorage) !== null && _localStorage !== void 0 ? _localStorage : void 0;
-	} catch {
-		return;
-	}
-};
 const isUsableRecord = (record) => {
 	if (!record || typeof record !== "object") return false;
 	const { v, id, createdAt, checksum } = record;
@@ -845,11 +1054,6 @@ const readStoredInstanceId = async (storage, logger) => {
 		logger.debug("[ConfigDirectorClient] The stored instance id failed validation, generating a new one");
 		return { outcome: "nothing usable" };
 	}
-	const age = Date.now() - record.createdAt;
-	if (age < 0 || age >= MAX_AGE_MS) {
-		logger.debug("[ConfigDirectorClient] The stored instance id has expired, generating a new one");
-		return { outcome: "nothing usable" };
-	}
 	return {
 		outcome: "stored",
 		instanceId: record.id
@@ -1069,23 +1273,6 @@ var PollingTransport = class extends AbstractPollingTransport {
 	}
 };
 //#endregion
-//#region ../js-client-core/src/browser-globals.ts
-const read = (readValue) => {
-	try {
-		return readValue(globalThis);
-	} catch {
-		return;
-	}
-};
-const readUserAgent = () => read((globals) => {
-	var _globals$navigator;
-	return (_globals$navigator = globals.navigator) === null || _globals$navigator === void 0 ? void 0 : _globals$navigator.userAgent;
-});
-const readHost = () => read((globals) => {
-	var _globals$location;
-	return (_globals$location = globals.location) === null || _globals$location === void 0 ? void 0 : _globals$location.host;
-});
-//#endregion
 //#region ../shared/src/context-kind.ts
 const CONTEXT_KIND_MAXIMUM_LENGTH = 64;
 const KIND_SAMPLE_MAXIMUM_CHARACTERS = 128;
@@ -1126,11 +1313,190 @@ const admitContext = (context) => {
 	};
 };
 //#endregion
+//#region ../shared/src/utf8-byte-length.ts
+const isHighSurrogate = (codeUnit) => codeUnit >= 55296 && codeUnit <= 56319;
+const isLowSurrogate = (codeUnit) => codeUnit >= 56320 && codeUnit <= 57343;
+const utf8ByteLength = (text) => {
+	let bytes = 0;
+	for (let i = 0; i < text.length; i++) {
+		const codeUnit = text.charCodeAt(i);
+		if (codeUnit <= 127) bytes += 1;
+		else if (codeUnit <= 2047) bytes += 2;
+		else if (isHighSurrogate(codeUnit) && i + 1 < text.length && isLowSurrogate(text.charCodeAt(i + 1))) {
+			bytes += 4;
+			i++;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+//#endregion
+//#region ../js-client-core/src/cached-values.ts
+const ENTRY_FORMAT_VERSION = 1;
+const DEFAULT_CONTEXT_KIND = "user";
+const CACHED_VALUES_STORAGE_KEY_PREFIX = "configdirector-sdk:cached-values:";
+const DEFAULT_CACHING_SIZE_LIMIT_BYTES = 256 * 1024;
+const planCaching = (connectionPlan, caching, platformProvider) => {
+	var _caching$provider;
+	if (connectionPlan.kind === "stay-offline") return {
+		kind: "no cache",
+		reason: "offline mode"
+	};
+	if ((caching === null || caching === void 0 ? void 0 : caching.enabled) === false) return {
+		kind: "no cache",
+		reason: "turned off"
+	};
+	const provider = (_caching$provider = caching === null || caching === void 0 ? void 0 : caching.provider) !== null && _caching$provider !== void 0 ? _caching$provider : platformProvider === null || platformProvider === void 0 ? void 0 : platformProvider(connectionPlan.clientSdkKey);
+	if (!provider) return {
+		kind: "no cache",
+		reason: "no provider available"
+	};
+	return {
+		kind: "cache",
+		provider,
+		clientSdkKey: connectionPlan.clientSdkKey
+	};
+};
+const contextTagFor = (context, instanceId) => {
+	var _context$kind;
+	const contextKind = (_context$kind = context === null || context === void 0 ? void 0 : context.kind) !== null && _context$kind !== void 0 ? _context$kind : DEFAULT_CONTEXT_KIND;
+	if ((context === null || context === void 0 ? void 0 : context.id) != null) return {
+		contextKind,
+		contextId: context.id
+	};
+	return {
+		contextKind,
+		anonymousInstanceId: instanceId
+	};
+};
+const sameContextTag = (stored, launch) => {
+	if (stored.contextKind !== launch.contextKind) return false;
+	if ("contextId" in stored && "contextId" in launch) return stored.contextId === launch.contextId;
+	if ("anonymousInstanceId" in stored && "anonymousInstanceId" in launch) return stored.anonymousInstanceId === launch.anonymousInstanceId;
+	return false;
+};
+const decideCachedValuesAdoption = (cachedValues, launchContextTag, hasReceivedLiveValues) => {
+	if (hasReceivedLiveValues) return "live values already arrived";
+	if (!sameContextTag(cachedValues.contextTag, launchContextTag)) return "context mismatch";
+	return "adopt";
+};
+const isContextTag = (candidate) => {
+	if (!candidate || typeof candidate !== "object") return false;
+	const { contextKind, contextId, anonymousInstanceId } = candidate;
+	if (typeof contextKind !== "string") return false;
+	return typeof contextId === "string" || typeof anonymousInstanceId === "string";
+};
+const isConfigStateMap = (candidate) => {
+	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return false;
+	return Object.values(candidate).every((config) => config && typeof config === "object" && typeof config.id === "string" && typeof config.key === "string");
+};
+const isEntryFor = (clientSdkKey, candidate) => {
+	if (!candidate || typeof candidate !== "object") return false;
+	const entry = candidate;
+	return entry.formatVersion === ENTRY_FORMAT_VERSION && entry.clientSdkKey === clientSdkKey && isContextTag(entry.contextTag) && typeof entry.environmentId === "string" && typeof entry.projectId === "string" && isConfigStateMap(entry.configs) && typeof entry.receivedAt === "number";
+};
+var CachedValuesStore = class {
+	constructor(provider, clientSdkKey, logger) {
+		this.provider = provider;
+		this.clientSdkKey = clientSdkKey;
+		this.logger = logger;
+		_defineProperty(this, "warned", /* @__PURE__ */ new Set());
+		_defineProperty(this, "pendingRead", void 0);
+		_defineProperty(this, "queuedCachedValues", void 0);
+		_defineProperty(this, "writing", false);
+	}
+	read() {
+		var _this$pendingRead;
+		(_this$pendingRead = this.pendingRead) !== null && _this$pendingRead !== void 0 || (this.pendingRead = this.readEntry());
+		return this.pendingRead;
+	}
+	replace(cachedValues) {
+		this.queuedCachedValues = cachedValues;
+		this.writeQueued();
+	}
+	async readEntry() {
+		let raw;
+		try {
+			raw = await this.provider.read();
+		} catch (error) {
+			this.warnOnce("read failed", "Could not read the values kept on the device, starting without them:", error);
+			return { outcome: "failed" };
+		}
+		if (raw == null || raw === "") return { outcome: "nothing stored" };
+		const entry = this.parseEntry(raw);
+		if (!entry) {
+			this.warnOnce("unreadable", "The values kept on the device could not be read and were removed, starting without them");
+			await this.removeEntry();
+			return { outcome: "unreadable" };
+		}
+		return {
+			outcome: "stored",
+			cachedValues: entry
+		};
+	}
+	parseEntry(raw) {
+		try {
+			const candidate = JSON.parse(raw);
+			return isEntryFor(this.clientSdkKey, candidate) ? candidate : void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeQueued() {
+		if (this.writing) return;
+		this.writing = true;
+		try {
+			while (this.queuedCachedValues) {
+				const cachedValues = this.queuedCachedValues;
+				this.queuedCachedValues = void 0;
+				await this.writeEntry(cachedValues);
+			}
+		} finally {
+			this.writing = false;
+		}
+	}
+	async writeEntry(cachedValues) {
+		const entry = {
+			formatVersion: ENTRY_FORMAT_VERSION,
+			clientSdkKey: this.clientSdkKey,
+			...cachedValues
+		};
+		const serialized = JSON.stringify(entry);
+		const size = utf8ByteLength(serialized);
+		const limit = this.provider.sizeLimit();
+		if (size > limit) {
+			this.warnOnce("over the size limit", `The values received (${size} bytes) exceed the caching provider's limit of ${limit} bytes, so no values are kept on the device`);
+			await this.removeEntry();
+			return;
+		}
+		try {
+			await this.provider.write(serialized);
+		} catch (error) {
+			this.warnOnce("write failed", "Could not keep the values on the device:", error);
+		}
+	}
+	async removeEntry() {
+		try {
+			await this.provider.remove();
+		} catch (error) {
+			this.warnOnce("remove failed", "Could not remove the values kept on the device:", error);
+		}
+	}
+	warnOnce(warning, message, ...details) {
+		if (this.warned.has(warning)) return;
+		this.warned.add(warning);
+		this.logger.warn(`[ConfigDirectorClient] ${message}`, ...details);
+	}
+};
+//#endregion
 //#region ../js-client-core/src/DefaultConfigDirectorClient.ts
 const MAX_EXPONENTIAL_DELAY = 9;
-var DefaultConfigDirectorClient = class {
-	constructor(telemetryClient, clientSdkKey, sdkOptions, clientOptions, internalClientOptions) {
-		var _clientOptions$logger, _clientOptions$connec, _clientOptions$connec2, _internalClientOption, _this$parseUrl, _clientOptions$connec3, _clientOptions$connec4, _clientOptions$connec5, _internalClientOption2, _clientOptions$hooks, _clientOptions$hooks2, _clientOptions$hooks3, _clientOptions$hooks4, _clientOptions$hooks5;
+var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
+	static from(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions) {
+		if (typeof clientSdkKeyOrOptions === "object") return new DefaultConfigDirectorClient(liveTelemetryClient, void 0, sdkOptions, clientSdkKeyOrOptions, internalClientOptions);
+		return new DefaultConfigDirectorClient(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions);
+	}
+	constructor(liveTelemetryClient, clientSdkKey, sdkOptions, clientOptions, internalClientOptions) {
+		var _clientOptions$logger, _clientOptions$connec, _clientOptions$connec2, _internalClientOption, _internalClientOption2, _clientOptions$hooks, _clientOptions$hooks2, _clientOptions$hooks3, _clientOptions$hooks4, _clientOptions$hooks5, _clientOptions$hooks6;
 		_defineProperty(this, "logger", void 0);
 		_defineProperty(this, "telemetryClient", void 0);
 		_defineProperty(this, "configSet", void 0);
@@ -1145,20 +1511,24 @@ var DefaultConfigDirectorClient = class {
 		_defineProperty(this, "readyPromise", void 0);
 		_defineProperty(this, "readyResolve", void 0);
 		_defineProperty(this, "currentContext", void 0);
-		_defineProperty(this, "connectionMode", void 0);
+		_defineProperty(this, "submittedContext", void 0);
+		_defineProperty(this, "connectionPlan", void 0);
 		_defineProperty(this, "clientSession", void 0);
+		_defineProperty(this, "cachedValuesStore", void 0);
+		_defineProperty(this, "servingCachedValues", false);
+		_defineProperty(this, "cachedValuesAdoptionStarted", false);
 		this.logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createDefaultLogger();
 		this.clientSession = resolveClientSession(this.logger, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.instanceIdStorage);
 		this.timeout = (_clientOptions$connec = clientOptions === null || clientOptions === void 0 || (_clientOptions$connec2 = clientOptions.connection) === null || _clientOptions$connec2 === void 0 ? void 0 : _clientOptions$connec2.timeout) !== null && _clientOptions$connec !== void 0 ? _clientOptions$connec : 3e3;
-		this.validateSdkKeyPresence(clientSdkKey);
 		const urlFactory = (_internalClientOption = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.urlFactory) !== null && _internalClientOption !== void 0 ? _internalClientOption : defaultUrlFactory;
-		const baseUrl = (_this$parseUrl = this.parseUrl(clientOptions === null || clientOptions === void 0 || (_clientOptions$connec3 = clientOptions.connection) === null || _clientOptions$connec3 === void 0 ? void 0 : _clientOptions$connec3.url, urlFactory)) !== null && _this$parseUrl !== void 0 ? _this$parseUrl : CLIENT_BASE_URL;
-		this.connectionMode = (_clientOptions$connec4 = clientOptions === null || clientOptions === void 0 || (_clientOptions$connec5 = clientOptions.connection) === null || _clientOptions$connec5 === void 0 ? void 0 : _clientOptions$connec5.mode) !== null && _clientOptions$connec4 !== void 0 ? _clientOptions$connec4 : "streaming";
-		this.telemetryClient = telemetryClient;
-		this.transport = (_internalClientOption2 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.transport) !== null && _internalClientOption2 !== void 0 ? _internalClientOption2 : this.buildTransport(clientSdkKey, sdkOptions, baseUrl, urlFactory, clientOptions, internalClientOptions);
+		this.connectionPlan = planConnection(clientSdkKey, clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.connection, urlFactory);
+		this.cachedValuesStore = this.buildCachedValuesStore(planCaching(this.connectionPlan, clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.caching, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.platformCachingProvider));
+		this.telemetryClient = this.buildTelemetryClient(liveTelemetryClient, clientOptions);
+		this.transport = (_internalClientOption2 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.transport) !== null && _internalClientOption2 !== void 0 ? _internalClientOption2 : this.buildTransport(sdkOptions, clientOptions, urlFactory, internalClientOptions);
 		this.transport.on("configSetReceived", (configSet) => {
 			var _this$readyResolve;
 			this.hasReceivedConfigSet = true;
+			this.servingCachedValues = false;
 			(_this$readyResolve = this.readyResolve) === null || _this$readyResolve === void 0 || _this$readyResolve.call(this);
 			const removedKeys = this.findKeysRemovedBy(configSet);
 			if (!this.configSet || configSet.kind == "full") this.configSet = configSet;
@@ -1166,6 +1536,7 @@ var DefaultConfigDirectorClient = class {
 				...this.configSet.configs,
 				...configSet.configs
 			};
+			this.keepValuesOnTheDevice(this.configSet);
 			const keys = Object.keys(configSet.configs);
 			this.emit("configsUpdated", {
 				keys,
@@ -1187,14 +1558,88 @@ var DefaultConfigDirectorClient = class {
 		this.registerHandler("configsUpdated", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks3 = clientOptions.hooks) === null || _clientOptions$hooks3 === void 0 ? void 0 : _clientOptions$hooks3.configsUpdated);
 		this.registerHandler("contextUpdated", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks4 = clientOptions.hooks) === null || _clientOptions$hooks4 === void 0 ? void 0 : _clientOptions$hooks4.contextUpdated);
 		this.registerHandler("connectionError", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks5 = clientOptions.hooks) === null || _clientOptions$hooks5 === void 0 ? void 0 : _clientOptions$hooks5.connectionError);
+		this.registerHandler("cachedValuesLoaded", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks6 = clientOptions.hooks) === null || _clientOptions$hooks6 === void 0 ? void 0 : _clientOptions$hooks6.cachedValuesLoaded);
+	}
+	buildCachedValuesStore(cachingPlan) {
+		switch (cachingPlan.kind) {
+			case "no cache":
+				this.logger.debug(`[ConfigDirectorClient] No values are kept on the device: ${cachingPlan.reason}`);
+				return;
+			case "cache": {
+				const store = new CachedValuesStore(cachingPlan.provider, cachingPlan.clientSdkKey, this.logger);
+				store.read();
+				return store;
+			}
+		}
+	}
+	startCachedValuesAdoption() {
+		const store = this.cachedValuesStore;
+		if (!store || this.cachedValuesAdoptionStarted) return;
+		this.cachedValuesAdoptionStarted = true;
+		this.adoptCachedValues(store);
+	}
+	async adoptCachedValues(store) {
+		const read = await store.read();
+		switch (read.outcome) {
+			case "nothing stored":
+			case "unreadable":
+			case "failed": return;
+			case "stored": break;
+		}
+		const { instanceId } = await this.clientSession;
+		const launchContextTag = contextTagFor(this.submittedContext, instanceId);
+		const adoption = decideCachedValuesAdoption(read.cachedValues, launchContextTag, this.hasReceivedConfigSet);
+		switch (adoption) {
+			case "adopt":
+				this.serveCachedValues(read.cachedValues);
+				return;
+			case "live values already arrived":
+			case "context mismatch":
+				this.logger.debug(`[ConfigDirectorClient] The values kept on the device were not adopted: ${adoption}`);
+				return;
+		}
+	}
+	serveCachedValues(cachedValues) {
+		const { environmentId, projectId, configs } = cachedValues;
+		this.configSet = {
+			environmentId,
+			projectId,
+			configs,
+			kind: "full"
+		};
+		this.servingCachedValues = true;
+		const keys = Object.keys(configs);
+		this.emit("cachedValuesLoaded", {});
+		this.emit("configsUpdated", {
+			keys,
+			removedKeys: []
+		});
+		this.updateWatchers(keys);
+		this.logger.debug("[ConfigDirectorClient] Serving the values kept on the device until live values arrive:", { keys });
+	}
+	keepValuesOnTheDevice(configSet) {
+		const store = this.cachedValuesStore;
+		if (!store) return;
+		const context = this.submittedContext;
+		const receivedAt = Date.now();
+		this.clientSession.then(({ instanceId }) => store.replace({
+			contextTag: contextTagFor(context, instanceId),
+			environmentId: configSet.environmentId,
+			projectId: configSet.projectId,
+			configs: configSet.configs,
+			receivedAt
+		}));
+	}
+	servedReason(reason) {
+		return this.servingCachedValues && reason === "found-match" ? "cached" : reason;
 	}
 	registerHandler(event, handler) {
 		if (!handler) return;
 		const handlers = Array.isArray(handler) ? handler : [handler];
 		for (const h of handlers) if (typeof h === "function") this.on(event, h);
 	}
-	resolvePollingIntervalForMode(configuredSeconds) {
-		if (this.connectionMode !== "polling") return;
+	pollingIntervalFor(mode, configuredSeconds) {
+		if (mode !== "polling") return;
 		const resolved = resolvePollingInterval(configuredSeconds, {
 			defaultSeconds: 60,
 			minimumSeconds: 30
@@ -1202,32 +1647,49 @@ var DefaultConfigDirectorClient = class {
 		if (resolved.warning) this.logger.warn(`[ConfigDirectorClient] ${resolved.warning}`);
 		return resolved.seconds;
 	}
-	buildTransport(clientSdkKey, sdkOptions, baseUrl, urlFactory, clientOptions, internalClientOptions) {
-		var _internalClientOption3, _clientOptions$connec6;
-		return new (this.getTransportConstructor(this.connectionMode))({
-			clientSession: this.clientSession,
-			clientSdkKey,
-			baseUrl,
-			resolveUrl: urlFactory,
-			metaContext: {
-				...clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata,
-				sdkName: sdkOptions.sdkName,
-				sdkVersion: sdkOptions.sdkVersion,
-				userAgent: readUserAgent(),
-				host: readHost()
-			},
-			logger: this.logger,
-			fetch: internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.fetch,
-			connectionRetryDelay: (_internalClientOption3 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.connectionRetryDelay) !== null && _internalClientOption3 !== void 0 ? _internalClientOption3 : ((attempt) => {
-				return Math.pow(2, Math.min(attempt, MAX_EXPONENTIAL_DELAY)) * 1e3;
-			}),
-			pollingInterval: this.resolvePollingIntervalForMode(clientOptions === null || clientOptions === void 0 || (_clientOptions$connec6 = clientOptions.connection) === null || _clientOptions$connec6 === void 0 ? void 0 : _clientOptions$connec6.pollingInterval)
-		});
+	buildTelemetryClient(liveTelemetryClient, clientOptions) {
+		const plan = this.connectionPlan;
+		switch (plan.kind) {
+			case "stay-offline": return discardingTelemetryClient;
+			case "connect": return liveTelemetryClient({
+				clientSdkKey: plan.clientSdkKey,
+				baseUrl: plan.baseUrl,
+				logger: this.logger,
+				metadata: clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata
+			});
+		}
 	}
-	getTransportConstructor(connectionMode) {
-		switch (connectionMode) {
+	buildTransport(sdkOptions, clientOptions, urlFactory, internalClientOptions) {
+		const plan = this.connectionPlan;
+		switch (plan.kind) {
+			case "stay-offline": return new OfflineTransport(plan.source);
+			case "connect":
+				var _internalClientOption3, _clientOptions$connec3;
+				return new (this.getTransportConstructor(plan.mode))({
+					clientSession: this.clientSession,
+					clientSdkKey: plan.clientSdkKey,
+					baseUrl: plan.baseUrl,
+					resolveUrl: urlFactory,
+					metaContext: {
+						...clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata,
+						sdkName: sdkOptions.sdkName,
+						sdkVersion: sdkOptions.sdkVersion,
+						userAgent: readUserAgent(),
+						host: readHost()
+					},
+					logger: this.logger,
+					fetch: internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.fetch,
+					connectionRetryDelay: (_internalClientOption3 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.connectionRetryDelay) !== null && _internalClientOption3 !== void 0 ? _internalClientOption3 : ((attempt) => {
+						return Math.pow(2, Math.min(attempt, MAX_EXPONENTIAL_DELAY)) * 1e3;
+					}),
+					pollingInterval: this.pollingIntervalFor(plan.mode, clientOptions === null || clientOptions === void 0 || (_clientOptions$connec3 = clientOptions.connection) === null || _clientOptions$connec3 === void 0 ? void 0 : _clientOptions$connec3.pollingInterval)
+				});
+		}
+	}
+	getTransportConstructor(mode) {
+		switch (mode) {
 			case "polling": return PollingTransport;
-			default: return StreamingTransport;
+			case "streaming": return StreamingTransport;
 		}
 	}
 	async initialize(context) {
@@ -1235,17 +1697,28 @@ var DefaultConfigDirectorClient = class {
 		await this.submitContext(context, "initialization");
 	}
 	async updateContext(context) {
-		await this.submitContext(context, "context update");
+		switch (this.connectionPlan.kind) {
+			case "connect":
+				await this.submitContext(context, "context update");
+				return;
+			case "stay-offline":
+				this.storeContext(this.admittedContextFor(context, "context update"));
+				return;
+		}
+	}
+	storeContext(context) {
+		this.currentContext = context;
+		this.emit("contextUpdated", { context });
 	}
 	async submitContext(context, submission) {
-		await this.connectToTransport(this.contextToConnectWith(context, submission), submission);
+		await this.connectToTransport(this.admittedContextFor(context, submission), submission);
 	}
-	contextToConnectWith(suppliedContext, submission) {
+	admittedContextFor(suppliedContext, submission) {
 		const admission = admitContext(suppliedContext);
 		switch (admission.outcome) {
 			case "admitted": return admission.context;
 			case "ignored":
-				this.logger.error(`[ConfigDirectorClient] Ignored the context supplied for ${submission} because its kind '${admission.kindSample}' is invalid; connecting as if no context was supplied. A context kind has 1 to 64 characters, using only lowercase letters, digits, '-' and '_'.`);
+				this.logger.error(`[ConfigDirectorClient] Ignored the context supplied for ${submission} because its kind '${admission.kindSample}' is invalid; continuing as if no context was supplied. A context kind has 1 to 64 characters, using only lowercase letters, digits, '-' and '_'.`);
 				this.telemetryClient.recordInvalidContext(admission.kindSample);
 				return;
 		}
@@ -1254,6 +1727,8 @@ var DefaultConfigDirectorClient = class {
 		return this.currentContext;
 	}
 	async connectToTransport(context, caller) {
+		this.submittedContext = context;
+		if (caller === "initialization") this.startCachedValuesAdoption();
 		try {
 			this.ready = false;
 			this.readyPromise = new Promise((resolve) => {
@@ -1277,11 +1752,21 @@ var DefaultConfigDirectorClient = class {
 			if (remainingTimeout > 0) await Promise.race([this.readyPromise, new Promise((resolve) => {
 				this.timeoutTimer = setTimeout(() => resolve(), remainingTimeout);
 			})]).finally(() => clearTimeout(this.timeoutTimer));
-			if (!this.ready) this.logger.warn(`[ConfigDirectorClient] Timed out waiting for ${caller} after ${this.timeout}ms. The client will continue to retry since there were no fatal errors detected. Configs will return the default value until the connection succeeds.`);
+			if (!this.ready) this.logger.warn(`[ConfigDirectorClient] Timed out waiting for ${caller} after ${this.timeout}ms. ${this.timeoutWarningDetails()}`);
 		} catch (error) {
+			if (error instanceof ConfigDirectorInitializationError) {
+				this.initializing = false;
+				throw error;
+			}
 			this.logger.error(`[ConfigDirectorClient] An error occurred during ${caller}: `, error);
 		}
 	}
+	timeoutWarningDetails() {
+		switch (this.connectionPlan.kind) {
+			case "connect": return "The client will continue to retry since there were no fatal errors detected. Configs will return the default value until the connection succeeds.";
+			case "stay-offline": return "The offline values were not delivered, so configs return the default value.";
+		}
+	}
 	findKeysRemovedBy(configSet) {
 		if (!this.configSet || configSet.kind != "full") return [];
 		return Object.keys(this.configSet.configs).filter((key) => !Object.prototype.hasOwnProperty.call(configSet.configs, key));
@@ -1348,6 +1833,7 @@ var DefaultConfigDirectorClient = class {
 			return defaultValue;
 		}
 		const parseResult = parseConfigValue(configState, defaultValue);
+		const reason = this.servedReason(parseResult.reason);
 		this.telemetryClient.evaluatedConfig({
 			contextId: (_this$currentContext2 = this.currentContext) === null || _this$currentContext2 === void 0 ? void 0 : _this$currentContext2.id,
 			type: configState.type,
@@ -1357,14 +1843,14 @@ var DefaultConfigDirectorClient = class {
 			evaluatedValue: parseResult.parsedValue,
 			evaluatedValueId: parseResult.parsedValueId,
 			usedDefault: parseResult.usedDefault,
-			evaluationReason: parseResult.reason
+			evaluationReason: reason
 		});
 		this.dispatchEvaluationEvent({
 			key: configKey,
 			value: parseResult.parsedValue,
 			valueId: (_parseResult$parsedVa = parseResult.parsedValueId) !== null && _parseResult$parsedVa !== void 0 ? _parseResult$parsedVa : void 0,
 			isDefaultValue: parseResult.usedDefault,
-			reason: parseResult.reason,
+			reason,
 			context: this.context
 		});
 		this.logger.debug(`[ConfigDirectorClient] Evaluated '${configKey}' to '${parseResult.parsedValue}'`);
@@ -1380,17 +1866,6 @@ var DefaultConfigDirectorClient = class {
 			this.logger.error(`[ConfigDirectorClient] Error executing event handlers for '${name}'`, error);
 		}
 	}
-	parseUrl(url, urlFactory) {
-		if (!url) return;
-		try {
-			return urlFactory(url);
-		} catch (error) {
-			throw new ConfigDirectorValidationError(`Invalid base URL '${url}'. Parsing failed: ${error}`);
-		}
-	}
-	validateSdkKeyPresence(sdkKey) {
-		if (!sdkKey || sdkKey.trim().length == 0) throw new ConfigDirectorValidationError("No client SDK key was provided, the client cannot be instantiated without a valid client SDK key");
-	}
 	validateDefaultValue(defaultValue) {
 		if (defaultValue === void 0 || defaultValue === null) throw new ConfigDirectorValidationError("Invalid default value. The default value for a config must be defined and non-null.");
 		if (typeof defaultValue === "function") throw new ConfigDirectorValidationError("Invalid default value. The default value for a config cannot be a function.");
@@ -1416,14 +1891,24 @@ var DefaultConfigDirectorClient = class {
 		this.handlersMap.clear();
 	}
 	pauseNetwork() {
-		this.logger.debug("[ConfigDirectorClient] pauseNetwork() called, pausing transport connection");
-		clearTimeout(this.timeoutTimer);
-		this.timeoutTimer = void 0;
-		this.transport.close();
-		this.ready = false;
+		switch (this.connectionPlan.kind) {
+			case "stay-offline": return;
+			case "connect":
+				this.logger.debug("[ConfigDirectorClient] pauseNetwork() called, pausing transport connection");
+				clearTimeout(this.timeoutTimer);
+				this.timeoutTimer = void 0;
+				this.transport.close();
+				this.ready = false;
+				return;
+		}
 	}
 	async resumeNetwork() {
-		await this.connectToTransport(this.currentContext, "network resume");
+		switch (this.connectionPlan.kind) {
+			case "stay-offline": return;
+			case "connect":
+				await this.connectToTransport(this.currentContext, "network resume");
+				return;
+		}
 	}
 	async close() {
 		var _this$readyResolve2;
@@ -1445,4 +1930,4 @@ var DefaultConfigDirectorClient = class {
 const INSTALLED_TEST_CLIENT_SLOT = Symbol.for("@configdirector/installed-test-client");
 const readInstalledTestClient = () => globalThis[INSTALLED_TEST_CLIENT_SLOT];
 //#endregion
-export { CLIENT_BASE_URL as a, ConfigDirectorConnectionError as c, _defineProperty as d, fetchWithTimeout as i, ConfigDirectorValidationError as l, readInstalledTestClient as n, createDefaultLogger as o, DefaultConfigDirectorClient as r, isFetchErrorFatal as s, INSTALLED_TEST_CLIENT_SLOT as t, Emitter as u };
+export { DEFAULT_CACHING_SIZE_LIMIT_BYTES as a, createDefaultLogger as c, ConfigDirectorConnectionError as d, ConfigDirectorValidationError as f, CACHED_VALUES_STORAGE_KEY_PREFIX as i, nativeValueConfigState as l, _defineProperty as m, readInstalledTestClient as n, fetchWithTimeout as o, Emitter as p, DefaultConfigDirectorClient as r, discardingTelemetryClient as s, INSTALLED_TEST_CLIENT_SLOT as t, isFetchErrorFatal as u };