@configdirector/react-native-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,121 +1,12 @@
 # ConfigDirector React Native SDK
 
-## Getting started
+This is the React Native SDK for [ConfigDirector](https://www.configdirector.com).
 
-### 1. Install
+## Documentation
 
-Install from NPM:
+Refer to the [official documentation for the React Native SDK](https://docs.configdirector.com/sdks/mobile/react-native).
 
-```bash
-npm install --save @configdirector/react-native-sdk
-```
-
-### 2. Initialize the provider using your client SDK key
-
-```tsx
-import { View } from "react-native";
-import AwesomeApp from "./AwesomeApp";
-import { ConfigDirectorProvider } from "@configdirector/react-native-sdk";
-
-export default function App() {
-  return (
-    <ConfigDirectorProvider
-      sdkKey={"YOUR-CLIENT-SDK-KEY"}
-      appName="MyAwesomeApp"
-      appVersion="1.0.0">
-      <View>
-        <AwesomeApp />
-      </View>
-    </ConfigDirectorProvider>
-  );
-}
-```
-
-### 3. Retrieve config values
-
-Retrieve a config value with the `useConfigValue` hook:
-
-```tsx
-import { useConfigValue } from "@configdirector/react-native-sdk";
-
-function MyComponent() {
-  const { value } = useConfigValue<string>("my-config", "default value");
-
-  return <p>My config value: {value}</p>;
-}
-
-export default MyComponent;
-```
-
-You can also determine if the client is still initializing, so rather than transition from the default value to the evaluated value, you can show a loading state until the client is ready and config values are evaluated:
-
-```tsx
-import { useConfigValue } from "@configdirector/react-native-sdk";
-
-function MyComponent() {
-  const { value, loading } = useConfigValue<string>(
-    "my-config",
-    "default value",
-  );
-
-  if (loading) {
-    return <p>Loading...</p>;
-  } else {
-    return <p>My config value: {value}</p>;
-  }
-}
-
-export default MyComponent;
-```
-
-### 4. Updating the user context
-
-Update the user context with the `useContext` hook:
-
-```tsx
-import {
-  useConfigValue,
-  useContext,
-} from "@configdirector/react-native-sdk";
-
-function MyComponent() {
-  const { value: myConfigValue } = useConfigValue<string>(
-    "my-config",
-    "default value",
-  );
-  const { updateContext } = useContext();
-
-  useEffect(() => {
-    updateContext({
-      id: "54321",
-      name: "Another User",
-      traits: { customProperty: "customValue" },
-    });
-  }, []);
-
-  return <p>My config value: {myConfigValue}</p>;
-}
-
-export default MyComponent;
-```
-
-## Requirements
-
-- React Native **0.71 or later** (requires `ReadableStream` support)
-- **Hermes** is strongly recommended. JavaScriptCore (JSC) is supported via a built-in UTF-8 fallback, but Hermes is the default engine in RN 0.70+ and provides better performance.
-
-## Expo
-
-This SDK is compatible with both **Expo managed workflow** and **bare workflow**.
-
-- In the **managed workflow**, Hermes is the default engine — no additional setup needed.
-- In the **bare workflow**, ensure Hermes is enabled in your `Podfile` (iOS) and `gradle.properties` (Android), which is the default in Expo SDK 47+.
-
-Expo SDK 48 (RN 0.71) or later is required.
-
-## License
-
-MIT
+There is also [a quickstart guide for ConfigDirector and any of our SDKs](https://docs.configdirector.com/getting-started/quickstart).
 
 ## Getting Help
 

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

@@ -61,6 +61,7 @@ type ConfigDirectorMetaContext = {
   appVersion?: string;
   appName?: string;
 };
+type ConnectionMode = "streaming" | "polling" | "one-time";
 //#endregion
 //#region ../js-client-core/src/types.d.ts
 /**
@@ -76,18 +77,26 @@ type ConfigDirectorClientOptions = {
    */
   connection?: {
     /**
-     * Whether to open a streaming connection or use a one-time pull of configuration state.
-     * If set to true, the streaming connection will remain open and receive updates whenever
+     * The connection mode to be used, one of `streaming` (default), `polling`, or `one-time`.
+     * If set to `streaming`, the connection will remain open and receive updates whenever
      * config state is updated on the ConfigDirector dashboard.
-     * When set to false, there will be an initial request to retrieve config state during
-     * initialization, and an additional request whenever {@link ConfigDirectorClient.updateContext}
-     * is called. But not updates will be received after those requests.
+     * When set to `polling`, there will be an initial request to retrieve config state during
+     * initialization, and additional requests on a `pollingInterval`.
+     * The `one-time` connection mode will only retrieve config state during initialization and
+     * context updates. It will not poll for regular updates.
      *
-     * Defaults to true (streaming connection)
+     * Defaults to `streaming`
      */
-    streaming?: boolean;
+    mode?: ConnectionMode;
     /**
-     * The timeout, in milliseconds, to be used in initialization and when updating the context.
+     * The polling interval in _seconds_ when the `mode` is set to `polling`. This option has no
+     * effect when the `mode` is set to `streaming` or `one-time`.
+     *
+     * Defaults to 60 seconds
+     */
+    pollingInterval?: number;
+    /**
+     * The timeout, in _milliseconds_, to be used in initialization and when updating the context.
      * If streaming is enabled, the operation (initialization or context update) may still succeed
      * after it times out if no unrecoverable errors are encountered (like an invalid SDK key).
      * If streaming is disabled, if the operation times out, it will not be retried.
@@ -246,7 +255,7 @@ declare class DefaultConsoleLogger implements ConfigDirectorLogger {
   info(message: string, ...args: any): void;
   warn(message: string, ...args: any): void;
   error(message: string, ...args: any): void;
-  private log;
+  protected log(loggerFunction: (...args: any) => void, level: ConfigDirectorLoggingLevel, message: string, ...args: any): void;
 }
 //#endregion
 //#region src/types.d.ts

package/dist/configdirector-react-native.mjs

@@ -679,6 +679,61 @@ const createDefaultLogger = (level, messageDecorator) => {
 	return new DefaultConsoleLogger(level !== null && level !== void 0 ? level : "warn", messageDecorator !== null && messageDecorator !== void 0 ? messageDecorator : new LogMessageDecorator());
 };
 //#endregion
+//#region ../shared/src/transport/AbstractPollingTransport.ts
+var AbstractPollingTransport = class {
+	constructor() {
+		_defineProperty(this, "fatalError", false);
+		_defineProperty(this, "pollingInterval", void 0);
+		_defineProperty(this, "pollingIntervalSeconds", 60);
+	}
+	clearPollingInterval() {
+		clearInterval(this.pollingInterval);
+	}
+	schedulePollingInterval(callback) {
+		clearInterval(this.pollingInterval);
+		if (this.pollingIntervalSeconds <= 0) return;
+		this.pollingInterval = setInterval(callback, this.pollingIntervalSeconds * 1e3);
+	}
+	async handleNonOkResponse(response) {
+		if (!response.ok) if (this.isStatusFatal(response.status)) {
+			this.fatalError = true;
+			throw this.prepareFatalResponseStatusError(response.status, await response.text());
+		} else throw new ConfigDirectorConnectionError(`Connection failed with status: ${response.status}`, response.status);
+	}
+	handleFetchError(fetchError) {
+		if (this.isFetchErrorFatal(fetchError)) {
+			this.fatalError = true;
+			this.close();
+			throw new ConfigDirectorConnectionError(`Connection failed with fatal error: ${fetchError}. This is an unrecoverable error, retry attempts will be ignored.`);
+		} else if (fetchError instanceof SyntaxError) throw new ConfigDirectorConnectionError(`Failed to parse the response from the server: ${fetchError}`);
+		else throw new ConfigDirectorConnectionError(`Connection failed with error: ${fetchError}.`);
+	}
+	prepareFatalResponseStatusError(responseStatus, errorBody) {
+		var _errorBody$trim$lengt, _errorBody$trim;
+		const status = responseStatus !== null && responseStatus !== void 0 ? responseStatus : 0;
+		return new ConfigDirectorConnectionError(`${`Connection failed with status: ${responseStatus !== null && responseStatus !== void 0 ? responseStatus : "unknown"}`}${((_errorBody$trim$lengt = errorBody === null || errorBody === void 0 || (_errorBody$trim = errorBody.trim()) === null || _errorBody$trim === void 0 ? void 0 : _errorBody$trim.length) !== null && _errorBody$trim$lengt !== void 0 ? _errorBody$trim$lengt : 0) > 0 ? ` (${errorBody})` : ""}. This is an unrecoverable error, retry attempts will be ignored.`, status);
+	}
+	isStatusFatal(status) {
+		return !!status && status >= 400 && status < 500;
+	}
+	isFetchErrorFatal(fetchError) {
+		if ((fetchError === null || fetchError === void 0 ? void 0 : fetchError.name) === "NotAllowedError") return true;
+		else if (fetchError instanceof TypeError) return true;
+		return false;
+	}
+	get isConnected() {
+		return this.pollingInterval !== void 0;
+	}
+	close() {
+		clearInterval(this.pollingInterval);
+		this.pollingInterval = void 0;
+	}
+	dispose() {
+		this.close();
+		this.clear();
+	}
+};
+//#endregion
 //#region ../shared/src/fetchWithTimeout.ts
 const fetchWithTimeout = async (timeout, resource, options, logger) => {
 	const abortController = new AbortController();
@@ -700,22 +755,35 @@ const fetchWithTimeout = async (timeout, resource, options, logger) => {
 	}
 };
 //#endregion
-//#region ../js-client-core/src/PullTransport.ts
-var PullTransport = class {
+//#region ../js-client-core/src/PollingTransport.ts
+var PollingTransport = class extends AbstractPollingTransport {
 	constructor(options) {
+		var _options$pollingInter;
+		super();
 		this.options = options;
 		_defineProperty(this, "logger", void 0);
 		_defineProperty(this, "eventEmitter", new Emitter());
 		_defineProperty(this, "url", void 0);
-		_defineProperty(this, "fatalError", false);
+		_defineProperty(this, "lastUpdateTimestamp", void 0);
 		this.options = options;
 		this.logger = options.logger;
-		this.url = options.resolveUrl("client/pull/v1", options.baseUrl);
+		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) {
+		this.clearPollingInterval();
+		await this.fetchConfigs(context, timeout);
+		this.schedulePollingInterval(() => {
+			this.fetchConfigs(context, timeout).catch((error) => {
+				this.logger.error("[PollingTransport] Error during polling:", error);
+			});
+		});
+		return this;
+	}
+	async fetchConfigs(context, timeout) {
 		if (this.fatalError) {
-			this.logger.warn("[PullTransport] There was a prior unrecoverable error. Ignoring attempt to reconnect.");
-			return this;
+			this.logger.warn("[PollingTransport] There was a prior unrecoverable error. Ignoring attempt to reconnect.");
+			return;
 		}
 		try {
 			const response = await fetchWithTimeout(timeout, this.url, {
@@ -724,32 +792,20 @@ var PullTransport = class {
 				body: JSON.stringify({
 					givenContext: context,
 					metaContext: this.options.metaContext,
-					clientSdkKey: this.options.clientSdkKey
+					clientSdkKey: this.options.clientSdkKey,
+					lastUpdateTimestamp: this.lastUpdateTimestamp
 				})
 			}, this.logger);
-			if (!response.ok) if (this.isStatusFatal(response.status)) {
-				this.fatalError = true;
-				throw this.prepareFatalResponseStatusError(response.status, await response.text());
-			} else throw new ConfigDirectorConnectionError(`Connection failed with status: ${response.status}`, response.status);
-			const json = JSON.parse(await response.text());
-			this.eventEmitter.emit("configSetReceived", json);
-			return this;
+			await this.handleNonOkResponse(response);
+			if (response.status == 200) {
+				const json = JSON.parse(await response.text());
+				this.lastUpdateTimestamp = json.timestamp;
+				this.eventEmitter.emit("configSetReceived", json);
+			}
 		} catch (fetchError) {
-			if (isFetchErrorFatal(fetchError)) {
-				this.fatalError = true;
-				throw new ConfigDirectorConnectionError(`Connection failed with fatal error: ${fetchError}. This is an unrecoverable error, retry attempts will be ignored.`);
-			} else if (fetchError instanceof SyntaxError) throw new ConfigDirectorConnectionError(`Failed to parse the response from the server: ${fetchError}`);
-			else throw new ConfigDirectorConnectionError(`Connection failed with error: ${fetchError}.`);
+			this.handleFetchError(fetchError);
 		}
 	}
-	prepareFatalResponseStatusError(responseStatus, errorBody) {
-		var _errorBody$trim$lengt, _errorBody$trim;
-		const status = responseStatus !== null && responseStatus !== void 0 ? responseStatus : 0;
-		return new ConfigDirectorConnectionError(`${`Connection failed with status: ${responseStatus !== null && responseStatus !== void 0 ? responseStatus : "unknown"}`}${((_errorBody$trim$lengt = errorBody === null || errorBody === void 0 || (_errorBody$trim = errorBody.trim()) === null || _errorBody$trim === void 0 ? void 0 : _errorBody$trim.length) !== null && _errorBody$trim$lengt !== void 0 ? _errorBody$trim$lengt : 0) > 0 ? ` (${errorBody})` : ""}. This is an unrecoverable error, retry attempts will be ignored.`, status);
-	}
-	isStatusFatal(status) {
-		return !!status && status >= 400 && status < 500;
-	}
 	on(name, handler) {
 		this.eventEmitter.on(name, handler);
 	}
@@ -759,10 +815,13 @@ var PullTransport = class {
 	clear() {
 		this.eventEmitter.clear();
 	}
-	close() {}
-	dispose() {
-		this.close();
-		this.clear();
+};
+//#endregion
+//#region ../js-client-core/src/OneTimeTransport.ts
+var OneTimeTransport = class extends PollingTransport {
+	constructor(options) {
+		super(options);
+		this.pollingIntervalSeconds = 0;
 	}
 };
 //#endregion
@@ -776,7 +835,7 @@ const CLIENT_BASE_URL = "https://client-sdk-api.configdirector.com";
 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, _navigator, _internalClientOption2;
+		var _clientOptions$logger, _clientOptions$connec, _clientOptions$connec2, _internalClientOption, _this$parseUrl, _clientOptions$connec3, _clientOptions$connec4, _clientOptions$connec5, _navigator, _internalClientOption2, _clientOptions$connec6;
 		_defineProperty(this, "logger", void 0);
 		_defineProperty(this, "telemetryClient", void 0);
 		_defineProperty(this, "configSet", void 0);
@@ -790,13 +849,13 @@ var DefaultConfigDirectorClient = class {
 		_defineProperty(this, "readyPromise", void 0);
 		_defineProperty(this, "readyResolve", void 0);
 		_defineProperty(this, "currentContext", void 0);
-		_defineProperty(this, "streaming", void 0);
+		_defineProperty(this, "connectionMode", void 0);
 		this.logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createDefaultLogger();
 		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;
 		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.streaming = (clientOptions === null || clientOptions === void 0 || (_clientOptions$connec4 = clientOptions.connection) === null || _clientOptions$connec4 === void 0 ? void 0 : _clientOptions$connec4.streaming) === false ? false : true;
-		const transportConstructor = this.streaming ? StreamingTransport : PullTransport;
+		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";
+		const transportConstructor = this.getTransportConstructor(this.connectionMode);
 		this.telemetryClient = telemetryClient;
 		this.transport = new transportConstructor({
 			clientSdkKey,
@@ -812,7 +871,8 @@ var DefaultConfigDirectorClient = class {
 			fetch: internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.fetch,
 			connectionRetryDelay: (_internalClientOption2 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.connectionRetryDelay) !== null && _internalClientOption2 !== void 0 ? _internalClientOption2 : ((attempt) => {
 				return Math.pow(2, Math.min(attempt, MAX_EXPONENTIAL_DELAY)) * 1e3;
-			})
+			}),
+			pollingInterval: clientOptions === null || clientOptions === void 0 || (_clientOptions$connec6 = clientOptions.connection) === null || _clientOptions$connec6 === void 0 ? void 0 : _clientOptions$connec6.pollingInterval
 		});
 		this.transport.on("configSetReceived", (configSet) => {
 			var _this$readyResolve;
@@ -833,6 +893,13 @@ var DefaultConfigDirectorClient = class {
 			this.logger.debug("[ConfigDirectorClient] ConfigSet updated from server:", { keys: configKeys });
 		});
 	}
+	getTransportConstructor(connectionMode) {
+		switch (connectionMode) {
+			case "one-time": return OneTimeTransport;
+			case "polling": return PollingTransport;
+			default: return StreamingTransport;
+		}
+	}
 	async initialize(context) {
 		this.initializing = true;
 		await this.connectToTransport(context, "initialization");
@@ -866,10 +933,7 @@ 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) {
-				const warningDetails = this.streaming ? "The client will continue to retry since there were no fatal errors detected. Configs will return the default value until the connection succeeds." : "Since the client was configured without streaming, configs may not update and always return the default value.";
-				this.logger.warn(`[ConfigDirectorClient] Timed out waiting for ${caller} after ${this.timeout}ms. ${warningDetails}`);
-			}
+			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.`);
 		} catch (error) {
 			this.logger.error(`[ConfigDirectorClient] An error occurred during ${caller}: `, error);
 		}
@@ -1303,6 +1367,11 @@ const encodeManually = (str) => {
 };
 //#endregion
 //#region src/reactNativeStreamingFetch.ts
+const abortError = (message) => {
+	const err = new Error(message);
+	err.name = "AbortError";
+	return err;
+};
 /**
 * A fetch-compatible function for React Native that uses XMLHttpRequest to
 * support streaming SSE responses. React Native's built-in fetch accumulates
@@ -1312,7 +1381,7 @@ const encodeManually = (str) => {
 */
 const reactNativeStreamingFetch = (url, init) => {
 	var _init$signal;
-	if ((_init$signal = init.signal) === null || _init$signal === void 0 ? void 0 : _init$signal.aborted) return Promise.reject(new DOMException("Request was aborted before it was opened", "AbortError"));
+	if ((_init$signal = init.signal) === null || _init$signal === void 0 ? void 0 : _init$signal.aborted) return Promise.reject(abortError("Request was aborted before it was opened"));
 	return new Promise((resolve, reject) => {
 		var _init$method, _ref;
 		const xhr = new XMLHttpRequest();
@@ -1356,7 +1425,7 @@ const reactNativeStreamingFetch = (url, init) => {
 		};
 		if (init.signal) init.signal.addEventListener("abort", () => {
 			xhr.abort();
-			if (!responseResolved) reject(new DOMException("Request was aborted", "AbortError"));
+			if (!responseResolved) reject(abortError("Request was aborted"));
 			else try {
 				streamController.close();
 			} catch {}
@@ -1423,7 +1492,7 @@ const createClient = (clientSdkKey, clientOptions) => {
 	const logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createConsoleLogger("warn");
 	return new DefaultConfigDirectorClient(new ReactNativeTelemetryClient(clientSdkKey, (clientOptions === null || clientOptions === void 0 || (_clientOptions$connec = clientOptions.connection) === null || _clientOptions$connec === void 0 ? void 0 : _clientOptions$connec.url) ? urlFactory(clientOptions.connection.url) : CLIENT_BASE_URL, logger, urlFactory), clientSdkKey, {
 		sdkName: "react-native-sdk",
-		sdkVersion: "0.2.0"
+		sdkVersion: "0.3.0"
 	}, {
 		...clientOptions,
 		logger

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/react-native-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React Native client SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",
@@ -21,7 +21,7 @@
   "homepage": "https://www.configdirector.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ConfigDirector/js-sdks"
+    "url": "git+https://github.com/ConfigDirector/js-sdks.git"
   },
   "main": "./dist/configdirector-react-native.mjs",
   "types": "./dist/configdirector-react-native.d.mts",
@@ -39,7 +39,7 @@
   ],
   "scripts": {
     "example": "yarn workspace @configdirector/react-native-sdk-example",
-    "clean": "del-cli dist",
+    "clean": "rm -fr dist",
     "build": "tsdown",
     "prepare": "yarn build",
     "typecheck": "tsc",
@@ -78,9 +78,9 @@
     "wtfnode": "^0.10.1"
   },
   "peerDependencies": {
-    "expo": ">=48",
+    "expo": ">=52",
     "react": "*",
-    "react-native": ">=0.71"
+    "react-native": ">=0.75"
   },
   "peerDependenciesMeta": {
     "expo": {