@nathanclaire/edge-telemetry-sdk 3.0.0 → 4.0.0

package/dist/src/adapters/viewport.d.ts

@@ -0,0 +1,15 @@
+/** §3.3 types all four never-null, so this returns all four or none of it is honest. */
+export type ViewportKeys = {
+    screen_density: number;
+    screen_width_px: number;
+    screen_height_px: number;
+    orientation: Orientation;
+};
+/** §3.3's cardinality is 2. A square window reports `portrait`. */
+export type Orientation = "portrait" | "landscape";
+/**
+ * @param cssWidth  logical width — dp on native, CSS px on web
+ * @param cssHeight logical height, same units
+ * @param density   the pixel ratio, so `cssWidth * density` is physical pixels on both
+ */
+export declare function viewportKeys(cssWidth: number, cssHeight: number, density: number): ViewportKeys;

package/dist/src/adapters/web/interactionWeb.web.d.ts

@@ -0,0 +1,36 @@
+import { Telemetry } from '../../core/telemetry';
+export declare class InteractionTrackerWeb {
+    private telemetry;
+    private started;
+    private readonly rage;
+    /**
+     * Monotonic aliveness counter. A DOM mutation, a request start or a view mint bumps it;
+     * a click that sees the same value a window later saw nothing happen. A counter rather
+     * than a timestamp so the comparison needs no clock and cannot be fooled by a clock that
+     * moved backwards.
+     */
+    private aliveTick;
+    private readonly pending;
+    private observer?;
+    constructor(telemetry: Telemetry);
+    start(): void;
+    private onClick;
+    /** Arm one dead-click window and emit when it closes. */
+    private watchForDeath;
+    /**
+     * Emit every open window **now**, with `ui.dead` **omitted** — the window never closed,
+     * so it was not evaluated, which is exactly what its absence means (§4.6). Inventing a
+     * verdict from a partial window is the false accusation the key is built to avoid.
+     */
+    private drainPending;
+    private emit;
+    private canObserve;
+    /**
+     * Observed only while a window is open. A permanently-connected whole-document observer
+     * is a real cost on a busy React tree, and there is nothing to answer between clicks.
+     * `attributes: true` because §4.6 counts an attribute-only change as alive — a CSS class
+     * flip is a response.
+     */
+    private connectObserver;
+    private disconnectObserver;
+}

package/dist/src/adapters/web/interceptFetchWeb.web.d.ts

@@ -1,14 +1,9 @@
 import { Telemetry } from '../../core/telemetry';
 /**
- * NetworkTrackerWeb intercepts all HTTP requests made through
- * `window.fetch` and `XMLHttpRequest` in a browser environment.
+ * NetworkTrackerWeb intercepts HTTP made through `window.fetch` and `XMLHttpRequest`.
  *
- * It logs detailed telemetry data such as request URL, HTTP method,
- * response status, request and response body sizes, request duration,
- * and error information, if any.
- *
- * This class should be instantiated once and the `start` method called
- * during application initialization to begin interception.
+ * Both are patched here, unlike native: browser `fetch` is a native implementation, not
+ * XHR-backed, so the two are genuinely separate channels and neither double-counts (§4.4).
  */
 export declare class NetworkTrackerWeb {
     private telemetry;
@@ -20,9 +15,6 @@ export declare class NetworkTrackerWeb {
     /**
      * Starts intercepting HTTP requests made through `fetch` and `XMLHttpRequest`.
      *
-     * This method patches the global `fetch` function and `XMLHttpRequest` methods
-     * `open` and `send` to gather telemetry and log it asynchronously.
-     *
      * @returns A Promise that resolves immediately once interception is setup.
      */
     start(): Promise<void>;

package/dist/src/adapters/web/navigationWeb.web.d.ts

@@ -26,4 +26,14 @@ export declare class NavigationTrackerWeb {
      * to detect route changes triggered by browser controls.
      */
     private listenPopState;
+    /**
+     * One route change: the existing `navigation` row, then rung 3 of the name ladder
+     * (§4.5.1) — the *last* rung, so an `attachNavigation` consumer's `route.name` outranks
+     * it whichever arrives first.
+     *
+     * Normalized by §4.4.1's rule, and the query string is dropped: there is no `view.url`
+     * and no raw path on the wire, because the identifier lives in the path
+     * (`/accounts/GB29-NWBK-…`) and query-stripping alone would not have addressed that.
+     */
+    private handleChange;
 }

package/dist/src/adapters/web/runtimeReady.web.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves once the marker is known — `undefined` when the platform has none to give, which
+ * releases the gate rather than leaving every launch reporting `abandoned` (§4.5.2).
+ */
+export declare function runtimeReadyAt(): Promise<number | undefined>;

package/dist/src/adapters/web/store.web.d.ts

@@ -0,0 +1,12 @@
+import { SyncStore } from '../../core/store';
+/**
+ * localStorage-backed Store for the web build (#89). Reads are synchronous, and
+ * that is the point: state written here is durable before the next line runs, so
+ * the crash-loss window closes rather than narrows.
+ *
+ * Every access is guarded. Touching `localStorage` throws — not returns null — in
+ * incognito with cookies blocked, in a partitioned third-party iframe, and once
+ * quota is exhausted; and the identifier isn't declared at all outside a browser.
+ * All of those are `unavailable`, never an exception out of the SDK.
+ */
+export declare function webStore(): SyncStore;

package/dist/src/adapters/web/webVitals.web.d.ts

@@ -0,0 +1,49 @@
+import { ViewLoadType } from '../viewManager';
+/**
+ * All this tracker needs of core. Structural, so it is testable without a `Telemetry`.
+ */
+type VitalsEmitter = {
+    logMetric(name: string, value: number, data?: Record<string, any>): unknown;
+    views: {
+        onBoundary(fn: (successorLoadType: ViewLoadType) => unknown): () => void;
+    };
+};
+export declare class WebVitalsTracker {
+    private telemetry;
+    /** The running values, held rather than emitted — see `start()`. */
+    private held;
+    /** What each held name last shipped, so an unchanged value does not re-ship at every hide. */
+    private emitted;
+    private started;
+    constructor(telemetry: VitalsEmitter);
+    /**
+     * Idempotent: a second call must not double-subscribe and double every vital row.
+     *
+     * LCP, FCP and TTFB fire once on the initial load, so they emit straight from the callback.
+     *
+     * ⚠ **CLS and INP subscribe with `reportAllChanges: true` as a running-value subscription,
+     * not an emission trigger.** The latest value is held in memory and shipped at the
+     * `ViewManager`'s background boundary — the library's default page-hide report loses both
+     * on a closed tab, because that report races the document's own teardown.
+     *
+     * ⚠ **All five are page-load-scoped, not view-scoped.** `LCP`, `FCP` and `TTFB` physically
+     * cannot recur on a soft navigation, so `view.id` on a vital row is always the *initial*
+     * view's. It is a real join key, it is just not "the view this happened in" for CLS and INP:
+     * `GROUP BY view.name` over vitals reads **"by entry point"**. Documented, not engineered
+     * around — view-scoping would need the Chrome-only Soft Navigations API.
+     */
+    start(): Promise<void>;
+    /**
+     * Awaited inside `beginView` while the departing view is still current, so the rows carry
+     * the view they were accumulated under. A name whose running value has not moved since its
+     * last row is skipped — a tab hidden twice with no shifts in between is not two CLS
+     * samples, and the library's own report has the same no-delta-no-report property.
+     *
+     * Keying on `value` alone is exact for both held vitals, not a shortcut: CLS is cumulative,
+     * so *any* shift moves it, and INP only changes when a worse interaction happens. An
+     * unchanged value therefore means the attribution is unchanged too.
+     */
+    private drain;
+    private emit;
+}
+export {};

package/dist/src/adapters/webSender.d.ts

@@ -1,3 +1,3 @@
 import { Sender } from '../core/telemetry';
-export declare function webSender(endpoint?: string, apiKey?: string, retryCount?: number): Sender;
-export declare function replayFailedWeb(endpoint?: string, apiKey?: string, retryCount?: number): Promise<void> | undefined;
+import { SyncStore } from '../core/store';
+export declare function webSender(endpoint?: string, apiKey?: string, store?: SyncStore, retryCount?: number): Sender;

package/dist/src/adapters/webVitals.d.ts

@@ -0,0 +1,25 @@
+/** The five names. All are already on `ALLOWED_NAMES`, and all ride the **metric** path. */
+export type VitalName = "LCP" | "FCP" | "CLS" | "INP" | "TTFB";
+/**
+ * Structurally typed against `web-vitals/attribution`'s metric, so this module compiles and
+ * tests without the library and cannot pull it into a shared import graph.
+ */
+export type VitalMetric = {
+    name: string;
+    value: number;
+    rating: string;
+    navigationType: string;
+    attribution?: Record<string, any>;
+};
+/**
+ * Build a vital row's attribute bag: four shared keys plus the per-vital ones (§5.3).
+ *
+ * ⚠ **LCP's four phases sum exactly to `value`** — that is the library's own guarantee and a
+ * testable claim, which is why `lcp.time_to_first_byte` deliberately duplicates the `TTFB` row
+ * rather than forcing a cross-row join to decompose one number.
+ *
+ * Everything the library did not produce is **omitted**, never nulled: `vital.target` and
+ * `vital.load_state` are absent on the vitals that have no element and no load state, and the
+ * SDK's absent-means-nothing discipline is what tells that apart from a zero.
+ */
+export declare function vitalAttributes(m: VitalMetric): Record<string, any>;

package/dist/src/adapters/xhrIntercept.d.ts

@@ -0,0 +1,53 @@
+import { Telemetry, LogSnapshot } from '../core/telemetry';
+import { TraceAttributes } from './traceManager';
+declare const PATCHED = "__edgeTelemetryXhrPatched";
+interface PendingRequest {
+    method: string;
+    url: string;
+    start: number;
+    body?: unknown;
+    /**
+     * Closes this request's contribution to §4.5.2's network settle. Bound at `send()` to the
+     * view that was live *then*, so a response landing after a route change belongs to the view
+     * it started in and does not hold the arriving one open.
+     */
+    settled?: (endedAt?: number) => void;
+    /**
+     * §6.3's Tier 1 keys, captured at `send()` so the parent is the root live *then* and
+     * `span.start_time` is the send. Called at `loadend` to stamp `span.duration_ms` off
+     * the same pair of timestamps `http.duration_ms` uses.
+     */
+    span?: (endedAt: number) => TraceAttributes;
+    /**
+     * §6.4's ownership flag: the consumer's own `traceparent`, recorded **at their write
+     * time** in the `setRequestHeader` patch. Never inferred from the value's shape — an
+     * SDK-minted and a consumer-minted header are byte-identical by construction — and reset
+     * by `open()`, which per spec clears the author request headers anyway.
+     */
+    consumerTraceparent?: string;
+    /**
+     * §3.1's attribution freeze: `session.id`, `session.start_time` and `view.id` as they
+     * were at `send()`. The 4-hour cap can rotate a session *while this request is in
+     * flight*, which would otherwise put S1's trace on an S2 row. No `at` — the row still
+     * reports its completion timestamp (§4.4).
+     */
+    snap?: LogSnapshot;
+}
+interface PatchedXhr extends XMLHttpRequest {
+    _telemetryRequest?: PendingRequest;
+    _telemetryListening?: boolean;
+}
+type XhrCtor = {
+    prototype: PatchedXhr;
+    [PATCHED]?: boolean;
+};
+/**
+ * Patches an `XMLHttpRequest` prototype so every completed request emits one `http.request`.
+ * Shared because the native build is XHR-*only* (§4.4: RN's `global.fetch` is XHR underneath,
+ * so patching both emits two events per call) while the web build patches XHR alongside its
+ * own `fetch` patch — same emit rules, two different sets of callers.
+ *
+ * @returns the unpatch, so `stop()` can restore the prototype.
+ */
+export declare function patchXHR(telemetry: Telemetry, xhr: XhrCtor): () => void;
+export {};

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

@@ -0,0 +1,20 @@
+import { TelemetryEvent } from './telemetry';
+/**
+ * The consumer's scrubbing hook (§3.6). One event, **synchronous**, run at **enqueue**.
+ *
+ * Enqueue and not flush: a failed send persists the batch through the `Store`, so a
+ * flush-time hook would let unscrubbed PII hit disk — and on native that disk outlives
+ * the process. Synchronous because `app.crash` flushes during teardown and a
+ * Promise-returning hook would put a host `await` in a dying app's path.
+ */
+export type BeforeSend = (event: TelemetryEvent) => TelemetryEvent | null;
+export type HookOutcome = {
+    kind: "kept";
+    event: TelemetryEvent;
+} | {
+    kind: "dropped";
+} | {
+    kind: "failed";
+};
+/** Run the hook and enforce the tiers on what comes back. */
+export declare function applyBeforeSend(original: TelemetryEvent, hook: BeforeSend): HookOutcome;

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

@@ -4,3 +4,10 @@ export declare const debug: {
     warn: (...args: any[]) => void;
     error: (...args: any[]) => void;
 };
+/**
+ * `__DEV__` on RN, `NODE_ENV` elsewhere. Dev-only *config* diagnostics (a malformed
+ * allowlist, the `Error.stackTraceLimit` advisory) surface through this rather than the
+ * `debug` gate above: they are wiring mistakes the consumer has to see while building,
+ * and `debug: true` is exactly what a consumer with a wiring mistake has not set.
+ */
+export declare function isDev(): boolean;

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

@@ -0,0 +1,23 @@
+import { AsyncStore, SyncStore } from './store';
+export type MemoryStoreOpts = {
+    /** Mirror the native build's Promise-returning shape instead of the web build's. */
+    async?: boolean;
+    /** Behave like incognito / a full disk: every call reports `unavailable`. */
+    unavailable?: boolean;
+    /** Pre-seeded contents. */
+    seed?: Record<string, string>;
+};
+/**
+ * In-memory Store (#89). A production-shaped seam that tests get to use, not a
+ * test-only affordance — it ships, and it is the right injection for a consumer
+ * that wants telemetry state to die with the process.
+ *
+ * Configurable to either build's shape so the sync/async asymmetry can be tested
+ * deliberately rather than assumed away.
+ */
+export declare function memoryStore(opts: MemoryStoreOpts & {
+    async: true;
+}): AsyncStore;
+export declare function memoryStore(opts?: MemoryStoreOpts & {
+    async?: false;
+}): SyncStore;

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

@@ -0,0 +1,41 @@
+/**
+ * Reading storage has three outcomes, not two.
+ *
+ * `unavailable` is a first-class path, not an error: incognito, partitioned iframes,
+ * Safari ITP eviction and full disks all land here, and they are the population
+ * `device.id_ephemeral` reports (wire contract §3.2). It is deliberately distinct
+ * from `miss` — "storage said no" is not "storage had nothing stored".
+ */
+export type StoreRead = {
+    status: "hit";
+    value: string;
+} | {
+    status: "miss";
+} | {
+    status: "unavailable";
+};
+/** Writes and removes carry the same unavailable path — quota exceeded, disk full. */
+export type StoreWrite = {
+    status: "ok";
+} | {
+    status: "unavailable";
+};
+/** Storage whose reads have completed by the time they return. The web build. */
+export interface SyncStore {
+    readonly sync: true;
+    get(key: string): StoreRead;
+    set(key: string, value: string): StoreWrite;
+    remove(key: string): StoreWrite;
+}
+/** Storage whose reads settle later. The native build. */
+export interface AsyncStore {
+    readonly sync: false;
+    get(key: string): Promise<StoreRead>;
+    set(key: string, value: string): Promise<StoreWrite>;
+    remove(key: string): Promise<StoreWrite>;
+}
+/**
+ * Either build. Shared core takes this; a caller that needs the synchronous
+ * guarantee narrows with `if (store.sync)` or takes `SyncStore` outright.
+ */
+export type Store = SyncStore | AsyncStore;