react-native-featureflags 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# React Native Betsy SDK
+
+Enterprise-grade feature flags for React Native.
+
+## Install
+
+```bash
+npm install react-native-featureflags
+```
+
+No separate core package install is required.
+Relay endpoint is baked into the SDK.
+
+## Quickstart
+
+```tsx
+import { useEffect } from 'react';
+import Flags from 'react-native-featureflags';
+
+export default function App() {
+  useEffect(() => {
+    void Flags.configure({
+      apiKey: 'pk_live_xxx',
+      user: {
+        id: 'user-123',
+        attributes: { plan: 'pro', country: 'US' },
+      },
+    });
+  }, []);
+
+  return <RootScreen />;
+}
+```
+
+## Login Later
+
+```tsx
+await Flags.login({
+  id: 'user-123',
+  attributes: { plan: 'pro' },
+});
+```
+
+`Flags.identify(user)` is an alias for `Flags.login(user)`.
+`Flags.login(user)` merges incoming attributes with existing attributes for that user ID.
+Unspecified keys are preserved.
+
+## Update Attributes
+
+```tsx
+await Flags.setAttributes({
+  country: 'US',
+  role: 'admin',
+});
+```
+
+`Flags.setAttributes(attrs)` updates attributes for the current logged-in user and also preserves keys you do not pass.
+
+## Evaluate Flags
+
+```tsx
+import { useFeatureFlag, useFlagsReady } from 'react-native-featureflags';
+
+export function CheckoutEntry() {
+  const ready = useFlagsReady();
+  const enabled = useFeatureFlag('new-checkout');
+
+  if (!ready) return <LoadingSkeleton />;
+  return enabled ? <CheckoutV2 /> : <CheckoutV1 />;
+}
+```
+
+Non-hook usage:
+
+```ts
+const enabled = Flags.getFlag('new-checkout', false);
+const all = Flags.getAllFlags();
+```
+
+## Logout Semantics
+
+`Flags.logout()` reverts to an anonymous user and immediately refreshes flags.
+The anonymous ID is persisted and reused across launches.
+
+## Persistence
+
+Default persistence is in-memory only. For offline bootstrapping, pass an AsyncStorage adapter:
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { createAsyncStorageAdapter } from 'react-native-featureflags';
+
+await Flags.configure({
+  apiKey: 'pk_live_xxx',
+  storage: createAsyncStorageAdapter(AsyncStorage),
+});
+```
+
+## Best Practices
+
+- Configure once at app launch.
+- Gate critical UI behind `useFlagsReady()`.
+- Use public API keys only.
+- Keep user attributes minimal and non-PII.
+
+## FAQ
+
+- Anonymous IDs: created when `user` is omitted in `configure`.
+- Offline mode: cached flags are used if cache is valid, then refreshed.
+- Retries/timeouts: fetch requests use timeout plus exponential backoff with jitter.

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+import { BetsyUser, UserAttributes } from './internal/core.js';
+import { ConfigureOptions, ExposeOptions, FlagsInternalState, TrackOptions } from './types.js';
+export declare class ReactNativeFlagsClient {
+    private readonly store;
+    private readonly sdkSource;
+    private pollTimer;
+    private telemetryTimer;
+    private config?;
+    private requestSequence;
+    private anonymousDeviceId;
+    private readonly attributesByUserId;
+    private offlineFallbackFlags;
+    private telemetryQueue;
+    private readonly exposureKeys;
+    private readonly assignmentKeys;
+    private readonly readEvaluationKeys;
+    private streamSocket;
+    private streamReconnectTimer;
+    private latestConfigVersion;
+    private configureSignature;
+    private configureInFlight;
+    subscribe: (callback: () => void) => () => void;
+    getState: () => FlagsInternalState;
+    configure(options: ConfigureOptions): Promise<void>;
+    private configureInternal;
+    login(user: BetsyUser): Promise<void>;
+    setAttributes(attributes: UserAttributes): Promise<void>;
+    identify(user: BetsyUser): Promise<void>;
+    logout(): Promise<void>;
+    refresh(): Promise<void>;
+    track(eventName: string, properties?: Record<string, unknown>, options?: TrackOptions): Promise<void>;
+    expose(flagKey: string, options?: ExposeOptions): Promise<void>;
+    notifyFlagRead(flagKey: string): void;
+    getFlag(key: string, defaultValue?: boolean): boolean;
+    getFeatureFlagValue<T>(key: string, defaultValue: T): T;
+    getFeatureFlagPayload(key: string): Record<string, unknown> | null;
+    getAllFlags(): Record<string, unknown>;
+    isReady(): boolean;
+    destroy(): void;
+    private getStorage;
+    private getUser;
+    private getTransport;
+    private enqueueTelemetryEvent;
+    private buildConfigureSignature;
+    private requireConfigured;
+    private resolveAnonymousUser;
+    private ensureAnonymousDeviceId;
+    private loadCachedUser;
+    private persistCachedUser;
+    private normalizeUser;
+    private normalizeAttributes;
+    private mergeUser;
+    private startPolling;
+    private stopPolling;
+    private startStreamOrPolling;
+    private startStreaming;
+    private stopStreaming;
+    private scheduleStreamReconnect;
+    private handleStreamMessage;
+    private resolveStreamUrl;
+    private startTelemetryFlush;
+    private flushTelemetry;
+    private enqueueReadEvaluationEvents;
+    private enqueueAssignmentEvents;
+    private enqueueExposure;
+    private clearError;
+    private extractOfflineFallbackFlags;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}