@lumin-monitor/react-native 0.1.0

package/dist/index.cjs

@@ -0,0 +1,382 @@
+"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, {
+  Client: () => Client,
+  init: () => init
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/ids.ts
+function uuidv4() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  const bytes = new Array(16);
+  for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = bytes.map((b) => b.toString(16).padStart(2, "0"));
+  return hex.slice(0, 4).join("") + "-" + hex.slice(4, 6).join("") + "-" + hex.slice(6, 8).join("") + "-" + hex.slice(8, 10).join("") + "-" + hex.slice(10, 16).join("");
+}
+var ANON_KEY = "lumin.anonymous_id";
+var SESSION_KEY = "lumin.session_id";
+var SESSION_LAST_SEEN_KEY = "lumin.session_last_seen";
+function detectAsyncStorage() {
+  try {
+    if (typeof require === "undefined") return null;
+    const mod = require("@react-native-async-storage/async-storage");
+    const candidate = mod?.default ?? mod;
+    if (candidate && typeof candidate.getItem === "function" && typeof candidate.setItem === "function") {
+      return candidate;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function memoryStorage() {
+  const m = /* @__PURE__ */ new Map();
+  return {
+    async getItem(k) {
+      return m.has(k) ? m.get(k) : null;
+    },
+    async setItem(k, v) {
+      m.set(k, v);
+    },
+    async removeItem(k) {
+      m.delete(k);
+    }
+  };
+}
+async function readSafe(s, key) {
+  try {
+    return await s.getItem(key);
+  } catch {
+    return null;
+  }
+}
+async function writeSafe(s, key, value) {
+  try {
+    await s.setItem(key, value);
+  } catch {
+  }
+}
+async function getOrCreateAnonymousId(storage) {
+  const existing = await readSafe(storage, ANON_KEY);
+  if (existing) return existing;
+  const id = uuidv4();
+  await writeSafe(storage, ANON_KEY, id);
+  return id;
+}
+async function getOrCreateSessionId(storage, idleMs, now = Date.now()) {
+  const existingId = await readSafe(storage, SESSION_KEY);
+  const lastSeenStr = await readSafe(storage, SESSION_LAST_SEEN_KEY);
+  const lastSeen = lastSeenStr ? Number(lastSeenStr) : NaN;
+  const expired = !existingId || !Number.isFinite(lastSeen) || now - lastSeen > idleMs;
+  const id = expired ? uuidv4() : existingId;
+  if (expired) {
+    await writeSafe(storage, SESSION_KEY, id);
+  }
+  await writeSafe(storage, SESSION_LAST_SEEN_KEY, String(now));
+  return id;
+}
+
+// src/client.ts
+var DEFAULT_BATCH_SIZE = 50;
+var DEFAULT_FLUSH_MS = 500;
+var DEFAULT_SESSION_IDLE_MS = 30 * 60 * 1e3;
+var SERVER_MAX_BATCH = 1e3;
+var DEFAULT_ENDPOINT = "https://api.getlumin.dev";
+var Client = class {
+  constructor(opts) {
+    this.userId = null;
+    this.cachedIds = null;
+    // Pending events queued before ids hydrate. `user_id` is stamped at enqueue
+    // time so a later identify() does not retroactively bind pre-identify events
+    // — matches the browser SDK's behaviour. Once `idsReady` resolves, the
+    // flushing path stamps `session_id` + `anonymous_id` and drains them.
+    this.pending = [];
+    this.buffer = [];
+    this.timer = null;
+    this.closed = false;
+    this.inflight = [];
+    this.appStateSub = null;
+    if (!opts.apiKey) throw new Error("lumin: apiKey required");
+    this.endpoint = validateEndpoint(opts.endpoint ?? DEFAULT_ENDPOINT);
+    this.apiKey = opts.apiKey;
+    this.batchSize = clampBatch(opts.batchSize ?? DEFAULT_BATCH_SIZE);
+    this.flushIntervalMs = Math.max(50, opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
+    this.sessionIdleMs = Math.max(1e3, opts.sessionIdleMs ?? DEFAULT_SESSION_IDLE_MS);
+    this.onError = opts.onError ?? ((err, dropped) => {
+      console.warn("[lumin] flush failed", { err, dropped });
+    });
+    this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
+    const resolvedStorage = opts.storage === null ? memoryStorage() : opts.storage ?? detectAsyncStorage() ?? memoryStorage();
+    this.storage = resolvedStorage;
+    this.appState = opts.appState === void 0 ? detectAppState() : opts.appState;
+    this.idsReady = this.hydrateIds();
+    this.installBackgroundFlush();
+  }
+  screen(name, properties) {
+    if (this.closed) return;
+    this.enqueue({
+      type: "page",
+      ...name !== void 0 ? { name } : {},
+      ...properties !== void 0 ? { properties } : {}
+    });
+  }
+  track(name, properties) {
+    if (this.closed) return;
+    if (!name) {
+      this.onError(new Error("track requires a name"), 0);
+      return;
+    }
+    this.enqueue({ type: "track", name, ...properties !== void 0 ? { properties } : {} });
+  }
+  identify(userId, traits) {
+    if (this.closed) return;
+    if (!userId) {
+      this.onError(new Error("identify requires a userId"), 0);
+      return;
+    }
+    this.userId = userId;
+    this.enqueue({ type: "identify", ...traits !== void 0 ? { properties: traits } : {} });
+  }
+  /**
+   * Drain the buffer to the server. Returns when the in-flight request
+   * settles (success or failure). Awaits id hydration first so a `flush()`
+   * called immediately after `init()` does not race the AsyncStorage read.
+   */
+  async flush() {
+    await this.drainPending();
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    this.cancelTimer();
+    const p = this.send(batch);
+    this.inflight.push(p);
+    try {
+      await p;
+    } finally {
+      this.inflight = this.inflight.filter((q) => q !== p);
+    }
+  }
+  /**
+   * Stop accepting events, flush whatever's buffered, wait for in-flight
+   * requests to settle, and remove the AppState listener. Idempotent.
+   */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.removeBackgroundFlush();
+    await this.flush();
+    await Promise.allSettled(this.inflight);
+  }
+  async getSessionId() {
+    const ids = await this.idsReady;
+    return ids.sessionId;
+  }
+  async getAnonymousId() {
+    const ids = await this.idsReady;
+    return ids.anonymousId;
+  }
+  // --- internals ---------------------------------------------------------
+  async hydrateIds() {
+    const anonymousId = await getOrCreateAnonymousId(this.storage);
+    const sessionId = await getOrCreateSessionId(this.storage, this.sessionIdleMs);
+    const ids = { anonymousId, sessionId };
+    this.cachedIds = ids;
+    return ids;
+  }
+  /**
+   * Refresh `cachedIds.sessionId` if the persisted lastSeenAt is older than
+   * `sessionIdleMs`. Called before each send so a long background pause →
+   * foreground burst opens a new session.
+   */
+  async refreshSessionIfIdle() {
+    if (!this.cachedIds) return;
+    const sid = await getOrCreateSessionId(this.storage, this.sessionIdleMs);
+    this.cachedIds.sessionId = sid;
+  }
+  enqueue(partial) {
+    const withUser = {
+      ts: Date.now(),
+      ...this.userId ? { user_id: this.userId } : {},
+      ...partial
+    };
+    if (!this.cachedIds) {
+      this.pending.push(withUser);
+      this.scheduleTimer();
+      return;
+    }
+    this.buffer.push(this.stamp(withUser, this.cachedIds));
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+      return;
+    }
+    this.scheduleTimer();
+  }
+  stamp(partial, ids) {
+    return {
+      session_id: ids.sessionId,
+      anonymous_id: ids.anonymousId,
+      ...partial
+    };
+  }
+  async drainPending() {
+    if (this.pending.length === 0 && this.cachedIds) return;
+    const ids = await this.idsReady;
+    await this.refreshSessionIfIdle();
+    const effective = this.cachedIds ?? ids;
+    if (this.pending.length === 0) return;
+    const drained = this.pending;
+    this.pending = [];
+    for (const p of drained) this.buffer.push(this.stamp(p, effective));
+  }
+  scheduleTimer() {
+    if (this.timer !== null) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.flushIntervalMs);
+  }
+  cancelTimer() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  async send(batch) {
+    if (batch.length === 0) return;
+    if (batch.length > SERVER_MAX_BATCH) {
+      this.onError(
+        new Error(`batch size ${batch.length} exceeds server max ${SERVER_MAX_BATCH}`),
+        batch.length
+      );
+      return;
+    }
+    const body = JSON.stringify({ events: batch });
+    try {
+      const res = await this.fetchImpl(this.endpoint + "/v1/events", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer " + this.apiKey
+        },
+        body
+      });
+      if (!res.ok) {
+        this.onError(new Error(`HTTP ${res.status}`), batch.length);
+      }
+    } catch (err) {
+      this.onError(err, batch.length);
+    }
+  }
+  /**
+   * Flush on app background/inactive. RN keeps the JS runtime alive for a
+   * short grace window after backgrounding (~30 s on iOS, similar on
+   * Android), which is enough for one batched POST to land. There is no
+   * `keepalive: true` equivalent on RN fetch — the OS-level grace window
+   * is the contract.
+   */
+  installBackgroundFlush() {
+    if (!this.appState) return;
+    this.appStateSub = this.appState.addEventListener("change", (state) => {
+      if (state === "background" || state === "inactive") {
+        if (this.buffer.length === 0 && this.pending.length === 0) return;
+        void this.flush();
+      }
+    });
+  }
+  removeBackgroundFlush() {
+    if (this.appStateSub) {
+      this.appStateSub.remove();
+      this.appStateSub = null;
+    }
+  }
+};
+function clampBatch(n) {
+  if (!Number.isFinite(n) || n < 1) return 1;
+  if (n > SERVER_MAX_BATCH) return SERVER_MAX_BATCH;
+  return Math.floor(n);
+}
+function detectAppState() {
+  try {
+    if (typeof require === "undefined") return null;
+    const rn = require("react-native");
+    const candidate = rn?.AppState;
+    if (candidate && typeof candidate.addEventListener === "function") {
+      return candidate;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function validateEndpoint(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`lumin: endpoint is not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`lumin: endpoint must be http(s); got ${url.protocol}//`);
+  }
+  const host = url.hostname;
+  const isLocalDev = host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost");
+  if (url.protocol === "http:" && !isLocalDev) {
+    throw new Error(`lumin: endpoint must use https:// for non-local hosts (got ${raw})`);
+  }
+  if (url.pathname.replace(/\/+$/, "") !== "") {
+    throw new Error(
+      `lumin: endpoint must be a base URL with no path; got pathname "${url.pathname}". Pass "https://api.getlumin.dev", not "https://api.getlumin.dev/v1/events".`
+    );
+  }
+  if (url.search !== "" || url.hash !== "") {
+    throw new Error(`lumin: endpoint must not include a query string or fragment; got ${raw}`);
+  }
+  if (!url.hostname) {
+    throw new Error(`lumin: endpoint is missing a hostname: ${raw}`);
+  }
+  return `${url.protocol}//${url.host}`;
+}
+
+// src/index.ts
+function init(opts) {
+  const c = new Client(opts);
+  return {
+    screen: c.screen.bind(c),
+    track: c.track.bind(c),
+    identify: c.identify.bind(c),
+    flush: c.flush.bind(c),
+    close: c.close.bind(c),
+    getSessionId: c.getSessionId.bind(c),
+    getAnonymousId: c.getAnonymousId.bind(c)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Client,
+  init
+});

package/dist/index.d.cts

@@ -0,0 +1,79 @@
+import { L as LuminClient, I as InitOptions } from './types-BeHbtR1J.cjs';
+export { A as AppStateLike, a as AsyncStorageLike, E as EventType, W as WireEvent } from './types-BeHbtR1J.cjs';
+
+declare class Client implements LuminClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly sessionIdleMs;
+    private readonly onError;
+    private readonly fetchImpl;
+    private readonly storage;
+    private readonly appState;
+    private userId;
+    private idsReady;
+    private cachedIds;
+    private pending;
+    private buffer;
+    private timer;
+    private closed;
+    private inflight;
+    private appStateSub;
+    constructor(opts: InitOptions);
+    screen(name?: string, properties?: Record<string, unknown>): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Drain the buffer to the server. Returns when the in-flight request
+     * settles (success or failure). Awaits id hydration first so a `flush()`
+     * called immediately after `init()` does not race the AsyncStorage read.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop accepting events, flush whatever's buffered, wait for in-flight
+     * requests to settle, and remove the AppState listener. Idempotent.
+     */
+    close(): Promise<void>;
+    getSessionId(): Promise<string>;
+    getAnonymousId(): Promise<string>;
+    private hydrateIds;
+    /**
+     * Refresh `cachedIds.sessionId` if the persisted lastSeenAt is older than
+     * `sessionIdleMs`. Called before each send so a long background pause →
+     * foreground burst opens a new session.
+     */
+    private refreshSessionIfIdle;
+    private enqueue;
+    private stamp;
+    private drainPending;
+    private scheduleTimer;
+    private cancelTimer;
+    private send;
+    /**
+     * Flush on app background/inactive. RN keeps the JS runtime alive for a
+     * short grace window after backgrounding (~30 s on iOS, similar on
+     * Android), which is enough for one batched POST to land. There is no
+     * `keepalive: true` equivalent on RN fetch — the OS-level grace window
+     * is the contract.
+     */
+    private installBackgroundFlush;
+    private removeBackgroundFlush;
+}
+
+/**
+ * Initialise the Lumin React Native SDK. Returns a client whose `screen`,
+ * `track`, `identify`, `flush`, and `close` methods are bound — safe to
+ * destructure.
+ *
+ * `init` is synchronous: the returned client buffers events while it reads
+ * AsyncStorage for the persistent anonymous and session ids in the
+ * background. Callers can `screen()` / `track()` / `identify()` immediately;
+ * the first flush waits for hydration to complete.
+ *
+ * Calling `init` multiple times produces independent clients; apps that
+ * want a single shared instance should pin one at the module level.
+ */
+declare function init(opts: InitOptions): LuminClient;
+
+export { Client, InitOptions, LuminClient, init };

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { L as LuminClient, I as InitOptions } from './types-BeHbtR1J.js';
+export { A as AppStateLike, a as AsyncStorageLike, E as EventType, W as WireEvent } from './types-BeHbtR1J.js';
+
+declare class Client implements LuminClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly sessionIdleMs;
+    private readonly onError;
+    private readonly fetchImpl;
+    private readonly storage;
+    private readonly appState;
+    private userId;
+    private idsReady;
+    private cachedIds;
+    private pending;
+    private buffer;
+    private timer;
+    private closed;
+    private inflight;
+    private appStateSub;
+    constructor(opts: InitOptions);
+    screen(name?: string, properties?: Record<string, unknown>): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Drain the buffer to the server. Returns when the in-flight request
+     * settles (success or failure). Awaits id hydration first so a `flush()`
+     * called immediately after `init()` does not race the AsyncStorage read.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop accepting events, flush whatever's buffered, wait for in-flight
+     * requests to settle, and remove the AppState listener. Idempotent.
+     */
+    close(): Promise<void>;
+    getSessionId(): Promise<string>;
+    getAnonymousId(): Promise<string>;
+    private hydrateIds;
+    /**
+     * Refresh `cachedIds.sessionId` if the persisted lastSeenAt is older than
+     * `sessionIdleMs`. Called before each send so a long background pause →
+     * foreground burst opens a new session.
+     */
+    private refreshSessionIfIdle;
+    private enqueue;
+    private stamp;
+    private drainPending;
+    private scheduleTimer;
+    private cancelTimer;
+    private send;
+    /**
+     * Flush on app background/inactive. RN keeps the JS runtime alive for a
+     * short grace window after backgrounding (~30 s on iOS, similar on
+     * Android), which is enough for one batched POST to land. There is no
+     * `keepalive: true` equivalent on RN fetch — the OS-level grace window
+     * is the contract.
+     */
+    private installBackgroundFlush;
+    private removeBackgroundFlush;
+}
+
+/**
+ * Initialise the Lumin React Native SDK. Returns a client whose `screen`,
+ * `track`, `identify`, `flush`, and `close` methods are bound — safe to
+ * destructure.
+ *
+ * `init` is synchronous: the returned client buffers events while it reads
+ * AsyncStorage for the persistent anonymous and session ids in the
+ * background. Callers can `screen()` / `track()` / `identify()` immediately;
+ * the first flush waits for hydration to complete.
+ *
+ * Calling `init` multiple times produces independent clients; apps that
+ * want a single shared instance should pin one at the module level.
+ */
+declare function init(opts: InitOptions): LuminClient;
+
+export { Client, InitOptions, LuminClient, init };