tuft-telemetry 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# `tuft-telemetry`
+
+An Expo-first flight recorder for coding agents. It owns Expo context, a durable journal, installation identity, lifecycle/network state, JavaScript error capture, route breadcrumbs, delivery, and cleanup.
+
+## Quick start
+
+The `endpoint` is the collector's base machine URL. The SDK appends `/v1/events`. The bearer token authorizes exactly one stream; the app never selects or sends a stream ID.
+
+```ts
+import { createExpoTelemetry } from "tuft-telemetry/expo";
+
+export const telemetry = createExpoTelemetry({
+  endpoint: process.env.EXPO_PUBLIC_TUFT_TELEMETRY_URL!,
+  token: process.env.EXPO_PUBLIC_TUFT_TELEMETRY_WRITE_TOKEN!,
+});
+```
+
+Initialization persists an installation ID, emits `app.launch` with build/update/device context, installs lifecycle/network listeners, chains the React Native global error handler, and tracks unhandled rejections. `shutdown()` restores installed handlers/listeners.
+
+Expo Router is an optional entry point so non-Router apps still bundle:
+
+```ts
+import { installExpoRouterTelemetry } from "tuft-telemetry/expo-router";
+
+export const removeRouterTelemetry = installExpoRouterTelemetry(telemetry);
+```
+
+Instrument causal phases rather than every function call:
+
+```ts
+const span = telemetry.startSpan("message.open", { source: "inbox" });
+try {
+  span.event("cache.checked", { hit });
+  const message = await loadMessage();
+  span.end({ bodyBytes: message.bodyBytes });
+} catch (error) {
+  span.fail(error, { phase: "network" });
+  throw error;
+}
+```
+
+Lower-level constructors and adapters remain exported for tests and custom integrations. See [the protocol](docs/protocol.md), [privacy model](docs/privacy.md), and [limitations](docs/limitations.md).

package/dist/expo-adapters.d.ts

@@ -0,0 +1,107 @@
+import { type Journal, type TelemetryClient } from "./index.js";
+export interface ExpoFile {
+    exists: boolean;
+    text(): Promise<string>;
+    write(data: string): void;
+    delete(): void;
+    move(destination: ExpoFile): Promise<void>;
+}
+export type ExpoFileFactory = (name: string) => ExpoFile;
+export declare function createExpoFileJournal(file: ExpoFileFactory): Journal;
+export declare function loadOrCreateInstallationId(metadata: {
+    exists: boolean;
+    textSync(): string;
+    write(data: string): void;
+}, generate: () => string): string;
+type Subscription = {
+    remove(): void;
+};
+export interface AppStateLike {
+    currentState: string;
+    addEventListener(event: "change", listener: (state: string) => void): Subscription;
+}
+export interface NetworkLike {
+    getNetworkStateAsync(): Promise<{
+        type?: string;
+        isConnected?: boolean;
+        isInternetReachable?: boolean;
+    }>;
+    addNetworkStateListener(listener: (state: {
+        type?: string;
+        isConnected?: boolean;
+        isInternetReachable?: boolean;
+    }) => void): Subscription;
+}
+export declare function installExpoLifecycle(client: TelemetryClient, modules: {
+    appState: AppStateLike;
+    network?: NetworkLike;
+}): () => void;
+export declare function collectExpoContext(modules: {
+    application?: {
+        applicationId?: string | null;
+        nativeApplicationVersion?: string | null;
+        nativeBuildVersion?: string | null;
+    };
+    updates?: {
+        updateId?: string | null;
+        runtimeVersion?: string | null;
+        channel?: string | null;
+        createdAt?: Date | null;
+        isEmbeddedLaunch?: boolean | null;
+        isEmergencyLaunch?: boolean | null;
+    };
+    device?: {
+        isDevice?: boolean;
+        modelName?: string | null;
+        osName?: string | null;
+        osVersion?: string | null;
+    };
+    platform?: string;
+}): {
+    app: {
+        applicationId: string | undefined;
+        version: string | undefined;
+        buildVersion: string | undefined;
+    };
+    runtime: {
+        platform: string | undefined;
+        updateId: string | undefined;
+        runtimeVersion: string | undefined;
+        updateChannel: string | undefined;
+        updateCreatedAt: string | undefined;
+        isEmbeddedUpdate: boolean | undefined;
+        isEmergencyLaunch: boolean | undefined;
+    };
+    device: {
+        isDevice: boolean | undefined;
+        model: string | undefined;
+        osName: string | undefined;
+        osVersion: string | undefined;
+    };
+};
+type ErrorUtilsLike = {
+    getGlobalHandler(): ((error: Error, fatal?: boolean) => void) | undefined;
+    setGlobalHandler(handler: (error: Error, fatal?: boolean) => void): void;
+};
+type RejectionTrackingOptions = {
+    allRejections: boolean;
+    onUnhandled(id: number, error: unknown): void;
+};
+export type RejectionTrackingLike = {
+    enable(options: RejectionTrackingOptions): void;
+    disable(): void;
+};
+type ErrorTarget = typeof globalThis & {
+    ErrorUtils?: ErrorUtilsLike;
+    HermesInternal?: {
+        enablePromiseRejectionTracker?(options: RejectionTrackingOptions): void;
+    };
+};
+export declare function installAutomaticErrors(client: TelemetryClient, target?: ErrorTarget, rejectionTracking?: RejectionTrackingLike): () => void;
+export type RouterLike = {
+    push?: (href: unknown, options?: unknown) => unknown;
+    replace?: (href: unknown, options?: unknown) => unknown;
+    navigate?: (href: unknown, options?: unknown) => unknown;
+};
+export declare function installExpoRouterBreadcrumbs(client: TelemetryClient, router?: RouterLike): () => void;
+export {};

package/dist/expo-adapters.js

@@ -0,0 +1,161 @@
+// @ref LLP 0081#one-call-expo-sdk-boundary
+import { normalizeRoute, } from "./index.js";
+export function createExpoFileJournal(file) {
+    return {
+        async load() {
+            for (const candidate of [file("events-v1.json"), file("events-v1.tmp")]) {
+                if (!candidate.exists)
+                    continue;
+                try {
+                    const value = JSON.parse(await candidate.text());
+                    if (Array.isArray(value))
+                        return value;
+                }
+                catch { }
+            }
+            return [];
+        },
+        async replace(records) {
+            const primary = file("events-v1.json");
+            const temporary = file("events-v1.tmp");
+            if (temporary.exists)
+                temporary.delete();
+            temporary.write(JSON.stringify(records));
+            if (primary.exists)
+                primary.delete();
+            await temporary.move(primary);
+        },
+    };
+}
+export function loadOrCreateInstallationId(metadata, generate) {
+    if (metadata.exists) {
+        try {
+            const parsed = JSON.parse(metadata.textSync());
+            if (typeof parsed.installationId === "string" && parsed.installationId)
+                return parsed.installationId;
+        }
+        catch { }
+    }
+    const installationId = generate();
+    metadata.write(JSON.stringify({ schemaVersion: 1, installationId }));
+    return installationId;
+}
+export function installExpoLifecycle(client, modules) {
+    let lastAppState = modules.appState.currentState, online = true;
+    const app = modules.appState.addEventListener("change", (next) => {
+        if (next === lastAppState)
+            return;
+        client.breadcrumb("app.state.changed", { from: lastAppState, to: next });
+        lastAppState = next;
+        if (next === "background")
+            void client.flush({ timeoutMs: 1_500 });
+        if (next === "active" && online)
+            void client.flush();
+    });
+    let network;
+    if (modules.network) {
+        network = modules.network.addNetworkStateListener((state) => {
+            const next = state.isConnected !== false;
+            client.breadcrumb("network.state.changed", {
+                type: state.type ?? null,
+                connected: state.isConnected ?? null,
+                internetReachable: state.isInternetReachable ?? null,
+            });
+            client.setOnline(next);
+            online = next;
+        });
+        void modules.network.getNetworkStateAsync().then((initial) => {
+            online = initial.isConnected !== false;
+            client.setOnline(online);
+        }, () => { });
+    }
+    return () => {
+        app.remove();
+        network?.remove();
+    };
+}
+export function collectExpoContext(modules) {
+    return {
+        app: {
+            applicationId: modules.application?.applicationId ?? undefined,
+            version: modules.application?.nativeApplicationVersion ?? undefined,
+            buildVersion: modules.application?.nativeBuildVersion ?? undefined,
+        },
+        runtime: {
+            platform: modules.platform,
+            updateId: modules.updates?.updateId ?? undefined,
+            runtimeVersion: modules.updates?.runtimeVersion ?? undefined,
+            updateChannel: modules.updates?.channel ?? undefined,
+            updateCreatedAt: modules.updates?.createdAt?.toISOString(),
+            isEmbeddedUpdate: modules.updates?.isEmbeddedLaunch ?? undefined,
+            isEmergencyLaunch: modules.updates?.isEmergencyLaunch ?? undefined,
+        },
+        device: {
+            isDevice: modules.device?.isDevice,
+            model: modules.device?.modelName ?? undefined,
+            osName: modules.device?.osName ?? undefined,
+            osVersion: modules.device?.osVersion ?? undefined,
+        },
+    };
+}
+export function installAutomaticErrors(client, target = globalThis, rejectionTracking) {
+    const errorUtils = target.ErrorUtils, previous = errorUtils?.getGlobalHandler();
+    const handler = (error, fatal) => {
+        client.error("javascript.uncaught", error, { fatal: fatal ?? false });
+        void client.flush({ timeoutMs: 1_500 });
+        previous?.(error, fatal);
+    };
+    errorUtils?.setGlobalHandler(handler);
+    const captureRejection = (_id, error) => client.error("javascript.unhandled_rejection", error);
+    const rejection = (event) => captureRejection(0, event.reason);
+    let disableRejectionTracking;
+    if (target.addEventListener) {
+        target.addEventListener("unhandledrejection", rejection);
+        disableRejectionTracking = () => target.removeEventListener("unhandledrejection", rejection);
+    }
+    else if (target.HermesInternal?.enablePromiseRejectionTracker) {
+        target.HermesInternal.enablePromiseRejectionTracker({
+            allRejections: true,
+            onUnhandled: captureRejection,
+        });
+    }
+    else if (rejectionTracking) {
+        rejectionTracking.enable({
+            allRejections: true,
+            onUnhandled: captureRejection,
+        });
+        disableRejectionTracking = () => rejectionTracking.disable();
+    }
+    return () => {
+        if (errorUtils?.getGlobalHandler() === handler && previous)
+            errorUtils.setGlobalHandler(previous);
+        disableRejectionTracking?.();
+    };
+}
+export function installExpoRouterBreadcrumbs(client, router) {
+    if (!router)
+        return () => { };
+    const originals = new Map();
+    for (const method of ["push", "replace", "navigate"]) {
+        const original = router[method];
+        if (!original)
+            continue;
+        originals.set(method, original);
+        router[method] = ((href, options) => {
+            const path = typeof href === "string"
+                ? href
+                : href && typeof href === "object" && "pathname" in href
+                    ? String(href.pathname)
+                    : "unknown";
+            client.breadcrumb("navigation.changed", {
+                action: method,
+                route: normalizeRoute(path),
+            });
+            return original.call(router, href, options);
+        });
+    }
+    return () => {
+        for (const [method, original] of originals)
+            router[method] = original;
+    };
+}

package/dist/expo-router.d.ts

@@ -0,0 +1,2 @@
+import type { TelemetryClient } from "./index.js";
+export declare function installExpoRouterTelemetry(client: TelemetryClient): () => void;

package/dist/expo-router.js

@@ -0,0 +1,5 @@
+import { router } from "expo-router";
+import { installExpoRouterBreadcrumbs, } from "./expo-adapters.js";
+export function installExpoRouterTelemetry(client) {
+    return installExpoRouterBreadcrumbs(client, router);
+}

package/dist/expo.d.ts

@@ -0,0 +1,6 @@
+import { type ClientOptions, type TelemetryClient } from "./index.js";
+export type CreateExpoTelemetryOptions = Pick<ClientOptions, "endpoint" | "token" | "enabled" | "redactKeys"> & {
+    flushLaunch?: boolean;
+};
+export declare function createExpoTelemetry(options: CreateExpoTelemetryOptions): TelemetryClient;
+export * from "./expo-adapters.js";

package/dist/expo.js

@@ -0,0 +1,49 @@
+// @ref LLP 0081#one-call-expo-sdk-boundary
+import * as Application from "expo-application";
+import * as Crypto from "expo-crypto";
+import * as Device from "expo-device";
+import { Directory, File, Paths } from "expo-file-system";
+import * as Network from "expo-network";
+import * as Updates from "expo-updates";
+import * as RejectionTracking from "promise/setimmediate/rejection-tracking";
+import { AppState, Platform } from "react-native";
+import { createExpoFileJournal, collectExpoContext, installAutomaticErrors, installExpoLifecycle, loadOrCreateInstallationId, } from "./expo-adapters.js";
+import { createTelemetryClient, } from "./index.js";
+export function createExpoTelemetry(options) {
+    const directory = new Directory(Paths.document, "tuft-telemetry");
+    if (!directory.exists)
+        directory.create({ idempotent: true, intermediates: true });
+    const makeFile = (name) => new File(directory, name);
+    const metadata = new File(directory, "metadata-v1.json");
+    const persistInstallationId = async (next) => {
+        metadata.write(JSON.stringify({ schemaVersion: 1, installationId: next }));
+    };
+    const installationId = loadOrCreateInstallationId(metadata, Crypto.randomUUID);
+    const client = createTelemetryClient({
+        ...options,
+        journal: createExpoFileJournal(makeFile),
+        installationId,
+        ids: Crypto.randomUUID,
+        persistInstallationId,
+        context: collectExpoContext({
+            application: Application,
+            updates: Updates,
+            device: Device,
+            platform: Platform.OS,
+        }),
+    });
+    const cleanups = [
+        installExpoLifecycle(client, { appState: AppState, network: Network }),
+        installAutomaticErrors(client, globalThis, RejectionTracking),
+    ];
+    const shutdown = client.shutdown.bind(client);
+    client.shutdown = async () => {
+        cleanups.forEach((cleanup) => cleanup());
+        await shutdown();
+    };
+    client.event("app.launch");
+    if (options.flushLaunch !== false)
+        void client.flush({ timeoutMs: 3_000 });
+    return client;
+}
+export * from "./expo-adapters.js";

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+export type TelemetryValue = string | number | boolean | null;
+export type TelemetryAttributes = Record<string, TelemetryValue>;
+export type TelemetryKind = "event" | "error" | "breadcrumb" | "span_start" | "span_end" | "marker";
+export interface TelemetryEnvelope {
+    schemaVersion: 1;
+    id: string;
+    timestamp: string;
+    sequence: number;
+    kind: TelemetryKind;
+    level: "debug" | "info" | "warn" | "error";
+    name: string;
+    attributes: TelemetryAttributes;
+    installationId: string;
+    launchId: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    app?: {
+        applicationId?: string;
+        version?: string;
+        buildVersion?: string;
+    };
+    runtime?: {
+        platform?: string;
+        route?: string;
+        updateId?: string;
+        runtimeVersion?: string;
+        updateChannel?: string;
+        updateCreatedAt?: string;
+        isEmbeddedUpdate?: boolean;
+        isEmergencyLaunch?: boolean;
+    };
+    device?: {
+        isDevice?: boolean;
+        model?: string;
+        osName?: string;
+        osVersion?: string;
+    };
+    error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+        cause?: string;
+    };
+}
+export interface Journal {
+    load(): Promise<TelemetryEnvelope[]>;
+    replace(records: TelemetryEnvelope[]): Promise<void>;
+}
+export interface Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    event(name: string, attributes?: TelemetryAttributes): void;
+    end(attributes?: TelemetryAttributes): void;
+    fail(error: unknown, attributes?: TelemetryAttributes): void;
+}
+export type FlushResult = {
+    status: "empty" | "uploaded" | "retrying" | "rejected" | "offline" | "suspended" | "timeout";
+    count: number;
+    retryAfterMs?: number;
+};
+export type DeliveryStatus = {
+    online: boolean;
+    suspended: boolean;
+    reason?: "authentication" | "configuration" | "shutdown";
+    queued: number;
+    lastRejection?: {
+        status: number;
+        count: number;
+    };
+};
+export type ProblemMarker = {
+    code: string;
+    uploaded: boolean;
+};
+export interface TelemetryClient {
+    event(name: string, attributes?: TelemetryAttributes): void;
+    error(name: string, error: unknown, attributes?: TelemetryAttributes): void;
+    breadcrumb(name: string, attributes?: TelemetryAttributes): void;
+    startSpan(name: string, attributes?: TelemetryAttributes, parent?: Span): Span;
+    flush(options?: {
+        timeoutMs?: number;
+    }): Promise<FlushResult>;
+    mark(name?: string, attributes?: TelemetryAttributes): Promise<ProblemMarker>;
+    setOnline(online: boolean): void;
+    getStatus(): Promise<DeliveryStatus>;
+    clear(): Promise<void>;
+    resetInstallationId(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface ClientOptions {
+    endpoint: string;
+    token: string;
+    journal: Journal;
+    installationId?: string;
+    enabled?: boolean;
+    autoFlush?: boolean;
+    flushDelayMs?: number;
+    batchSize?: number;
+    maxEvents?: number;
+    maxBytes?: number;
+    ids?: () => string;
+    now?: () => number;
+    fetch?: typeof fetch;
+    context?: Pick<TelemetryEnvelope, "app" | "runtime" | "device">;
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+        jitter?: number;
+    };
+    redactKeys?: (string | RegExp)[];
+    persistInstallationId?: (id: string) => Promise<void>;
+}
+export declare function redactAttributes(input: TelemetryAttributes | Record<string, unknown>, extra?: (string | RegExp)[]): TelemetryAttributes;
+export declare function normalizeRoute(path: string, template?: string): string;
+export declare function normalizeError(value: unknown): TelemetryEnvelope["error"];
+export declare function randomId(): `${string}-${string}-${string}-${string}-${string}`;
+export declare function createTelemetryClient(options: ClientOptions): TelemetryClient;

package/dist/index.js

@@ -0,0 +1,308 @@
+const SECRET = /authorization|cookie|token|password|secret|api[-_]?key|session(?:id|credential)?/i;
+const encoder = new TextEncoder();
+const isScalar = (value) => value === null || ["string", "number", "boolean"].includes(typeof value);
+export function redactAttributes(input, extra = []) {
+    const out = {};
+    for (const [rawKey, rawValue] of Object.entries(input).slice(0, 32)) {
+        const key = rawKey.slice(0, 80);
+        const secret = SECRET.test(key) ||
+            extra.some((rule) => typeof rule === "string"
+                ? rule.toLowerCase() === key.toLowerCase()
+                : ((rule.lastIndex = 0), rule.test(key)));
+        if (secret)
+            out[key] = "[REDACTED]";
+        else if (isScalar(rawValue))
+            out[key] =
+                typeof rawValue === "string" ? rawValue.slice(0, 2_000) : rawValue;
+    }
+    return out;
+}
+export function normalizeRoute(path, template) {
+    if (template)
+        return template.split(/[?#]/)[0];
+    return path
+        .split(/[?#]/)[0]
+        .split("/")
+        .map((part) => !part
+        ? ""
+        : /^(\d+|[0-9a-f]{8,}|[A-Za-z0-9_-]{16,})$/i.test(part)
+            ? ":segment"
+            : part)
+        .join("/");
+}
+export function normalizeError(value) {
+    if (!(value instanceof Error))
+        return { message: String(value).slice(0, 2_000) };
+    const seen = new Set();
+    const causes = [];
+    let current = value.cause;
+    while (current != null && !seen.has(current) && causes.length < 5) {
+        seen.add(current);
+        causes.push(current instanceof Error ? current.message : String(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return {
+        name: value.name.slice(0, 120),
+        message: value.message.slice(0, 2_000),
+        stack: value.stack?.slice(0, 16_000),
+        cause: causes.length ? causes.join(" <- ").slice(0, 2_000) : undefined,
+    };
+}
+export function randomId() {
+    return (globalThis.crypto?.randomUUID?.() ??
+        `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`);
+}
+function reportCode() {
+    const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+    return Array.from({ length: 6 }, () => chars[Math.floor(Math.random() * chars.length)]).join("");
+}
+function encodedBytes(value) {
+    return encoder.encode(JSON.stringify(value)).byteLength;
+}
+function trimRecords(records, maxEvents, maxBytes) {
+    let dropped = Math.max(0, records.length - maxEvents);
+    if (dropped)
+        records.splice(0, dropped);
+    let totalBytes = 2 + Math.max(0, records.length - 1);
+    const sizes = records.map((record) => encodedBytes(record));
+    totalBytes += sizes.reduce((sum, size) => sum + size, 0);
+    while (records.length && totalBytes > maxBytes) {
+        totalBytes -= sizes.shift() ?? 0;
+        if (records.length > 1)
+            totalBytes -= 1;
+        records.shift();
+        dropped++;
+    }
+    return dropped;
+}
+export function createTelemetryClient(options) {
+    const enabled = options.enabled ?? true, id = options.ids ?? randomId, now = options.now ?? Date.now, launchId = id();
+    let installationId = options.installationId ?? id();
+    let sequence = 0, closed = false, online = true, suspended = false, suspendReason, lastRejection;
+    let timer;
+    let journalQueue = Promise.resolve(), flushFlight, failures = 0;
+    let journalCache;
+    const maxEvents = options.maxEvents ?? 1_000, maxBytes = options.maxBytes ?? 2_000_000, batchSize = options.batchSize ?? 100;
+    const transaction = (work) => {
+        const next = journalQueue.then(work, work);
+        journalQueue = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    const loadJournal = async () => {
+        journalCache ??= await options.journal.load();
+        return journalCache;
+    };
+    const read = () => transaction(async () => [...(await loadJournal())]);
+    const mutate = (work) => transaction(async () => {
+        const records = [...(await loadJournal())];
+        const next = await work(records);
+        await options.journal.replace(next);
+        journalCache = [...next];
+        return next;
+    });
+    const make = (name, kind, attributes = {}, level = "info", links = {}, error) => ({
+        schemaVersion: 1,
+        id: id(),
+        timestamp: new Date(now()).toISOString(),
+        sequence: ++sequence,
+        kind,
+        level,
+        name: name.slice(0, 160),
+        attributes: redactAttributes(attributes, options.redactKeys),
+        installationId,
+        launchId,
+        ...options.context,
+        ...links,
+        ...(error === undefined ? {} : { error: normalizeError(error) }),
+    });
+    const schedule = (delay = options.flushDelayMs ?? 1_000, replace = false) => {
+        if (!enabled ||
+            closed ||
+            suspended ||
+            !online ||
+            options.autoFlush === false)
+            return;
+        if (timer && !replace)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void flush();
+        }, Math.max(0, delay));
+    };
+    const append = (record) => {
+        void mutate((records) => {
+            records.push(record);
+            let dropped = trimRecords(records, maxEvents, maxBytes);
+            if (dropped && record.name !== "telemetry.events_dropped") {
+                records.push(make("telemetry.events_dropped", "event", { count: dropped }, "warn"));
+                dropped += trimRecords(records, maxEvents, maxBytes);
+            }
+            return records;
+        });
+        schedule();
+    };
+    const record = (name, kind, attributes, level, links, error) => {
+        if (enabled && !closed)
+            append(make(name, kind, attributes, level, links, error));
+    };
+    const flush = (settings = {}) => {
+        if (closed && suspendReason === "shutdown")
+            return Promise.resolve({ status: "suspended", count: 0 });
+        if (suspended)
+            return Promise.resolve({ status: "suspended", count: 0 });
+        if (!online)
+            return Promise.resolve({ status: "offline", count: 0 });
+        if (flushFlight)
+            return flushFlight;
+        const flight = (async () => {
+            let uploaded = 0;
+            while (online && !suspended) {
+                const batch = (await read()).slice(0, batchSize);
+                if (!batch.length)
+                    return { status: uploaded ? "uploaded" : "empty", count: uploaded };
+                const controller = new AbortController(), timeout = setTimeout(() => controller.abort(), settings.timeoutMs ?? 10_000);
+                try {
+                    const response = await (options.fetch ?? globalThis.fetch)(`${options.endpoint.replace(/\/+$/, "")}/v1/events`, {
+                        method: "POST",
+                        signal: controller.signal,
+                        headers: {
+                            authorization: `Bearer ${options.token}`,
+                            "content-type": "application/json",
+                        },
+                        body: JSON.stringify({ schemaVersion: 1, events: batch }),
+                    });
+                    if (response.ok) {
+                        const accepted = new Set(batch.map((item) => item.id));
+                        await mutate((all) => all.filter((item) => !accepted.has(item.id)));
+                        failures = 0;
+                        uploaded += batch.length;
+                        continue;
+                    }
+                    if ([401, 403].includes(response.status)) {
+                        suspended = true;
+                        suspendReason = "authentication";
+                        return { status: "rejected", count: uploaded };
+                    }
+                    if (response.status === 400 || response.status === 422) {
+                        const rejected = new Set(batch.map((item) => item.id));
+                        await mutate((all) => all.filter((item) => !rejected.has(item.id)));
+                        lastRejection = { status: response.status, count: batch.length };
+                        continue;
+                    }
+                    if ([408, 425, 429].includes(response.status) ||
+                        response.status >= 500) {
+                        failures++;
+                        const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"), now(), backoffMs(failures, options.backoff));
+                        schedule(retryAfterMs, true);
+                        return { status: "retrying", count: uploaded, retryAfterMs };
+                    }
+                    suspended = true;
+                    suspendReason = "configuration";
+                    lastRejection = { status: response.status, count: batch.length };
+                    return { status: "rejected", count: uploaded };
+                }
+                catch {
+                    failures++;
+                    const retryAfterMs = backoffMs(failures, options.backoff);
+                    schedule(retryAfterMs, true);
+                    return {
+                        status: controller.signal.aborted ? "timeout" : "retrying",
+                        count: uploaded,
+                        retryAfterMs,
+                    };
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            return { status: online ? "suspended" : "offline", count: uploaded };
+        })().finally(() => {
+            flushFlight = undefined;
+        });
+        flushFlight = flight;
+        return flight;
+    };
+    const startSpan = (name, attributes = {}, parent) => {
+        const traceId = parent?.traceId ?? id(), spanId = id(), started = globalThis.performance?.now?.() ?? now();
+        let ended = false;
+        const links = { traceId, spanId, parentSpanId: parent?.spanId };
+        record(name, "span_start", attributes, "info", links);
+        const finish = (level, attrs, error) => {
+            if (ended)
+                return;
+            ended = true;
+            record(name, "span_end", {
+                ...attrs,
+                durationMs: Math.max(0, (globalThis.performance?.now?.() ?? now()) - started),
+            }, level, links, error);
+        };
+        return {
+            traceId,
+            spanId,
+            event: (eventName, attrs) => record(eventName, "event", attrs, "info", links),
+            end: (attrs) => finish("info", attrs),
+            fail: (error, attrs) => finish("error", attrs, error),
+        };
+    };
+    return {
+        event: (name, attrs) => record(name, "event", attrs),
+        error: (name, error, attrs) => record(name, "error", attrs, "error", {}, error),
+        breadcrumb: (name, attrs) => record(name, "breadcrumb", attrs, "debug"),
+        startSpan,
+        flush,
+        async mark(name = "problem.marked", attrs = {}) {
+            const code = reportCode();
+            record(name, "marker", { ...attrs, reportCode: code }, "warn");
+            const result = await flush({ timeoutMs: 3_000 });
+            return { code, uploaded: result.status === "uploaded" };
+        },
+        setOnline(next) {
+            const recovered = !online && next;
+            online = next;
+            if (!next && timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (recovered)
+                schedule(0, true);
+        },
+        async getStatus() {
+            return {
+                online,
+                suspended,
+                reason: suspendReason,
+                queued: (await read()).length,
+                lastRejection,
+            };
+        },
+        async clear() {
+            await mutate(() => []);
+        },
+        async resetInstallationId() {
+            installationId = id();
+            await options.persistInstallationId?.(installationId);
+        },
+        async shutdown() {
+            if (timer)
+                clearTimeout(timer);
+            await flush({ timeoutMs: 3_000 });
+            closed = true;
+            suspended = true;
+            suspendReason = "shutdown";
+        },
+    };
+}
+function backoffMs(failures, options = {}) {
+    const base = options.baseMs ?? 1_000, max = options.maxMs ?? 60_000, jitter = options.jitter ?? 0.2, raw = Math.min(max, base * 2 ** Math.max(0, failures - 1));
+    return Math.round(raw * (1 - jitter + Math.random() * jitter * 2));
+}
+function parseRetryAfter(value, now, fallback) {
+    if (!value)
+        return fallback;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1_000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - now) : fallback;
+}

package/docs/limitations.md

@@ -0,0 +1,5 @@
+# Limitations
+
+This is not a native crash reporter. Native crashes, OOMs, ANRs, and process termination before a journal write completes can be invisible. Background execution and delivery are opportunistic on iOS and Android. Keep Sentry or a platform-native crash reporter for native failures; share launch, trace, build, and update IDs when bridging the two systems.
+
+The current prototype provides the core recorder, delivery protocol, persistent installation identity, Expo file journal/context/lifecycle/network integration, JavaScript exception hooks, and normalized imperative Expo Router breadcrumbs. Update-log deduplication, notification/task helpers, declarative route observation for navigation that bypasses the imperative router, secure token storage, and on-device integration tests remain follow-on work before a production release.

package/docs/privacy.md

@@ -0,0 +1,5 @@
+# Privacy and redaction
+
+Only scalar attributes are accepted. Secret-shaped keys (`authorization`, `cookie`, `token`, `password`, `secret`, API keys, and session credentials) are replaced with `[REDACTED]`; applications can add exact keys or regular expressions. Names, keys, strings, stacks, attribute counts, event counts, and journal bytes are bounded. Routes drop query strings and fragments and replace ID-shaped segments.
+
+Do not instrument bodies, headers, message/email contents, text input, clipboard data, arbitrary props, or URLs containing user data. Production enablement should be explicit and collector tokens must be write-only.

package/docs/protocol.md

@@ -0,0 +1,5 @@
+# Collector protocol v1
+
+The setup API supplies a base `collector_url`. The SDK sends `POST {collector_url}/v1/events` with `Authorization: Bearer <write-only token>` and JSON `{ "schemaVersion": 1, "events": [...] }`. The daemon resolves the one authorized stream from the token; clients cannot select a stream.
+
+Any 2xx response acknowledges every event in that request. The SDK atomically removes those IDs and continues draining batches. `408`, `425`, `429`, `5xx`, network errors, and timeouts retain the batch and schedule retry; valid `Retry-After` values are honored. `401`/`403` suspend delivery with an authentication status. `400`/`422` drop the poison batch and record a local diagnostic so later valid events are not blocked. Other permanent responses suspend delivery with a configuration status and retain the batch for inspection. Collectors must ignore unknown envelope fields and deduplicate by event `id`.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tuft-telemetry",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./expo": {
+      "types": "./dist/expo.d.ts",
+      "import": "./dist/expo.js"
+    },
+    "./expo-router": {
+      "types": "./dist/expo-router.d.ts",
+      "import": "./dist/expo-router.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "promise": "^8.3.0"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-application": "*",
+    "expo-crypto": "*",
+    "expo-device": "*",
+    "expo-file-system": "*",
+    "expo-network": "*",
+    "expo-router": "*",
+    "expo-updates": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-router": {
+      "optional": true
+    }
+  }
+}