@configdirector/react-native-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConfigDirector
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# ConfigDirector React Native SDK
+
+## Getting started
+
+### 1. Install
+
+Install from NPM:
+
+```bash
+npm install --save @configdirector/react-native-sdk
+```
+
+
+## Usage
+
+
+```tsx
+import { createClient } from "@configdirector/react-native-sdk";
+
+```
+
+
+## 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

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

@@ -0,0 +1,309 @@
+import { Component, PropsWithChildren } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region ../js-client-core/src/Emitter.d.ts
+type EventType = string | symbol;
+type EventsRecord = Record<EventType, any>;
+type Handler<TEventsRecord extends EventsRecord, TKey extends keyof TEventsRecord> = (payload: TEventsRecord[TKey]) => void;
+interface EventProvider<TEventsRecord extends EventsRecord> {
+  on<TName extends keyof TEventsRecord>(name: TName, handler: Handler<TEventsRecord, TName>): void;
+  off<TName extends keyof TEventsRecord>(name: TName, handler?: Handler<TEventsRecord, TName>): void;
+  clear(): void;
+}
+//#endregion
+//#region ../shared/src/types.d.ts
+type ConfigEnumLikeType = {
+  [key: string]: string | number;
+};
+type ConfigValueType = string | number | boolean | object | ConfigEnumLikeType;
+type ConfigDirectorLoggingLevel = "debug" | "info" | "warn" | "error" | "off";
+interface ConfigDirectorLogger {
+  debug(message: string, ...args: any): void;
+  info(message: string, ...args: any): void;
+  warn(message: string, ...args: any): void;
+  error(message: string, ...args: any): void;
+}
+interface ConfigDirectorLogMessageDecorator {
+  decorateMessage(message: string): string;
+}
+/**
+ * The user's context to be sent to ConfigDirector. 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.
+   * 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.
+   */
+  id?: string;
+  /**
+   * The user'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.
+   */
+  traits?: {
+    [key: string]: unknown;
+  };
+};
+/**
+ * Metadata about your application. It is recommended you include these values when configuring
+ * a ConfigDirector client so that you can use them in targeting rules.
+ */
+type ConfigDirectorMetaContext = {
+  appVersion?: string;
+  appName?: string;
+};
+//#endregion
+//#region ../js-client-core/src/types.d.ts
+/**
+ * Configuration options for the {@link ConfigDirectorClient}
+ */
+type ConfigDirectorClientOptions = {
+  /**
+   * Application metadata that remains constant through the lifetime of the connection
+   */
+  metadata?: ConfigDirectorMetaContext;
+  /**
+   * Connection options
+   */
+  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
+     * 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.
+     *
+     * Defaults to true (streaming connection)
+     */
+    streaming?: boolean;
+    /**
+     * 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.
+     */
+    timeout?: number;
+    /**
+     * The base URL to the ConfigDirector SDK server. To be used only when needing to route through a
+     * proxy to connect to the ConfigDirector SDK server. Please refer to the docs on how to configure
+     * a proxy for the client SDK.
+     */
+    url?: string;
+  };
+  /**
+   * A logger that implements {@link ConfigDirectorLogger}. It defaults to the ConfigDirector console
+   * logger set to 'warn' level.
+   *
+   * The log level of the default logger can be adjusted by creating a default logger with the desired
+   * level and providing it in this property:
+   * @example
+   * import { createClient, createConsoleLogger } from "@configdirector/client-sdk";
+   * const client = createClient(
+   *   "YOUR-SDK-KEY",
+   *   { logger: createConsoleLogger("debug") },
+   * );
+   */
+  logger?: ConfigDirectorLogger;
+};
+type ClientConnectAction = "initialization" | "context update" | "network resume";
+type ClientEvents = {
+  configsUpdated: {
+    keys: string[];
+  };
+  clientReady: {
+    action: ClientConnectAction;
+  };
+};
+type WatchHandler<T extends ConfigValueType> = (message: T) => void;
+/**
+ * The ConfigDirector SDK client object.
+ *
+ * Applications should create a single instance of `ConfigDirectorClient`, and call
+ * {@link initialize} during application initialization.
+ *
+ * After initialization, to update the user's context, so that targeting rules are evaluated
+ * with the updated context, call {@link updateContext}.
+ */
+interface ConfigDirectorClient extends EventProvider<ClientEvents> {
+  /**
+   * Initializes the connection to ConfigDirector to retrieve config evaluations. Until
+   * initialization is successful, all flags will return their default value provided to
+   * {@link watch} or {@link getValue}.
+   *
+   * If the connection fails or is interrupted with a transient error (network error,
+   * internal server error, etc) the client will continue to attempt to connect. However,
+   * if the connection fails with a persistent error, like an invalid SDK key, the client will
+   * 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).
+   */
+  initialize(context?: ConfigDirectorContext): Promise<void>;
+  /**
+   * Updates the user's context and re-evaluates all config and flag values based on the new context.
+   *
+   * @param context The current user's context to be used for evaluating targeting rules (required).
+   */
+  updateContext(context: ConfigDirectorContext): Promise<void>;
+  /**
+   * Returns whether or not the client is ready after calling {@link initialize} or {@link updateContext}
+   *
+   * The definition of ready is that the connection to the server was successful, and config state
+   * was received.
+   */
+  get isReady(): boolean;
+  /**
+   * Evaluates a config and returns its value based on the current context and targeting rules
+   *
+   * @returns The evaluated config value, or the `defaultValue` if the config state was unavailable
+   * @param configKey The config key to evaluate
+   * @param defaultValue The default value to be returned if the config state is unavailable. For
+   * example, if the client cannot connect to the server due to network conditions, or if getValue
+   * is called before initialization is done.
+   */
+  getValue<T extends ConfigValueType>(configKey: string, defaultValue: T): T;
+  /**
+   * Watches for changes to a a config evaluation value. Whenever the config value changes, the
+   * provided callback function will be called with the new value. Changes can happen due to updates
+   * to the config in the ConfigDirector dashboard, or if the context is updated via {@link updateContext}.
+   *
+   * @returns An 'unwatch' function that can be called to remove the subscriber
+   *
+   * @param configKey The config key to watch
+   * @param defaultValue The default value to be referenced if the config state is unavailable
+   * @param callback The callback function to be called whenever the config value is updated
+   */
+  watch<T extends ConfigValueType>(configKey: string, defaultValue: T, callback: WatchHandler<T>): () => void;
+  /**
+   * Removes a particular subscriber to the given `configKey`, or all subscribers if no callback
+   * is provided.
+   *
+   * @param configKey The config key to remove subscribers from
+   * @param callback The subscriber to be removed. If not provided, all subscribers are removed for
+   * the given `configKey`.
+   */
+  unwatch<T extends ConfigValueType>(configKey: string, callback?: WatchHandler<T>): void;
+  /**
+   * Removes all subscribers from all config keys
+   */
+  unwatchAll(): void;
+  /**
+   * Pauses the network connection without clearing event handlers, watch handlers, or config
+   * state. Intended for mobile environments where the OS may kill background connections (e.g.
+   * when the app is backgrounded on iOS/Android).
+   *
+   * Call {@link resumeNetwork} to re-establish the connection.
+   */
+  pauseNetwork(): void;
+  /**
+   * Resumes a connection that was paused via {@link pauseNetwork}, using the last context that
+   * was provided to {@link initialize} or {@link updateContext}.
+   */
+  resumeNetwork(): Promise<void>;
+  /**
+   * Disposes of the client. All connections are closed, and all event and config key subscribers
+   * are removed.
+   *
+   * Intended to be called when your application shuts down
+   */
+  dispose(): void;
+}
+//#endregion
+//#region ../shared/src/logger.d.ts
+declare class DefaultConsoleLogger implements ConfigDirectorLogger {
+  private readonly level;
+  private readonly decorator;
+  private readonly dateFormatter;
+  constructor(level: ConfigDirectorLoggingLevel, decorator: ConfigDirectorLogMessageDecorator);
+  debug(message: string, ...args: any): void;
+  info(message: string, ...args: any): void;
+  warn(message: string, ...args: any): void;
+  error(message: string, ...args: any): void;
+  private log;
+}
+//#endregion
+//#region src/types.d.ts
+type ClientStatus = "loading" | "ready" | "default";
+interface ConfigDirectorContextData {
+  client?: ConfigDirectorClient;
+  updatedAt?: Date;
+  status: ClientStatus;
+}
+type ConfigDirectorProviderState = ConfigDirectorContextData;
+/** Minimal connectivity state shape consumed from @react-native-community/netinfo */
+type NetInfoState = {
+  isConnected: boolean | null;
+};
+/**
+ * A subscription function with the same signature as `NetInfo.addEventListener` from
+ * `@react-native-community/netinfo`. Pass this prop to enable immediate reconnection
+ * when the device regains network connectivity instead of waiting for the next
+ * exponential-backoff retry.
+ *
+ * @example
+ * import NetInfo from '@react-native-community/netinfo';
+ * <ConfigDirectorProvider netInfoSubscribe={NetInfo.addEventListener} ... />
+ */
+type NetInfoSubscribe = (callback: (state: NetInfoState) => void) => () => void;
+type ConfigDirectorProviderOptions = {
+  sdkKey: string;
+  appName?: string;
+  appVersion?: string;
+  url?: string;
+  timeout?: number;
+  context?: ConfigDirectorContext;
+  logger?: ConfigDirectorLogger;
+  netInfoSubscribe?: NetInfoSubscribe;
+};
+//#endregion
+//#region src/provider.d.ts
+declare class ConfigDirectorProvider extends Component<PropsWithChildren<ConfigDirectorProviderOptions>, ConfigDirectorProviderState> {
+  private appStateSubscription;
+  private netInfoUnsubscribe;
+  private wasOffline;
+  constructor(props: ConfigDirectorProviderOptions);
+  componentDidMount(): Promise<void>;
+  componentDidUpdate(prevProps: PropsWithChildren<ConfigDirectorProviderOptions>): Promise<void>;
+  private handleAppStateChange;
+  private handleConnectivityChange;
+  private reconnect;
+  componentWillUnmount(): void;
+  render(): _$react_jsx_runtime0.JSX.Element;
+}
+//#endregion
+//#region src/hooks.d.ts
+declare const useConfigValue: <T extends ConfigValueType>(key: string, defaultValue: T) => {
+  value: T;
+  readyStatus: ClientStatus;
+  loading: boolean;
+};
+declare const useConfigDirectorContext: () => {
+  updateContext: (context: ConfigDirectorContext) => Promise<void>;
+};
+declare const useConfigDirectorClient: () => {
+  client: ConfigDirectorClient;
+};
+//#endregion
+//#region src/client.d.ts
+declare const createClient: (clientSdkKey: string, clientOptions?: ConfigDirectorClientOptions) => ConfigDirectorClient;
+//#endregion
+//#region src/errors.d.ts
+declare class ConfigDirectorReactContextError extends Error {
+  readonly name: string;
+  constructor(message: string);
+}
+//#endregion
+//#region src/logger.d.ts
+declare const createConsoleLogger: (level?: ConfigDirectorLoggingLevel) => DefaultConsoleLogger;
+//#endregion
+export { type ClientStatus, type ConfigDirectorClient, type ConfigDirectorClientOptions, type ConfigDirectorContext, type ConfigDirectorLogger, type ConfigDirectorLoggingLevel, ConfigDirectorProvider, type ConfigDirectorProviderOptions, ConfigDirectorReactContextError, type NetInfoSubscribe, createClient, createConsoleLogger, useConfigDirectorClient, useConfigDirectorContext, useConfigValue };