@rootnode-app/react-native 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @rootnode-app/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Rootnode](https://rootnode.app) for React Native / Expo apps — **one install,
+one init**: crash reporting (native engine included), analytics with offline
+queueing and sessions, person properties, push registration.
+
+```bash
+npx expo install @rootnode-app/react-native
+```
+
+> Includes a native crash engine — ship it with a new build (EAS), not an OTA
+> update.
+
+```tsx
+import { Rootnode } from '@rootnode-app/react-native';
+
+Rootnode.init({
+  dsn: process.env.EXPO_PUBLIC_ROOTNODE_DSN,       // crash reporting
+  apiKey: process.env.EXPO_PUBLIC_ROOTNODE_KEY,    // analytics (rn_…)
+});
+
+export default Rootnode.wrap(App);
+
+// analytics — queued on disk, batched, survives offline & restarts
+Rootnode.screen('FundDetail');                  // screen_viewed + sticky screen
+Rootnode.capture('fund_viewed', { code: 'TLY' });
+
+// identity: after sign-in (also moves the push token to this user)
+await Rootnode.identify(userId, { plan: 'pro' });
+await Rootnode.reset();                          // on sign-out
+
+// push — permission + Expo token + registration in one call
+await Rootnode.registerForPush(userId);
+
+// crashes are automatic; manual reports:
+Rootnode.captureException(err, { route: '/funds/TLY' });
+```
+
+### What you get automatically
+
+- **Sessions**: `session_id` rotates after 30 min in background;
+  `app_opened` / `app_backgrounded` emitted; flush on background.
+- **Context** on every event: platform, OS/app version, device timezone,
+  `update_id` when expo-updates is present.
+- **Offline-safe queue**: persisted via AsyncStorage or expo-file-system when
+  available (memory otherwise), failed sends retry, capped at 1000.
+- **Crash-proof contract**: no SDK error ever reaches your app; missing
+  native modules degrade features to no-ops.
+
+Delivery credentials for push stay in **your** Expo project (expo.dev —
+APNs automatic, Android needs a one-time FCM service-account upload). Full
+guides: [integration](https://rootnode.app/docs/integration.md) ·
+[push](https://rootnode.app/docs/push.md).
+
+MIT © Doğan Aktı

package/dist/core.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Platform-free core of the React Native SDK: queue + batching + retry,
+ * persisted across restarts, session rotation, anonymous→user identity.
+ * Everything platform-ish (AppState, expo modules, Sentry) is injected by
+ * the binding in index.ts — so this logic runs (and is tested) in plain node.
+ *
+ * Contract: nothing here ever throws into the host app.
+ */
+export interface CoreStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+export interface CoreDeps {
+    fetch: typeof fetch;
+    now: () => number;
+    /** Persisted queue + identity; null = memory only. */
+    storage?: CoreStorage | null;
+    /** Static context merged into every event's properties. */
+    context: () => Record<string, unknown>;
+    onError?: (message: string) => void;
+}
+export interface CoreConfig {
+    apiKey: string;
+    host: string;
+    flushIntervalMs?: number;
+    sessionTimeoutMs?: number;
+}
+export declare class RootnodeCore {
+    private readonly cfg;
+    private readonly deps;
+    private pending;
+    private id;
+    private session;
+    private backgroundedAt;
+    private stickyScreen;
+    private flushing;
+    private timer;
+    constructor(cfg: CoreConfig, deps: CoreDeps);
+    get distinctId(): string;
+    get sessionId(): string;
+    /** Restore identity + queue; start the flush timer. Never throws. */
+    start(): Promise<void>;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    /** Track a screen view and make it the sticky context for later events. */
+    screen(name: string): void;
+    identify(userId: string, set?: Record<string, unknown>): Promise<void>;
+    /** Sign-out: fresh anonymous identity and a fresh session. */
+    reset(): Promise<void>;
+    appBackgrounded(): void;
+    appForegrounded(): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private doFlush;
+    private persistQueue;
+    private persistId;
+    private report;
+}

package/dist/core.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Platform-free core of the React Native SDK: queue + batching + retry,
+ * persisted across restarts, session rotation, anonymous→user identity.
+ * Everything platform-ish (AppState, expo modules, Sentry) is injected by
+ * the binding in index.ts — so this logic runs (and is tested) in plain node.
+ *
+ * Contract: nothing here ever throws into the host app.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootnodeCore = void 0;
+const QUEUE_KEY = 'rootnode.queue';
+const ID_KEY = 'rootnode.distinct_id';
+const QUEUE_CAP = 1000;
+const AUTO_FLUSH_AT = 20;
+// No Node builtins here — this file must bundle under Metro (React Native).
+// Prefer the Web Crypto UUID when the runtime has one; fall back to a plain
+// Math.random v4 (these are analytics ids, not secrets).
+const uuid = () => {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === 'function')
+        return c.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
+        const r = (Math.random() * 16) | 0;
+        return (ch === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+};
+class RootnodeCore {
+    constructor(cfg, deps) {
+        this.cfg = cfg;
+        this.deps = deps;
+        this.pending = [];
+        this.id = `anon-${uuid()}`;
+        this.session = uuid();
+        this.backgroundedAt = null;
+        this.flushing = null;
+        this.timer = null;
+    }
+    get distinctId() {
+        return this.id;
+    }
+    get sessionId() {
+        return this.session;
+    }
+    /** Restore identity + queue; start the flush timer. Never throws. */
+    async start() {
+        try {
+            const saved = await this.deps.storage?.getItem(ID_KEY);
+            if (saved)
+                this.id = saved;
+            else
+                await this.persistId();
+            const q = await this.deps.storage?.getItem(QUEUE_KEY);
+            if (q) {
+                const parsed = JSON.parse(q);
+                if (Array.isArray(parsed))
+                    this.pending.push(...parsed.slice(-QUEUE_CAP));
+            }
+        }
+        catch (e) {
+            this.report(`restore failed: ${String(e)}`);
+        }
+        const interval = this.cfg.flushIntervalMs ?? 10000;
+        if (interval > 0) {
+            this.timer = setInterval(() => void this.flush(), interval);
+            this.timer?.unref?.();
+        }
+    }
+    capture(event, properties = {}) {
+        try {
+            this.pending.push({
+                event,
+                distinct_id: this.id,
+                timestamp: new Date(this.deps.now()).toISOString(),
+                properties: {
+                    ...this.deps.context(),
+                    ...(this.stickyScreen ? { screen: this.stickyScreen } : {}),
+                    ...properties,
+                    session_id: this.session,
+                },
+            });
+            if (this.pending.length > QUEUE_CAP)
+                this.pending.splice(0, this.pending.length - QUEUE_CAP);
+            void this.persistQueue();
+            if (this.pending.length >= AUTO_FLUSH_AT)
+                void this.flush();
+        }
+        catch (e) {
+            this.report(`capture failed: ${String(e)}`);
+        }
+    }
+    /** Track a screen view and make it the sticky context for later events. */
+    screen(name) {
+        this.stickyScreen = name;
+        this.capture('screen_viewed', { screen: name });
+    }
+    async identify(userId, set) {
+        try {
+            this.id = userId;
+            await this.persistId();
+            this.capture('$identify', set ? { $set: set } : {});
+            await this.flush();
+        }
+        catch (e) {
+            this.report(`identify failed: ${String(e)}`);
+        }
+    }
+    /** Sign-out: fresh anonymous identity and a fresh session. */
+    async reset() {
+        this.id = `anon-${uuid()}`;
+        this.session = uuid();
+        await this.persistId();
+    }
+    appBackgrounded() {
+        this.backgroundedAt = this.deps.now();
+        this.capture('app_backgrounded', {});
+        void this.flush();
+    }
+    appForegrounded() {
+        const timeout = this.cfg.sessionTimeoutMs ?? 30 * 60 * 1000;
+        const away = this.backgroundedAt != null ? this.deps.now() - this.backgroundedAt : 0;
+        this.backgroundedAt = null;
+        if (away >= timeout) {
+            this.session = uuid();
+            this.capture('app_opened', {});
+        }
+    }
+    async flush() {
+        // Queue behind an in-flight flush (events captured meanwhile must go out
+        // too), then take the slot. The while re-check keeps concurrent callers
+        // from double-sending the same batch.
+        while (this.flushing)
+            await this.flushing;
+        const run = this.doFlush().finally(() => {
+            if (this.flushing === run)
+                this.flushing = null;
+        });
+        this.flushing = run;
+        return run;
+    }
+    async close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        await this.flush();
+    }
+    async doFlush() {
+        try {
+            if (!this.cfg.apiKey || this.pending.length === 0)
+                return;
+            const batch = this.pending.slice(0, QUEUE_CAP);
+            const res = await this.deps.fetch(`${this.cfg.host}/v1/capture`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ api_key: this.cfg.apiKey, batch }),
+            });
+            if (res.status < 400) {
+                this.pending.splice(0, batch.length);
+                await this.persistQueue();
+            }
+            else
+                this.report(`capture refused: http ${res.status}`);
+        }
+        catch (e) {
+            this.report(`flush failed: ${String(e)}`);
+        }
+    }
+    async persistQueue() {
+        try {
+            await this.deps.storage?.setItem(QUEUE_KEY, JSON.stringify(this.pending));
+        }
+        catch {
+            /* storage is a convenience, never a requirement */
+        }
+    }
+    async persistId() {
+        try {
+            await this.deps.storage?.setItem(ID_KEY, this.id);
+        }
+        catch {
+            /* same */
+        }
+    }
+    report(msg) {
+        try {
+            this.deps.onError?.(`[rootnode] ${msg}`);
+        }
+        catch {
+            /* the error hook must not throw either */
+        }
+    }
+}
+exports.RootnodeCore = RootnodeCore;

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Rootnode for React Native / Expo: one install, one init.
+ *   Rootnode.init({ dsn, apiKey })   → crash (Sentry engine inside) + analytics + sessions
+ *   Rootnode.registerForPush(userId) → push token registry
+ * Every platform module is loaded defensively: a missing/incompatible native
+ * module degrades that feature to a no-op instead of crashing the app.
+ */
+export interface RootnodeConfig {
+    /** Crash DSN of this app's target. Omit to disable crash reporting. */
+    dsn?: string;
+    /** Analytics API key (rn_…). Omit to disable analytics. */
+    apiKey?: string;
+    /** Defaults to https://rootnode.app (or the DSN's host). */
+    host?: string;
+    environment?: string;
+    /** Session gap that starts a new session (default 30 min). */
+    sessionTimeoutMs?: number;
+    flushIntervalMs?: number;
+    /** Extra options passed straight to the crash engine's init. */
+    crashOptions?: Record<string, unknown>;
+    onError?: (message: string) => void;
+}
+type Loader = (name: string) => any;
+/** Test seam: swap module loading (vitest has no RN runtime). */
+export declare function _setLoader(l: Loader): void;
+declare class RootnodeClient {
+    private core;
+    private sentry;
+    private cfg;
+    private lastPushToken;
+    private appStateSub;
+    /** Safe to call once at startup; everything after degrades gracefully. */
+    init(cfg: RootnodeConfig): void;
+    captureException(err: unknown, context?: Record<string, unknown>): void;
+    /** Wrap your root component (touch/startup instrumentation). Identity if crash is off. */
+    wrap<T>(component: T): T;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    screen(name: string): void;
+    identify(userId: string, set?: Record<string, unknown>): Promise<void>;
+    reset(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Ask permission (if needed), fetch the Expo push token, register it. */
+    registerForPush(distinctId?: string): Promise<boolean>;
+    unregisterPush(): Promise<void>;
+    private base;
+    private postPushToken;
+    private makeStorage;
+    private makeContext;
+    private watchAppState;
+}
+export declare const Rootnode: RootnodeClient;
+export { RootnodeCore } from './core';

package/dist/index.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootnodeCore = exports.Rootnode = void 0;
+exports._setLoader = _setLoader;
+const core_1 = require("./core");
+let load = (name) => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(name);
+};
+/** Test seam: swap module loading (vitest has no RN runtime). */
+function _setLoader(l) {
+    load = l;
+}
+function tryLoad(name, onError) {
+    try {
+        return load(name);
+    }
+    catch {
+        onError?.(`[rootnode] optional module ${name} unavailable — feature disabled`);
+        return null;
+    }
+}
+class RootnodeClient {
+    constructor() {
+        this.core = null;
+        this.sentry = null;
+        this.cfg = {};
+        this.lastPushToken = null;
+        this.appStateSub = null;
+    }
+    /** Safe to call once at startup; everything after degrades gracefully. */
+    init(cfg) {
+        try {
+            this.cfg = cfg;
+            const host = cfg.host?.replace(/\/$/, '') ??
+                (cfg.dsn?.match(/^https?:\/\/[^@]+@([^/]+)\//)?.[1]
+                    ? `https://${cfg.dsn.match(/^https?:\/\/[^@]+@([^/]+)\//)[1]}`
+                    : 'https://rootnode.app');
+            if (cfg.dsn) {
+                this.sentry = tryLoad('@sentry/react-native', cfg.onError);
+                this.sentry?.init?.({
+                    dsn: cfg.dsn,
+                    environment: cfg.environment,
+                    tracesSampleRate: 0,
+                    ...cfg.crashOptions,
+                });
+            }
+            if (cfg.apiKey) {
+                this.core = new core_1.RootnodeCore({
+                    apiKey: cfg.apiKey,
+                    host,
+                    flushIntervalMs: cfg.flushIntervalMs,
+                    sessionTimeoutMs: cfg.sessionTimeoutMs,
+                }, {
+                    fetch: (...a) => fetch(...a),
+                    now: () => Date.now(),
+                    storage: this.makeStorage(),
+                    context: this.makeContext(),
+                    onError: cfg.onError,
+                });
+                void this.core.start().then(() => this.core?.capture('app_opened', {}));
+                this.watchAppState();
+            }
+        }
+        catch (e) {
+            cfg.onError?.(`[rootnode] init failed: ${String(e)}`);
+        }
+    }
+    // ------------------------------------------------------------- crash
+    captureException(err, context) {
+        try {
+            this.sentry?.captureException?.(err, context ? { extra: context } : undefined);
+        }
+        catch {
+            /* never into the app */
+        }
+    }
+    /** Wrap your root component (touch/startup instrumentation). Identity if crash is off. */
+    wrap(component) {
+        try {
+            return this.sentry?.wrap ? this.sentry.wrap(component) : component;
+        }
+        catch {
+            return component;
+        }
+    }
+    // --------------------------------------------------------- analytics
+    capture(event, properties = {}) {
+        this.core?.capture(event, properties);
+    }
+    screen(name) {
+        this.core?.screen(name);
+    }
+    async identify(userId, set) {
+        await this.core?.identify(userId, set);
+        // The device now belongs to this user — move its push address too.
+        if (this.lastPushToken)
+            await this.postPushToken(this.lastPushToken, userId);
+    }
+    async reset() {
+        await this.core?.reset();
+    }
+    async flush() {
+        await this.core?.flush();
+    }
+    async close() {
+        try {
+            this.appStateSub?.remove?.();
+        }
+        catch {
+            /* already gone */
+        }
+        await this.core?.close();
+    }
+    // -------------------------------------------------------------- push
+    /** Ask permission (if needed), fetch the Expo push token, register it. */
+    async registerForPush(distinctId) {
+        try {
+            if (!this.cfg.apiKey)
+                return false;
+            const Notifications = tryLoad('expo-notifications', this.cfg.onError);
+            if (!Notifications)
+                return false;
+            const Device = tryLoad('expo-device', this.cfg.onError);
+            if (Device && Device.isDevice === false)
+                return false; // simulators get nothing
+            const perm = await Notifications.getPermissionsAsync();
+            const granted = perm?.granted ? true : (await Notifications.requestPermissionsAsync())?.granted;
+            if (!granted)
+                return false;
+            const token = (await Notifications.getExpoPushTokenAsync())?.data;
+            if (!token)
+                return false;
+            this.lastPushToken = token;
+            return this.postPushToken(token, distinctId ?? this.core?.distinctId ?? 'anonymous');
+        }
+        catch (e) {
+            this.cfg.onError?.(`[rootnode] push register failed: ${String(e)}`);
+            return false;
+        }
+    }
+    async unregisterPush() {
+        try {
+            if (!this.lastPushToken || !this.cfg.apiKey)
+                return;
+            await fetch(`${this.base()}/v1/push/unregister`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ api_key: this.cfg.apiKey, token: this.lastPushToken }),
+            });
+            this.lastPushToken = null;
+        }
+        catch {
+            /* goal state is "not registered"; a lost unregister self-heals via pruning */
+        }
+    }
+    // ---------------------------------------------------------- plumbing
+    base() {
+        return (this.cfg.host?.replace(/\/$/, '') ??
+            (this.cfg.dsn?.match(/^https?:\/\/[^@]+@([^/]+)\//)?.[1]
+                ? `https://${this.cfg.dsn.match(/^https?:\/\/[^@]+@([^/]+)\//)[1]}`
+                : 'https://rootnode.app'));
+    }
+    async postPushToken(token, distinctId) {
+        try {
+            const res = await fetch(`${this.base()}/v1/push/register`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ api_key: this.cfg.apiKey, distinct_id: distinctId, token }),
+            });
+            return res.status < 400;
+        }
+        catch (e) {
+            this.cfg.onError?.(`[rootnode] push register failed: ${String(e)}`);
+            return false;
+        }
+    }
+    makeStorage() {
+        const AsyncStorage = tryLoad('@react-native-async-storage/async-storage', undefined)?.default;
+        if (AsyncStorage?.getItem)
+            return AsyncStorage;
+        const FS = tryLoad('expo-file-system/legacy', undefined) ?? tryLoad('expo-file-system', undefined);
+        if (FS?.documentDirectory && FS.readAsStringAsync) {
+            const path = (k) => `${FS.documentDirectory}${k.replace(/[^\w.-]/g, '_')}.json`;
+            return {
+                getItem: async (k) => {
+                    try {
+                        return await FS.readAsStringAsync(path(k));
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+                setItem: async (k, v) => {
+                    await FS.writeAsStringAsync(path(k), v);
+                },
+            };
+        }
+        return null; // memory-only queue — still works, just not restart-proof
+    }
+    makeContext() {
+        const RN = tryLoad('react-native', undefined);
+        const Device = tryLoad('expo-device', undefined);
+        const App = tryLoad('expo-application', undefined);
+        const Updates = tryLoad('expo-updates', undefined);
+        return () => {
+            const ctx = {};
+            try {
+                if (RN?.Platform?.OS)
+                    ctx.platform = RN.Platform.OS;
+                if (Device?.osVersion)
+                    ctx.os_version = String(Device.osVersion);
+                if (App?.nativeApplicationVersion)
+                    ctx.app_version = App.nativeApplicationVersion;
+                const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+                if (tz)
+                    ctx.device_tz = tz;
+                if (Updates?.updateId)
+                    ctx.update_id = Updates.updateId;
+            }
+            catch {
+                /* context is best-effort */
+            }
+            return ctx;
+        };
+    }
+    watchAppState() {
+        try {
+            const RN = tryLoad('react-native', this.cfg.onError);
+            if (!RN?.AppState?.addEventListener)
+                return;
+            this.appStateSub = RN.AppState.addEventListener('change', (state) => {
+                if (state === 'background' || state === 'inactive')
+                    this.core?.appBackgrounded();
+                else if (state === 'active')
+                    this.core?.appForegrounded();
+            });
+        }
+        catch {
+            /* no AppState = no session rotation, nothing else breaks */
+        }
+    }
+}
+exports.Rootnode = new RootnodeClient();
+var core_2 = require("./core");
+Object.defineProperty(exports, "RootnodeCore", { enumerable: true, get: function () { return core_2.RootnodeCore; } });

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@rootnode-app/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Rootnode for React Native / Expo apps: crash reporting, analytics, sessions and push registration — one install, one init.",
+  "license": "MIT",
+  "author": "Doğan Aktı",
+  "homepage": "https://rootnode.app/docs/integration.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doganakti/rootnode.git",
+    "directory": "sdk/react-native"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {
+    "@sentry/react-native": ">=5.0.0",
+    "expo-device": "*",
+    "expo-notifications": "*"
+  },
+  "peerDependencies": {
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  }
+}