@configdirector/react-native-sdk 1.6.0 → 1.7.0

package/README.md

@@ -10,6 +10,16 @@ React Native SDK for [ConfigDirector](https://www.configdirector.com), remote co
 npm install --save @configdirector/react-native-sdk
 ```
 
+Install `@react-native-async-storage/async-storage` as well, so the SDK can keep the same client
+session for six hours across app starts. It is an optional peer dependency and works in Expo Go.
+Without it, every app start begins a new client session and the SDK logs a warning.
+
+```bash
+npm install --save @react-native-async-storage/async-storage
+# or in an Expo project
+npx expo install @react-native-async-storage/async-storage
+```
+
 ## Retrieve a value
 
 ```tsx
@@ -74,6 +84,10 @@ package's files are `.mjs` files, which the `jest-expo` and `@react-native/jest-
 transform, so a Jest setup must let `transformIgnorePatterns` transform both packages and add a
 `transform` entry for `.mjs` files; the documentation shows the configuration for both presets.
 `jest-expo` requires `@react-native/jest-preset` as a peer dependency, so install it in either case.
+The test client never touches AsyncStorage. A test that builds a real client instead, through
+`createClient` or a provider given an `sdkKey`, logs the warning that AsyncStorage is missing and
+starts a new client session under either preset; add `@babel/plugin-transform-dynamic-import` to the
+Babel test environment for that client to use the AsyncStorage Jest mock instead.
 
 ## Documentation
 

package/dist/configdirector-react-native-testing.d.mts

@@ -1,4 +1,4 @@
-import { i as ConfigDirectorContext, n as ConfigDirectorClient, o as ConfigDirectorLogger } from "./types-fcPMBgiX.mjs";
+import { i as ConfigDirectorContext, n as ConfigDirectorClient, o as ConfigDirectorLogger } from "./types-P1hoU2Ru.mjs";
 
 //#region ../shared/src/errors.d.ts
 declare class ConfigDirectorConnectionError extends Error {
@@ -102,7 +102,8 @@ interface TestClient {
   failContextUpdate(): void;
   /**
    * The context of every `initialize` and `updateContext` call, in call order. `initialize` without
-   * a context records an empty context. Resumes are not recorded.
+   * a context records an empty context, and so does a call whose context has an invalid kind, since
+   * the client connects without it. Resumes are not recorded.
    */
   readonly contextUpdates: ConfigDirectorContext[];
 }

package/dist/configdirector-react-native-testing.mjs

@@ -1,4 +1,4 @@
-import { c as ConfigDirectorConnectionError, d as _defineProperty, l as ConfigDirectorValidationError, o as createDefaultLogger, r as DefaultConfigDirectorClient, t as INSTALLED_TEST_CLIENT_SLOT, u as Emitter } from "./installedTestClient-CxGEAMOE.mjs";
+import { c as ConfigDirectorConnectionError, d as _defineProperty, l as ConfigDirectorValidationError, o as createDefaultLogger, r as DefaultConfigDirectorClient, t as INSTALLED_TEST_CLIENT_SLOT, u as Emitter } from "./installedTestClient-LWv5ji8J.mjs";
 //#region ../shared/src/testing/values.ts
 const encodeTestValue$1 = (key, value) => {
 	if (key.trim().length == 0) throw new ConfigDirectorValidationError("Invalid config key. The key of a test value cannot be empty.");
@@ -288,6 +288,7 @@ const TEST_CLIENT_SDK_KEY = "test-client";
 const noopTelemetryClient = {
 	updateContext: async () => {},
 	evaluatedConfig: () => {},
+	recordInvalidContext: () => {},
 	close: async () => {}
 };
 var InMemoryTestClient = class {
@@ -391,7 +392,7 @@ const installTestClient = (testClient) => {
 const createTestClient = (options) => {
 	return createTestClient$1({
 		sdkName: "react-native-sdk",
-		sdkVersion: "1.6.0"
+		sdkVersion: "1.7.0"
 	}, options);
 };
 //#endregion

package/dist/configdirector-react-native.d.mts

@@ -1,4 +1,4 @@
-import { a as ConfigDirectorLogMessageDecorator, c as ConfigValueType, i as ConfigDirectorContext, l as ConnectionMode, n as ConfigDirectorClient, o as ConfigDirectorLogger, r as ConfigDirectorClientOptions, s as ConfigDirectorLoggingLevel, t as ClientHooks } from "./types-fcPMBgiX.mjs";
+import { a as ConfigDirectorLogMessageDecorator, c as ConfigValueType, i as ConfigDirectorContext, l as ConnectionMode, n as ConfigDirectorClient, o as ConfigDirectorLogger, r as ConfigDirectorClientOptions, s as ConfigDirectorLoggingLevel, t as ClientHooks } from "./types-P1hoU2Ru.mjs";
 import { Component, PropsWithChildren } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 

package/dist/configdirector-react-native.mjs

@@ -1,4 +1,4 @@
-import { a as CLIENT_BASE_URL, d as _defineProperty, i as fetchWithTimeout, n as readInstalledTestClient, o as createDefaultLogger, r as DefaultConfigDirectorClient, s as isFetchErrorFatal } from "./installedTestClient-CxGEAMOE.mjs";
+import { a as CLIENT_BASE_URL, d as _defineProperty, i as fetchWithTimeout, n as readInstalledTestClient, o as createDefaultLogger, r as DefaultConfigDirectorClient, s as isFetchErrorFatal } from "./installedTestClient-LWv5ji8J.mjs";
 import React, { Component, useContext as useContext$1 } from "react";
 import { AppState, NativeModules } from "react-native";
 import { sha256 } from "@noble/hashes/sha2.js";
@@ -285,6 +285,63 @@ var EvaluatedConfigEventPreprocessor = class {
 		};
 	}
 };
+var InvalidContextSubmissions = class {
+	constructor() {
+		_defineProperty(this, "countsByKindSample", /* @__PURE__ */ new Map());
+		_defineProperty(this, "countBeyondSampleLimit", 0);
+		_defineProperty(this, "startTime", void 0);
+	}
+	record(kindSample) {
+		var _this$startTime;
+		(_this$startTime = this.startTime) !== null && _this$startTime !== void 0 || (this.startTime = /* @__PURE__ */ new Date());
+		return this.add(kindSample, 1);
+	}
+	absorb(entries) {
+		for (const entry of entries) {
+			if (this.startTime === void 0 || entry.startTime < this.startTime) this.startTime = entry.startTime;
+			this.add(entry.event.kindSample, entry.count);
+		}
+	}
+	add(kindSample, count) {
+		if (kindSample !== void 0) {
+			const knownCount = this.countsByKindSample.get(kindSample);
+			if (knownCount !== void 0) {
+				this.countsByKindSample.set(kindSample, knownCount + count);
+				return "known-kind-sample";
+			}
+			if (this.countsByKindSample.size < 20) {
+				this.countsByKindSample.set(kindSample, count);
+				return "new-kind-sample";
+			}
+		}
+		const firstBeyondSampleLimit = this.countBeyondSampleLimit === 0;
+		this.countBeyondSampleLimit += count;
+		return firstBeyondSampleLimit ? "first-beyond-sample-limit" : "beyond-sample-limit";
+	}
+	takeSnapshot() {
+		var _this$startTime2;
+		const endTime = /* @__PURE__ */ new Date();
+		const startTime = (_this$startTime2 = this.startTime) !== null && _this$startTime2 !== void 0 ? _this$startTime2 : endTime;
+		const entryOf = (count, kindSample) => ({
+			startTime,
+			endTime,
+			count,
+			event: {
+				reason: "invalid-context-kind",
+				kindSample
+			}
+		});
+		const sampledEntries = Array.from(this.countsByKindSample, ([kindSample, count]) => entryOf(count, kindSample));
+		const entries = this.countBeyondSampleLimit > 0 ? [...sampledEntries, entryOf(this.countBeyondSampleLimit)] : sampledEntries;
+		this.clear();
+		return entries;
+	}
+	clear() {
+		this.countsByKindSample.clear();
+		this.countBeyondSampleLimit = 0;
+		this.startTime = void 0;
+	}
+};
 //#endregion
 //#region ../js-client-core/src/telemetry/ClientTelemetryEventCollector.ts
 var ClientTelemetryEventCollector = class extends TelemetryEventCollector {
@@ -293,6 +350,7 @@ var ClientTelemetryEventCollector = class extends TelemetryEventCollector {
 		_defineProperty(this, "evaluationEventSnapshotPreprocessor", void 0);
 		_defineProperty(this, "reporter", void 0);
 		_defineProperty(this, "_context", void 0);
+		_defineProperty(this, "invalidContextSubmissions", new InvalidContextSubmissions());
 		this.reporter = new ClientEventReporter(options);
 		this.evaluationEventSnapshotPreprocessor = new EvaluatedConfigEventPreprocessor(options.valueIdGenerator);
 	}
@@ -306,6 +364,12 @@ var ClientTelemetryEventCollector = class extends TelemetryEventCollector {
 		if (!this.collectEvents) return;
 		this.evaluationEventQueue.push(event);
 	}
+	recordInvalidContext(kindSample) {
+		this.invalidContextSubmissions.record(kindSample);
+	}
+	absorbInvalidContextSubmissions(entries) {
+		this.invalidContextSubmissions.absorb(entries);
+	}
 	async forceFlush() {
 		this.cancelScheduledFlush();
 		await this.flushAndScheduleNext();
@@ -320,7 +384,10 @@ var ClientTelemetryEventCollector = class extends TelemetryEventCollector {
 		return await ((_this$reporter = this.reporter) === null || _this$reporter === void 0 ? void 0 : _this$reporter.report({
 			context: this._context,
 			discreteEvents: {},
-			aggregatedEvents: { evaluatedConfig: this.aggregator.aggregate(evaluationSnapshot) },
+			aggregatedEvents: {
+				evaluatedConfig: this.aggregator.aggregate(evaluationSnapshot),
+				invalidContext: this.invalidContextSubmissions.takeSnapshot()
+			},
 			droppedEvents: { evaluatedConfig: evaluationSnapshot.droppedCount }
 		}));
 	}
@@ -453,6 +520,36 @@ const resolveMetadata = (provided, logger) => {
 	return metadata;
 };
 //#endregion
+//#region src/instanceIdStorage.ts
+const lookUpAsyncStorage = async () => {
+	try {
+		const { default: storage } = await import("@react-native-async-storage/async-storage");
+		return {
+			outcome: "installed",
+			storage
+		};
+	} catch {
+		return { outcome: "not installed" };
+	}
+};
+const asyncStorageInstanceIdStorage = (logger) => {
+	const asyncStorageLookup = lookUpAsyncStorage().then((lookup) => {
+		if (lookup.outcome === "not installed") logger.warn("The ConfigDirector SDK could not find @react-native-async-storage/async-storage, so every app start counts as a new client session. Install it for the SDK to keep the client session for six hours across app starts.");
+		return lookup;
+	});
+	const installedAsyncStorage = async () => {
+		const lookup = await asyncStorageLookup;
+		switch (lookup.outcome) {
+			case "installed": return lookup.storage;
+			case "not installed": throw new Error("@react-native-async-storage/async-storage is not installed");
+		}
+	};
+	return {
+		getItem: async (key) => (await installedAsyncStorage()).getItem(key),
+		setItem: async (key, value) => (await installedAsyncStorage()).setItem(key, value)
+	};
+};
+//#endregion
 //#region src/utf8Encoder.ts
 /**
 * Encodes a string to a UTF-8 byte sequence.
@@ -607,6 +704,9 @@ var ReactNativeTelemetryClient = class {
 	evaluatedConfig(event) {
 		this.collector.evaluatedConfig(this.sanitizeEvaluatedConfigEvent(event));
 	}
+	recordInvalidContext(kindSample) {
+		this.collector.recordInvalidContext(kindSample);
+	}
 	async close() {
 		await this.collector.close();
 	}
@@ -646,7 +746,7 @@ const createClient = (clientSdkKey, clientOptions) => {
 	var _clientOptions$logger, _clientOptions$connec;
 	const sdkIdentity = {
 		sdkName: "react-native-sdk",
-		sdkVersion: "1.6.0"
+		sdkVersion: "1.7.0"
 	};
 	const logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createConsoleLogger("warn");
 	const metadata = resolveMetadata(clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata, logger);
@@ -663,7 +763,8 @@ const createClient = (clientSdkKey, clientOptions) => {
 		metadata
 	}, {
 		fetch: reactNativeStreamingFetch,
-		urlFactory
+		urlFactory,
+		instanceIdStorage: asyncStorageInstanceIdStorage(logger)
 	});
 };
 //#endregion

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

@@ -438,11 +438,15 @@ var StreamingTransport = class {
 		_defineProperty(this, "eventEmitter", new Emitter());
 		_defineProperty(this, "url", void 0);
 		_defineProperty(this, "timeoutTimer", void 0);
+		_defineProperty(this, "connectionGeneration", 0);
 		this.options = options;
 		this.logger = options.logger;
 		this.url = options.resolveUrl("client/sse/v1", options.baseUrl);
 	}
 	async connect(context, timeout) {
+		const generation = ++this.connectionGeneration;
+		const clientSession = await this.options.clientSession;
+		if (generation !== this.connectionGeneration) return this;
 		if (this.eventSource) this.close();
 		const eventSourcePromise = new Promise((resolve, reject) => {
 			this.eventSource = createEventSourceClient({
@@ -454,7 +458,8 @@ var StreamingTransport = class {
 					givenContext: context,
 					metaContext: this.options.metaContext,
 					clientSdkKey: this.options.clientSdkKey,
-					instanceId: this.options.instanceId
+					instanceId: clientSession.instanceId,
+					ephemeral: clientSession.ephemeral
 				}),
 				onMessage: ({ data }) => {
 					this.dispatchMessage(data);
@@ -520,6 +525,7 @@ var StreamingTransport = class {
 	}
 	close() {
 		var _this$eventSource;
+		this.connectionGeneration++;
 		(_this$eventSource = this.eventSource) === null || _this$eventSource === void 0 || _this$eventSource.close();
 		clearTimeout(this.timeoutTimer);
 	}
@@ -783,10 +789,11 @@ const generateInstanceId = () => {
 	});
 };
 //#endregion
-//#region ../js-client-core/src/instance-id.ts
+//#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}$/;
 const fnv1a = (input, offsetBasis) => {
@@ -802,7 +809,7 @@ 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 getLocalStorage = () => {
+const localStorageIfAvailable = () => {
 	try {
 		var _localStorage;
 		return (_localStorage = globalThis.localStorage) !== null && _localStorage !== void 0 ? _localStorage : void 0;
@@ -818,34 +825,37 @@ const isUsableRecord = (record) => {
 	if (!UUID_V4_PATTERN.test(id)) return false;
 	return checksum === checksumFor(id, createdAt);
 };
-const readStoredInstanceId = (storage, logger) => {
+const readStoredInstanceId = async (storage, logger) => {
 	let raw;
 	try {
-		raw = storage.getItem(STORAGE_KEY);
+		raw = await storage.getItem(STORAGE_KEY);
 	} catch (error) {
-		logger === null || logger === void 0 || logger.debug("[ConfigDirectorClient] Could not read the stored instance id, generating a new one", error);
-		return;
+		logger.debug("[ConfigDirectorClient] Could not read the stored instance id, using an ephemeral one", error);
+		return { outcome: "failed" };
 	}
-	if (!raw) return;
+	if (typeof raw !== "string" || raw === "") return { outcome: "nothing usable" };
 	let record;
 	try {
 		record = JSON.parse(raw);
 	} catch {
-		logger === null || logger === void 0 || logger.debug("[ConfigDirectorClient] The stored instance id is not valid JSON, generating a new one");
-		return;
+		logger.debug("[ConfigDirectorClient] The stored instance id is not valid JSON, generating a new one");
+		return { outcome: "nothing usable" };
 	}
 	if (!isUsableRecord(record)) {
-		logger === null || logger === void 0 || logger.debug("[ConfigDirectorClient] The stored instance id failed validation, generating a new one");
-		return;
+		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 === null || logger === void 0 || logger.debug("[ConfigDirectorClient] The stored instance id has expired, generating a new one");
-		return;
+		logger.debug("[ConfigDirectorClient] The stored instance id has expired, generating a new one");
+		return { outcome: "nothing usable" };
 	}
-	return record.id;
+	return {
+		outcome: "stored",
+		instanceId: record.id
+	};
 };
-const storeInstanceId = (storage, id, logger) => {
+const persistInstanceId = async (storage, id, logger) => {
 	const createdAt = Date.now();
 	const record = {
 		v: RECORD_VERSION,
@@ -854,19 +864,54 @@ const storeInstanceId = (storage, id, logger) => {
 		checksum: checksumFor(id, createdAt)
 	};
 	try {
-		storage.setItem(STORAGE_KEY, JSON.stringify(record));
+		await storage.setItem(STORAGE_KEY, JSON.stringify(record));
+		return true;
 	} catch (error) {
-		logger === null || logger === void 0 || logger.debug("[ConfigDirectorClient] Could not persist the instance id", error);
+		logger.debug("[ConfigDirectorClient] Could not persist the instance id, using it as an ephemeral one", error);
+		return false;
+	}
+};
+const settleFromStorage = async (storage, provisionalId, deadline, logger) => {
+	const read = await readStoredInstanceId(storage, logger);
+	switch (read.outcome) {
+		case "stored": return { instanceId: read.instanceId };
+		case "failed": return {
+			instanceId: provisionalId,
+			ephemeral: true
+		};
+		case "nothing usable": break;
 	}
+	if (deadline.passed) return {
+		instanceId: provisionalId,
+		ephemeral: true
+	};
+	return await persistInstanceId(storage, provisionalId, logger) ? { instanceId: provisionalId } : {
+		instanceId: provisionalId,
+		ephemeral: true
+	};
 };
-const resolveInstanceId = (logger) => {
-	const storage = getLocalStorage();
-	if (!storage) return generateInstanceId();
-	const storedInstanceId = readStoredInstanceId(storage, logger);
-	if (storedInstanceId) return storedInstanceId;
-	const instanceId = generateInstanceId();
-	storeInstanceId(storage, instanceId, logger);
-	return instanceId;
+const resolveClientSession = (logger, storage = localStorageIfAvailable()) => {
+	const provisionalId = generateInstanceId();
+	if (!storage) {
+		logger.debug("[ConfigDirectorClient] No instance id storage is available, using an ephemeral instance id");
+		return Promise.resolve({
+			instanceId: provisionalId,
+			ephemeral: true
+		});
+	}
+	const deadline = { passed: false };
+	let deadlineTimer;
+	const fallbackAtDeadline = new Promise((resolve) => {
+		deadlineTimer = setTimeout(() => {
+			deadline.passed = true;
+			logger.warn(`[ConfigDirectorClient] The instance id storage did not respond within ${STORAGE_DEADLINE_MS}ms, using an ephemeral instance id`);
+			resolve({
+				instanceId: provisionalId,
+				ephemeral: true
+			});
+		}, STORAGE_DEADLINE_MS);
+	});
+	return Promise.race([settleFromStorage(storage, provisionalId, deadline, logger), fallbackAtDeadline]).finally(() => clearTimeout(deadlineTimer));
 };
 //#endregion
 //#region ../shared/src/transport/AbstractPollingTransport.ts
@@ -954,25 +999,33 @@ var PollingTransport = class extends AbstractPollingTransport {
 		_defineProperty(this, "eventEmitter", new Emitter());
 		_defineProperty(this, "url", void 0);
 		_defineProperty(this, "lastUpdateTimestamp", void 0);
+		_defineProperty(this, "connectionGeneration", 0);
 		this.options = options;
 		this.logger = options.logger;
 		this.url = options.resolveUrl("client/polling/v1", options.baseUrl);
 		this.pollingIntervalSeconds = (_options$pollingInter = options.pollingInterval) !== null && _options$pollingInter !== void 0 ? _options$pollingInter : 60;
 	}
 	async connect(context, timeout) {
+		const generation = ++this.connectionGeneration;
 		this.clearPollingInterval();
+		const clientSession = await this.options.clientSession;
+		if (generation !== this.connectionGeneration) return this;
 		try {
-			await this.fetchConfigs(context, timeout);
+			await this.fetchConfigs(context, timeout, clientSession);
 		} finally {
 			if (!this.fatalError) this.schedulePollingInterval(() => {
-				this.fetchConfigs(context, timeout).catch((error) => {
+				this.fetchConfigs(context, timeout, clientSession).catch((error) => {
 					this.logger.error("[PollingTransport] Error during polling:", error);
 				});
 			});
 		}
 		return this;
 	}
-	async fetchConfigs(context, timeout) {
+	close() {
+		this.connectionGeneration++;
+		super.close();
+	}
+	async fetchConfigs(context, timeout, clientSession) {
 		if (this.fatalError) {
 			this.logger.warn("[PollingTransport] There was a prior unrecoverable error. Ignoring attempt to reconnect.");
 			return;
@@ -985,7 +1038,8 @@ var PollingTransport = class extends AbstractPollingTransport {
 					givenContext: context,
 					metaContext: this.options.metaContext,
 					clientSdkKey: this.options.clientSdkKey,
-					instanceId: this.options.instanceId,
+					instanceId: clientSession.instanceId,
+					ephemeral: clientSession.ephemeral,
 					lastUpdateTimestamp: this.lastUpdateTimestamp
 				})
 			}, this.logger);
@@ -1032,6 +1086,46 @@ const readHost = () => read((globals) => {
 	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;
+const isContextKindCharacter = (character) => character >= "a" && character <= "z" || character >= "0" && character <= "9" || character === "-" || character === "_";
+const isValidContextKind = (kind) => {
+	if (kind.length < 1 || kind.length > CONTEXT_KIND_MAXIMUM_LENGTH) return false;
+	for (const character of kind) if (!isContextKindCharacter(character)) return false;
+	return true;
+};
+const isAcceptedKind = (kind) => kind === void 0 || kind === null || typeof kind === "string" && isValidContextKind(kind);
+const stringFormOf = (kind) => {
+	if (typeof kind === "string") return kind;
+	try {
+		return String(kind);
+	} catch {
+		return Object.prototype.toString.call(kind);
+	}
+};
+const firstCharactersOf = (text, maximumCharacters) => {
+	let sample = "";
+	let characterCount = 0;
+	for (const character of text) {
+		if (characterCount === maximumCharacters) break;
+		sample += character;
+		characterCount += 1;
+	}
+	return sample;
+};
+const admitContext = (context) => {
+	const kind = context === null || context === void 0 ? void 0 : context.kind;
+	if (isAcceptedKind(kind)) return {
+		outcome: "admitted",
+		context
+	};
+	return {
+		outcome: "ignored",
+		kindSample: firstCharactersOf(stringFormOf(kind), KIND_SAMPLE_MAXIMUM_CHARACTERS)
+	};
+};
+//#endregion
 //#region ../js-client-core/src/DefaultConfigDirectorClient.ts
 const MAX_EXPONENTIAL_DELAY = 9;
 var DefaultConfigDirectorClient = class {
@@ -1052,9 +1146,9 @@ var DefaultConfigDirectorClient = class {
 		_defineProperty(this, "readyResolve", void 0);
 		_defineProperty(this, "currentContext", void 0);
 		_defineProperty(this, "connectionMode", void 0);
-		_defineProperty(this, "instanceId", void 0);
+		_defineProperty(this, "clientSession", void 0);
 		this.logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createDefaultLogger();
-		this.instanceId = resolveInstanceId(this.logger);
+		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;
@@ -1111,7 +1205,7 @@ var DefaultConfigDirectorClient = class {
 	buildTransport(clientSdkKey, sdkOptions, baseUrl, urlFactory, clientOptions, internalClientOptions) {
 		var _internalClientOption3, _clientOptions$connec6;
 		return new (this.getTransportConstructor(this.connectionMode))({
-			instanceId: this.instanceId,
+			clientSession: this.clientSession,
 			clientSdkKey,
 			baseUrl,
 			resolveUrl: urlFactory,
@@ -1138,10 +1232,23 @@ var DefaultConfigDirectorClient = class {
 	}
 	async initialize(context) {
 		if (!this.hasReceivedConfigSet) this.initializing = true;
-		await this.connectToTransport(context, "initialization");
+		await this.submitContext(context, "initialization");
 	}
 	async updateContext(context) {
-		await this.connectToTransport(context, "context update");
+		await this.submitContext(context, "context update");
+	}
+	async submitContext(context, submission) {
+		await this.connectToTransport(this.contextToConnectWith(context, submission), submission);
+	}
+	contextToConnectWith(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.telemetryClient.recordInvalidContext(admission.kindSample);
+				return;
+		}
 	}
 	get context() {
 		return this.currentContext;
@@ -1161,7 +1268,7 @@ var DefaultConfigDirectorClient = class {
 			const startTime = (/* @__PURE__ */ new Date()).getTime();
 			await this.transport.connect(context !== null && context !== void 0 ? context : {}, this.timeout, caller);
 			this.currentContext = context;
-			this.telemetryClient.updateContext(context);
+			this.telemetryClient.updateContext(context).catch((error) => this.logger.warn("[ConfigDirectorClient] Telemetry could not update the context: ", error));
 			this.emit("contextUpdated", { context });
 			const elapsedTime = (/* @__PURE__ */ new Date()).getTime() - startTime;
 			const remainingTimeout = this.timeout - elapsedTime;
@@ -1323,7 +1430,7 @@ var DefaultConfigDirectorClient = class {
 		this.logger.debug("[ConfigDirectorClient] close() has been called, closing connection to server");
 		clearTimeout(this.timeoutTimer);
 		(_this$readyResolve2 = this.readyResolve) === null || _this$readyResolve2 === void 0 || _this$readyResolve2.call(this, true);
-		this.telemetryClient.close();
+		this.telemetryClient.close().catch((error) => this.logger.warn("[ConfigDirectorClient] Telemetry could not close: ", error));
 		this.transport.close();
 		this.ready = false;
 		this.initializing = false;

package/dist/{types-fcPMBgiX.d.mts → types-P1hoU2Ru.d.mts}

@@ -33,27 +33,40 @@ type ConfigEvaluation = {
   context?: ConfigDirectorContext;
 };
 /**
- * The user's context to be sent to ConfigDirector. This context will be used for targeting
- * rules evaluation.
+ * The context to be sent to ConfigDirector: the user or other entity, such as a device or an
+ * organization, that configs are evaluated for. This context will be used for targeting rules
+ * evaluation.
  */
 type ConfigDirectorContext = {
   /**
-   * The user's identifier. This should be a value that uniquely identifies an application
-   * user.
+   * The context's identifier. This should be a value that uniquely identifies the user or other
+   * entity among contexts of the same {@link kind}.
    * In the case of anonymous users, you could generate a UUID or alternatively not provide
    * the {@link id} and the SDK will generate a random UUID. However, keep in mind that this
-   * value is used for segmenting users in percentage rollouts, and changes to the {@link id}
-   * could result in the user being assigned to a different percentile.
+   * value is used for segmenting contexts in percentage rollouts, and changes to the {@link id}
+   * could result in the context being assigned to a different percentile.
    */
   id?: string;
   /**
-   * The user's display name. This will be shown in the ConfigDirector dashboard and may be
+   * The kind of entity this context represents, such as `user`, `device`, `organization`,
+   * `tenant` or `listing`. You can use any other kind that fits your application. A kind has 1
+   * to 64 characters, using only lowercase letters (`a`-`z`), digits, `-` and `_`. It is used
+   * exactly as given, without trimming or changing its case.
+   *
+   * A context with an invalid kind is ignored as a whole: the SDK logs an error and evaluates
+   * as if no context had been provided.
+   *
+   * @default "user"
+   */
+  kind?: string;
+  /**
+   * The context's display name. This will be shown in the ConfigDirector dashboard and may be
    * used for targeting rules.
    */
   name?: string;
   /**
-   * Any arbitrary traits for the current user. They will be shown in the ConfigDirector
-   * dashboard and may be used for targeting rules.
+   * Any arbitrary traits for the context. They will be shown in the ConfigDirector dashboard
+   * and may be used for targeting rules.
    */
   traits?: {
     [key: string]: unknown;
@@ -202,17 +215,25 @@ interface ConfigDirectorClient extends EventProvider<ClientEvents> {
    * not attempt to re-connect and an error will be logged to the console or the provided
    * logger.
    *
-   * @param context The current user's context to be used for evaluating targeting rules (optional).
+   * A context whose {@link ConfigDirectorContext.kind} is invalid is ignored as a whole: an error is
+   * logged, and the client connects as if no context had been provided.
+   *
+   * @param context The current context to be used for evaluating targeting rules (optional).
    */
   initialize(context?: ConfigDirectorContext): Promise<void>;
   /**
-   * Updates the user's context and re-evaluates all config and flag values based on the new context.
+   * Updates the context and re-evaluates all config and flag values based on the new context.
+   *
+   * A context whose {@link ConfigDirectorContext.kind} is invalid is ignored as a whole: an error is
+   * logged, the previous context is no longer used, and the client connects as if no context had been
+   * provided.
    *
-   * @param context The current user's context to be used for evaluating targeting rules (required).
+   * @param context The current context to be used for evaluating targeting rules (required).
    */
   updateContext(context: ConfigDirectorContext): Promise<void>;
   /**
-   * Returns the current context the client is configured with, or undefined if there is no context.
+   * Returns the current context the client is configured with, or undefined if there is no context,
+   * including after a context with an invalid kind was ignored.
    *
    * Note that the value returned does not updated immediately after calling {@link updateContext}. Only
    * once the underlying connection was successful or timed out, the current context is updated. This is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/react-native-sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "React Native client SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",
@@ -71,7 +71,9 @@
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",
+    "@babel/plugin-transform-dynamic-import": "^7",
     "@eslint/js": "^10.0.1",
+    "@react-native-async-storage/async-storage": "^3.1.1",
     "@react-native/babel-preset": "^0.85.0",
     "@react-native/jest-preset": "^0.86.2",
     "@rollup/plugin-replace": "^6.0.3",
@@ -96,11 +98,15 @@
     "wtfnode": "^0.10.1"
   },
   "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.0.0",
     "expo": ">=52",
     "react": "*",
     "react-native": ">=0.75"
   },
   "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
     "expo": {
       "optional": true
     }
@@ -130,7 +136,7 @@
       "^@eventsource/(.*)$": "<rootDir>/../eventsource/src/$1"
     },
     "transformIgnorePatterns": [
-      "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@noble)/)"
+      "node_modules/(?!((jest-)?react-native|@react-native(-community|-async-storage)?|@noble)/)"
     ]
   }
 }