@scalebun/react-native 1.0.1 → 1.0.2

package/src/storage/StorageBackend.ts

@@ -1,272 +1,272 @@
-/**
- * ScaleBun SDK — Storage Backend Abstraction
- *
- * Pluggable, synchronous key-value storage interface used by the PersistentQueue,
- * the Engage throttle/test-seen stores, the event tracker identifiers, and the
- * device id. It is the SDK's single storage seam — no feature talks to a storage
- * implementation directly.
- *
- * DEFAULT BACKEND — first-party, zero third-party dependency:
- * The default React Native backend (`NativeKVBackend`) is backed by the SDK's
- * OWN native module (`ScaleBunStorage`), which persists to an app-private file
- * (Android `filesDir/scalebun_kv.json`, iOS Application Support). App developers
- * install NOTHING — the native module ships inside `@scalebun/react-native`.
- *
- * Because this interface is synchronous (it is read at module-load time) but
- * native file IO is asynchronous, `NativeKVBackend` keeps a synchronous in-memory
- * mirror that is hydrated ONCE from the native store via the synchronous
- * `getAllSync()` method, then kept in sync with the disk through asynchronous,
- * coalesced write-through (`setItems` / `removeItems`).
- *
- * FALLBACK:
- * If the native module is unavailable (e.g. the app has not rebuilt native code,
- * web/SSR, or a unit-test environment), the factory falls back to `MemoryBackend`
- * and logs exactly ONE honest warning per app launch. Data will not survive a
- * restart in that mode — but the SDK keeps functioning.
- */
-
-import { logger } from '../core/logger/internalLogger';
-import ScaleBunStorage from '../specs/NativeScaleBunStorage';
-
-// ─── Interface ──────────────────────────────────────────────────────────────
-
-/**
- * Minimal synchronous key-value storage interface for the persistent queue and
- * the SDK's small identifiers/state.
- *
- * All operations are synchronous. The default native backend satisfies this with
- * an in-memory mirror over an app-private file (hydrated once at init, written
- * back asynchronously). Implementations must never throw.
- */
-export interface StorageBackend {
-    /** Read a value by key. Returns undefined if not found. */
-    get(key: string): string | undefined;
-
-    /** Write a value by key. Overwrites if key exists. */
-    set(key: string, value: string): void;
-
-    /** Delete a key. No-op if key doesn't exist. */
-    delete(key: string): void;
-
-    /**
-     * Return all keys currently stored.
-     * Used during leftover drain to discover entries from previous runs.
-     */
-    getAllKeys(): string[];
-}
-
-// ─── MemoryBackend ──────────────────────────────────────────────────────────
-
-/**
- * In-memory storage backend. Data does NOT survive app restarts.
- *
- * Used for:
- * - Unit tests (no native deps)
- * - Emergency fallback when the native durable store is unavailable
- * - Environments where persistence is explicitly disabled
- */
-export class MemoryBackend implements StorageBackend {
-    private data = new Map<string, string>();
-
-    get(key: string): string | undefined {
-        return this.data.get(key);
-    }
-
-    set(key: string, value: string): void {
-        this.data.set(key, value);
-    }
-
-    delete(key: string): void {
-        this.data.delete(key);
-    }
-
-    getAllKeys(): string[] {
-        return Array.from(this.data.keys());
-    }
-}
-
-// ─── NativeKVBackend ────────────────────────────────────────────────────────
-
-/**
- * Minimal shape of the native `ScaleBunStorage` module this backend depends on.
- * Declared structurally (not imported as the codegen `Spec`) so tests can inject
- * a plain fake and so the backend never hard-depends on the generated type.
- */
-export interface NativeKVModule {
-    getAllSync(): string;
-    setItems(entriesJson: string): Promise<void> | void;
-    removeItems(keysJson: string): Promise<void> | void;
-    clear(): Promise<void> | void;
-}
-
-/**
- * Durable, first-party storage backed by the SDK's own `ScaleBunStorage` native
- * module. Data survives app restarts, crashes, and force-kills (modulo the small
- * window of the most-recent un-flushed write — see below).
- *
- * Strategy:
- *   - On construction, `getAllSync()` loads the entire persisted namespace into a
- *     synchronous in-memory `Map` (the mirror).
- *   - Reads (`get` / `getAllKeys`) serve the mirror synchronously.
- *   - Writes (`set` / `delete`) update the mirror immediately, then enqueue a
- *     pending change that is flushed to the native store on a microtask. Pending
- *     sets/deletes for the same key are coalesced; ordering is preserved per key.
- *
- * Durability window: a write is in the mirror immediately but reaches disk on the
- * next flush. A process kill in that sub-millisecond window can lose the most
- * recent write(s). This matches any async-persistence store and is the price of
- * not blocking the JS thread on every event. Everything already on disk is safe
- * and atomically written by the native side.
- */
-export class NativeKVBackend implements StorageBackend {
-    private readonly native: NativeKVModule;
-    private readonly mirror: Map<string, string>;
-
-    /** Keys whose latest value still needs to be pushed to the native store. */
-    private pendingSets = new Map<string, string>();
-    /** Keys whose deletion still needs to be pushed to the native store. */
-    private pendingDeletes = new Set<string>();
-    private flushScheduled = false;
-
-    constructor(native: NativeKVModule) {
-        this.native = native;
-        this.mirror = this._hydrate();
-    }
-
-    /** Load the full persisted namespace synchronously into the mirror. */
-    private _hydrate(): Map<string, string> {
-        const map = new Map<string, string>();
-        try {
-            const raw = this.native.getAllSync();
-            if (raw) {
-                const obj = JSON.parse(raw) as Record<string, unknown>;
-                for (const k of Object.keys(obj)) {
-                    const v = obj[k];
-                    if (typeof v === 'string') map.set(k, v);
-                }
-            }
-        } catch (e) {
-            // A corrupt/unreadable store must not break init — start empty and
-            // let the native side overwrite with the next atomic flush.
-            logger.warn('[StorageBackend] Native store hydrate failed; starting empty this run:', (e as Error)?.message);
-        }
-        return map;
-    }
-
-    get(key: string): string | undefined {
-        return this.mirror.get(key);
-    }
-
-    set(key: string, value: string): void {
-        this.mirror.set(key, value);
-        this.pendingSets.set(key, value);
-        this.pendingDeletes.delete(key);
-        this._scheduleFlush();
-    }
-
-    delete(key: string): void {
-        this.mirror.delete(key);
-        this.pendingDeletes.add(key);
-        this.pendingSets.delete(key);
-        this._scheduleFlush();
-    }
-
-    getAllKeys(): string[] {
-        return Array.from(this.mirror.keys());
-    }
-
-    /** Coalesce pending writes and flush them to the native store on a microtask. */
-    private _scheduleFlush(): void {
-        if (this.flushScheduled) return;
-        this.flushScheduled = true;
-        // Microtask: batch every synchronous set/delete in the current tick into a
-        // single native round-trip, so a popBatch() of 50 entries is one flush.
-        Promise.resolve().then(() => this._flush());
-    }
-
-    private _flush(): void {
-        this.flushScheduled = false;
-        try {
-            if (this.pendingSets.size > 0) {
-                const obj: Record<string, string> = {};
-                for (const [k, v] of this.pendingSets) obj[k] = v;
-                this.pendingSets.clear();
-                void Promise.resolve(this.native.setItems(JSON.stringify(obj)))?.catch?.(() => {});
-            }
-            if (this.pendingDeletes.size > 0) {
-                const keys = Array.from(this.pendingDeletes);
-                this.pendingDeletes.clear();
-                void Promise.resolve(this.native.removeItems(JSON.stringify(keys)))?.catch?.(() => {});
-            }
-        } catch {
-            // Native write-through failure is non-fatal; the mirror remains correct
-            // for this session and the next flush retries newer writes.
-        }
-    }
-}
-
-// ─── Factory ────────────────────────────────────────────────────────────────
-
-/**
- * Resolve the SDK's native KV module, or null if it isn't present in this
- * runtime (web/SSR, Jest, or an app that hasn't rebuilt native after upgrading).
- */
-function getNativeModule(): NativeKVModule | null {
-    const mod = ScaleBunStorage as unknown as NativeKVModule | null | undefined;
-    if (mod && typeof mod.getAllSync === 'function') return mod;
-    return null;
-}
-
-/**
- * Shared singleton — `createStorageBackend()` must return the SAME instance to
- * every caller so the in-memory mirror, the pending-write queue, and the
- * one-time fallback warning are not duplicated across features.
- */
-let sharedBackend: StorageBackend | null = null;
-
-/**
- * Create (once) and return the shared storage backend for the current
- * environment.
- *
- * Selection order:
- *   1. `NativeKVBackend` over the first-party `ScaleBunStorage` native module
- *      (durable, app-private file — the default for React Native).
- *   2. `MemoryBackend` (emergency fallback — no persistence), with exactly ONE
- *      honest warning per launch. The warning never mentions any third-party
- *      library.
- *
- * Idempotent: subsequent calls return the cached instance.
- */
-export function createStorageBackend(): StorageBackend {
-    if (sharedBackend) return sharedBackend;
-
-    const native = getNativeModule();
-    if (native) {
-        try {
-            sharedBackend = new NativeKVBackend(native);
-            logger.debug('[StorageBackend] Using native durable backend (ScaleBunStorage)');
-            return sharedBackend;
-        } catch (e) {
-            logger.warn('[StorageBackend] Native durable store failed to initialize; ' +
-                'using in-memory storage for this launch — events may not survive an app restart:', (e as Error)?.message);
-            sharedBackend = new MemoryBackend();
-            return sharedBackend;
-        }
-    }
-
-    logger.warn(
-        '[StorageBackend] Native durable store unavailable; using in-memory storage ' +
-        'for this launch — events may not survive an app restart. ' +
-        'Rebuild the app with the ScaleBun native module to enable disk persistence.',
-    );
-    sharedBackend = new MemoryBackend();
-    return sharedBackend;
-}
-
-/**
- * TEST-ONLY: reset the shared backend singleton so each test can exercise the
- * factory's selection logic from a clean slate.
- */
-export function __resetStorageBackendForTests(): void {
-    sharedBackend = null;
-}
+/**
+ * ScaleBun SDK — Storage Backend Abstraction
+ *
+ * Pluggable, synchronous key-value storage interface used by the PersistentQueue,
+ * the Engage throttle/test-seen stores, the event tracker identifiers, and the
+ * device id. It is the SDK's single storage seam — no feature talks to a storage
+ * implementation directly.
+ *
+ * DEFAULT BACKEND — first-party, zero third-party dependency:
+ * The default React Native backend (`NativeKVBackend`) is backed by the SDK's
+ * OWN native module (`ScaleBunStorage`), which persists to an app-private file
+ * (Android `filesDir/scalebun_kv.json`, iOS Application Support). App developers
+ * install NOTHING — the native module ships inside `@scalebun/react-native`.
+ *
+ * Because this interface is synchronous (it is read at module-load time) but
+ * native file IO is asynchronous, `NativeKVBackend` keeps a synchronous in-memory
+ * mirror that is hydrated ONCE from the native store via the synchronous
+ * `getAllSync()` method, then kept in sync with the disk through asynchronous,
+ * coalesced write-through (`setItems` / `removeItems`).
+ *
+ * FALLBACK:
+ * If the native module is unavailable (e.g. the app has not rebuilt native code,
+ * web/SSR, or a unit-test environment), the factory falls back to `MemoryBackend`
+ * and logs exactly ONE honest warning per app launch. Data will not survive a
+ * restart in that mode — but the SDK keeps functioning.
+ */
+
+import { logger } from '../core/logger/internalLogger';
+import ScaleBunStorage from '../specs/NativeScaleBunStorage';
+
+// ─── Interface ──────────────────────────────────────────────────────────────
+
+/**
+ * Minimal synchronous key-value storage interface for the persistent queue and
+ * the SDK's small identifiers/state.
+ *
+ * All operations are synchronous. The default native backend satisfies this with
+ * an in-memory mirror over an app-private file (hydrated once at init, written
+ * back asynchronously). Implementations must never throw.
+ */
+export interface StorageBackend {
+    /** Read a value by key. Returns undefined if not found. */
+    get(key: string): string | undefined;
+
+    /** Write a value by key. Overwrites if key exists. */
+    set(key: string, value: string): void;
+
+    /** Delete a key. No-op if key doesn't exist. */
+    delete(key: string): void;
+
+    /**
+     * Return all keys currently stored.
+     * Used during leftover drain to discover entries from previous runs.
+     */
+    getAllKeys(): string[];
+}
+
+// ─── MemoryBackend ──────────────────────────────────────────────────────────
+
+/**
+ * In-memory storage backend. Data does NOT survive app restarts.
+ *
+ * Used for:
+ * - Unit tests (no native deps)
+ * - Emergency fallback when the native durable store is unavailable
+ * - Environments where persistence is explicitly disabled
+ */
+export class MemoryBackend implements StorageBackend {
+    private data = new Map<string, string>();
+
+    get(key: string): string | undefined {
+        return this.data.get(key);
+    }
+
+    set(key: string, value: string): void {
+        this.data.set(key, value);
+    }
+
+    delete(key: string): void {
+        this.data.delete(key);
+    }
+
+    getAllKeys(): string[] {
+        return Array.from(this.data.keys());
+    }
+}
+
+// ─── NativeKVBackend ────────────────────────────────────────────────────────
+
+/**
+ * Minimal shape of the native `ScaleBunStorage` module this backend depends on.
+ * Declared structurally (not imported as the codegen `Spec`) so tests can inject
+ * a plain fake and so the backend never hard-depends on the generated type.
+ */
+export interface NativeKVModule {
+    getAllSync(): string;
+    setItems(entriesJson: string): Promise<void> | void;
+    removeItems(keysJson: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+
+/**
+ * Durable, first-party storage backed by the SDK's own `ScaleBunStorage` native
+ * module. Data survives app restarts, crashes, and force-kills (modulo the small
+ * window of the most-recent un-flushed write — see below).
+ *
+ * Strategy:
+ *   - On construction, `getAllSync()` loads the entire persisted namespace into a
+ *     synchronous in-memory `Map` (the mirror).
+ *   - Reads (`get` / `getAllKeys`) serve the mirror synchronously.
+ *   - Writes (`set` / `delete`) update the mirror immediately, then enqueue a
+ *     pending change that is flushed to the native store on a microtask. Pending
+ *     sets/deletes for the same key are coalesced; ordering is preserved per key.
+ *
+ * Durability window: a write is in the mirror immediately but reaches disk on the
+ * next flush. A process kill in that sub-millisecond window can lose the most
+ * recent write(s). This matches any async-persistence store and is the price of
+ * not blocking the JS thread on every event. Everything already on disk is safe
+ * and atomically written by the native side.
+ */
+export class NativeKVBackend implements StorageBackend {
+    private readonly native: NativeKVModule;
+    private readonly mirror: Map<string, string>;
+
+    /** Keys whose latest value still needs to be pushed to the native store. */
+    private pendingSets = new Map<string, string>();
+    /** Keys whose deletion still needs to be pushed to the native store. */
+    private pendingDeletes = new Set<string>();
+    private flushScheduled = false;
+
+    constructor(native: NativeKVModule) {
+        this.native = native;
+        this.mirror = this._hydrate();
+    }
+
+    /** Load the full persisted namespace synchronously into the mirror. */
+    private _hydrate(): Map<string, string> {
+        const map = new Map<string, string>();
+        try {
+            const raw = this.native.getAllSync();
+            if (raw) {
+                const obj = JSON.parse(raw) as Record<string, unknown>;
+                for (const k of Object.keys(obj)) {
+                    const v = obj[k];
+                    if (typeof v === 'string') map.set(k, v);
+                }
+            }
+        } catch (e) {
+            // A corrupt/unreadable store must not break init — start empty and
+            // let the native side overwrite with the next atomic flush.
+            logger.warn('[StorageBackend] Native store hydrate failed; starting empty this run:', (e as Error)?.message);
+        }
+        return map;
+    }
+
+    get(key: string): string | undefined {
+        return this.mirror.get(key);
+    }
+
+    set(key: string, value: string): void {
+        this.mirror.set(key, value);
+        this.pendingSets.set(key, value);
+        this.pendingDeletes.delete(key);
+        this._scheduleFlush();
+    }
+
+    delete(key: string): void {
+        this.mirror.delete(key);
+        this.pendingDeletes.add(key);
+        this.pendingSets.delete(key);
+        this._scheduleFlush();
+    }
+
+    getAllKeys(): string[] {
+        return Array.from(this.mirror.keys());
+    }
+
+    /** Coalesce pending writes and flush them to the native store on a microtask. */
+    private _scheduleFlush(): void {
+        if (this.flushScheduled) return;
+        this.flushScheduled = true;
+        // Microtask: batch every synchronous set/delete in the current tick into a
+        // single native round-trip, so a popBatch() of 50 entries is one flush.
+        Promise.resolve().then(() => this._flush());
+    }
+
+    private _flush(): void {
+        this.flushScheduled = false;
+        try {
+            if (this.pendingSets.size > 0) {
+                const obj: Record<string, string> = {};
+                for (const [k, v] of this.pendingSets) obj[k] = v;
+                this.pendingSets.clear();
+                void Promise.resolve(this.native.setItems(JSON.stringify(obj)))?.catch?.(() => {});
+            }
+            if (this.pendingDeletes.size > 0) {
+                const keys = Array.from(this.pendingDeletes);
+                this.pendingDeletes.clear();
+                void Promise.resolve(this.native.removeItems(JSON.stringify(keys)))?.catch?.(() => {});
+            }
+        } catch {
+            // Native write-through failure is non-fatal; the mirror remains correct
+            // for this session and the next flush retries newer writes.
+        }
+    }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the SDK's native KV module, or null if it isn't present in this
+ * runtime (web/SSR, Jest, or an app that hasn't rebuilt native after upgrading).
+ */
+function getNativeModule(): NativeKVModule | null {
+    const mod = ScaleBunStorage as unknown as NativeKVModule | null | undefined;
+    if (mod && typeof mod.getAllSync === 'function') return mod;
+    return null;
+}
+
+/**
+ * Shared singleton — `createStorageBackend()` must return the SAME instance to
+ * every caller so the in-memory mirror, the pending-write queue, and the
+ * one-time fallback warning are not duplicated across features.
+ */
+let sharedBackend: StorageBackend | null = null;
+
+/**
+ * Create (once) and return the shared storage backend for the current
+ * environment.
+ *
+ * Selection order:
+ *   1. `NativeKVBackend` over the first-party `ScaleBunStorage` native module
+ *      (durable, app-private file — the default for React Native).
+ *   2. `MemoryBackend` (emergency fallback — no persistence), with exactly ONE
+ *      honest warning per launch. The warning never mentions any third-party
+ *      library.
+ *
+ * Idempotent: subsequent calls return the cached instance.
+ */
+export function createStorageBackend(): StorageBackend {
+    if (sharedBackend) return sharedBackend;
+
+    const native = getNativeModule();
+    if (native) {
+        try {
+            sharedBackend = new NativeKVBackend(native);
+            logger.debug('[StorageBackend] Using native durable backend (ScaleBunStorage)');
+            return sharedBackend;
+        } catch (e) {
+            logger.warn('[StorageBackend] Native durable store failed to initialize; ' +
+                'using in-memory storage for this launch — events may not survive an app restart:', (e as Error)?.message);
+            sharedBackend = new MemoryBackend();
+            return sharedBackend;
+        }
+    }
+
+    logger.warn(
+        '[StorageBackend] Native durable store unavailable; using in-memory storage ' +
+        'for this launch — events may not survive an app restart. ' +
+        'Rebuild the app with the ScaleBun native module to enable disk persistence.',
+    );
+    sharedBackend = new MemoryBackend();
+    return sharedBackend;
+}
+
+/**
+ * TEST-ONLY: reset the shared backend singleton so each test can exercise the
+ * factory's selection logic from a clean slate.
+ */
+export function __resetStorageBackendForTests(): void {
+    sharedBackend = null;
+}

package/src/transport/auth/sdkSession.ts

@@ -1,27 +1,27 @@
-export class SdkSessionManager {
-    private token?: string;
-    private expiresAt?: number;
-
-    setSession(token: string, expiresIn: number) {
-        this.token = token;
-        this.expiresAt = Date.now() + expiresIn * 1000;
-    }
-
-    getToken(): string | undefined {
-        if (this.token && this.expiresAt && Date.now() < this.expiresAt) {
-            return this.token;
-        }
-        return undefined;
-    }
-
-    isExpired(): boolean {
-        return !this.getToken();
-    }
-
-    clear() {
-        this.token = undefined;
-        this.expiresAt = undefined;
-    }
-}
-
-export const sdkSession = new SdkSessionManager();
+export class SdkSessionManager {
+    private token?: string;
+    private expiresAt?: number;
+
+    setSession(token: string, expiresIn: number) {
+        this.token = token;
+        this.expiresAt = Date.now() + expiresIn * 1000;
+    }
+
+    getToken(): string | undefined {
+        if (this.token && this.expiresAt && Date.now() < this.expiresAt) {
+            return this.token;
+        }
+        return undefined;
+    }
+
+    isExpired(): boolean {
+        return !this.getToken();
+    }
+
+    clear() {
+        this.token = undefined;
+        this.expiresAt = undefined;
+    }
+}
+
+export const sdkSession = new SdkSessionManager();

package/src/transport/backoff/exponentialJitter.ts

@@ -1,9 +1,9 @@
-/**
- * Exponential backoff with jitter.
- */
-export function getDelayWithJitter(attempt: number, base = 1000): number {
-    const cap = 30000;
-    const delay = Math.min(cap, base * Math.pow(2, attempt));
-    const jitter = delay * 0.2 * Math.random();
-    return delay + jitter;
-}
+/**
+ * Exponential backoff with jitter.
+ */
+export function getDelayWithJitter(attempt: number, base = 1000): number {
+    const cap = 30000;
+    const delay = Math.min(cap, base * Math.pow(2, attempt));
+    const jitter = delay * 0.2 * Math.random();
+    return delay + jitter;
+}