@lapwy/react-native 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @lapwy/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.
+lapwy for React Native and Expo.
+
+```sh
+npm install @lapwy/react-native @react-native-async-storage/async-storage
+```
+
+```js
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { init, screen, track } from "@lapwy/react-native";
+
+init({ site: "lw_…", app: "fernshop", storage: AsyncStorage });  // once, at start-up
+screen("Home");                                                  // on every screen
+track("add_to_cart", { product: "monstera" });
+```
+
+Screens can be followed for you: `navigationTracker` for React Navigation, `useScreen` for Expo Router or any screen component.
+
+A user is told apart by one random id per install, kept in the storage you pass. Events wait in a queue that survives being offline and the app being closed. Time on a screen counts only while the app is in the foreground.

package/dist/index.cjs

@@ -0,0 +1,254 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  flush: () => flush,
+  init: () => init,
+  navigationTracker: () => navigationTracker,
+  optOut: () => optOut,
+  reset: () => reset,
+  screen: () => screen,
+  track: () => track,
+  useScreen: () => useScreen
+});
+module.exports = __toCommonJS(src_exports);
+var import_react = require("react");
+var import_react_native = require("react-native");
+var DEFAULT_ENDPOINT = "https://in.lapwy.com/e";
+var ID_KEY = "lapwy_device_id";
+var QUEUE_KEY = "lapwy_queue";
+var MAX_QUEUE = 500;
+var state = null;
+var early = [];
+function hex(bytes) {
+  const a = new Uint8Array(bytes);
+  const c = globalThis.crypto;
+  if (c && c.getRandomValues) c.getRandomValues(a);
+  else for (let i = 0; i < bytes; i++) a[i] = Math.floor(Math.random() * 256);
+  let s = "";
+  for (let i = 0; i < bytes; i++) s += (a[i] + 256).toString(16).slice(1);
+  return s;
+}
+function uuid() {
+  const h = hex(16);
+  return h.slice(0, 8) + "-" + h.slice(8, 12) + "-4" + h.slice(13, 16) + "-a" + h.slice(17, 20) + "-" + h.slice(20);
+}
+function screenUrl(app, name) {
+  const path = name.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+  return `app://${app}/${path}`;
+}
+function save(s) {
+  var _a;
+  (_a = s.options.storage) == null ? void 0 : _a.setItem(QUEUE_KEY, JSON.stringify(s.queue)).catch(() => void 0);
+}
+function add(s, kind, extra) {
+  if (s.out) return;
+  const e = { id: uuid(), t: Date.now(), k: kind, u: s.screenUrl, p: s.screenId };
+  for (const k in extra) if (extra[k] !== void 0) e[k] = extra[k];
+  s.queue.push(e);
+  if (s.queue.length > MAX_QUEUE) s.queue.splice(0, s.queue.length - MAX_QUEUE);
+  save(s);
+  if (!s.timer) s.timer = setTimeout(() => void flush(), 2e3);
+}
+function osVersion() {
+  var _a;
+  if (import_react_native.Platform.OS !== "android") return String(import_react_native.Platform.Version);
+  const release = (_a = import_react_native.Platform.constants) == null ? void 0 : _a.Release;
+  return release == null ? "" : String(release).split(".").slice(0, 2).join(".");
+}
+function client(s) {
+  const { width, height } = import_react_native.Dimensions.get("window");
+  let language = "";
+  try {
+    language = Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+  }
+  return {
+    sw: Math.round(width),
+    sh: Math.round(height),
+    l: language,
+    rel: s.options.version || "",
+    pf: import_react_native.Platform.OS,
+    osv: osVersion(),
+    // The usual cut between a phone and a tablet: 600 points on the short side.
+    dt: import_react_native.Platform.isPad || Math.min(width, height) >= 600 ? "tablet" : "mobile"
+  };
+}
+async function flush() {
+  const s = state;
+  if (!s) return;
+  if (s.timer) clearTimeout(s.timer);
+  s.timer = 0;
+  await s.ready;
+  if (s.sending || !s.queue.length) return;
+  s.sending = true;
+  const events = s.queue.slice(0, 50);
+  try {
+    const res = await fetch(s.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "text/plain" },
+      body: JSON.stringify({ k: s.options.site, v: s.id || void 0, sdk: "react-native-0.1", now: Date.now(), c: client(s), e: events })
+    });
+    if (res.status === 429 || res.status >= 500) throw new Error("retry");
+    s.queue = s.queue.filter((e) => !events.includes(e));
+    s.backoff = 0;
+    save(s);
+    s.sending = false;
+    if (s.queue.length) s.timer = setTimeout(() => void flush(), 200);
+  } catch {
+    s.sending = false;
+    s.timer = setTimeout(() => void flush(), Math.min(5e3 * Math.pow(2, s.backoff++), 3e5));
+  }
+}
+function settle(s) {
+  if (s.shownAt) {
+    s.engaged += Date.now() - s.shownAt;
+    s.shownAt = 0;
+  }
+  if (s.screenId && s.engaged >= 1e3) add(s, "engagement", { v: s.engaged });
+  s.engaged = 0;
+}
+function later(run) {
+  if (state) run();
+  else if (early.length < 100) early.push(run);
+}
+function init(options) {
+  if (state || !options.site) return;
+  const s = {
+    options,
+    endpoint: options.endpoint || DEFAULT_ENDPOINT,
+    app: (options.app || "app").toLowerCase().replace(/[^a-z0-9.-]+/g, "-") || "app",
+    id: "",
+    ready: Promise.resolve(),
+    queue: [],
+    screenUrl: "",
+    screenId: "",
+    shownAt: 0,
+    engaged: 0,
+    timer: 0,
+    backoff: 0,
+    sending: false,
+    out: false
+  };
+  s.screenUrl = screenUrl(s.app, "");
+  state = s;
+  const storage = options.storage;
+  s.ready = (async () => {
+    if (!storage) return;
+    try {
+      const [id, queued] = await Promise.all([storage.getItem(ID_KEY), storage.getItem(QUEUE_KEY)]);
+      s.id = id && /^[0-9a-f]{16,64}$/.test(id) ? id : hex(16);
+      if (s.id !== id) await storage.setItem(ID_KEY, s.id);
+      const old = queued ? JSON.parse(queued) : [];
+      if (Array.isArray(old) && old.length) s.queue = old.concat(s.queue).slice(-MAX_QUEUE);
+    } catch {
+    }
+  })();
+  import_react_native.AppState.addEventListener("change", (next) => {
+    if (next === "active") {
+      if (!s.shownAt) s.shownAt = Date.now();
+      void flush();
+    } else {
+      settle(s);
+      void flush();
+    }
+  });
+  if (options.errors !== false) {
+    const utils = globalThis.ErrorUtils;
+    if (utils) {
+      const before = utils.getGlobalHandler();
+      let reported = 0;
+      utils.setGlobalHandler((error, fatal) => {
+        try {
+          const e = error;
+          const msg = String(e && e.message || error || "").slice(0, 300);
+          if (msg && reported++ < 10) {
+            add(s, "error", { n: String(e && e.name || "Error").slice(0, 60), props: { msg, fatal: Boolean(fatal) } });
+            void flush();
+          }
+        } catch {
+        }
+        before(error, fatal);
+      });
+    }
+  }
+  const waiting = early;
+  early = [];
+  waiting.forEach((run) => run());
+}
+function screen(name, props) {
+  later(() => {
+    const s = state;
+    const url = screenUrl(s.app, name);
+    if (url === s.screenUrl && s.screenId && !props) return;
+    settle(s);
+    const from = s.screenId ? s.screenUrl : "";
+    s.screenUrl = url;
+    s.screenId = hex(8);
+    s.shownAt = import_react_native.AppState.currentState === "active" || import_react_native.AppState.currentState == null ? Date.now() : 0;
+    add(s, "pageview", { r: from, ti: name, props });
+  });
+}
+function track(name, props) {
+  later(() => {
+    if (typeof name === "string" && name) add(state, "custom", { n: name.slice(0, 100), props });
+  });
+}
+function optOut(stop) {
+  later(() => {
+    var _a, _b;
+    const s = state;
+    s.out = stop;
+    if (!stop) return;
+    s.queue = [];
+    s.id = "";
+    (_a = s.options.storage) == null ? void 0 : _a.removeItem(QUEUE_KEY).catch(() => void 0);
+    (_b = s.options.storage) == null ? void 0 : _b.removeItem(ID_KEY).catch(() => void 0);
+  });
+}
+function navigationTracker(ref) {
+  const report = () => {
+    const route = ref.getCurrentRoute();
+    if (route) screen(route.name);
+  };
+  return { onReady: report, onStateChange: report };
+}
+function useScreen(name) {
+  (0, import_react.useEffect)(() => {
+    if (name) screen(name);
+  }, [name]);
+}
+function reset() {
+  if (state == null ? void 0 : state.timer) clearTimeout(state.timer);
+  state = null;
+  early = [];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  flush,
+  init,
+  navigationTracker,
+  optOut,
+  reset,
+  screen,
+  track,
+  useScreen
+});

package/dist/index.d.cts

@@ -0,0 +1,60 @@
+export type Props = Record<string, string | number | boolean>;
+/** Where the id and the waiting events are kept. AsyncStorage fits; so does anything with these three methods. */
+export type Storage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+};
+export type Options = {
+    /** The app's public key, from its Install screen in lapwy. */
+    site: string;
+    /** A short name for the app, such as its bundle name. It stands where a website's domain would. */
+    app?: string;
+    /** Where events go. Defaults to lapwy's own ingest. */
+    endpoint?: string;
+    /** Keeps the install id and the queue between launches. Without it every launch is a new user and nothing survives a restart. */
+    storage?: Storage;
+    /** Your app's version, to see what a release changed. */
+    version?: string;
+    /** Report uncaught JavaScript errors. On by default. */
+    errors?: boolean;
+};
+/**
+ * Sends what is waiting. Called on its own a moment after anything is
+ * tracked and when the app goes to the background; call it yourself only
+ * when you need the events out right now.
+ */
+export declare function flush(): Promise<void>;
+/** Starts tracking. Call it once, when the app starts. A second call does nothing. */
+export declare function init(options: Options): void;
+/** The user is looking at a screen. Call it when a screen comes up, with its name or path. */
+export declare function screen(name: string, props?: Props): void;
+/** Something a user did: track("add_to_cart", { product: "monstera" }). Revenue goes in as revenue and currency. */
+export declare function track(name: string, props?: Props): void;
+/**
+ * Stop or resume tracking for this user, for an in-app "do not track" switch.
+ * Stopping also throws away what is waiting and forgets the install id.
+ */
+export declare function optOut(stop: boolean): void;
+/**
+ * For React Navigation: reports every screen the user moves to.
+ *
+ *   const navigation = useNavigationContainerRef();
+ *   <NavigationContainer ref={navigation} {...navigationTracker(navigation)}>
+ */
+export declare function navigationTracker(ref: {
+    getCurrentRoute(): {
+        name: string;
+    } | undefined;
+}): {
+    onReady: () => void;
+    onStateChange: () => void;
+};
+/**
+ * Reports a screen from inside a component. With Expo Router, once in the root layout:
+ *
+ *   useScreen(usePathname());
+ */
+export declare function useScreen(name: string | null | undefined): void;
+/** For tests: forget everything, as if the app had just been installed. */
+export declare function reset(): void;

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+export type Props = Record<string, string | number | boolean>;
+/** Where the id and the waiting events are kept. AsyncStorage fits; so does anything with these three methods. */
+export type Storage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+};
+export type Options = {
+    /** The app's public key, from its Install screen in lapwy. */
+    site: string;
+    /** A short name for the app, such as its bundle name. It stands where a website's domain would. */
+    app?: string;
+    /** Where events go. Defaults to lapwy's own ingest. */
+    endpoint?: string;
+    /** Keeps the install id and the queue between launches. Without it every launch is a new user and nothing survives a restart. */
+    storage?: Storage;
+    /** Your app's version, to see what a release changed. */
+    version?: string;
+    /** Report uncaught JavaScript errors. On by default. */
+    errors?: boolean;
+};
+/**
+ * Sends what is waiting. Called on its own a moment after anything is
+ * tracked and when the app goes to the background; call it yourself only
+ * when you need the events out right now.
+ */
+export declare function flush(): Promise<void>;
+/** Starts tracking. Call it once, when the app starts. A second call does nothing. */
+export declare function init(options: Options): void;
+/** The user is looking at a screen. Call it when a screen comes up, with its name or path. */
+export declare function screen(name: string, props?: Props): void;
+/** Something a user did: track("add_to_cart", { product: "monstera" }). Revenue goes in as revenue and currency. */
+export declare function track(name: string, props?: Props): void;
+/**
+ * Stop or resume tracking for this user, for an in-app "do not track" switch.
+ * Stopping also throws away what is waiting and forgets the install id.
+ */
+export declare function optOut(stop: boolean): void;
+/**
+ * For React Navigation: reports every screen the user moves to.
+ *
+ *   const navigation = useNavigationContainerRef();
+ *   <NavigationContainer ref={navigation} {...navigationTracker(navigation)}>
+ */
+export declare function navigationTracker(ref: {
+    getCurrentRoute(): {
+        name: string;
+    } | undefined;
+}): {
+    onReady: () => void;
+    onStateChange: () => void;
+};
+/**
+ * Reports a screen from inside a component. With Expo Router, once in the root layout:
+ *
+ *   useScreen(usePathname());
+ */
+export declare function useScreen(name: string | null | undefined): void;
+/** For tests: forget everything, as if the app had just been installed. */
+export declare function reset(): void;

package/dist/index.js

@@ -0,0 +1,222 @@
+// src/index.ts
+import { useEffect } from "react";
+import { AppState, Dimensions, Platform } from "react-native";
+var DEFAULT_ENDPOINT = "https://in.lapwy.com/e";
+var ID_KEY = "lapwy_device_id";
+var QUEUE_KEY = "lapwy_queue";
+var MAX_QUEUE = 500;
+var state = null;
+var early = [];
+function hex(bytes) {
+  const a = new Uint8Array(bytes);
+  const c = globalThis.crypto;
+  if (c && c.getRandomValues) c.getRandomValues(a);
+  else for (let i = 0; i < bytes; i++) a[i] = Math.floor(Math.random() * 256);
+  let s = "";
+  for (let i = 0; i < bytes; i++) s += (a[i] + 256).toString(16).slice(1);
+  return s;
+}
+function uuid() {
+  const h = hex(16);
+  return h.slice(0, 8) + "-" + h.slice(8, 12) + "-4" + h.slice(13, 16) + "-a" + h.slice(17, 20) + "-" + h.slice(20);
+}
+function screenUrl(app, name) {
+  const path = name.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+  return `app://${app}/${path}`;
+}
+function save(s) {
+  var _a;
+  (_a = s.options.storage) == null ? void 0 : _a.setItem(QUEUE_KEY, JSON.stringify(s.queue)).catch(() => void 0);
+}
+function add(s, kind, extra) {
+  if (s.out) return;
+  const e = { id: uuid(), t: Date.now(), k: kind, u: s.screenUrl, p: s.screenId };
+  for (const k in extra) if (extra[k] !== void 0) e[k] = extra[k];
+  s.queue.push(e);
+  if (s.queue.length > MAX_QUEUE) s.queue.splice(0, s.queue.length - MAX_QUEUE);
+  save(s);
+  if (!s.timer) s.timer = setTimeout(() => void flush(), 2e3);
+}
+function osVersion() {
+  var _a;
+  if (Platform.OS !== "android") return String(Platform.Version);
+  const release = (_a = Platform.constants) == null ? void 0 : _a.Release;
+  return release == null ? "" : String(release).split(".").slice(0, 2).join(".");
+}
+function client(s) {
+  const { width, height } = Dimensions.get("window");
+  let language = "";
+  try {
+    language = Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+  }
+  return {
+    sw: Math.round(width),
+    sh: Math.round(height),
+    l: language,
+    rel: s.options.version || "",
+    pf: Platform.OS,
+    osv: osVersion(),
+    // The usual cut between a phone and a tablet: 600 points on the short side.
+    dt: Platform.isPad || Math.min(width, height) >= 600 ? "tablet" : "mobile"
+  };
+}
+async function flush() {
+  const s = state;
+  if (!s) return;
+  if (s.timer) clearTimeout(s.timer);
+  s.timer = 0;
+  await s.ready;
+  if (s.sending || !s.queue.length) return;
+  s.sending = true;
+  const events = s.queue.slice(0, 50);
+  try {
+    const res = await fetch(s.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "text/plain" },
+      body: JSON.stringify({ k: s.options.site, v: s.id || void 0, sdk: "react-native-0.1", now: Date.now(), c: client(s), e: events })
+    });
+    if (res.status === 429 || res.status >= 500) throw new Error("retry");
+    s.queue = s.queue.filter((e) => !events.includes(e));
+    s.backoff = 0;
+    save(s);
+    s.sending = false;
+    if (s.queue.length) s.timer = setTimeout(() => void flush(), 200);
+  } catch {
+    s.sending = false;
+    s.timer = setTimeout(() => void flush(), Math.min(5e3 * Math.pow(2, s.backoff++), 3e5));
+  }
+}
+function settle(s) {
+  if (s.shownAt) {
+    s.engaged += Date.now() - s.shownAt;
+    s.shownAt = 0;
+  }
+  if (s.screenId && s.engaged >= 1e3) add(s, "engagement", { v: s.engaged });
+  s.engaged = 0;
+}
+function later(run) {
+  if (state) run();
+  else if (early.length < 100) early.push(run);
+}
+function init(options) {
+  if (state || !options.site) return;
+  const s = {
+    options,
+    endpoint: options.endpoint || DEFAULT_ENDPOINT,
+    app: (options.app || "app").toLowerCase().replace(/[^a-z0-9.-]+/g, "-") || "app",
+    id: "",
+    ready: Promise.resolve(),
+    queue: [],
+    screenUrl: "",
+    screenId: "",
+    shownAt: 0,
+    engaged: 0,
+    timer: 0,
+    backoff: 0,
+    sending: false,
+    out: false
+  };
+  s.screenUrl = screenUrl(s.app, "");
+  state = s;
+  const storage = options.storage;
+  s.ready = (async () => {
+    if (!storage) return;
+    try {
+      const [id, queued] = await Promise.all([storage.getItem(ID_KEY), storage.getItem(QUEUE_KEY)]);
+      s.id = id && /^[0-9a-f]{16,64}$/.test(id) ? id : hex(16);
+      if (s.id !== id) await storage.setItem(ID_KEY, s.id);
+      const old = queued ? JSON.parse(queued) : [];
+      if (Array.isArray(old) && old.length) s.queue = old.concat(s.queue).slice(-MAX_QUEUE);
+    } catch {
+    }
+  })();
+  AppState.addEventListener("change", (next) => {
+    if (next === "active") {
+      if (!s.shownAt) s.shownAt = Date.now();
+      void flush();
+    } else {
+      settle(s);
+      void flush();
+    }
+  });
+  if (options.errors !== false) {
+    const utils = globalThis.ErrorUtils;
+    if (utils) {
+      const before = utils.getGlobalHandler();
+      let reported = 0;
+      utils.setGlobalHandler((error, fatal) => {
+        try {
+          const e = error;
+          const msg = String(e && e.message || error || "").slice(0, 300);
+          if (msg && reported++ < 10) {
+            add(s, "error", { n: String(e && e.name || "Error").slice(0, 60), props: { msg, fatal: Boolean(fatal) } });
+            void flush();
+          }
+        } catch {
+        }
+        before(error, fatal);
+      });
+    }
+  }
+  const waiting = early;
+  early = [];
+  waiting.forEach((run) => run());
+}
+function screen(name, props) {
+  later(() => {
+    const s = state;
+    const url = screenUrl(s.app, name);
+    if (url === s.screenUrl && s.screenId && !props) return;
+    settle(s);
+    const from = s.screenId ? s.screenUrl : "";
+    s.screenUrl = url;
+    s.screenId = hex(8);
+    s.shownAt = AppState.currentState === "active" || AppState.currentState == null ? Date.now() : 0;
+    add(s, "pageview", { r: from, ti: name, props });
+  });
+}
+function track(name, props) {
+  later(() => {
+    if (typeof name === "string" && name) add(state, "custom", { n: name.slice(0, 100), props });
+  });
+}
+function optOut(stop) {
+  later(() => {
+    var _a, _b;
+    const s = state;
+    s.out = stop;
+    if (!stop) return;
+    s.queue = [];
+    s.id = "";
+    (_a = s.options.storage) == null ? void 0 : _a.removeItem(QUEUE_KEY).catch(() => void 0);
+    (_b = s.options.storage) == null ? void 0 : _b.removeItem(ID_KEY).catch(() => void 0);
+  });
+}
+function navigationTracker(ref) {
+  const report = () => {
+    const route = ref.getCurrentRoute();
+    if (route) screen(route.name);
+  };
+  return { onReady: report, onStateChange: report };
+}
+function useScreen(name) {
+  useEffect(() => {
+    if (name) screen(name);
+  }, [name]);
+}
+function reset() {
+  if (state == null ? void 0 : state.timer) clearTimeout(state.timer);
+  state = null;
+  early = [];
+}
+export {
+  flush,
+  init,
+  navigationTracker,
+  optOut,
+  reset,
+  screen,
+  track,
+  useScreen
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@lapwy/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "lapwy for React Native and Expo: init, screen, track, with an offline queue.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json && node ../../scripts/cts-types.mjs"
+  }
 }