@nathanclaire/edge-telemetry-sdk 3.0.0 → 4.0.0

package/dist/src/core/telemetry.d.ts

@@ -1,4 +1,47 @@
 import { ScreenTimingTracker } from '../adapters/screenTiming';
+import { ViewManager, ViewNameSource } from '../adapters/viewManager';
+import { TraceManager } from '../adapters/traceManager';
+import { ErrorSource } from '../adapters/crashCapture';
+import { Store } from './store';
+import { BeforeSend } from './beforeSend';
+import { Orientation } from '../adapters/viewport';
+export type { BeforeSend } from './beforeSend';
+export type { Orientation };
+/** `sdk.drop_reason` (§11). `rejected` has no producer until 4xx-drops-the-batch lands (#113). */
+export type DropReason = "queue_full" | "store_full" | "rejected";
+/**
+ * §4.7's two error names. Both book `sdk.error_count` and `view.error_count` — a closed
+ * enumeration, not resource failures and not `console.warn`. Only `app.crash` gets the
+ * dedicated crash path and the eviction reprieve, which is the whole point of the split:
+ * `COUNT(event_name='app.crash')` must stay a crash count nobody can forget to filter.
+ */
+export declare const isErrorName: (name?: string) => boolean;
+export declare function evictIndex(events: TelemetryEvent[]): number;
+/** Store key for the self-minted, persisted `device.id` (#91). */
+export declare const DEVICE_ID_KEY = "telemetry_device_id";
+/** Store key for the resumable session record (#92). */
+export declare const SESSION_KEY = "telemetry_session";
+/** `session.reason` domains: 3 on session.started, the last 2 on session.finalized (§4.1/§4.2). */
+export type SessionReason = "launch" | "idle" | "max_duration";
+export type SessionEndReason = Exclude<SessionReason, "launch">;
+/**
+ * §4.6's mint/emit split, for the one event that has one. A `ui.interaction` is emitted
+ * after its dead-click window, so its wire `timestamp` and its `view.id` / `view.name` /
+ * `session.id` are snapshotted at the click and replayed here — otherwise a tap that
+ * navigates is booked against the view it opened.
+ */
+export type LogSnapshot = {
+    /**
+     * Epoch ms of the click. Becomes the row's `timestamp`. **Omitted by a span-carrying row
+     * that is not deferred** — an `http.request` freezes its *attribution* at send but still
+     * reports the completion time §4.4 gives it.
+     */
+    at?: number;
+    viewId: string;
+    sessionId: string;
+    /** Epoch ms — `session.start_time` freezes with the id it belongs to (§3.1). */
+    sessionStart: number;
+};
 export type TelemetryEvent = {
     type: 'event' | 'metric';
     eventName?: string;
@@ -9,7 +52,13 @@ export type TelemetryEvent = {
 };
 export interface Sender {
     send(events: TelemetryEvent[]): Promise<void>;
-    onFailure?(events: TelemetryEvent[]): Promise<void>;
+    /**
+     * Persist a batch that could not be sent. Returns how many rows the offline store's
+     * cap cost, so core can book them as `sdk.drop_reason = "store_full"` (§9.4) — the
+     * counter lives on the Context block, which only core assembles. `void` is still a
+     * valid return: a consumer's own sender is not obliged to have a cap.
+     */
+    onFailure?(events: TelemetryEvent[]): Promise<number | void>;
     replayFailed?(): Promise<void>;
 }
 export interface CrashHandlerOptions {
@@ -20,13 +69,7 @@ export interface CrashHandler {
 }
 export interface NetworkInfo {
     type?: string;
-    isConnected?: boolean;
-}
-export interface WebExtraNetworkInfo {
-    type?: string;
-    isConnected?: boolean;
-    downlink?: number;
-    effectiveType?: string;
+    is_connected?: boolean;
 }
 export interface NetworkInfoHandler {
     start(telemetry: Telemetry): Promise<NetworkInfo>;
@@ -43,7 +86,9 @@ export interface NetworkHandler {
     start(): Promise<void>;
 }
 export interface MemoryHandler {
-    recordMemoryUsage(): Promise<void>;
+    start(): Promise<void>;
+    /** Torn down by `shutdown()`: unlike the rAF-driven trackers this one owns a timer. */
+    stop?(): void;
 }
 export interface NavigationHandler {
     start(): Promise<void>;
@@ -52,35 +97,44 @@ export interface DeviceInfo {
     app: {
         name: string;
         version: string;
-        buildNumber?: string;
-        packageName?: string;
+        build_number?: string;
+        package_name?: string;
     };
     device: {
-        id: string;
         platform: string;
-        platformVersion?: string;
+        platform_version?: string;
         model?: string;
         manufacturer?: string;
         brand?: string;
-        androidSdk?: string;
-        androidRelease?: string;
-        fingerprint?: string;
+        android_sdk?: string;
+        android_release?: string;
         hardware?: string;
         product?: string;
-        iosSystemName?: string;
-        iosDeviceName?: string;
+        ios_system_name?: string;
+        cpu_abi?: string;
+        low_ram?: boolean;
+        screen_density?: number;
+        screen_width_px?: number;
+        screen_height_px?: number;
+        orientation?: Orientation;
     };
 }
 export interface UserProfile {
     userId?: string;
+    /** @deprecated Removed in v5 — use `identify({ name })`. Still the source of `user.name`. */
     fullName?: string;
+    /** @deprecated Removed in v5 — never reached the wire; `identify()` could not set it. */
     firstName?: string;
+    /** @deprecated Removed in v5 — never reached the wire; `identify()` could not set it. */
     lastName?: string;
     email?: string;
     phone?: string;
+    /** @deprecated Removed in v5 — no column and no reader; `user.avatar` is off the wire (§3.4). */
     avatar?: string;
     customAttributes?: Record<string, any>;
+    /** @deprecated Removed in v5 — in-memory only, so it meant "first identify() this process" (§3.4). */
     createdAt?: number;
+    /** @deprecated Removed in v5 — byte-identical to `createdAt` for any one-identify() app (§3.4). */
     updatedAt?: number;
 }
 type Opts = {
@@ -89,11 +143,18 @@ type Opts = {
     flushIntervalMs?: number;
     endpoint?: string;
     sessionId?: string;
-    userId?: string | null;
+    userId?: string;
     sdkVersion?: string;
     platform?: string;
+    traceLaunchStart?: number;
     deviceInfoHandler?: DeviceInfoHandler;
     networkInfoHandler?: NetworkInfoHandler;
+    store?: Store;
+    beforeSend?: BeforeSend;
+    sessionSampleRate?: number;
+    traceHostAllowlist?: string[];
+    buildId?: string;
+    deprecatedScreenFeeds?: boolean;
 };
 /**
  * Telemetry core: queueing, batching, retries, auto-replay and session/user management.
@@ -109,14 +170,26 @@ export declare class Telemetry {
     private crashHandler?;
     private navigationTracker?;
     screens: ScreenTimingTracker;
+    readonly views: ViewManager;
+    readonly trace: TraceManager;
+    webInteractions?: {
+        start(): void;
+    };
+    webVitals?: {
+        start(): Promise<void>;
+    };
+    private readonly deprecatedScreenFeeds;
     currentScreen?: string;
     private networkInfoHandler;
     private deviceInfoHandler;
+    readonly store: Store;
     private frameDropsHandler?;
     private networkHandler?;
     private memoryHandler?;
     private navigationHandler?;
     private userId?;
+    private deviceIdEphemeral;
+    private deviceIdPromise?;
     private userProfile?;
     private sessionId;
     private sessionStart;
@@ -126,9 +199,46 @@ export declare class Telemetry {
     private breadcrumbs;
     private lastActivity?;
     private sessionSequence;
+    private eventSequence;
     private sessionEventCount;
     private errorCount;
+    private readonly configuredSampleRate;
+    private sampleRate;
+    private sampled;
+    private readonly beforeSend?;
+    /** `app.build_id` (§4.8). Empty string is *not* a build id — it is an unset one. */
+    private readonly buildId?;
+    private hookDropped;
+    private hookFailed;
+    private eventsDropped;
+    private dropReason?;
+    private crashPersistedThrough;
+    private appStartEmitted;
     constructor(opts?: Opts);
+    /**
+     * §4.7 — report a handled error. Accepts `unknown` on purpose: half of real `catch`
+     * blocks receive a string or an axios rejection object, and a consumer should not have
+     * to prove to TypeScript that it is an `Error` before reporting it.
+     *
+     * Emits `app.error`, **never** `app.crash`. There is deliberately no public path to
+     * `app.crash` — a consumer's own code must not be able to manufacture rows in the one
+     * table an unfiltered crash-free rate is read from.
+     *
+     * `source` is SDK-internal (`captureConsole` passes `"console"`); the public wrappers
+     * forward two arguments, so a consumer can only ever produce `"reported"`. Routing the
+     * console path through here rather than through `log()` directly is what keeps the
+     * `error.fatal` rule in one place.
+     */
+    captureError(error: unknown, context?: Record<string, any>, source?: ErrorSource): Promise<void>;
+    /**
+     * Extend the breadcrumb trail without emitting anything. §4.7 demotes `console.warn` to
+     * exactly this — React's dev-mode warnings were the bulk of v3's `app.crash` volume.
+     *
+     * SDK-internal: `public` only so `adapters/crashCapture.ts` can reach it. Not on
+     * `TelemetryBase` and not part of the consumer API — a host app that wants a trail entry
+     * should `log()` an event, which extends the trail anyway.
+     */
+    addBreadcrumb(name: string, data?: Record<string, any>): void;
     trackErrors(crashHandler: CrashHandler, options?: CrashHandlerOptions): void;
     getDeviceInfo(deviceInfoHandler: DeviceInfoHandler): void;
     getNetworkInfo(networkInfoHandler: NetworkInfoHandler): void;
@@ -136,33 +246,126 @@ export declare class Telemetry {
     trackNetworkRequests(networkHandler: NetworkHandler): void;
     trackMemoryUsage(memoryHandler: MemoryHandler): void;
     autoTrackNavigation(navigationHandler?: NavigationHandler): void;
+    /**
+     * The per-session sample roll (§3.6). Never per-event: per-event sampling punches
+     * holes that desynchronise the per-view counters by a random factor per view.
+     *
+     * `Math.random()` is deliberate here where `randomHex` refuses it — this decides one
+     * boolean that dies with the session, not an id that persists forever, and a biased
+     * PRNG costs a fraction of a percent of sample accuracy rather than a permanent
+     * identity collision.
+     */
+    private rollSample;
+    /** §3.3 / §4.7's platform split, from the entry's declared `platform` opt — never a global. */
+    private isNativePlatform;
     private generateSessionId;
     setSessionId(id: string): void;
     getSessionId(): string;
+    /**
+     * Freeze the identity a deferred row must report (§4.6). Read **synchronously at the
+     * moment the thing happened**, so a `log()` that lands after a route change or a session
+     * rotation still books the click where it occurred.
+     */
+    snapshot(at?: number): LogSnapshot;
     /** Collector endpoint, so fetch/XHR adapters can skip self-capturing the SDK's own POST. */
     getEndpoint(): string | undefined;
-    startNewSession(): void;
-    /** Emit session.started for the current session (init / resume). */
-    startSession(): Promise<void>;
-    /** Finalize the current session: journey summary + sdk.error_count, then an immediate flush. */
-    finalizeSession(): Promise<void>;
+    /**
+     * Sampling stays **session-level** (§6.5): an unsampled session injects no header at
+     * all — not a `flags=00` id. Read by the interceptors, which sit outside `log()`'s own
+     * sampled-out early return and so need the decision directly.
+     */
+    isSampled(): boolean;
+    /**
+     * The entry's one call at init (§4.2): resume the durable session when the gap is
+     * inside the idle window, otherwise close the stale one out and start fresh.
+     *
+     * Process death, tab close, hard reload and bfcache restore all land here, and all
+     * four **resume** — which is why a resumed session must not re-emit `session.started`
+     * (§4.1), or `COUNT(session.started)` stops equalling session count.
+     */
+    resumeOrStartSession(): Promise<void>;
+    private hydrateAndAnnounce;
+    /**
+     * `app.start` (§4.3/§6.2): once per process, a **root** of `trace.root_type = launch`,
+     * carrying the launch root minted in the constructor. Idempotent because the web build
+     * re-runs `resumeOrStartSession()` on a bfcache restore, which is a resumed process and
+     * not a new one.
+     */
+    private emitAppStart;
+    /**
+     * Read the durable record and adopt it. Adoption happens even when the session has
+     * expired: `session.finalized` has to ship under the *old* `session.id` and
+     * `session.start_time` before the fresh one takes over.
+     */
+    private hydrateSession;
+    /**
+     * Which boundary, if any, the current session has crossed. Idle is checked first:
+     * when a long session has also gone quiet, the reason it ended is that the user left.
+     *
+     * Inert until `lastActivity` is set, so a bare `new Telemetry()` that never started a
+     * session never rotates one.
+     */
+    private expiryReason;
+    /**
+     * Write the session through the `Store` so the next process can resume it.
+     *
+     * ponytail: one write per event. Web's is a synchronous `localStorage` write; native's
+     * is an AsyncStorage round-trip — debounce here if it ever shows up in a trace.
+     */
+    private persistSession;
+    /** Emit session.started for the current session. */
+    startSession(reason: SessionReason): Promise<void>;
+    /**
+     * Finalize the current session: journey summary + sdk.error_count, then an immediate flush.
+     *
+     * The backend discards `duration_ms` and `event_count` and derives both (§4.2) — they
+     * stay on the wire because the event survives as the carrier for `session.reason` and
+     * `sdk.error_count`, neither of which is derivable. Duration is stamped from
+     * `lastActivity`, never `now`: a lazily-detected rotation must report 2 minutes of use,
+     * not the 6 idle hours that followed it.
+     */
+    finalizeSession(reason: SessionEndReason): Promise<void>;
     /** Begin a fresh session: new id/start, reset per-session counters, emit session.started. */
-    newSession(): Promise<void>;
-    /** Idle/boundary rotation: finalize the old session then start a fresh one (the pair). */
-    rotateSession(): Promise<void>;
+    newSession(reason: SessionReason): Promise<void>;
+    /** Boundary rotation: finalize the old session then start a fresh one (the pair). */
+    rotateSession(reason: SessionEndReason): Promise<void>;
+    /** Truncated at source (§3.2): the collector caps at 255 and we must not be the one over. */
     setUserId(id: string): void;
-    getUserId(): string | undefined | null;
-    generateUserId(): string;
+    getUserId(): string | undefined;
+    /**
+     * The SDK-owned `device.id` (§3.2/§3.3): self-minted, written through the `Store`,
+     * uninstall-scoped, stable across process restarts, and never rotated by login,
+     * logout or a profile clear.
+     *
+     * The platform suffix is the entry's (ios|android|web), not the device-info adapter's:
+     * this id is persisted forever, so it must not depend on a call that can throw on first run.
+     *
+     * `getUniqueId()` is deliberately not used — it already carries two lifetimes on RN
+     * alone (ANDROID_ID survives reinstall, identifierForVendor does not), so one identity
+     * column would mean two things.
+     *
+     * When the Store reports `unavailable` — incognito, a partitioned iframe, ITP
+     * eviction, a full disk — the id lives for one process only and `device.id_ephemeral`
+     * rides the Context block to say so, because that population is otherwise
+     * indistinguishable from real installs and reads as traffic growth.
+     */
+    private getDeviceId;
     /**
      * Set complete user profile information
      */
     setUserProfile(profile: Partial<UserProfile>): void;
     /**
-     * EdgeRum-style identify(): attach host-app identity (name/email/phone) to subsequent
-     * events and emit one `user.profile.update`. The SDK-owned anonymous `user.id` is
-     * preserved — identify never changes it. (#31)
+     * EdgeRum-style identify(): record the host-app profile and emit the one event that
+     * carries it — `user.profile.update` (§4.10, #107). The PII is no longer on the
+     * Context block of every event.
+     *
+     * `userId` is optional and new in v4: the one call that sends a profile should also
+     * set the key that profile attaches to, since `user.id` is consumer-supplied (§3.2)
+     * and an unkeyed profile has nothing to upsert on. Omitting it leaves `user.id`
+     * exactly as it was — identify never mints one.
      */
     identify(profile: {
+        userId?: string;
         name?: string;
         email?: string;
         phone?: string;
@@ -205,7 +408,30 @@ export declare class Telemetry {
      * Log a named event. Keeps existing signature compatibility.
      * Automatically attaches userId and sessionId to every queued event.
      */
-    log(name: string, data?: Record<string, any>): Promise<void>;
+    log(name: string, data?: Record<string, any>, snapshot?: LogSnapshot): Promise<void>;
+    /**
+     * The crash path (§2 / §9.4): persist the whole queue, then send **one** batch reordered
+     * so the crash rides in it. Not a drain — a dying process gets one round trip.
+     *
+     * ⚠ The web/native asymmetry is real and is not fixed here. On web the `Store` is
+     * synchronous `localStorage`, so the persist has *landed* by the time the next line runs
+     * and the loss window closes. On native it is an AsyncStorage round-trip that a SIGKILL
+     * can outrun, so the window only narrows. Awaiting harder does not change that; the
+     * asymmetry is the `Store` port's whole point (`core/store.ts`).
+     *
+     * The persisted copy is a safety copy, not a handoff: the queue is left intact, because
+     * an `app.crash` is not always fatal — `window.onerror` fires and the page keeps running
+     * — and the process usually lives on. A successful send therefore
+     * leaves a duplicate on disk to replay next launch — which is what `event.sequence` and
+     * the backend's `(session_id, event_sequence)` dedup exist for (§2.4).
+     *
+     * *One* duplicate. Each row is written at most once by this path, watermarked on
+     * `event.sequence`: a chatty app crash-flushes often, and re-persisting the whole queue
+     * each time would fill the store with copies of
+     * its own backlog and book `store_full` drops that are not loss — corrupting the very
+     * counter this change adds.
+     */
+    private flushCrash;
     /**
      * Build the v3 Context block that rides on every event AND metric: the flattened
      * device/network snapshot, the caller's data, identity + session + sdk fields, and the
@@ -219,15 +445,59 @@ export declare class Telemetry {
      * (memory/frames) must not keep a session alive and defeat the 30-min idle rotation.
      */
     logMetric(metricName: string, value: number, data?: Record<string, any>): Promise<void>;
+    /**
+     * The single enqueue point: neither the sample decision nor `beforeSend` can be
+     * bypassed by a future emit path, and the hook runs *before* the queue — which is
+     * what keeps scrubbed fields off disk when a send fails and the batch is persisted.
+     *
+     * The sample check is repeated by log()/logMetric() ahead of `collectContext()`, so
+     * a sampled-out session does no work per event; this one is the backstop that makes
+     * the guarantee structural rather than a convention two call sites happen to follow.
+     *
+     * The two counters are separate on purpose: "my volume is down 40%" has to
+     * distinguish *my rule is too broad* from *my rule is crashing*, and one merged
+     * counter answers neither.
+     */
+    private enqueue;
+    /**
+     * Hold the in-memory queue at its cap (§9.4), booking what it costs.
+     *
+     * The count lands on the *next* event's Context block, not this one's — `collectContext()`
+     * has already run by the time we get here. That is §3.7's stated behaviour, not a bug.
+     */
+    private capQueue;
+    /**
+     * Book dropped rows against the monotonic counter and the reason that shipped last.
+     * Takes `Sender.onFailure`'s return shape as-is — a sender with no cap returns nothing.
+     */
+    private recordDrop;
     private flattenWithPrefix;
     /**
      * Explicit metric helper (optional convenience) — routes through the v3 metric path.
      */
     recordMetric(name: string, value: number, data?: Record<string, any>): Promise<void>;
     flush(): Promise<void>;
+    /**
+     * Book an acknowledged (2xx) batch. `session.sequence` orders a session's batches (#29),
+     * and it is persisted because a resumed session restarting at 0 would emit duplicate
+     * (session.id, session.sequence) pairs and stop ordering anything (#92).
+     */
+    private ackBatch;
     getQueue(): TelemetryEvent[];
     shutdown(): Promise<void>;
     getEventCount(): number;
-    recordRouteChange(from: string, to: string): void | undefined;
+    /**
+     * A route change: the view boundary (§4.5) plus, on native only, the two deprecated
+     * feeds (§4.11). v3's two native screen paths were disjoint — `attachNavigation` never
+     * touched `inst.screens`, so a React Navigation consumer emitted `navigation` on every
+     * route change and never a single `screen.duration`. Unifying them here is what fixes
+     * that, which is why a *deprecated* event starts firing where it never has.
+     */
+    recordRouteChange(from: string, to: string): Promise<void>;
+    /**
+     * Feed the name ladder (§4.5.1). Rungs 1 and 2 arrive unnormalized; rung 3's caller
+     * normalizes before calling. Whether this re-stamps the current view or mints a
+     * successor is the ladder's decision, not the caller's.
+     */
+    enterView(name: string, source: ViewNameSource): Promise<void>;
 }
-export {};

package/dist/src/core/userProfile.d.ts

@@ -0,0 +1,12 @@
+import { UserProfile } from './telemetry';
+export declare const NAME_CAP = 255;
+export declare const EMAIL_CAP = 255;
+export declare const PHONE_CAP = 50;
+export declare const CUSTOM_MAX_KEYS = 64;
+export declare const CUSTOM_KEY_CAP = 64;
+export declare const CUSTOM_VALUE_CAP = 255;
+/**
+ * The wire keys for `user.profile.update`. `user.id` is not here — it rides the Context
+ * block, where it is present on this event by construction.
+ */
+export declare function buildProfileAttributes(profile: UserProfile | undefined): Record<string, any>;

package/dist/src/core/utils/json.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `JSON.stringify` that returns `undefined` instead of throwing — a cycle, a `toJSON` that
+ * threw, a `BigInt`. Shared by `user.custom.*`'s bag rule (§4.10) and `flattenWithPrefix`'s
+ * depth cap: both exist so a bad consumer payload is a dropped key rather than an exception
+ * raised inside the SDK, in the host app's own call stack.
+ */
+export declare function stringifyOrDrop(value: unknown): string | undefined;

package/dist/src/core/utils/uuid.d.ts

@@ -1,2 +1,11 @@
-export declare function generateId(): string;
+/**
+ * Wire-contract ids carry a 16-hex-char (64-bit) random segment (§3.3) — except W3C
+ * `trace.id`, which is 32 (§6.1). The length is the caller's; the entropy source is not.
+ *
+ * Entropy is `crypto.getRandomValues`, not `Math.random()` (#91): `device.id` is now
+ * persisted, so a collision is *permanent* — two handsets merge into one device row and
+ * one rate-limit bucket forever — where a session collision was transient. RN has no
+ * WebCrypto of its own; the native entry imports `react-native-get-random-values`
+ * (already a dependency) to install it before the first id is minted.
+ */
 export declare function randomHex(length?: number): string;

package/dist/src/createTelemetry.native.d.ts

@@ -1,4 +1,6 @@
 import { TelemetryNative } from './index.native';
+import { Store } from './core/store';
+import { BeforeSend } from './core/beforeSend';
 export type TelemetryOpts = {
     apiKey: string;
     sender?: any;
@@ -7,6 +9,11 @@ export type TelemetryOpts = {
     endpoint?: string;
     captureConsole?: boolean;
     debug?: boolean;
+    store?: Store;
+    beforeSend?: BeforeSend;
+    sessionSampleRate?: number;
+    traceHostAllowlist?: string[];
+    buildId?: string;
 };
 export declare function assertApiKey(apiKey?: string): void;
 /**

package/dist/src/createTelemetry.web.d.ts

@@ -1,4 +1,6 @@
 import { TelemetryWeb } from './index.web';
+import { SyncStore } from './core/store';
+import { BeforeSend } from './core/beforeSend';
 export type TelemetryOpts = {
     apiKey: string;
     sender?: any;
@@ -7,6 +9,11 @@ export type TelemetryOpts = {
     endpoint?: string;
     captureConsole?: boolean;
     debug?: boolean;
+    store?: SyncStore;
+    beforeSend?: BeforeSend;
+    sessionSampleRate?: number;
+    traceHostAllowlist?: string[];
+    buildId?: string;
 };
 export declare function assertApiKey(apiKey?: string): void;
 /**

package/dist/src/index.base.d.ts

@@ -1,10 +1,14 @@
 type ProfileInput = {
     userId?: string;
+    /** @deprecated Removed in v5 — use `identify({ name })`. */
     fullName?: string;
+    /** @deprecated Removed in v5 — never reaches the wire (§3.4). */
     firstName?: string;
+    /** @deprecated Removed in v5 — never reaches the wire (§3.4). */
     lastName?: string;
     email?: string;
     phone?: string;
+    /** @deprecated Removed in v5 — never reaches the wire (§3.4). */
     avatar?: string;
     customAttributes?: Record<string, any>;
 };
@@ -13,11 +17,22 @@ export declare abstract class TelemetryBase {
     log(event: string, data?: Record<string, any>): Promise<any>;
     flush(): Promise<any>;
     shutdown(): Promise<any>;
+    /**
+     * React Navigation → rung 2 of the name ladder, on **both** builds (§4.5.1, #96).
+     * `getCurrentRoute()` is a navigation-tree API that works identically on RN-Web, so a
+     * consumer wires navigation once and gets the same `view.name` on web and native.
+     */
+    attachNavigation(navigationRef: any): Promise<void>;
+    /**
+     * §4.7 — report a handled error as `app.error`. Accepts `unknown`, so a `catch` block
+     * that received a string or an axios rejection object needs no narrowing first.
+     * There is no public path to `app.crash`, by design (#100).
+     */
+    captureError(error: unknown, context?: Record<string, any>): Promise<any>;
     trackErrors(options?: {
         captureConsole?: boolean;
     }): Promise<any>;
     setUserId(id: string): Promise<void>;
-    generateUserId(): Promise<any>;
     setUserProfile(profile: ProfileInput): Promise<void>;
     setUserDetails(details: ProfileInput): Promise<void>;
     updateUserProfile(updates: ProfileInput): Promise<void>;
@@ -26,6 +41,7 @@ export declare abstract class TelemetryBase {
     setUserName(fullName: string, firstName?: string, lastName?: string): Promise<void>;
     setUserContact(email?: string, phone?: string): Promise<void>;
     identify(profile: {
+        userId?: string;
         name?: string;
         email?: string;
         phone?: string;

package/dist/src/index.native.d.ts

@@ -1,6 +1,19 @@
 import { TelemetryBase } from './index.base';
+import { Store } from './core/store';
+import { BeforeSend } from './core/beforeSend';
 export { createTelemetry, type TelemetryOpts } from './createTelemetry.native';
+export type { Store, SyncStore, AsyncStore, StoreRead, StoreWrite } from './core/store';
+export { memoryStore, type MemoryStoreOpts } from './core/memoryStore';
+export type { BeforeSend } from './core/beforeSend';
 export declare class TelemetryNative extends TelemetryBase {
+    /** ≥3 named taps in a 1000 ms window, keyed on the name — see `trackTap`. */
+    private readonly tapRage;
+    /**
+     * The resolved core, once `instancePromise` settles. `trackTap` is the one public method that
+     * cannot afford an `await` before it reads the world: the host's own press handler
+     * navigates on the very next line (§4.6's mint/emit split).
+     */
+    private resolved?;
     constructor(opts?: {
         apiKey?: string;
         sender?: any;
@@ -9,20 +22,44 @@ export declare class TelemetryNative extends TelemetryBase {
         endpoint?: string;
         captureConsole?: boolean;
         debug?: boolean;
+        store?: Store;
+        beforeSend?: BeforeSend;
+        sessionSampleRate?: number;
+        traceHostAllowlist?: string[];
+        buildId?: string;
     });
-    private startSessionOnInit;
-    private attachAppState;
     attachAppLifecycle(): Promise<void>;
     getDeviceInfo(): Promise<any>;
     getNetworkInfo(): Promise<any>;
     trackFrameDrops(): Promise<any>;
     trackNetworkRequests(): Promise<any>;
     trackMemoryUsage(): Promise<any>;
-    screenStart(name: string): Promise<void>;
-    screenEnd(name: string): Promise<void>;
-    trackRoute(from: string, to: string): Promise<void>;
-    interactionProps(): Promise<{
-        onStartShouldSetResponderCapture: () => boolean;
-    }>;
-    attachNavigation(navigationRef: any): Promise<void>;
+    screenStart(name: string): Promise<any>;
+    screenEnd(name: string): Promise<any>;
+    trackRoute(from: string, to: string): Promise<any>;
+    /**
+     * §4.6's native producer, explicit-only (#103). `interactionProps()` is gone with
+     * `user.interaction` (#102): it sat on the consumer's **root** `<View>`, where
+     * `PressEvent.nativeEvent.target` is a node tag number with no public API resolving it,
+     * so it could not tell a tap on a button from a tap on padding and every row it emitted
+     * was un-nameable. There is no role model to gate on and no DOM to derive from, so
+     * anything auto-derived here would be either wrong or a PII leak.
+     *
+     * `name` is web's rung 1 — explicit author intent — so it ships **unnormalized and
+     * uncapped**, and `ui.name_source` has exactly **two** values: `edge_action`, or `none`
+     * for a blank name, whose `ui.target` is `unnamed`. **`surface` never appears**: it only
+     * means something where role-less elements exist.
+     *
+     * ⚠ **The mint/emit split.** The row's `timestamp`, `view.id`, `view.name` and
+     * `session.id` are snapshotted **here, synchronously**, because the host's press handler
+     * navigates on the next line and the emit rides a promise. Stamping emit time would
+     * attribute a navigating tap to **the view it opened**, inverting every "which screen
+     * frustrates users" query. Before `instancePromise` settles there is no core to snapshot
+     * from, so a tap that early falls back to emit-time identity — the launch view either
+     * way.
+     *
+     * ⚠ **`ui.dead` is absent on every native row**, never `false`: with no DOM there is no
+     * mutation signal, so any dead-click *rate* must filter to the web build.
+     */
+    trackTap(name: string): Promise<any>;
 }