@scalebun-release/react-native 2.5.0

package/src/core/context/device.ts

@@ -0,0 +1,169 @@
+/**
+ * The ONE place that answers "what device is this?".
+ *
+ * It was previously answered three incompatible ways at once:
+ *
+ *   1. The replay lane asked the native bridge and got the truth.
+ *   2. The analytics lane took `ScaleBun.init({ context })` verbatim and shipped whatever the
+ *      integrator typed. Production carries `device_model: "android"`, `manufacturer: "android"`
+ *      and `sdk_version: "qa-app-1.0"` because an app hand-wrote them — none of those are a model,
+ *      a manufacturer, or an SDK version.
+ *   3. Seven call sites wrote `Platform.OS === 'ios' ? 'ios' : 'android'`, which reports every
+ *      non-iOS platform — windows, macos, web — as Android.
+ *
+ * Detection belongs to the SDK. An integrator cannot be expected to know the device better than the
+ * process running on it, and asking them to means the field is wrong whenever they guess.
+ *
+ * Every value here is measured or absent. Nothing is defaulted to a plausible-looking constant: a
+ * fabricated device model is indistinguishable from a real one to whoever reads the dashboard, which
+ * is strictly worse than an empty field.
+ */
+import { SDK_VERSION } from '../constants/version';
+
+/**
+ * The real `Platform.OS`, never narrowed.
+ *
+ * React Native's own union is `'ios' | 'android' | 'windows' | 'macos' | 'web'`, and the protocol's
+ * platform field is an open enum precisely so new ones travel without a release. Collapsing that to
+ * a two-way ternary is what made every macOS and Windows session read as Android.
+ */
+export type PlatformOS = 'ios' | 'android' | 'windows' | 'macos' | 'web' | 'unknown';
+
+interface RNPlatform {
+    OS?: string;
+    Version?: string | number;
+    constants?: {
+        Manufacturer?: string;
+        Model?: string;
+        Brand?: string;
+        Release?: string;
+        osVersion?: string;
+        systemName?: string;
+    };
+}
+
+function rnPlatform(): RNPlatform | null {
+    try {
+        return (require('react-native') as { Platform?: RNPlatform }).Platform ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * `Platform.OS`, verbatim.
+ *
+ * `'unknown'` when React Native itself cannot be loaded — the previous `catch { return 'android' }`
+ * turned "we could not tell" into a confident, wrong answer.
+ */
+export function resolvePlatformOS(): PlatformOS {
+    const os = rnPlatform()?.OS;
+    switch (os) {
+        case 'ios':
+        case 'android':
+        case 'windows':
+        case 'macos':
+        case 'web':
+            return os;
+        default:
+            // A platform React Native gained after this build. Pass it through rather than guess —
+            // the wire's platform field is an open enum for exactly this case.
+            return (os as PlatformOS) ?? 'unknown';
+    }
+}
+
+/**
+ * `'ios' | 'android'` for the few call sites whose payload genuinely only has those two, keeping the
+ * narrowing HONEST: `null` where it used to silently say Android.
+ */
+export function resolveMobileOS(): 'ios' | 'android' | null {
+    const os = resolvePlatformOS();
+    return os === 'ios' || os === 'android' ? os : null;
+}
+
+/** The keys this module owns. An integrator-supplied value for any of them is overridden. */
+export const DETECTED_CONTEXT_KEYS = [
+    'sdk_version',
+    'platform_os',
+    'os_version',
+    'device_model',
+    'manufacturer',
+] as const;
+
+/**
+ * Everything derivable WITHOUT the native bridge, so the very first event already carries it.
+ *
+ * The bridge is async and may not be installed at all (Expo Go, an older native binary); waiting on
+ * it would leave the opening events of every session unattributed. `Platform.constants` is populated
+ * synchronously at startup and covers Android fully — iOS exposes no model there, which is why
+ * `device_model` stays absent on iOS until {@link nativeDeviceContext} fills it in.
+ */
+export function staticDeviceContext(): Record<string, string> {
+    const platform = rnPlatform();
+    const out: Record<string, string> = {
+        sdk_version: SDK_VERSION,
+        platform_os: resolvePlatformOS(),
+    };
+    if (!platform) return out;
+
+    const c = platform.constants ?? {};
+    // Android: Release is the marketing version ("14"); Version is the API level (34).
+    // iOS: osVersion is the real thing; Platform.Version mirrors it.
+    const osVersion = c.Release ?? c.osVersion ?? (platform.Version != null ? String(platform.Version) : undefined);
+    if (osVersion) out.os_version = String(osVersion);
+    if (c.Model) out.device_model = String(c.Model);
+    if (c.Manufacturer) out.manufacturer = String(c.Manufacturer);
+    else if (c.Brand) out.manufacturer = String(c.Brand);
+    // iOS exposes no manufacturer because it does not need to: every device running iOS is Apple's.
+    // A tautology, not a guess — and it means the field is populated on event #1 rather than waiting
+    // for a bridge that may never answer.
+    else if (out.platform_os === 'ios') out.manufacturer = 'Apple';
+    return out;
+}
+
+/** Bridge values, once the native module answers. Absent keys stay absent. */
+export function nativeDeviceContext(info: {
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    manufacturer?: string;
+} | null): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (!info) return out;
+    if (info.osVersion) out.os_version = info.osVersion;
+    if (info.deviceModel) out.device_model = info.deviceModel;
+    if (info.manufacturer) out.manufacturer = info.manufacturer;
+    return out;
+}
+
+/**
+ * Merge the integrator's context with what we detected — DETECTED WINS on the keys above.
+ *
+ * The inversion is deliberate. Config normally wins over defaults, but these are not defaults: they
+ * are measurements, and a measurement must not be overridable by a guess. Everything outside
+ * {@link DETECTED_CONTEXT_KEYS} — `language`, `timezone`, `network_type`, anything app-specific —
+ * is still the integrator's to set, untouched.
+ */
+export function mergeDeviceContext(
+    configured: Record<string, unknown> | undefined,
+    detected: Record<string, string> = staticDeviceContext(),
+): Record<string, unknown> {
+    return { ...(configured ?? {}), ...detected };
+}
+
+/**
+ * The analytics envelope lane's platform value, AUTO-DETECTED.
+ *
+ * The init config's `platform` field was documented as "Default: react_native" — so every
+ * integration that did not hand-write `platform: 'ios' | 'android'` stamped the literal
+ * `react_native` on all its analytics events, and the dashboard's platform filters (which split
+ * ios/android) silently excluded them. Asking the developer for a value the runtime knows is an
+ * integration tax with a failure mode; `Platform.OS` answers it exactly.
+ *
+ * `react_native` remains only for the genuinely-unknown case (RN unloadable, or an OS the wire
+ * enum does not carry) — an honest "RN, platform untold" rather than a confident wrong answer.
+ */
+export function resolveEventPlatform(): 'ios' | 'android' | 'web' | 'react_native' {
+    const os = resolvePlatformOS();
+    return os === 'ios' || os === 'android' || os === 'web' ? os : 'react_native';
+}

package/src/core/context/user.ts

@@ -0,0 +1,26 @@
+export interface UserContext {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: any;
+}
+
+export interface AppContext {
+    name?: string;
+    version?: string;
+    build?: string;
+    bundleId?: string;
+}
+
+export interface DeviceContext {
+    id: string;
+    model?: string;
+    os?: string;
+    osVersion?: string;
+    locale?: string;
+}
+
+export interface SessionContext {
+    id: string;
+    startTime: number;
+}

package/src/core/contracts/IFeature.ts

@@ -0,0 +1,53 @@
+/**
+ * ScaleBun SDK — Feature Contract
+ *
+ * Interface for pluggable SDK features (replay, network, crash, etc.).
+ * Each feature follows the same lifecycle: register → initialize → teardown.
+ *
+ * SOLID: Interface Segregation — features only implement what they need.
+ * SOLID: Open/Closed — new features are added by implementing this interface.
+ *
+ * Canonical source: @scalebun/sdk-contracts/features
+ */
+
+/** Context provided to features during initialization */
+export interface FeatureContext {
+    /** Track an event through the SDK pipeline */
+    trackEvent: (name: string, payload?: Record<string, unknown>) => void;
+    /** Get the debug stream (if debug is enabled) */
+    getDebugStream: () => unknown | null;
+    /** App lifecycle state */
+    getAppState: () => 'active' | 'background' | 'inactive';
+}
+
+/**
+ * Contract for SDK features.
+ *
+ * Each feature module (network monitoring, crash reporting, replay, etc.)
+ * implements this interface and registers itself with the FeatureRegistry.
+ */
+export interface IFeature {
+    /** Unique feature name (e.g. 'network', 'crash', 'replay') */
+    readonly name: string;
+
+    /**
+     * Initialize the feature with the provided context.
+     * May be async for features that need native module setup.
+     */
+    initialize(context: FeatureContext): void | Promise<void>;
+
+    /**
+     * Tear down the feature and release all resources.
+     * Must be synchronous and safe to call multiple times.
+     */
+    teardown(): void;
+
+    /** Whether the feature is currently active */
+    readonly isActive: boolean;
+}
+
+// Re-export from contracts — consumers can migrate to new import path
+export type {
+    IFeature as ContractIFeature,
+    FeatureContext as ContractFeatureContext,
+} from '../../vendor/sdk-contracts';

package/src/core/di/container.ts

@@ -0,0 +1,26 @@
+export class Container {
+    private services = new Map<string, any>();
+
+    register<T>(key: string, instance: T): T {
+        this.services.set(key, instance);
+        return instance;
+    }
+
+    get<T>(key: string): T {
+        const service = this.services.get(key);
+        if (!service) {
+            throw new Error(`Service ${key} not found in container`);
+        }
+        return service;
+    }
+
+    has(key: string): boolean {
+        return this.services.has(key);
+    }
+
+    clear() {
+        this.services.clear();
+    }
+}
+
+export const coreContainer = new Container();

package/src/core/encoding/base64.ts

@@ -0,0 +1,46 @@
+/**
+ * ScaleBun SDK — base64 → binary decode (RN-safe).
+ *
+ * Used by the object-storage upload paths (replay frames + engage attachments) to
+ * turn a base64 payload into real binary bytes for a presigned PUT. We deliberately
+ * do NOT use the `fetch('data:…').blob()` round-trip: under the new architecture
+ * that rejects with "Network request failed". RN's XHR accepts a `Uint8Array` body
+ * and transfers `.buffer` to native as binary, so a decoded byte array uploads
+ * faithfully.
+ */
+
+const B64_ALPHABET =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Decode a base64 string (no data-URI prefix) into a Uint8Array of raw bytes. */
+export function base64ToBytes(base64: string): Uint8Array {
+    // Prefer the runtime decoder when present (Hermes ≥ RN 0.71 ships atob).
+    const g: any = globalThis as any;
+    if (typeof g.atob === 'function') {
+        const bin: string = g.atob(base64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i) & 0xff;
+        return out;
+    }
+    return decodeManual(base64);
+}
+
+function decodeManual(base64: string): Uint8Array {
+    const clean = base64.replace(/[^A-Za-z0-9+/=]/g, '');
+    const pad = clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0;
+    const outLen = Math.floor((clean.length * 3) / 4) - pad;
+    const out = new Uint8Array(outLen);
+    let p = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const c0 = B64_ALPHABET.indexOf(clean[i]);
+        const c1 = B64_ALPHABET.indexOf(clean[i + 1]);
+        const c2 = B64_ALPHABET.indexOf(clean[i + 2]);
+        const c3 = B64_ALPHABET.indexOf(clean[i + 3]);
+        const n =
+            (c0 << 18) | (c1 << 12) | ((c2 & 63) << 6) | (c3 & 63);
+        if (p < outLen) out[p++] = (n >> 16) & 0xff;
+        if (p < outLen) out[p++] = (n >> 8) & 0xff;
+        if (p < outLen) out[p++] = n & 0xff;
+    }
+    return out;
+}

package/src/core/id/deviceId.ts

@@ -0,0 +1,51 @@
+import { noThrow } from '../lifecycle/crashSafe';
+import { createStorageBackend } from '../../storage/StorageBackend';
+
+const STORAGE_KEY = 'scalebun_device_id';
+const storage = createStorageBackend();
+let cachedDeviceId: string | null = null;
+
+/**
+ * Generates or retrieves a unique device ID.
+ */
+export function getDeviceId(): string {
+    if (cachedDeviceId) {
+        return cachedDeviceId;
+    }
+
+    try {
+        const stored = storage.get(STORAGE_KEY);
+        if (stored) {
+            cachedDeviceId = stored;
+            return stored;
+        }
+    } catch {
+        // Fallback if storage fails
+    }
+
+    const newId = noThrow(() => {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }, 'unknown-device-id') || 'unknown-device-id';
+
+    cachedDeviceId = newId;
+
+    try {
+        storage.set(STORAGE_KEY, newId);
+    } catch {
+        // Fallback if storage fails
+    }
+
+    return newId;
+}
+
+/**
+ * Generates a unique session ID.
+ */
+export function generateSessionId(): string {
+    return 'ses-' + getDeviceId() + '-' + Date.now().toString(36);
+}
+

package/src/core/id/installationId.ts

@@ -0,0 +1,52 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
+
+/**
+ * The SDK's canonical per-install id.
+ *
+ * ONE install, ONE id, every lane. This is deliberately NOT `getDeviceId()` —
+ * that is a separate value under a separate storage key, and the backend schema
+ * annotates the two as different ("stable per-install id from the SDK (≠
+ * deviceId)").
+ *
+ * It matters because the backend joins a bundle's OTA installs to that device's
+ * sessions through this value. OTA events have always been keyed by it; the
+ * session lane did not send it at all, so on the server the two could only be
+ * connected for devices that happened to have registered for push. Release
+ * health then reported "no data" for bundles that were running perfectly well —
+ * or crashing badly.
+ *
+ * Lives here rather than inside one feature so the OTA orchestrator and the
+ * session adapter cannot drift to two different ids.
+ */
+export function resolveInstallationId(): string {
+    try {
+        const storage = createStorageBackend();
+        const existing = storage.get(K_INSTALLATION_ID);
+        if (existing) return existing;
+        const id = `inst-${randomSegment()}${randomSegment()}`;
+        storage.set(K_INSTALLATION_ID, id);
+        return id;
+    } catch {
+        // Storage unavailable (tests, exotic hosts): a per-process id keeps the
+        // lanes functional; it stabilizes on the first run where storage works.
+        return `inst-ephemeral-${randomSegment()}`;
+    }
+}
+
+/** 8 chars of base36 entropy, crypto-backed when the runtime offers it. */
+function randomSegment(): string {
+    try {
+        const g = globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array } };
+        if (g.crypto?.getRandomValues) {
+            const bytes = g.crypto.getRandomValues(new Uint8Array(6));
+            return Array.from(bytes)
+                .map((b) => b.toString(36).padStart(2, '0'))
+                .join('')
+                .slice(0, 8);
+        }
+    } catch {
+        // fall through to Math.random
+    }
+    return Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+}

package/src/core/lifecycle/appLifecycle.ts

@@ -0,0 +1,33 @@
+import { AppState, AppStateStatus } from 'react-native';
+import { logger } from '../logger/internalLogger';
+
+export type LifecycleListener = (state: AppStateStatus) => void;
+
+class AppLifecycle {
+    private listeners: LifecycleListener[] = [];
+    private currentState: AppStateStatus = AppState.currentState;
+
+    constructor() {
+        AppState.addEventListener('change', this.handleStateChange);
+    }
+
+    private handleStateChange = (nextState: AppStateStatus) => {
+        __DEV__ && logger.debug(`App state changed: ${this.currentState} -> ${nextState}`);
+        this.currentState = nextState;
+        this.listeners.forEach((l) => l(nextState));
+    };
+
+    addListener(listener: LifecycleListener) {
+        this.listeners.push(listener);
+    }
+
+    removeListener(listener: LifecycleListener) {
+        this.listeners = this.listeners.filter((l) => l !== listener);
+    }
+
+    getCurrentState() {
+        return this.currentState;
+    }
+}
+
+export const appLifecycle = new AppLifecycle();

package/src/core/lifecycle/crashSafe.ts

@@ -0,0 +1,29 @@
+/**
+ * Crash safety utilities for the SDK.
+ * Ensures that internal SDK failures do not crash the host application.
+ */
+
+export function noThrow<T>(fn: () => T, fallback?: T): T | undefined {
+    try {
+        return fn();
+    } catch (error) {
+        if (__DEV__) {
+            console.warn('[ScaleBun] Internal non-fatal error:', error);
+        }
+        return fallback;
+    }
+}
+
+export async function safeAsync<T>(
+    fn: () => Promise<T>,
+    fallback?: T
+): Promise<T | undefined> {
+    try {
+        return await fn();
+    } catch (error) {
+        if (__DEV__) {
+            console.warn('[ScaleBun] Internal async error:', error);
+        }
+        return fallback;
+    }
+}

package/src/core/logger/errorClassification.ts

@@ -0,0 +1,108 @@
+/**
+ * ScaleBun SDK — Error Classification
+ *
+ * Pure helpers that classify transport/flush failures so the SDK can decide
+ * whether an error is a normal, recoverable condition (request aborted,
+ * timeout, offline, backend temporarily down) or a genuine fatal integration
+ * bug that the host developer must act on.
+ *
+ * Recoverable errors MUST NOT be logged through `console.error` — in React
+ * Native that triggers a LogBox / RedBox overlay for what is really a routine
+ * retry. See `internalLogger` for how levels map to console methods.
+ */
+
+/** Reason codes describing why a flush/transport attempt failed. */
+export type FailureReason =
+    | 'request_aborted'
+    | 'timeout'
+    | 'offline'
+    | 'server_error'
+    | 'unknown';
+
+function nameOf(error: unknown): string {
+    if (error && typeof error === 'object' && 'name' in error) {
+        return String((error as { name?: unknown }).name ?? '');
+    }
+    return '';
+}
+
+function messageOf(error: unknown): string {
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String((error as { message?: unknown }).message ?? '');
+    }
+    return typeof error === 'string' ? error : '';
+}
+
+/**
+ * AbortError — the request was cancelled via an AbortController. This happens
+ * on intentional cancel, app backgrounding, navigation interruption, or a
+ * timeout that aborts the underlying fetch.
+ */
+export function isAbortError(error: unknown): boolean {
+    if (nameOf(error) === 'AbortError') return true;
+    // Some RN/fetch polyfills surface aborts only via message text.
+    return /\baborted\b/i.test(messageOf(error));
+}
+
+/** Timeout — the SDK aborted the request because it exceeded the deadline. */
+export function isTimeoutError(error: unknown): boolean {
+    if (nameOf(error) === 'TimeoutError') return true;
+    if (error && typeof error === 'object' && (error as { isTimeout?: unknown }).isTimeout === true) {
+        return true;
+    }
+    return /\btimed?\s*out\b/i.test(messageOf(error));
+}
+
+/**
+ * Network error — device offline or the backend host is unreachable. RN's
+ * fetch rejects with a generic `TypeError: Network request failed`.
+ */
+export function isNetworkError(error: unknown): boolean {
+    const msg = messageOf(error).toLowerCase();
+    return (
+        nameOf(error) === 'NetworkError' ||
+        msg.includes('network request failed') ||
+        msg.includes('failed to fetch') ||
+        msg.includes('network error') ||
+        msg.includes('connection') && msg.includes('refused')
+    );
+}
+
+/**
+ * Recoverable flush error — the events were not delivered but can safely be
+ * returned to the queue and retried later. Covers abort, timeout, offline,
+ * and transient backend unavailability (HTTP 5xx / 429).
+ *
+ * `status` is the HTTP status when the transport returned a response (used to
+ * treat 5xx and 429 as recoverable).
+ */
+export function isRecoverableFlushError(error: unknown, status?: number): boolean {
+    if (isAbortError(error) || isTimeoutError(error) || isNetworkError(error)) {
+        return true;
+    }
+    if (typeof status === 'number' && (status >= 500 || status === 429)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Fatal SDK error — not recoverable by retrying. Today this means anything we
+ * could not classify as recoverable. Used to decide whether to surface via
+ * `console.error`. Callers may pass a known HTTP `status` to keep client
+ * errors (4xx, except 429) classified as fatal/actionable.
+ */
+export function isFatalSdkError(error: unknown, status?: number): boolean {
+    return !isRecoverableFlushError(error, status);
+}
+
+/** Human-readable reason code for logs and internal status. */
+export function describeErrorReason(error: unknown, status?: number): FailureReason {
+    if (isTimeoutError(error)) return 'timeout';
+    if (isAbortError(error)) return 'request_aborted';
+    if (isNetworkError(error)) return 'offline';
+    if (typeof status === 'number' && (status >= 500 || status === 429)) {
+        return 'server_error';
+    }
+    return 'unknown';
+}

package/src/core/logger/internalLogger.ts

@@ -0,0 +1,65 @@
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4,
+}
+
+/** Public, string-based log level used in SDK init config. */
+export type LogLevelName = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+const LEVEL_BY_NAME: Record<LogLevelName, LogLevel> = {
+    silent: LogLevel.NONE,
+    error: LogLevel.ERROR,
+    warn: LogLevel.WARN,
+    info: LogLevel.INFO,
+    debug: LogLevel.DEBUG,
+};
+
+class InternalLogger {
+    private level: LogLevel = LogLevel.WARN;
+
+    setLevel(level: LogLevel) {
+        this.level = level;
+    }
+
+    /** Set level from the public string name used in config (e.g. 'warn'). */
+    setLevelByName(name: LogLevelName) {
+        const resolved = LEVEL_BY_NAME[name];
+        if (resolved !== undefined) {
+            this.level = resolved;
+        }
+    }
+
+    /** Current numeric level — exposed for callers that branch on dev verbosity. */
+    getLevel(): LogLevel {
+        return this.level;
+    }
+
+    debug(...args: any[]) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.debug('[ScaleBun:Debug]', ...args);
+        }
+    }
+
+    info(...args: any[]) {
+        if (this.level <= LogLevel.INFO) {
+            console.info('[ScaleBun:Info]', ...args);
+        }
+    }
+
+    warn(...args: any[]) {
+        if (this.level <= LogLevel.WARN) {
+            console.warn('[ScaleBun:Warn]', ...args);
+        }
+    }
+
+    error(...args: any[]) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error('[ScaleBun:Error]', ...args);
+        }
+    }
+}
+
+export const logger = new InternalLogger();