@goliapkg/sentori-react-native 4.0.0 → 5.1.0

package/lib/verbs.js

@@ -0,0 +1,153 @@
+// The five event verbs (design.md §4). Everything here is
+// synchronous, never throws, and returns the client-minted event id
+// — the zero-cost iron rule made code.
+//
+//   sentori.error(err)    出了什么事?
+//   sentori.warn(name)    用户哪里不舒服?
+//   sentori.trace(name)   这里发生了什么?
+//   sentori.assert(n, ok) 这里应该成立吗?
+//   sentori.probe(ref)    那个 bug 回来了吗?
+import { coerceError, parseStack, pushSignal, safeFn, snapshotSignals, uuidV7, } from '@goliapkg/sentori-core';
+import { getConfig } from './config';
+import { collectDevice } from './device';
+import { onEventEmitted } from './emit-hooks';
+import { currentContext, currentUserKey } from './scope';
+import { countAssert, enqueue } from './transport';
+/** Serialize any Error instances found in the data argument — the
+ *  error-in-data convention (design.md §4): a caught-but-noteworthy
+ *  exception needs no special API. One level deep is enough; nested
+ *  containers of errors are an anti-pattern we don't reward. */
+const serializeData = (data) => {
+    if (!data)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+        out[k] = v instanceof Error ? toSentoriError(v) : v;
+    }
+    return out;
+};
+const toSentoriError = (e) => ({
+    type: e.name || 'Error',
+    message: e.message,
+    stack: parseStack(e.stack),
+    cause: e.cause instanceof Error
+        ? toSentoriError(e.cause)
+        : null,
+});
+const platformOf = () => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const RN = require('react-native');
+        const os = RN.Platform?.OS;
+        if (os === 'ios')
+            return 'ios';
+        if (os === 'android')
+            return 'android';
+    }
+    catch {
+        // headless / test environment
+    }
+    return 'javascript';
+};
+/** Assemble + enqueue one event. The single funnel every verb uses. */
+const emit = (kind, opts) => {
+    const id = uuidV7();
+    const config = getConfig();
+    if (!config || !config.enabled)
+        return id; // no-op before init — iron rule
+    const payload = {};
+    if (opts.error)
+        payload.error = opts.error;
+    const data = serializeData(opts.data);
+    if (data)
+        payload.data = data;
+    const ctx = currentContext();
+    if (ctx)
+        payload.context = ctx;
+    if (opts.withSignals) {
+        const signals = snapshotSignals();
+        if (signals.length > 0)
+            payload.signals = signals;
+    }
+    const device = collectDevice();
+    if (device)
+        payload.device = device;
+    let event = {
+        id,
+        kind,
+        occurredAt: new Date().toISOString(),
+        platform: platformOf(),
+        release: config.release,
+        environment: config.environment,
+        name: opts.name,
+        surface: opts.surface,
+        userKey: currentUserKey(),
+        payload,
+    };
+    if (config.beforeSend) {
+        try {
+            const out = config.beforeSend(event);
+            if (out === null)
+                return id; // deliberate drop
+            if (out && typeof out === 'object')
+                event = out;
+        }
+        catch {
+            // Hook broke: the un-mutated event ships. The host's bug must
+            // not cost them the crash report.
+        }
+    }
+    enqueue(event);
+    onEventEmitted(event);
+    return id;
+};
+// ── the verbs ──────────────────────────────────────────────────────
+export const error = safeFn('error', (err, data) => {
+    const coerced = coerceError(err);
+    return emit('error', {
+        error: toSentoriError(coerced),
+        data,
+        withSignals: true,
+    });
+});
+export const warn = safeFn('warn', (name, data) => {
+    // A hand-written warn's surface can ride in data.surface; the
+    // detected scenarios pass it explicitly via warnDetected.
+    const surface = data && typeof data.surface === 'object'
+        ? data.surface
+        : undefined;
+    return emit('warn', { name, surface, data, withSignals: true });
+});
+/** SDK-internal: a detected warn scenario with an explicit surface. */
+export const warnDetected = (scenario, surface, data) => emit('warn', { name: scenario, surface, data, withSignals: true });
+export const trace = safeFn('trace', (name, data, opts) => {
+    // Every trace is context: it lands in the ring regardless.
+    pushSignal('trace', { name, ...(data ?? {}) });
+    if (opts?.quiet)
+        return uuidV7();
+    return emit('trace', { name, data });
+});
+export const assert = safeFn('assert', (name, ok, data) => {
+    const config = getConfig();
+    if (config)
+        countAssert(name, ok, config.release);
+    if (ok)
+        return uuidV7(); // passes aggregate; they are never events
+    return emit('assert', { name, data, withSignals: true });
+});
+export const probe = safeFn('probe', (ref, data) => {
+    // A tripwire: reaching this call IS the signal. Never throws,
+    // never changes control flow (design.md §4).
+    return emit('probe', { name: ref, data });
+});
+// safeFn returns `R | undefined`; the public surface promises a
+// string. An internal failure mints an id that simply never ships —
+// honest enough, and the host never sees a throw.
+export const verbs = {
+    error: (err, data) => error(err, data) ?? uuidV7(),
+    warn: (name, data) => warn(name, data) ?? uuidV7(),
+    trace: (name, data, opts) => trace(name, data, opts) ?? uuidV7(),
+    assert: (name, ok, data) => assert(name, ok, data) ?? uuidV7(),
+    probe: (ref, data) => probe(ref, data) ?? uuidV7(),
+};
+//# sourceMappingURL=verbs.js.map

package/lib/verbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbs.js","sourceRoot":"","sources":["../src/verbs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goliapkg/sentori-react-native",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "description": "Sentori SDK for React Native — JS-layer error capture, native crash handlers (iOS / Android), batched transport, fetch + react-navigation tracing.",
   "license": "Apache-2.0 OR MIT",
   "author": "GOLIA K.K. <takagi@golia.jp> (https://golia.jp)",
@@ -46,6 +46,7 @@
     "sentori-rn-upload-source-bundle": "bin/sentori-rn-upload-source-bundle.cjs"
   },
   "files": [
+    "MIGRATION.md",
     "lib/",
     "src/",
     "bin/",
@@ -90,12 +91,12 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/react": "^19",
-    "typescript": "^6"
+    "typescript": "^7"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "^1.4.0"
+    "@goliapkg/sentori-core": "^2.1.0"
   }
 }

package/src/__tests__/iron-rule.test.ts

@@ -0,0 +1,128 @@
+// The zero-cost iron rule, as executable gates (design.md §6).
+//
+// Dimension 3 (failure isolation): no Sentori failure may ever
+// throw into, block, or alter the host app. These tests inject the
+// failures; a single uncaught throw fails the suite.
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+
+import { clearSignals } from '@goliapkg/sentori-core';
+
+import { __resetForTests as resetConfig, setConfig } from '../config';
+import { init, __resetForTests as resetInit } from '../init';
+import { __resetForTests as resetScope, patchContext, setUser } from '../scope';
+import {
+  __resetForTests as resetTransport,
+  flush,
+  startTransport,
+} from '../transport';
+import { verbs } from '../verbs';
+
+const baseConfig = {
+  token: 'st_test',
+  ingestUrl: 'http://localhost:18080',
+  release: 'app@1.0.0',
+  environment: 'test',
+  enabled: true,
+  detect: { rageTap: true, longFreeze: true, slowColdStart: true, slowApi: false },
+  replaySeconds: 30,
+};
+
+const originalFetch = globalThis.fetch;
+
+const resetAll = () => {
+  resetTransport();
+  resetConfig();
+  resetScope();
+  resetInit();
+  clearSignals();
+};
+
+describe('iron rule: failure isolation', () => {
+  beforeEach(() => {
+    resetAll();
+    setConfig(baseConfig);
+    startTransport();
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    resetAll();
+  });
+
+  it('server 500 never reaches the caller', async () => {
+    globalThis.fetch = (async () => new Response('boom', { status: 500 })) as typeof fetch;
+    verbs.error(new Error('x'));
+    await flush(); // retries internally, persists, never rejects
+    expect(true).toBe(true);
+  });
+
+  it('network down never reaches the caller', async () => {
+    globalThis.fetch = (async () => {
+      throw new TypeError('Network request failed');
+    }) as typeof fetch;
+    verbs.warn('rage_tap');
+    await flush();
+    expect(true).toBe(true);
+  });
+
+  it('a hostile beforeSend cannot break the verb', () => {
+    setConfig({
+      ...baseConfig,
+      beforeSend: () => {
+        throw new Error('host bug');
+      },
+    });
+    const id = verbs.error(new Error('x'));
+    expect(typeof id).toBe('string');
+  });
+
+  it('fuzz: the verbs accept garbage without throwing', () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    const huge = 'x'.repeat(1_000_000);
+
+    expect(typeof verbs.error(null)).toBe('string');
+    expect(typeof verbs.error(undefined)).toBe('string');
+    expect(typeof verbs.error(42)).toBe('string');
+    expect(typeof verbs.error(circular)).toBe('string');
+    expect(typeof verbs.warn('', circular)).toBe('string');
+    expect(typeof verbs.warn(huge)).toBe('string');
+    expect(typeof verbs.trace('t', { huge })).toBe('string');
+    expect(typeof verbs.assert('a', false, circular)).toBe('string');
+    expect(typeof verbs.probe('p', { circular })).toBe('string');
+    setUser({ id: huge });
+    setUser(null);
+    patchContext(circular);
+  });
+
+  it('every verb before init is a silent no-op returning an id', () => {
+    resetAll();
+    expect(typeof verbs.error(new Error('x'))).toBe('string');
+    expect(typeof verbs.warn('w')).toBe('string');
+    expect(typeof verbs.trace('t')).toBe('string');
+    expect(typeof verbs.assert('a', false)).toBe('string');
+    expect(typeof verbs.probe('p')).toBe('string');
+  });
+
+  it('init with a broken config degrades to no-op, never throws', () => {
+    resetAll();
+    init(undefined as never);
+    init({} as never);
+    init({ token: '', ingestUrl: '' } as never);
+    expect(typeof verbs.error(new Error('x'))).toBe('string');
+  });
+});
+
+describe('iron rule: init timing', () => {
+  beforeEach(resetAll);
+  afterEach(resetAll);
+
+  it('init completes inside the 50 ms budget', () => {
+    const start = performance.now();
+    init(baseConfig);
+    const ms = performance.now() - start;
+    // The budget is for the synchronous path; native drains and the
+    // offline queue are fire-and-forget behind it.
+    expect(ms).toBeLessThan(50);
+  });
+});

package/src/__tests__/replay-screens.test.ts

@@ -0,0 +1,63 @@
+// The screens ring: capacity, drain shape, mask-query isolation,
+// and graceful absence on an old native build.
+
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+
+import { __resetForTests as resetMask, maskedNativeIds, registerMaskQuery } from '../mask';
+import {
+  __resetForTests as resetRing,
+  __setCaptureForTests,
+  drainScreenReplay,
+  startScreenReplay,
+} from '../replay-screens';
+
+afterEach(() => {
+  resetRing();
+  resetMask();
+});
+
+describe('mask query', () => {
+  test('unregistered → empty', () => {
+    expect(maskedNativeIds()).toEqual([]);
+  });
+
+  test('registered query flows through and filters junk', () => {
+    registerMaskQuery(() => ['camera-feed', 42 as unknown as string, 'user-email']);
+    expect(maskedNativeIds()).toEqual(['camera-feed', 'user-email']);
+  });
+
+  test('a throwing query masks nothing and never throws', () => {
+    registerMaskQuery(() => {
+      throw new Error('boom');
+    });
+    expect(maskedNativeIds()).toEqual([]);
+  });
+});
+
+describe('screens ring', () => {
+  test('drain on an empty ring is null (old native builds)', () => {
+    startScreenReplay(60);
+    expect(drainScreenReplay()).toBeNull();
+  });
+
+  test('drain emits NDJSON with negative relative timestamps', async () => {
+    let n = 0;
+    __setCaptureForTests(
+      mock(async () => ({ base64: `frame${(n += 1)}`, mediaType: 'image/jpeg' })),
+    );
+    startScreenReplay(60);
+    await new Promise((r) => setTimeout(r, 2_600));
+    const out = drainScreenReplay();
+    expect(out).not.toBeNull();
+    const lines = (out ?? '')
+      .split('\n')
+      .map((l) => JSON.parse(l) as { t: number; base64: string });
+    expect(lines.length).toBeGreaterThanOrEqual(1);
+    for (const l of lines) {
+      expect(l.t).toBeLessThanOrEqual(0);
+      expect(l.base64.startsWith('frame')).toBe(true);
+    }
+    // drain does not clear: a second error still sees the window
+    expect(drainScreenReplay()).not.toBeNull();
+  }, 10_000);
+});

package/src/__tests__/responsiveness-detector.test.ts

@@ -0,0 +1,74 @@
+// dead_button / sluggish_button verdict logic.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEAD_THRESHOLD,
+  DEAD_WINDOW_MS,
+  RESPONSE_WINDOW_MS,
+  SLUGGISH_COOLDOWN_MS,
+  SLUGGISH_MS,
+  classifyTap,
+  recordDeadTap,
+  recordSluggish,
+} from '../responsiveness-detector';
+
+describe('classifyTap', () => {
+  test('a fast reaction is responsive', () => {
+    expect(classifyTap(1000, [1300])).toBe('responsive');
+  });
+
+  test('a slow reaction is sluggish', () => {
+    expect(classifyTap(1000, [1000 + SLUGGISH_MS + 200])).toBe('sluggish');
+  });
+
+  test('no reaction inside the window is dead', () => {
+    expect(classifyTap(1000, [])).toBe('dead');
+    expect(classifyTap(1000, [1000 + RESPONSE_WINDOW_MS + 500])).toBe('dead');
+  });
+
+  test('signals from before the tap do not count', () => {
+    expect(classifyTap(1000, [900, 500])).toBe('dead');
+  });
+
+  test('the earliest reaction decides', () => {
+    expect(classifyTap(1000, [1000 + SLUGGISH_MS + 400, 1200])).toBe('responsive');
+  });
+});
+
+describe('recordDeadTap', () => {
+  test('warns only at the threshold, then resets', () => {
+    const buckets = new Map<number, number[]>();
+    let warned = 0;
+    for (let i = 0; i < DEAD_THRESHOLD * 2; i++) {
+      if (recordDeadTap(buckets, 7, 1000 + i * 100)) warned += 1;
+    }
+    expect(warned).toBe(2);
+  });
+
+  test('stale dead taps age out of the window', () => {
+    const buckets = new Map<number, number[]>();
+    recordDeadTap(buckets, 7, 0);
+    recordDeadTap(buckets, 7, 100);
+    // Third tap arrives after the window: the old two are gone.
+    expect(recordDeadTap(buckets, 7, DEAD_WINDOW_MS + 200)).toBe(false);
+  });
+
+  test('targets are independent', () => {
+    const buckets = new Map<number, number[]>();
+    recordDeadTap(buckets, 1, 0);
+    recordDeadTap(buckets, 1, 10);
+    expect(recordDeadTap(buckets, 2, 20)).toBe(false);
+    expect(recordDeadTap(buckets, 1, 30)).toBe(true);
+  });
+});
+
+describe('recordSluggish', () => {
+  test('cooldown gates repeat warns per target', () => {
+    const warns = new Map<number, number>();
+    expect(recordSluggish(warns, 7, 1000)).toBe(true);
+    expect(recordSluggish(warns, 7, 2000)).toBe(false);
+    expect(recordSluggish(warns, 7, 1000 + SLUGGISH_COOLDOWN_MS + 1)).toBe(true);
+    expect(recordSluggish(warns, 8, 2000)).toBe(true);
+  });
+});

package/src/__tests__/screenshot.test.ts

@@ -59,8 +59,6 @@ describe('uploadAttachment', () => {
     expect(seen.auth).toBe('Bearer st_pk_test');
     expect(out).not.toBeNull();
     expect(out!.ref).toBe('019e3000-7000-7000-8000-000000000001');
-    expect(out!.kind).toBe('screenshot');
-    expect(out!.source).toBe('js');
   });
 
   test('returns null on a non-201 response', async () => {