@scalebun/react-native 1.0.2 → 1.0.4

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/CrashFeature.ts

@@ -1,52 +1,71 @@
-/**
- * ScaleBun SDK — Crash Feature
- *
- * Installs the JS global error handler (ErrorUtils) and routes every uncaught
- * exception through the central CrashReporter, which fans it out to all sinks
- * (desktop event stream + SaaS backend errors endpoint).
- *
- * SOLID: Single Responsibility — only owns the JS crash-handler lifecycle.
- * Delivery concerns live in CrashReporter / its sinks.
- */
-
-import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
-import { installCrashReporting } from './index';
-import { getCrashReporter } from './CrashReporter';
-
-export class CrashFeature implements IFeature {
-    readonly name = 'crash';
-    private active = false;
-    private flushFn: () => Promise<void>;
-
-    constructor(flushFn: () => Promise<void>) {
-        this.flushFn = flushFn;
-    }
-
-    initialize(_context: FeatureContext): void {
-        if (this.active) return;
-        installCrashReporting((error: Error, isFatal: boolean) => {
-            getCrashReporter().report({
-                source: 'js',
-                type: isFatal ? 'crash' : 'handled',
-                isFatal,
-                message: error.message,
-                stack: error.stack,
-            });
-
-            if (isFatal) {
-                // Best-effort: also flush the event queue before the app dies.
-                this.flushFn();
-            }
-        });
-        this.active = true;
-    }
-
-    teardown(): void {
-        // Global error handler is process-global — cannot safely uninstall.
-        this.active = false;
-    }
-
-    get isActive(): boolean {
-        return this.active;
-    }
-}
+/**
+ * ScaleBun SDK — Crash Feature
+ *
+ * Installs the JS global error handler (ErrorUtils) and routes every uncaught
+ * exception through the central CrashReporter, which fans it out to all sinks
+ * (desktop event stream + SaaS backend errors endpoint).
+ *
+ * SOLID: Single Responsibility — only owns the JS crash-handler lifecycle.
+ * Delivery concerns live in CrashReporter / its sinks.
+ */
+
+import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
+import { installCrashReporting } from './index';
+import { installRejectionHandler } from './rejectionHandler';
+import { getCrashReporter } from './CrashReporter';
+
+export class CrashFeature implements IFeature {
+    readonly name = 'crash';
+    private active = false;
+    private flushFn: () => Promise<void>;
+
+    constructor(flushFn: () => Promise<void>) {
+        this.flushFn = flushFn;
+    }
+
+    initialize(_context: FeatureContext): void {
+        if (this.active) return;
+        installCrashReporting((error: Error, isFatal: boolean) => {
+            getCrashReporter().report({
+                source: 'js',
+                type: isFatal ? 'crash' : 'handled',
+                isFatal,
+                message: error.message,
+                stack: error.stack,
+            });
+
+            if (isFatal) {
+                // Best-effort: also flush the event queue before the app dies.
+                this.flushFn();
+            }
+        });
+
+        /**
+         * Unhandled promise rejections — a SEPARATE intake from ErrorUtils, which never sees them.
+         *
+         * Never fatal: a rejected promise does not stop the app, so it is reported as 'handled' and
+         * does not flush. Marking these fatal would inflate the crash count with errors the user
+         * never experienced as a crash.
+         */
+        installRejectionHandler((error: Error) => {
+            getCrashReporter().report({
+                source: 'js',
+                type: 'handled',
+                isFatal: false,
+                message: error.message,
+                stack: error.stack,
+            });
+        });
+
+        this.active = true;
+    }
+
+    teardown(): void {
+        // Global error handler is process-global — cannot safely uninstall.
+        this.active = false;
+    }
+
+    get isActive(): boolean {
+        return this.active;
+    }
+}