@scalebun/react-native 1.0.3 → 1.0.4

package/src/core/config/schema.ts

@@ -6,11 +6,19 @@ export const ConfigSchema = z.object({
     projectId: z.string().min(1).optional(),
     publishableKey: z.string().min(1).optional(),
     /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud
-     * ({@link DEFAULT_API_BASE_URL}). Override only for staging or a
-     * self-hosted backend. Still validated as a URL when supplied.
-     */
-    apiBaseUrl: z.string().url('apiBaseUrl must be a valid URL').default(DEFAULT_API_BASE_URL),
+     * Backend API base URL. LOCKED to {@link DEFAULT_API_BASE_URL} — the ScaleBun
+     * cloud endpoint is fixed and cannot be overridden by integrators. Any value
+     * supplied here is accepted (no validation error, for backward compatibility)
+     * but ignored: the bootstrapper force-overwrites it with DEFAULT_API_BASE_URL
+     * immediately after parse. To point the SDK at a different backend, change the
+     * constant at build time.
+     */
+    // Thunk, not a bare string: `default()` is typed `Partial<T> | (() => T)`, and for
+    // `z.any()` T is `any`, so `Partial<any>` widens to an index signature that a string
+    // does not satisfy. The function overload does, and DefaultSchema calls it only when
+    // the input is undefined — identical at runtime, and it type-checks, which `bob build`
+    // requires to emit definitions at all.
+    apiBaseUrl: z.any().default(() => DEFAULT_API_BASE_URL),
     debug: z.boolean().default(false),
     /**
      * SDK internal log verbosity. Recoverable transport failures are logged at

package/src/core/context/device.ts

@@ -0,0 +1,146 @@
+/**
+ * The ONE place that answers "what device is this?".
+ *
+ * It was previously answered three incompatible ways at once:
+ *
+ *   1. The replay lane asked the native bridge and got the truth.
+ *   2. The analytics lane took `ScaleBun.init({ context })` verbatim and shipped whatever the
+ *      integrator typed. Production carries `device_model: "android"`, `manufacturer: "android"`
+ *      and `sdk_version: "qa-app-1.0"` because an app hand-wrote them — none of those are a model,
+ *      a manufacturer, or an SDK version.
+ *   3. Seven call sites wrote `Platform.OS === 'ios' ? 'ios' : 'android'`, which reports every
+ *      non-iOS platform — windows, macos, web — as Android.
+ *
+ * Detection belongs to the SDK. An integrator cannot be expected to know the device better than the
+ * process running on it, and asking them to means the field is wrong whenever they guess.
+ *
+ * Every value here is measured or absent. Nothing is defaulted to a plausible-looking constant: a
+ * fabricated device model is indistinguishable from a real one to whoever reads the dashboard, which
+ * is strictly worse than an empty field.
+ */
+import { SDK_VERSION } from '../constants/version';
+
+/**
+ * The real `Platform.OS`, never narrowed.
+ *
+ * React Native's own union is `'ios' | 'android' | 'windows' | 'macos' | 'web'`, and the protocol's
+ * platform field is an open enum precisely so new ones travel without a release. Collapsing that to
+ * a two-way ternary is what made every macOS and Windows session read as Android.
+ */
+export type PlatformOS = 'ios' | 'android' | 'windows' | 'macos' | 'web' | 'unknown';
+
+interface RNPlatform {
+    OS?: string;
+    Version?: string | number;
+    constants?: {
+        Manufacturer?: string;
+        Model?: string;
+        Brand?: string;
+        Release?: string;
+        osVersion?: string;
+        systemName?: string;
+    };
+}
+
+function rnPlatform(): RNPlatform | null {
+    try {
+        return (require('react-native') as { Platform?: RNPlatform }).Platform ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * `Platform.OS`, verbatim.
+ *
+ * `'unknown'` when React Native itself cannot be loaded — the previous `catch { return 'android' }`
+ * turned "we could not tell" into a confident, wrong answer.
+ */
+export function resolvePlatformOS(): PlatformOS {
+    const os = rnPlatform()?.OS;
+    switch (os) {
+        case 'ios':
+        case 'android':
+        case 'windows':
+        case 'macos':
+        case 'web':
+            return os;
+        default:
+            // A platform React Native gained after this build. Pass it through rather than guess —
+            // the wire's platform field is an open enum for exactly this case.
+            return (os as PlatformOS) ?? 'unknown';
+    }
+}
+
+/**
+ * `'ios' | 'android'` for the few call sites whose payload genuinely only has those two, keeping the
+ * narrowing HONEST: `null` where it used to silently say Android.
+ */
+export function resolveMobileOS(): 'ios' | 'android' | null {
+    const os = resolvePlatformOS();
+    return os === 'ios' || os === 'android' ? os : null;
+}
+
+/** The keys this module owns. An integrator-supplied value for any of them is overridden. */
+export const DETECTED_CONTEXT_KEYS = [
+    'sdk_version',
+    'platform_os',
+    'os_version',
+    'device_model',
+    'manufacturer',
+] as const;
+
+/**
+ * Everything derivable WITHOUT the native bridge, so the very first event already carries it.
+ *
+ * The bridge is async and may not be installed at all (Expo Go, an older native binary); waiting on
+ * it would leave the opening events of every session unattributed. `Platform.constants` is populated
+ * synchronously at startup and covers Android fully — iOS exposes no model there, which is why
+ * `device_model` stays absent on iOS until {@link nativeDeviceContext} fills it in.
+ */
+export function staticDeviceContext(): Record<string, string> {
+    const platform = rnPlatform();
+    const out: Record<string, string> = {
+        sdk_version: SDK_VERSION,
+        platform_os: resolvePlatformOS(),
+    };
+    if (!platform) return out;
+
+    const c = platform.constants ?? {};
+    // Android: Release is the marketing version ("14"); Version is the API level (34).
+    // iOS: osVersion is the real thing; Platform.Version mirrors it.
+    const osVersion = c.Release ?? c.osVersion ?? (platform.Version != null ? String(platform.Version) : undefined);
+    if (osVersion) out.os_version = String(osVersion);
+    if (c.Model) out.device_model = String(c.Model);
+    if (c.Manufacturer) out.manufacturer = String(c.Manufacturer);
+    else if (c.Brand) out.manufacturer = String(c.Brand);
+    return out;
+}
+
+/** Bridge values, once the native module answers. Absent keys stay absent. */
+export function nativeDeviceContext(info: {
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+} | null): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (!info) return out;
+    if (info.osVersion) out.os_version = info.osVersion;
+    if (info.deviceModel) out.device_model = info.deviceModel;
+    return out;
+}
+
+/**
+ * Merge the integrator's context with what we detected — DETECTED WINS on the keys above.
+ *
+ * The inversion is deliberate. Config normally wins over defaults, but these are not defaults: they
+ * are measurements, and a measurement must not be overridable by a guess. Everything outside
+ * {@link DETECTED_CONTEXT_KEYS} — `language`, `timezone`, `network_type`, anything app-specific —
+ * is still the integrator's to set, untouched.
+ */
+export function mergeDeviceContext(
+    configured: Record<string, unknown> | undefined,
+    detected: Record<string, string> = staticDeviceContext(),
+): Record<string, unknown> {
+    return { ...(configured ?? {}), ...detected };
+}

package/src/debug/replayWiring.ts

@@ -10,6 +10,7 @@ import type { ReplayConfig } from '../features/replay/public/types';
 import type { DebugTransport } from './transport';
 import type { SessionManager as SessionManagerType } from '../features/session/SessionManager';
 import { logger } from '../core/logger/internalLogger';
+import { resolvePlatformOS } from '../core/context/device';
 
 // ─── State ──────────────────────────────────────────────────────────────────
 
@@ -90,7 +91,7 @@ export function wireNativeCaptureDeferred(
                                 byteSize: result.sizeBytes || Math.round(result.base64.length * 0.75),
                                 format: (result.format ?? 'jpeg') as string,
                                 frameHash: (result as any).frameHash as string | undefined,
-                                platform: (Platform.OS === 'ios' ? 'ios' : 'android') as 'android' | 'ios',
+                                platform: resolvePlatformOS() as 'android' | 'ios',
                             };
                         } catch {
                             return null;

package/src/features/bugreport/BugReportFeature.ts

@@ -0,0 +1,128 @@
+/**
+ * F-BUG (React Native) — bug-report feature.
+ *
+ * Ported from the web SDK's `features/bugreport/BugReportFeature.ts`, deliberately keeping its
+ * split: this class is THIN. It raises the capture signal and holds a `submitFn` injected by the
+ * facade, which owns session + transport and therefore owns the HTTP. Duplicating the submit here
+ * would give the two SDKs two contracts to drift apart.
+ *
+ * WHAT DOES NOT PORT
+ * The web feature lazy-imports a DOM launcher widget (`widget.ts`, 185 lines of document/CSS). RN
+ * has no DOM: the form is rendered by `EngagePromptView`, which already exists, already handles the
+ * native modal/keyboard behaviour, and is already what `shake_device` puts on screen. Building a
+ * second prompt system for this would be the same mistake in a different repo.
+ *
+ * TRIGGERING
+ * `shake_device` is already wired end to end — native CoreMotion/SensorManager →
+ * `engageShakeBridge` → `gestureTriggerDetector.reportShake()` → the `$gesture` signal lane → the
+ * engage trigger engine. This feature is a submit target for that flow, not a second detector.
+ */
+import { logger } from '../../core/logger/internalLogger';
+import type { EngageAttachmentDraft } from '../engage/engageTypes';
+
+/** Why a submit did not produce a report id. Mirrors the web SDK's discriminated failure union. */
+export type BugFailure = 'init' | 'consent' | 'send' | 'empty';
+
+/** Resolves to the report id, or to `{ e }` naming WHICH branch failed. */
+export type BugSubmitResult = string | { e: BugFailure };
+
+export interface BugReportInput {
+  /** The issue text. Required — a report with no description is not a report. */
+  message: string;
+  title?: string;
+  /**
+   * Reporter's email. Optional on purpose: the session usually already resolves to an end user, so
+   * the form should PREFILL this rather than demand it from someone who just shook their phone in
+   * frustration. `BugReport.reporterEmail` is nullable server-side.
+   */
+  email?: string;
+  /**
+   * An approved voice note, produced by `features/engage/captureVoiceAttachment`.
+   *
+   * That module returns a transcript as a PREFILL and only marks `transcriptApproved` once the user
+   * has explicitly accepted the wording. This feature must never submit an unapproved draft — a
+   * machine transcription of someone's voice, sent without them confirming it, is a different
+   * product decision than the one that pipeline was built for.
+   */
+  voice?: EngageAttachmentDraft;
+}
+
+type SubmitFn = (input: BugReportInput) => Promise<BugSubmitResult>;
+
+export class BugReportFeature {
+  readonly name = 'bugReport';
+
+  private active = false;
+  private submitFn: SubmitFn | null = null;
+  /** Raises the 'report' capture signal so replay flushes its buffer into the current session. */
+  private signalFn: (() => void) | null = null;
+
+  get isActive(): boolean {
+    return this.active;
+  }
+
+  setup(hooks: { signal?: () => void } = {}): void {
+    this.signalFn = hooks.signal ?? null;
+    this.active = true;
+  }
+
+  /**
+   * Flush replay into the session so the report has its visual context.
+   *
+   * Fail-soft: replay may be disabled, paused, or unsupported on this build. A report without a
+   * replay anchor is still a useful report, so this must never block a submit.
+   */
+  signalReport(): void {
+    try {
+      this.signalFn?.();
+    } catch {
+      /* never let a capture-signal failure break a bug report */
+    }
+  }
+
+  /** Wired by the facade after init — the full submit path (transport + session + context). */
+  setSubmit(fn: SubmitFn): void {
+    this.submitFn = fn;
+  }
+
+  /**
+   * Submit a report.
+   *
+   * Returns rather than throws, always. This is called from a UI the host app renders, often from a
+   * user gesture; an exception escaping into a React Native render tree is a redbox for the
+   * customer's user, over a bug report they were trying to send us.
+   */
+  async submit(input: BugReportInput): Promise<BugSubmitResult> {
+    if (!input || !input.message || input.message.trim().length === 0) {
+      logger.warn('[scalebun] reportBug: a message is required');
+      return { e: 'empty' };
+    }
+    // No submitFn means the facade never finished wiring. That is 'init', not a send failure —
+    // the distinction is what tells an integrator to check their setup rather than their network.
+    if (!this.submitFn) return { e: 'init' };
+
+    if (input.voice && !input.voice.transcriptApproved) {
+      // Refused rather than silently stripped: dropping the attachment would send a report the user
+      // believes contains their voice note, and they would never learn it did not.
+      logger.warn('[scalebun] reportBug: voice note has no approved transcript — not sending');
+      return { e: 'empty' };
+    }
+
+    try {
+      // Order matters and mirrors the web path: signal BEFORE submit so the replay bytes are already
+      // in flight, and so the report's replay coordinate refers to a frame that exists. A flush
+      // cannot retroactively manufacture a frame, so a missing anchor must stay missing rather than
+      // become a misleading "start of session" link in the dashboard.
+      this.signalReport();
+      return await this.submitFn(input);
+    } catch {
+      return { e: 'send' };
+    }
+  }
+
+  teardown(): void {
+    this.submitFn = null;
+    this.signalFn = null;
+    this.active = false;
+  }
+}

package/src/features/bugreport/buildPayload.ts

@@ -0,0 +1,116 @@
+/**
+ * Builds the body for POST /ingestion/sessions/:sessionId/bug-reports.
+ *
+ * Kept as a PURE function with no transport, no bridge and no clock of its own, because the wire
+ * shape is a cross-repo contract and the only way to keep it honest is to be able to assert it
+ * directly. Every bound below is copied from the server DTO
+ * (wzb-dashboard-backend/src/features/bug-reports/dto/submit-bug-report.dto.ts) rather than guessed:
+ *
+ *   clientReportId?   string            idempotency key -> BugReport.clientReportId (@unique)
+ *   title?            string   <= 300
+ *   message           string   <= 20000  -> BugReport.description  (REQUIRED)
+ *   email?            string   <= 320
+ *   url?              string   <= 2000
+ *   console?          unknown[]          recent breadcrumbs
+ *   screenshotKey?    string   <= 512, [A-Za-z0-9._/-] and no ".."
+ *   timestamp?        number             2000-01-01 .. 2100-01-01 in epoch MILLIS
+ *   replaySeq?        int      0 .. 2147483647
+ *   replaySegmentId?  string   <= 256
+ *
+ * Truncating here rather than letting the server 400 is deliberate: a 20,001-character description
+ * is a real report from a real annoyed user, and losing it to a validation error helps nobody. The
+ * ceiling is theirs, so we respect it at the edge. Nothing is silently REWRITTEN — only cut, and
+ * only at bounds the server would otherwise reject outright.
+ */
+
+/** Mirrors SubmitBugReportDto. Optional keys are omitted entirely rather than sent as undefined. */
+export interface BugReportPayload {
+  clientReportId?: string;
+  title?: string;
+  message: string;
+  email?: string;
+  url?: string;
+  console?: unknown[];
+  screenshotKey?: string;
+  timestamp?: number;
+  replaySeq?: number;
+  replaySegmentId?: string;
+}
+
+export interface ReplayCoord {
+  seq?: number | null;
+  segmentId?: string | null;
+}
+
+const MAX_TITLE = 300;
+const MAX_MESSAGE = 20_000;
+const MAX_EMAIL = 320;
+const MAX_SEGMENT_ID = 256;
+/** The server rejects outside these; a drifted device clock must not cost us the whole report. */
+const TS_MIN = 946684800000; // 2000-01-01
+const TS_MAX = 4102444800000; // 2100-01-01
+const MAX_BREADCRUMBS = 50;
+
+function clip(v: string | undefined | null, max: number): string | undefined {
+  if (typeof v !== 'string') return undefined;
+  const t = v.trim();
+  return t.length === 0 ? undefined : t.slice(0, max);
+}
+
+export function buildBugReportPayload(
+  input: { message: string; title?: string; email?: string; clientReportId?: string },
+  breadcrumbs: readonly unknown[] = [],
+  ctx: { replayCoord?: ReplayCoord | null; timestamp?: number } = {},
+): BugReportPayload {
+  const message = (input.message ?? '').trim().slice(0, MAX_MESSAGE);
+
+  const payload: BugReportPayload = { message };
+
+  const title = clip(input.title, MAX_TITLE);
+  if (title) payload.title = title;
+
+  const email = clip(input.email, MAX_EMAIL);
+  if (email) payload.email = email;
+
+  const clientReportId = clip(input.clientReportId, 200);
+  if (clientReportId) payload.clientReportId = clientReportId;
+
+  if (breadcrumbs.length > 0) payload.console = breadcrumbs.slice(-MAX_BREADCRUMBS);
+
+  /**
+   * An out-of-range clock is DROPPED, not clamped.
+   *
+   * Clamping would invent a `reportedAt` the device never observed, and the server keeps that column
+   * separate from `createdAt` precisely so the two can be compared. A missing client time is honest;
+   * a fabricated one silently corrupts that comparison.
+   */
+  const ts = ctx.timestamp;
+  if (typeof ts === 'number' && Number.isFinite(ts) && ts >= TS_MIN && ts <= TS_MAX) {
+    payload.timestamp = ts;
+  }
+
+  /**
+   * The replay anchor is included ONLY when a frame actually existed at submit time.
+   *
+   * Defaulting `replaySeq` to 0 would point every anchor-less report at the start of the session,
+   * which reads in the dashboard exactly like a real anchor and is wrong. Replay may be disabled,
+   * paused, or yet to produce a frame; absent must stay absent.
+   */
+  const seq = ctx.replayCoord?.seq;
+  if (typeof seq === 'number' && Number.isInteger(seq) && seq >= 0 && seq <= 2147483647) {
+    payload.replaySeq = seq;
+    const segmentId = clip(ctx.replayCoord?.segmentId ?? undefined, MAX_SEGMENT_ID);
+    if (segmentId) payload.replaySegmentId = segmentId;
+  }
+
+  /**
+   * `url` is intentionally NEVER set on React Native.
+   *
+   * The field means a page URL. The nearest mobile concept is the current screen name, and putting
+   * a screen name in a column called `url` is exactly the field-misuse that makes a dashboard show
+   * one thing and mean another. Screen context already reaches the report through the session it is
+   * attached to. If mobile needs its own field, that is a schema change, not a reused column.
+   */
+
+  return payload;
+}

package/src/features/crash/CrashReporter.ts

@@ -18,7 +18,7 @@ import { noThrow } from '../../core/lifecycle/crashSafe';
 import { SessionManager } from '../session/SessionManager';
 
 /** Where the crash originated. */
-export type CrashSource = 'js' | 'handled' | 'native';
+export type CrashSource = 'js' | 'handled' | 'native' | 'manual';
 
 /** Normalized, transport-agnostic crash report. */
 export interface CrashReport {
@@ -40,6 +40,25 @@ export interface CrashReport {
     timestamp?: string;
     /** Free-form extra context (thread name, signal, cause, ...). */
     metadata?: Record<string, unknown>;
+    /**
+     * The session this crash BELONGS to, when that is not the current one.
+     *
+     * Set only by a recovered native crash: it happened in a process that is already gone, so the
+     * session it belongs to is not the session running now. Without it the report is routed through
+     * whichever SessionManager exists at drain time and lands on the NEW session — marking a healthy
+     * session crashed and the crashed one clean.
+     *
+     * Absent means "the current session", which is correct for every live report.
+     */
+    sessionId?: string;
+    /**
+     * Stable id for a recovered native crash — the idempotency key.
+     *
+     * Generated ONCE when the crash was first written to disk, never per attempt, so any number of
+     * retries collapse to one backend record. An id minted at upload time would defeat dedupe
+     * entirely and turn every retry into a fresh duplicate crash.
+     */
+    crashId?: string;
 }
 
 /**
@@ -111,11 +130,31 @@ export class BackendErrorsSink implements CrashSink {
     deliver(report: CrashReport): void {
         const transport = SessionManager.getExistingInstance()?.getBackendTransport();
         if (!transport) return;
+        // D12: this used to forward four fields and drop the rest — so a native
+        // crash's signal/thread/exception-type were captured on device and
+        // discarded one call before the wire, every RN error row had a NULL
+        // platform (making Issue.primaryPlatform mean "web-only"), and fatality
+        // was indistinguishable from a handled error. The receiver has always
+        // accepted all of these.
         transport.queueError({
             type: report.type,
             message: report.message,
             stack: report.stack,
             screenName: report.screenName,
+            platform: report.platform,
+            isFatal: report.isFatal,
+            metadata: report.metadata,
+            /**
+             * Carried through so the transport can address the ORIGINAL session.
+             *
+             * Set only on a recovered native crash, whose session died with its process. Omitted
+             * for every live report, where the current session is the right answer — so this
+             * changes nothing about normal error delivery.
+             */
+            ...(report.sessionId ? { sessionId: report.sessionId } : {}),
+            // Becomes SessionError.clientId, which is @unique — that constraint is what turns a
+            // retried crash into one record instead of a duplicate.
+            ...(report.crashId ? { clientId: report.crashId } : {}),
         });
         // Best-effort immediate delivery so the crash surfaces quickly.
         transport.flushErrors().catch(() => {});

package/src/features/crash/capture.ts

@@ -1,21 +1,48 @@
-import { createEnvelope } from '../../pipeline/envelope/envelope';
-import { memoryQueue } from '../../pipeline/queue/memoryQueue';
 import { noThrow } from '../../core/lifecycle/crashSafe';
+import { getCrashReporter } from './CrashReporter';
 
-export function captureException(error: Error, extra?: any) {
+/**
+ * Manual error/message capture — the `Sentry.captureException` equivalent.
+ *
+ * D3: these used to write envelopes into `memoryQueue`, a queue whose only
+ * drain (`Dispatcher.flush`) was registered in the DI container and never
+ * resolved by anything — every capture was accumulated and discarded. They
+ * were also never exported, so the two entry points were reachable by nobody
+ * and delivered to nowhere.
+ *
+ * Now they ride the SAME pipeline as automatic crash capture (CrashReporter →
+ * BackendErrorsSink → `/ingestion/sessions/:id/errors`) — the one path in this
+ * SDK that is proven to land rows.
+ */
+export function captureException(
+    error: Error,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
     noThrow(() => {
-        const envelope = createEnvelope('crash', {
+        getCrashReporter().report({
+            type: 'handled',
             message: error.message,
             stack: error.stack,
-            ...extra,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
         });
-        memoryQueue.add(envelope);
     });
 }
 
-export function captureMessage(message: string) {
+export function captureMessage(
+    message: string,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
     noThrow(() => {
-        const envelope = createEnvelope('log', { message, level: 'info' });
-        memoryQueue.add(envelope);
+        getCrashReporter().report({
+            type: 'handled',
+            message,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
+        });
     });
 }