@lumin-monitor/react-native 0.1.0

package/dist/index.js

@@ -0,0 +1,358 @@
+import {
+  __require
+} from "./chunk-3RG5ZIWI.js";
+
+// 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)
+  };
+}
+export {
+  Client,
+  init
+};

package/dist/react-navigation.cjs

@@ -0,0 +1,51 @@
+"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/react-navigation.ts
+var react_navigation_exports = {};
+__export(react_navigation_exports, {
+  useLuminScreenviews: () => useLuminScreenviews
+});
+module.exports = __toCommonJS(react_navigation_exports);
+var import_react = require("react");
+function useLuminScreenviews(client, navigationRef) {
+  const lastRoute = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (!client || !navigationRef) return;
+    const fire = () => {
+      const route = navigationRef.getCurrentRoute?.();
+      const name = route?.name;
+      if (!name) return;
+      if (lastRoute.current === name) return;
+      lastRoute.current = name;
+      client.screen(name);
+    };
+    if (navigationRef.isReady?.()) fire();
+    const unsubReady = navigationRef.addListener("ready", fire);
+    const unsubState = navigationRef.addListener("state", fire);
+    return () => {
+      unsubReady();
+      unsubState();
+    };
+  }, [client, navigationRef]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useLuminScreenviews
+});

package/dist/react-navigation.d.cts

@@ -0,0 +1,32 @@
+import { L as LuminClient } from './types-BeHbtR1J.cjs';
+
+/**
+ * Subset of @react-navigation/native's NavigationContainerRef the hook needs.
+ * Typed structurally so we do not pull react-navigation types into the SDK's
+ * public surface — the app already has them.
+ */
+interface NavigationRefLike {
+    isReady?(): boolean;
+    getCurrentRoute?(): {
+        name?: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+    addListener(event: "state" | "ready", listener: () => void): () => void;
+}
+/**
+ * Auto-fire `client.screen()` on every React Navigation route change. Drop
+ * into the component that renders `<NavigationContainer ref={navigationRef}>`
+ * once.
+ *
+ * The hook fires once per route name change. Same-name navigations (e.g.
+ * pushing a new instance of the same screen with different params) do not
+ * re-emit — params are usually filter state, not real screen views, and
+ * double-counting them inflates funnel metrics. If you want per-param
+ * tracking, call `screen()` manually from the route's effect.
+ *
+ * Pass `null` for `client` (e.g. when the SDK is disabled in dev) and the
+ * hook becomes a no-op.
+ */
+declare function useLuminScreenviews(client: LuminClient | null | undefined, navigationRef: NavigationRefLike | null | undefined): void;
+
+export { type NavigationRefLike, useLuminScreenviews };

package/dist/react-navigation.d.ts

@@ -0,0 +1,32 @@
+import { L as LuminClient } from './types-BeHbtR1J.js';
+
+/**
+ * Subset of @react-navigation/native's NavigationContainerRef the hook needs.
+ * Typed structurally so we do not pull react-navigation types into the SDK's
+ * public surface — the app already has them.
+ */
+interface NavigationRefLike {
+    isReady?(): boolean;
+    getCurrentRoute?(): {
+        name?: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+    addListener(event: "state" | "ready", listener: () => void): () => void;
+}
+/**
+ * Auto-fire `client.screen()` on every React Navigation route change. Drop
+ * into the component that renders `<NavigationContainer ref={navigationRef}>`
+ * once.
+ *
+ * The hook fires once per route name change. Same-name navigations (e.g.
+ * pushing a new instance of the same screen with different params) do not
+ * re-emit — params are usually filter state, not real screen views, and
+ * double-counting them inflates funnel metrics. If you want per-param
+ * tracking, call `screen()` manually from the route's effect.
+ *
+ * Pass `null` for `client` (e.g. when the SDK is disabled in dev) and the
+ * hook becomes a no-op.
+ */
+declare function useLuminScreenviews(client: LuminClient | null | undefined, navigationRef: NavigationRefLike | null | undefined): void;
+
+export { type NavigationRefLike, useLuminScreenviews };

package/dist/react-navigation.js

@@ -0,0 +1,28 @@
+import "./chunk-3RG5ZIWI.js";
+
+// src/react-navigation.ts
+import { useEffect, useRef } from "react";
+function useLuminScreenviews(client, navigationRef) {
+  const lastRoute = useRef(null);
+  useEffect(() => {
+    if (!client || !navigationRef) return;
+    const fire = () => {
+      const route = navigationRef.getCurrentRoute?.();
+      const name = route?.name;
+      if (!name) return;
+      if (lastRoute.current === name) return;
+      lastRoute.current = name;
+      client.screen(name);
+    };
+    if (navigationRef.isReady?.()) fire();
+    const unsubReady = navigationRef.addListener("ready", fire);
+    const unsubState = navigationRef.addListener("state", fire);
+    return () => {
+      unsubReady();
+      unsubState();
+    };
+  }, [client, navigationRef]);
+}
+export {
+  useLuminScreenviews
+};

package/dist/types-BeHbtR1J.d.cts

@@ -0,0 +1,96 @@
+type EventType = "page" | "track" | "identify";
+interface WireEvent {
+    ts?: number;
+    session_id: string;
+    anonymous_id?: string;
+    user_id?: string;
+    type: EventType;
+    name?: string;
+    url?: string;
+    referrer?: string;
+    properties?: Record<string, unknown>;
+    trace_id?: string;
+}
+/**
+ * Minimal AsyncStorage shape the SDK actually consumes. Matches both
+ * @react-native-async-storage/async-storage (community) and the legacy
+ * react-native built-in. Apps that ship a different storage backend can
+ * implement this directly.
+ */
+interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem?(key: string): Promise<void>;
+}
+interface InitOptions {
+    /** API key minted in the Lumin UI (settings → API keys). Must be `lmn_pub_*`. */
+    apiKey: string;
+    /**
+     * Base URL of the Lumin ingest endpoint. Defaults to
+     * `https://api.getlumin.dev`. Override only for local development against
+     * a Lumin instance you are running yourself or for a customer-side
+     * same-origin proxy.
+     *
+     * Validation: must parse as a valid URL with no path beyond `/`. `https://`
+     * is required except when the hostname is `localhost`, `127.0.0.1`, or a
+     * `.localhost` subdomain (where `http://` is allowed). Invalid shapes
+     * throw synchronously from `init()` so misconfigurations surface at boot.
+     */
+    endpoint?: string;
+    /** Max events to buffer before forcing a flush. Default 50. */
+    batchSize?: number;
+    /** Max ms between flushes. Default 500. */
+    flushIntervalMs?: number;
+    /**
+     * Session idle timeout. A new session_id is minted on the next event if
+     * the time since the last event exceeds this value. Default 30 min
+     * (matches the industry-standard analytics convention).
+     */
+    sessionIdleMs?: number;
+    /**
+     * Optional error sink. Called with the failed batch + reason so apps can
+     * surface drops. Default: console.warn.
+     */
+    onError?: (err: unknown, dropped: number) => void;
+    /**
+     * Override the global fetch. Tests use this to capture requests without
+     * spinning up a network stub.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Override the AsyncStorage implementation. The SDK auto-detects
+     * `@react-native-async-storage/async-storage` when the peer dep is
+     * installed; pass this only when you bring a different storage backend
+     * (e.g. an MMKV-backed shim) or to disable persistence in tests.
+     * Pass `null` explicitly to opt out of storage entirely (in-memory ids).
+     */
+    storage?: AsyncStorageLike | null;
+    /**
+     * Override the React Native AppState module. Defaults to `react-native`'s
+     * AppState; tests pass a stub.
+     */
+    appState?: AppStateLike | null;
+}
+/**
+ * Minimal AppState shape the SDK consumes (subset of react-native's AppState).
+ * The SDK auto-detects `react-native` at runtime; pass this only for tests or
+ * non-RN environments.
+ */
+interface AppStateLike {
+    addEventListener(type: "change", listener: (state: string) => void): {
+        remove: () => void;
+    };
+}
+interface LuminClient {
+    screen(name?: string, properties?: Record<string, unknown>): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Current session id. Resolves once AsyncStorage hydration finishes. */
+    getSessionId(): Promise<string>;
+    /** Current anonymous id. Resolves once AsyncStorage hydration finishes. */
+    getAnonymousId(): Promise<string>;
+}
+
+export type { AppStateLike as A, EventType as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a };

package/dist/types-BeHbtR1J.d.ts

@@ -0,0 +1,96 @@
+type EventType = "page" | "track" | "identify";
+interface WireEvent {
+    ts?: number;
+    session_id: string;
+    anonymous_id?: string;
+    user_id?: string;
+    type: EventType;
+    name?: string;
+    url?: string;
+    referrer?: string;
+    properties?: Record<string, unknown>;
+    trace_id?: string;
+}
+/**
+ * Minimal AsyncStorage shape the SDK actually consumes. Matches both
+ * @react-native-async-storage/async-storage (community) and the legacy
+ * react-native built-in. Apps that ship a different storage backend can
+ * implement this directly.
+ */
+interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem?(key: string): Promise<void>;
+}
+interface InitOptions {
+    /** API key minted in the Lumin UI (settings → API keys). Must be `lmn_pub_*`. */
+    apiKey: string;
+    /**
+     * Base URL of the Lumin ingest endpoint. Defaults to
+     * `https://api.getlumin.dev`. Override only for local development against
+     * a Lumin instance you are running yourself or for a customer-side
+     * same-origin proxy.
+     *
+     * Validation: must parse as a valid URL with no path beyond `/`. `https://`
+     * is required except when the hostname is `localhost`, `127.0.0.1`, or a
+     * `.localhost` subdomain (where `http://` is allowed). Invalid shapes
+     * throw synchronously from `init()` so misconfigurations surface at boot.
+     */
+    endpoint?: string;
+    /** Max events to buffer before forcing a flush. Default 50. */
+    batchSize?: number;
+    /** Max ms between flushes. Default 500. */
+    flushIntervalMs?: number;
+    /**
+     * Session idle timeout. A new session_id is minted on the next event if
+     * the time since the last event exceeds this value. Default 30 min
+     * (matches the industry-standard analytics convention).
+     */
+    sessionIdleMs?: number;
+    /**
+     * Optional error sink. Called with the failed batch + reason so apps can
+     * surface drops. Default: console.warn.
+     */
+    onError?: (err: unknown, dropped: number) => void;
+    /**
+     * Override the global fetch. Tests use this to capture requests without
+     * spinning up a network stub.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Override the AsyncStorage implementation. The SDK auto-detects
+     * `@react-native-async-storage/async-storage` when the peer dep is
+     * installed; pass this only when you bring a different storage backend
+     * (e.g. an MMKV-backed shim) or to disable persistence in tests.
+     * Pass `null` explicitly to opt out of storage entirely (in-memory ids).
+     */
+    storage?: AsyncStorageLike | null;
+    /**
+     * Override the React Native AppState module. Defaults to `react-native`'s
+     * AppState; tests pass a stub.
+     */
+    appState?: AppStateLike | null;
+}
+/**
+ * Minimal AppState shape the SDK consumes (subset of react-native's AppState).
+ * The SDK auto-detects `react-native` at runtime; pass this only for tests or
+ * non-RN environments.
+ */
+interface AppStateLike {
+    addEventListener(type: "change", listener: (state: string) => void): {
+        remove: () => void;
+    };
+}
+interface LuminClient {
+    screen(name?: string, properties?: Record<string, unknown>): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Current session id. Resolves once AsyncStorage hydration finishes. */
+    getSessionId(): Promise<string>;
+    /** Current anonymous id. Resolves once AsyncStorage hydration finishes. */
+    getAnonymousId(): Promise<string>;
+}
+
+export type { AppStateLike as A, EventType as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a };