@emit-vision/sdk-react-native 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emit Vision
+
+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

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @emit-vision/sdk-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.
+React Native helper layer for `@emit-vision/sdk-js`. Wraps the browser SDK with
+React Native equivalents for storage, connectivity, and error handling —
+works with both bare React Native and Expo.
+
+📖 **[Full sdk-react-native reference →](https://emitvision.com/docs/sdk-react-native)**
+
+## Installation
+
+```bash
+npm install @emit-vision/sdk-react-native @emit-vision/sdk-js
+```
+
+Optional (recommended):
+
+```bash
+npm install @react-native-async-storage/async-storage @react-native-community/netinfo
+```
+
+## Quick Start
+
+```tsx
+import { useEffect } from "react";
+import { AppState, ErrorUtils } from "react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import NetInfo from "@react-native-community/netinfo";
+import { initRN } from "@emit-vision/sdk-react-native";
+
+export function App() {
+  useEffect(() => {
+    let client: Awaited<ReturnType<typeof initRN>> | undefined;
+
+    initRN({
+      dsn: process.env.EXPO_PUBLIC_EMIT_VISION_DSN,
+      environment: process.env.NODE_ENV,
+      asyncStorage: AsyncStorage,
+      appState: AppState,
+      netInfo: NetInfo,
+      errorUtils: ErrorUtils,
+    }).then((c) => {
+      client = c;
+    });
+
+    return () => {
+      client?.close();
+    };
+  }, []);
+
+  return <Router />;
+}
+```
+
+All of `asyncStorage`, `appState`, `netInfo`, and `errorUtils` are optional —
+pass only the platform APIs you want wired in.
+
+## useEmitVision()
+
+```tsx
+import { useEmitVision } from "@emit-vision/sdk-react-native";
+
+function SaveButton() {
+  const { captureEvent } = useEmitVision();
+
+  return (
+    <TouchableOpacity onPress={() => captureEvent("settings_saved")}>
+      <Text>Save</Text>
+    </TouchableOpacity>
+  );
+}
+```
+
+## Consent
+
+Pass `consentRequired: true` to `initRN`, then record the user's choice:
+
+```tsx
+import { grantConsent, declineConsent } from "@emit-vision/sdk-react-native";
+
+<Button title="Accept" onPress={() => grantConsent()} />
+<Button title="Decline" onPress={() => declineConsent()} />
+```
+
+When you pass `asyncStorage` to `initRN`, the choice is saved through it, so a
+grant or a decline survives app restarts and the user isn't asked again.
+
+**Without `asyncStorage` (and without a `consentStorage`), the choice is kept
+in memory only and is forgotten when the app restarts.**
+
+To persist consent somewhere other than AsyncStorage, pass a `consentStorage`
+to `initRN`. It takes precedence over `asyncStorage` for consent. `getItem`
+must answer synchronously; writes may be async:
+
+```ts
+import type { ConsentStorage } from "@emit-vision/sdk-js";
+
+const consentStorage: ConsentStorage = {
+  getItem: (key) => cache.get(key) ?? null,
+  setItem: (key, value) => {
+    cache.set(key, value);
+    return persist(key, value);
+  },
+  removeItem: (key) => {
+    cache.delete(key);
+    return unpersist(key);
+  },
+};
+
+await initRN({ dsn, consentRequired: true, consentStorage });
+```
+
+See the [consent model](https://emitvision.com/docs/sdk-js#consent) for the
+states and what is sent in each.
+
+## Notes
+
+- Page-view auto-capture is disabled — there is no DOM in React Native.
+- Unhandled promise rejections are not automatically captured (different
+  runtime guarantees than the browser); track manually with `captureError`.
+- No optional peer package? Implement `AsyncStorageLike`/`NetInfoLike`
+  yourself and pass it to `initRN` — see the full reference for an example.
+
+## Documentation
+
+- [sdk-react-native reference](https://emitvision.com/docs/sdk-react-native) — full API reference and guides
+- [Getting started](https://emitvision.com/docs/introduction)
+- [Installation & configuration](https://emitvision.com/docs/installation)
+- [Browser SDK](https://emitvision.com/docs/sdk-js) · [React SDK](https://emitvision.com/docs/sdk-react)
+- [Troubleshooting](https://emitvision.com/docs/troubleshooting)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { EmitVisionOptions, captureEvent, captureError, identify, group, consent, grantConsent, declineConsent, getConsentState, onConsentChange, flush, setContext, setTags } from '@emit-vision/sdk-js';
+export { CaptureOptions, ConsentState, EmitVisionOptions, EmitVisionUser, captureError, captureEvent, consent, declineConsent, flush, getConsentState, grantConsent, group, identify, onConsentChange, setContext, setTags } from '@emit-vision/sdk-js';
+
+type AsyncStorageLike = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem?(key: string): Promise<void>;
+};
+type NetInfoState = {
+    isConnected: boolean | null;
+};
+type AppStateLike = {
+    addEventListener(type: "change", handler: (state: string) => void): {
+        remove(): void;
+    };
+};
+type ErrorUtilsLike = {
+    setGlobalHandler(handler: (error: Error, isFatal?: boolean) => void): void;
+    getGlobalHandler(): ((error: Error, isFatal?: boolean) => void) | null;
+};
+
+type RNInitOptions = EmitVisionOptions & {
+    asyncStorage?: AsyncStorageLike;
+    netInfo?: {
+        addEventListener(listener: (state: NetInfoState) => void): (() => void) | {
+            remove(): void;
+        } | void;
+    };
+    appState?: AppStateLike;
+    errorUtils?: ErrorUtilsLike;
+};
+type RNClient = {
+    close(): void;
+};
+declare function initRN(options: RNInitOptions): Promise<RNClient>;
+
+type EmitVisionRNApi = {
+    captureEvent: typeof captureEvent;
+    captureError: typeof captureError;
+    identify: typeof identify;
+    group: typeof group;
+    consent: typeof consent;
+    grantConsent: typeof grantConsent;
+    declineConsent: typeof declineConsent;
+    getConsentState: typeof getConsentState;
+    onConsentChange: typeof onConsentChange;
+    flush: typeof flush;
+    setContext: typeof setContext;
+    setTags: typeof setTags;
+};
+declare function useEmitVision(): EmitVisionRNApi;
+
+export { type AppStateLike, type AsyncStorageLike, type EmitVisionRNApi, type ErrorUtilsLike, type NetInfoState, type RNClient, type RNInitOptions, initRN, useEmitVision };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/index.ts
+import {
+  captureEvent as captureEvent2,
+  captureError as captureError3,
+  identify as identify2,
+  group as group2,
+  consent as consent2,
+  grantConsent as grantConsent2,
+  declineConsent as declineConsent2,
+  getConsentState as getConsentState2,
+  onConsentChange as onConsentChange2,
+  flush as flush3,
+  setContext as setContext2,
+  setTags as setTags2
+} from "@emit-vision/sdk-js";
+
+// src/client-rn.ts
+import {
+  consentStorageKey,
+  init,
+  flush,
+  captureError
+} from "@emit-vision/sdk-js";
+
+// src/consent-storage.ts
+async function createConsentStorage(asyncStorage, key) {
+  const cache = /* @__PURE__ */ new Map();
+  try {
+    const stored = await asyncStorage.getItem(key);
+    if (stored) cache.set(key, stored);
+  } catch {
+  }
+  return {
+    getItem: (k) => cache.get(k) ?? null,
+    setItem: (k, v) => {
+      cache.set(k, v);
+      return asyncStorage.setItem(k, v);
+    },
+    removeItem: (k) => {
+      cache.delete(k);
+      return asyncStorage.removeItem?.(k);
+    }
+  };
+}
+
+// src/client-rn.ts
+var ANON_ID_KEY = "__ev_anon_id";
+async function getOrCreateAnonId(storage) {
+  try {
+    const stored = await storage.getItem(ANON_ID_KEY);
+    if (stored) return stored;
+    const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : Math.random().toString(36).slice(2) + Date.now().toString(36);
+    await storage.setItem(ANON_ID_KEY, id);
+    return id;
+  } catch {
+    return void 0;
+  }
+}
+async function initRN(options) {
+  const { asyncStorage, netInfo, appState, errorUtils, ...sdkOptions } = options;
+  const sessionId = sdkOptions.sessionId ?? (asyncStorage ? await getOrCreateAnonId(asyncStorage) : void 0);
+  const consentStorage = sdkOptions.consentStorage ?? (asyncStorage ? await createConsentStorage(
+    asyncStorage,
+    consentStorageKey(sdkOptions.apiKey ?? "", sdkOptions.projectId)
+  ) : void 0);
+  const client = init({
+    ...sdkOptions,
+    sessionId,
+    consentStorage,
+    autoCapture: {
+      ...sdkOptions.autoCapture,
+      pageViews: false
+    }
+  });
+  let appStateSub;
+  if (appState) {
+    appStateSub = appState.addEventListener("change", (nextState) => {
+      if (nextState === "inactive" || nextState === "background") {
+        void flush().catch(() => void 0);
+      }
+    });
+  }
+  let prevErrorHandler = null;
+  if (errorUtils && options.autoCapture?.errors !== false) {
+    prevErrorHandler = errorUtils.getGlobalHandler();
+    errorUtils.setGlobalHandler((error, isFatal) => {
+      captureError(error, {
+        context: { isFatal: isFatal ?? false, source: "ErrorUtils" }
+      });
+      prevErrorHandler?.(error, isFatal);
+    });
+  }
+  let netInfoUnsub;
+  if (netInfo) {
+    const sub = netInfo.addEventListener((state) => {
+      if (state.isConnected) {
+        void flush().catch(() => void 0);
+      }
+    });
+    if (typeof sub === "function") {
+      netInfoUnsub = sub;
+    } else if (sub && typeof sub.remove === "function") {
+      netInfoUnsub = () => sub.remove();
+    }
+  }
+  return {
+    close() {
+      appStateSub?.remove();
+      netInfoUnsub?.();
+      if (errorUtils && prevErrorHandler !== null) {
+        errorUtils.setGlobalHandler(prevErrorHandler);
+      }
+      client.close();
+    }
+  };
+}
+
+// src/useEmitVision.ts
+import {
+  captureEvent,
+  captureError as captureError2,
+  identify,
+  group,
+  consent,
+  grantConsent,
+  declineConsent,
+  getConsentState,
+  onConsentChange,
+  flush as flush2,
+  setContext,
+  setTags
+} from "@emit-vision/sdk-js";
+var api = {
+  captureEvent,
+  captureError: captureError2,
+  identify,
+  group,
+  consent,
+  grantConsent,
+  declineConsent,
+  getConsentState,
+  onConsentChange,
+  flush: flush2,
+  setContext,
+  setTags
+};
+function useEmitVision() {
+  return api;
+}
+export {
+  captureError3 as captureError,
+  captureEvent2 as captureEvent,
+  consent2 as consent,
+  declineConsent2 as declineConsent,
+  flush3 as flush,
+  getConsentState2 as getConsentState,
+  grantConsent2 as grantConsent,
+  group2 as group,
+  identify2 as identify,
+  initRN,
+  onConsentChange2 as onConsentChange,
+  setContext2 as setContext,
+  setTags2 as setTags,
+  useEmitVision
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@emit-vision/sdk-react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "React Native SDK for emit-vision analytics and error tracking.",
+  "private": false,
+  "license": "MIT",
+  "author": "Emit Vision",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.73.0",
+    "@react-native-async-storage/async-storage": ">=2.0.0",
+    "@react-native-community/netinfo": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "@react-native-community/netinfo": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@emit-vision/sdk-js": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }