@lumin-monitor/react-native 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to `@lumin-monitor/react-native` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-05-26
+
+### Added
+
+- **Mobile device classification.** The SDK now sends an `X-Lumin-Client`
+  header on every batch — `sdk=rn/0.4.0; os=ios; os_version=17.4` plus
+  optional `device=<model>` when the new `deviceInfo` init option is
+  provided. The Lumin API uses the header to fill the same `ua_os` /
+  `ua_device_type` columns the browser SDK has always populated via the
+  User-Agent header, so mobile sessions stop showing up as empty / desktop
+  in the sessions UI. A new `ua_device` column captures the device model.
+- `init({ deviceInfo })` — pass an instance of `react-native-device-info`
+  (or any `DeviceInfoLike` shim) to include the device model. Opt-in;
+  omit it and the SDK still reports `os` + `os_version` from React Native's
+  built-in `Platform` constants. Not auto-detected — same opt-in policy as
+  `storage` (0.3.0), to keep Metro bundling clean.
+- Exported `DeviceInfoLike` type for consumers writing their own shims.
+
+### Server compatibility
+
+Requires Lumin API at or after the matching server release (which adds the
+`X-Lumin-Client` parser and the `ua_device` column migration). Older
+servers will ignore the header — events still ingest, mobile rows just
+keep landing with empty `ua_*` columns.
+
 ## [0.3.0] - 2026-05-26
 
 ### Fixed
@@ -108,6 +133,7 @@ can hold events from web and mobile and tie them to the same user via
   `useLuminScreenviews(client, navigationRef)` for React Navigation v6+ apps.
 - Ships dual ESM + CJS bundle with full `.d.ts` types.
 
+[0.4.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.4.0
 [0.3.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.3.0
 [0.2.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.2.0
 [0.1.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.1.0

package/README.md

@@ -16,6 +16,8 @@ the same user.
 pnpm add @lumin-monitor/react-native
 # plus, if you want persistent ids across app launches (recommended):
 pnpm add @react-native-async-storage/async-storage
+# plus, if you want device-model tracking in the sessions UI:
+pnpm add react-native-device-info
 ```
 
 `@react-native-async-storage/async-storage` is no longer auto-detected
@@ -25,6 +27,10 @@ launches and let the 30-minute idle session window survive a cold start.
 Omit `storage` (or pass `null`) to use in-memory ids that reset on every
 cold start — fine for prototypes.
 
+`react-native-device-info` is also opt-in (same reason). Without it the
+SDK still reports `os` + `os_version` via the `X-Lumin-Client` header —
+see [Device classification](#device-classification).
+
 React Navigation is an optional peer dep, only needed if you import
 `@lumin-monitor/react-native/react-navigation`.
 
@@ -76,10 +82,11 @@ hydration to complete before sending.
 | `sessionIdleMs`   | `1800000` (30 min)            | A new session id is minted on the next event after this much inactivity.   |
 | `onError`         | `console.warn`                | Called as `(err, droppedCount)` when a batch fails.                         |
 | `fetch`           | global `fetch`                | Override for tests.                                                         |
-| `storage`         | auto-detect AsyncStorage      | Pass a custom `AsyncStorageLike`, or `null` to opt out (in-memory ids).     |
+| `storage`         | `null` (in-memory ids)        | Pass `AsyncStorage` for persistence across launches. See *Install* above.    |
 | `appState`        | auto-detect react-native      | Pass `null` to disable the background-flush listener.                       |
 | `captureUnhandledErrors` | `true`                 | Install an `ErrorUtils.setGlobalHandler` chain. See *Error capture* below.  |
 | `errorUtils`      | auto-detect global ErrorUtils | Override the ErrorUtils-like object the SDK installs into.                  |
+| `deviceInfo`      | `null` (no device model)      | Pass `DeviceInfo` from `react-native-device-info` to include the device model in the `X-Lumin-Client` header. See *Device classification* below. |
 
 ### `screen(name?, properties?)`
 
@@ -211,6 +218,45 @@ tracking, call `screen()` manually from the route's effect.
 Peer deps: `react >= 18`, `@react-navigation/native >= 6`. Both are
 optional — the subpath only loads them when imported.
 
+## Device classification
+
+Browser SDKs send a meaningful `User-Agent`; the Lumin server parses it
+into `ua_browser` / `ua_os` / `ua_device_type` columns that the sessions
+UI groups by. React Native's `fetch` sends `okhttp/…` or `CFNetwork/…`,
+which carries no device info, so the SDK ships an `X-Lumin-Client` header
+on every batch instead:
+
+```
+X-Lumin-Client: sdk=rn/0.4.0; os=ios; os_version=17.4
+```
+
+`os` and `os_version` come from React Native's built-in `Platform`
+constants — no peer dep required. The server folds the header into the
+same `ua_os` / `ua_device_type` columns the browser SDK has always used,
+so mobile sessions show up in the UI alongside web sessions.
+
+For the device model (`iPhone15,3`, `Pixel 7`), install
+[`react-native-device-info`](https://www.npmjs.com/package/react-native-device-info)
+and pass it through:
+
+```ts
+import DeviceInfo from "react-native-device-info";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { init } from "@lumin-monitor/react-native";
+
+export const lumin = init({
+  apiKey: process.env.EXPO_PUBLIC_LUMIN_BROWSER_API_KEY!,
+  storage: AsyncStorage,
+  deviceInfo: DeviceInfo, // populates X-Lumin-Client: device=<model>
+});
+```
+
+The SDK never `require()`s `react-native-device-info` — same opt-in
+policy as `storage`, to keep Metro bundling clean (see CHANGELOG 0.3.0).
+If the installed version of `react-native-device-info` ever changes its
+shape, ship a tiny adapter that satisfies `DeviceInfoLike`
+(`{ getModel(): string }`).
+
 ## Session semantics
 
 Sessions are **idle-based**, not tied to a single foreground period:

package/dist/index.cjs

@@ -97,6 +97,7 @@ 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 SDK_VERSION = "0.4.0";
 var Client = class {
   constructor(opts) {
     this.prevErrorHandler = void 0;
@@ -129,6 +130,7 @@ var Client = class {
     this.storage = opts.storage ?? memoryStorage();
     this.appState = opts.appState === void 0 ? detectAppState() : opts.appState;
     this.errorUtils = opts.errorUtils === void 0 ? detectErrorUtils() : opts.errorUtils;
+    this.clientHeader = buildClientHeader(opts.deviceInfo ?? null);
     this.idsReady = this.hydrateIds();
     this.installBackgroundFlush();
     if (opts.captureUnhandledErrors !== false) {
@@ -291,13 +293,15 @@ var Client = class {
       return;
     }
     const body = JSON.stringify({ events: batch });
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: "Bearer " + this.apiKey
+    };
+    if (this.clientHeader) headers["X-Lumin-Client"] = this.clientHeader;
     try {
       const res = await this.fetchImpl(this.endpoint + "/v1/events", {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: "Bearer " + this.apiKey
-        },
+        headers,
         body
       });
       if (!res.ok) {
@@ -405,6 +409,28 @@ function clampBatch(n) {
   if (n > SERVER_MAX_BATCH) return SERVER_MAX_BATCH;
   return Math.floor(n);
 }
+function buildClientHeader(deviceInfo) {
+  const parts = [`sdk=rn/${SDK_VERSION}`];
+  const platform = import_react_native.Platform;
+  const osRaw = platform?.OS;
+  if (typeof osRaw === "string" && osRaw) {
+    parts.push(`os=${encodeURIComponent(osRaw)}`);
+  } else {
+    return "";
+  }
+  const versionRaw = platform?.Version;
+  if (versionRaw !== void 0 && versionRaw !== null && versionRaw !== "") {
+    parts.push(`os_version=${encodeURIComponent(String(versionRaw))}`);
+  }
+  if (deviceInfo && typeof deviceInfo.getModel === "function") {
+    try {
+      const model = deviceInfo.getModel();
+      if (model) parts.push(`device=${encodeURIComponent(model)}`);
+    } catch {
+    }
+  }
+  return parts.join("; ");
+}
 function detectAppState() {
   const candidate = import_react_native.AppState;
   if (candidate && typeof candidate.addEventListener === "function") {

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { L as LuminClient, I as InitOptions } from './types-DMUQWor6.cjs';
-export { A as AppStateLike, a as AsyncStorageLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-DMUQWor6.cjs';
+import { L as LuminClient, I as InitOptions } from './types-B6rqS9Vp.cjs';
+export { A as AppStateLike, a as AsyncStorageLike, D as DeviceInfoLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-B6rqS9Vp.cjs';
 
 declare class Client implements LuminClient {
     private readonly endpoint;
@@ -12,6 +12,7 @@ declare class Client implements LuminClient {
     private readonly storage;
     private readonly appState;
     private readonly errorUtils;
+    private readonly clientHeader;
     private prevErrorHandler;
     private errorHandlerInstalled;
     private readonly recentErrors;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LuminClient, I as InitOptions } from './types-DMUQWor6.js';
-export { A as AppStateLike, a as AsyncStorageLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-DMUQWor6.js';
+import { L as LuminClient, I as InitOptions } from './types-B6rqS9Vp.js';
+export { A as AppStateLike, a as AsyncStorageLike, D as DeviceInfoLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-B6rqS9Vp.js';
 
 declare class Client implements LuminClient {
     private readonly endpoint;
@@ -12,6 +12,7 @@ declare class Client implements LuminClient {
     private readonly storage;
     private readonly appState;
     private readonly errorUtils;
+    private readonly clientHeader;
     private prevErrorHandler;
     private errorHandlerInstalled;
     private readonly recentErrors;

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import { AppState as RNAppState } from "react-native";
+import { AppState as RNAppState, Platform as RNPlatform } from "react-native";
 
 // src/ids.ts
 function uuidv4() {
@@ -70,6 +70,7 @@ 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 SDK_VERSION = "0.4.0";
 var Client = class {
   constructor(opts) {
     this.prevErrorHandler = void 0;
@@ -102,6 +103,7 @@ var Client = class {
     this.storage = opts.storage ?? memoryStorage();
     this.appState = opts.appState === void 0 ? detectAppState() : opts.appState;
     this.errorUtils = opts.errorUtils === void 0 ? detectErrorUtils() : opts.errorUtils;
+    this.clientHeader = buildClientHeader(opts.deviceInfo ?? null);
     this.idsReady = this.hydrateIds();
     this.installBackgroundFlush();
     if (opts.captureUnhandledErrors !== false) {
@@ -264,13 +266,15 @@ var Client = class {
       return;
     }
     const body = JSON.stringify({ events: batch });
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: "Bearer " + this.apiKey
+    };
+    if (this.clientHeader) headers["X-Lumin-Client"] = this.clientHeader;
     try {
       const res = await this.fetchImpl(this.endpoint + "/v1/events", {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: "Bearer " + this.apiKey
-        },
+        headers,
         body
       });
       if (!res.ok) {
@@ -378,6 +382,28 @@ function clampBatch(n) {
   if (n > SERVER_MAX_BATCH) return SERVER_MAX_BATCH;
   return Math.floor(n);
 }
+function buildClientHeader(deviceInfo) {
+  const parts = [`sdk=rn/${SDK_VERSION}`];
+  const platform = RNPlatform;
+  const osRaw = platform?.OS;
+  if (typeof osRaw === "string" && osRaw) {
+    parts.push(`os=${encodeURIComponent(osRaw)}`);
+  } else {
+    return "";
+  }
+  const versionRaw = platform?.Version;
+  if (versionRaw !== void 0 && versionRaw !== null && versionRaw !== "") {
+    parts.push(`os_version=${encodeURIComponent(String(versionRaw))}`);
+  }
+  if (deviceInfo && typeof deviceInfo.getModel === "function") {
+    try {
+      const model = deviceInfo.getModel();
+      if (model) parts.push(`device=${encodeURIComponent(model)}`);
+    } catch {
+    }
+  }
+  return parts.join("; ");
+}
 function detectAppState() {
   const candidate = RNAppState;
   if (candidate && typeof candidate.addEventListener === "function") {

package/dist/react-navigation.d.cts

@@ -1,4 +1,4 @@
-import { L as LuminClient } from './types-DMUQWor6.cjs';
+import { L as LuminClient } from './types-B6rqS9Vp.cjs';
 
 /**
  * Subset of @react-navigation/native's NavigationContainerRef the hook needs.

package/dist/react-navigation.d.ts

@@ -1,4 +1,4 @@
-import { L as LuminClient } from './types-DMUQWor6.js';
+import { L as LuminClient } from './types-B6rqS9Vp.js';
 
 /**
  * Subset of @react-navigation/native's NavigationContainerRef the hook needs.

package/dist/{types-DMUQWor6.d.cts → types-B6rqS9Vp.d.cts}

@@ -99,6 +99,22 @@ interface InitOptions {
      * runtime; tests pass a stub.
      */
     errorUtils?: ErrorUtilsLike | null;
+    /**
+     * Optional `react-native-device-info` instance (or any object satisfying
+     * `DeviceInfoLike`). When passed, the SDK adds `device=<model>` to the
+     * `X-Lumin-Client` header so the server can surface the device model in
+     * the sessions UI.
+     *
+     * Not auto-detected — passing it is opt-in, matching the `storage`
+     * pattern. The SDK never `require()`s the package, which keeps Metro
+     * bundling clean.
+     *
+     * ```ts
+     * import DeviceInfo from "react-native-device-info";
+     * init({ apiKey, deviceInfo: DeviceInfo });
+     * ```
+     */
+    deviceInfo?: DeviceInfoLike | null;
 }
 /**
  * Minimal shape of React Native's ErrorUtils. The SDK uses these three
@@ -108,6 +124,19 @@ interface ErrorUtilsLike {
     setGlobalHandler(handler: (err: unknown, isFatal?: boolean) => void): void;
     getGlobalHandler?(): ((err: unknown, isFatal?: boolean) => void) | undefined;
 }
+/**
+ * Minimal shape the SDK consumes from `react-native-device-info` (or any
+ * compatible shim). Structural so we don't pull react-native-device-info
+ * types into the SDK's public surface — the app already has them. Only
+ * `getModel` is required; future fields can be added the same way.
+ *
+ * Passed via `init({ deviceInfo: DeviceInfo })`. If omitted, the SDK still
+ * reports `os` + `os_version` from React Native's `Platform` constants —
+ * device model is the only thing that needs the optional peer dep.
+ */
+interface DeviceInfoLike {
+    getModel(): string;
+}
 /**
  * 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
@@ -137,4 +166,4 @@ interface LuminClient {
     getAnonymousId(): Promise<string>;
 }
 
-export type { AppStateLike as A, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };
+export type { AppStateLike as A, DeviceInfoLike as D, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };

package/dist/{types-DMUQWor6.d.ts → types-B6rqS9Vp.d.ts}

@@ -99,6 +99,22 @@ interface InitOptions {
      * runtime; tests pass a stub.
      */
     errorUtils?: ErrorUtilsLike | null;
+    /**
+     * Optional `react-native-device-info` instance (or any object satisfying
+     * `DeviceInfoLike`). When passed, the SDK adds `device=<model>` to the
+     * `X-Lumin-Client` header so the server can surface the device model in
+     * the sessions UI.
+     *
+     * Not auto-detected — passing it is opt-in, matching the `storage`
+     * pattern. The SDK never `require()`s the package, which keeps Metro
+     * bundling clean.
+     *
+     * ```ts
+     * import DeviceInfo from "react-native-device-info";
+     * init({ apiKey, deviceInfo: DeviceInfo });
+     * ```
+     */
+    deviceInfo?: DeviceInfoLike | null;
 }
 /**
  * Minimal shape of React Native's ErrorUtils. The SDK uses these three
@@ -108,6 +124,19 @@ interface ErrorUtilsLike {
     setGlobalHandler(handler: (err: unknown, isFatal?: boolean) => void): void;
     getGlobalHandler?(): ((err: unknown, isFatal?: boolean) => void) | undefined;
 }
+/**
+ * Minimal shape the SDK consumes from `react-native-device-info` (or any
+ * compatible shim). Structural so we don't pull react-native-device-info
+ * types into the SDK's public surface — the app already has them. Only
+ * `getModel` is required; future fields can be added the same way.
+ *
+ * Passed via `init({ deviceInfo: DeviceInfo })`. If omitted, the SDK still
+ * reports `os` + `os_version` from React Native's `Platform` constants —
+ * device model is the only thing that needs the optional peer dep.
+ */
+interface DeviceInfoLike {
+    getModel(): string;
+}
 /**
  * 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
@@ -137,4 +166,4 @@ interface LuminClient {
     getAnonymousId(): Promise<string>;
 }
 
-export type { AppStateLike as A, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };
+export type { AppStateLike as A, DeviceInfoLike as D, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumin-monitor/react-native",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React Native SDK for Lumin: screen / track / identify with batched ingest.",
   "keywords": [
     "lumin",