@sazabi/react-native 0.0.0-stage → 0.1.1

package/dist/client-sdk-core/before-send.d.ts

@@ -0,0 +1,15 @@
+import type { BeforeSend, ClientEvent } from "./types.js";
+/**
+ * The host's `beforeSend` hook, run so that it can never break the SDK: a
+ * hook that throws or returns something other than an event drops the event
+ * (a hook that redacts must not fail open) and warns once per reason. An
+ * event captured synchronously while the hook runs (a `log()` or
+ * `addEvent()` call inside it) is dropped rather than sent around the hook
+ * or fed back into it, so a hook can never recurse. A request the hook
+ * starts completes later and produces an ordinary network event the hook
+ * sees like any other; the hook is responsible for excluding it.
+ */
+export declare const createBeforeSendGate: (hook: BeforeSend | undefined, warnOnce: (warning: {
+    reason: string;
+    message: string;
+}) => void) => ((event: ClientEvent) => ClientEvent | null);

package/dist/client-sdk-core/clock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Monotonic milliseconds for durations and ordering. `performance.now()` where
+ * the host has it (every browser, React Native on Hermes); `Date.now()` as the
+ * fallback so the core never assumes a global.
+ */
+export declare const monotonicNow: () => number;

package/dist/client-sdk-core/console.d.ts

@@ -0,0 +1,23 @@
+import type { ClientEvent, ConsoleCaptureLevel } from "./types.js";
+export interface ConsoleCaptureOptions {
+    emit(event: ClientEvent): void;
+    levels: ConsoleCaptureLevel[];
+    /** Lines the SDK itself prints start with this and are never re-captured. */
+    selfPrefix: string;
+}
+export interface ConsoleCaptureHandle {
+    teardown(): void;
+}
+/**
+ * Print through the console without mirroring the line into the event
+ * stream: for a host-facing message the SDK prints on another component's
+ * behalf (the dev-mode rejection warning it relays for React Native).
+ */
+export declare const withoutConsoleCapture: (print: () => void) => void;
+/**
+ * Mirror selected console levels into the event stream as `log` events.
+ * The original console method always runs first (devtools behavior is never
+ * altered) and capture failures are swallowed. Lines the SDK itself prints
+ * (prefixed with `selfPrefix`) are skipped to avoid self-capture.
+ */
+export declare const installConsoleCapture: (options: ConsoleCaptureOptions) => ConsoleCaptureHandle;

package/dist/client-sdk-core/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @sazabi/client-sdk-core: the platform-neutral half of the Sazabi client
+ * SDKs. Private and bundled into @sazabi/browser and @sazabi/react-native at
+ * build time; never published, never imported by anything else. Compiles
+ * without the DOM lib (see host-globals.d.ts), so a browser global here is a
+ * typecheck error.
+ */
+export { flattenAttributes, truncateValue } from "./attributes.js";
+export { monotonicNow } from "./clock.js";
+export { type ConsoleCaptureHandle, type ConsoleCaptureOptions, installConsoleCapture, withoutConsoleCapture, } from "./console.js";
+export { intakeBaseFromUrl, publicKeyFromIntakeUrl, type ResolvedIntakeEndpoint, resolveIntakeEndpoint, } from "./intake-url.js";
+export { activateNetworkCapture, consumeWrapperSeen, deactivateNetworkCapture, emitNetworkEvent, ensureXhrPatch, getActiveNetworkCapture, isAborted, isActiveInjectionTarget, isAllowedForInjection, type NetworkCaptureOptions, type NetworkEventDetails, readRequestId, recordWrapperRequest, redactUrl, resetWrapperLedger, severityForStatus, uninstallXhrPatch, urlPath, } from "./network-capture.js";
+export { isWrapped, markWrapped, WRAPPED_MARKER } from "./patch-marker.js";
+export { createPointerTracker, type DerivedTap, type PointerContact, type PointerTarget, type PointerTracker, type PointerTrackerOptions, type PointerType, } from "./pointer.js";
+export { createRandomBytes, newPrefixedId, type RandomBytes, randomHex, toHex, } from "./random.js";
+export { createMemoryStore, createSessionManager, type SessionManager, type SessionManagerOptions, type SessionStore, } from "./session.js";
+export { createTraceContextManager, type HostSpanContext, readHostSpanContext, type RequestTraceContext, type TraceContextManager, } from "./trace-context.js";
+export { createSdkHealthReporter, SDK_DIAGNOSTIC_KEY, type SdkHealthDiagnostic, type SdkHealthReport, type SdkHealthReporter, } from "./sdk-health.js";
+export { createTransport, encodeLogRecord, type FetchLike, type OtlpLogRecord, type Transport, type TransportOptions, } from "./transport.js";
+export { isUnderBase, type ParsedUrl, parseAbsoluteUrl } from "./url.js";
+export { createBeforeSendGate } from "./before-send.js";
+export type { AttributeValue, BeforeSend, ClientEvent, ClientEventType, ConsoleCaptureConfig, ConsoleCaptureLevel, EventAttributes, EventSeverity, NetworkCaptureConfig, PointerCaptureConfig, } from "./types.js";

package/dist/client-sdk-core/intake-url.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resolving the intake endpoint from a single URL.
+ *
+ * Every Sazabi log source is configured with one intake URL, and public keys
+ * stay a low-level detail customers never handle. The key is already in the
+ * URL: the intake edge reconstructs it from the hostname
+ * (terraform/main/cloudfront-functions/intake-router.js), so the SDK does the
+ * same reconstruction locally and sends the Bearer header itself.
+ *
+ * Two keyed shapes exist, matching the edge's two grammars:
+ *   {hex}.{region}.intake.{domain}            prefixless (what log sources issue)
+ *   {adapter}-{hex}.{region}.intake.{domain}  keyed-adapter (legacy, still served)
+ *
+ * A URL in neither shape is not an error: it may be a proxy or a custom
+ * endpoint. The SDK then requires an explicit `publicKey`, so a
+ * misconfiguration surfaces as a clear warning rather than silent no-auth.
+ */
+export interface ResolvedIntakeEndpoint {
+    /**
+     * Base to POST to: origin plus any proxy path prefix, no trailing slash.
+     * The transport appends `/v1/logs`.
+     */
+    baseUrl: string;
+    /** Credential for the Authorization header, derived or explicit. */
+    publicKey: string;
+}
+/** Public key embedded in a keyed intake hostname, if it carries one. */
+export declare const publicKeyFromIntakeUrl: (url: string) => string | undefined;
+export declare const intakeBaseFromUrl: (url: string) => string | undefined;
+/**
+ * Resolve the endpoint from config. An explicit `publicKey` always wins, so a
+ * non-keyed or proxied endpoint stays configurable.
+ */
+export declare const resolveIntakeEndpoint: (config: {
+    intakeUrl?: string;
+    intakeHost?: string;
+    publicKey?: string;
+}) => ResolvedIntakeEndpoint | undefined;

package/dist/client-sdk-core/network-capture.d.ts

@@ -0,0 +1,90 @@
+import type { RequestTraceContext, TraceContextManager } from "./trace-context.js";
+import type { ClientEvent, EventSeverity } from "./types.js";
+/**
+ * Everything the network patches need at request time. A binding builds one
+ * at init and activates it; the patches themselves install dormant (possibly
+ * before init, via a register entrypoint) and consult the active slot per
+ * call. Undefined slot = transparent passthrough.
+ */
+export interface NetworkCaptureOptions {
+    emit(event: ClientEvent): void;
+    traceContext: TraceContextManager;
+    /** Emit network events. */
+    capture: boolean;
+    /** Inject `traceparent` into allowlisted requests. */
+    propagateTraceContext: boolean;
+    /** Injection allowlist; empty defers to `isDefaultInjectionTarget`. */
+    allowlist: (string | RegExp)[];
+    /** Query parameter names redacted from `url.full` beside the default list. */
+    redactQueryParams?: (string | RegExp)[];
+    /** Response headers probed for a platform request id, in priority order. */
+    requestIdHeaders: string[];
+    /** SDK-internal endpoints: never captured, never injected. */
+    isInternalUrl(url: string): boolean;
+    /**
+     * Absolute URL for a request target as the host resolves it, with embedded
+     * credentials stripped; undefined when the input cannot be parsed.
+     */
+    resolveUrl(raw: string): string | undefined;
+    /** Injection policy when the allowlist is empty (same-origin on the web). */
+    isDefaultInjectionTarget(resolved: string): boolean;
+    /** Origin elided from the display path in event bodies, if the host has one. */
+    displayOrigin?: string;
+    /** Host-reported offline state; a failure while offline reads as an abort. */
+    isOffline?(): boolean;
+}
+export declare const activateNetworkCapture: (options: NetworkCaptureOptions) => void;
+export declare const deactivateNetworkCapture: () => void;
+export declare const getActiveNetworkCapture: () => NetworkCaptureOptions | undefined;
+/** Compact display path: pathname when on the display origin, host+path otherwise. */
+export declare const urlPath: (resolved: string, displayOrigin?: string) => string;
+/** Status 0 means transport failure. */
+export declare const severityForStatus: (status: number) => EventSeverity;
+/**
+ * A recorded URL: the value of every sensitive parameter after the path
+ * replaced with `[redacted]`, in the query and in the fragment. `?` separates
+ * inside the fragment as well, so a hash router's `#/reset?token=…` is
+ * covered. Credentials in the authority are already gone (`resolveUrl`
+ * strips them). Applied to `url.full` of requests, resource rows and
+ * navigations, and to the page URL the browser SDK stamps on every event.
+ */
+export declare const redactUrl: (url: string, extra?: (string | RegExp)[]) => string;
+export declare const isAllowedForInjection: (options: NetworkCaptureOptions, resolved: string) => boolean;
+/** Injection eligibility for the active config; used by the browser's resource
+ * observer to decide whether a bypassed request is a diagnosable gap. */
+export declare const isActiveInjectionTarget: (resolved: string) => boolean;
+export declare const recordWrapperRequest: (url: string) => void;
+/** Consume a wrapper-seen record matching this request, if any. */
+export declare const consumeWrapperSeen: (url: string, startTime: number) => boolean;
+export declare const resetWrapperLedger: () => void;
+export interface NetworkEventDetails {
+    kind: "fetch" | "xhr";
+    method: string;
+    resolvedUrl: string;
+    status: number;
+    durationMs: number;
+    severity?: EventSeverity;
+    failureMessage?: string;
+    injected?: RequestTraceContext;
+    requestId?: string;
+    requestIdHeader?: string;
+}
+export declare const emitNetworkEvent: (options: NetworkCaptureOptions, details: NetworkEventDetails) => void;
+export declare const readRequestId: (options: NetworkCaptureOptions, getHeader: (name: string) => string | null | undefined) => {
+    requestId?: string;
+    requestIdHeader?: string;
+};
+export declare const isAborted: (error: unknown, signalAborted?: boolean, offline?: boolean) => boolean;
+/**
+ * Install the dormant XMLHttpRequest patch around whatever implementation is
+ * currently live. Idempotent, and re-wraps when a later actor replaced the
+ * prototype methods after an earlier install (the displaced wrapper is an
+ * inert passthrough, so single-processing holds).
+ */
+export declare const ensureXhrPatch: () => void;
+/**
+ * Restore the natives if the current implementations are still ours; if
+ * someone patched on top of us, restoring would clobber them, and the
+ * inactive wrappers pass through.
+ */
+export declare const uninstallXhrPatch: () => void;

package/dist/client-sdk-core/patch-marker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared across every Sazabi client SDK so two SDKs bundled into one app
+ * recognize each other's wrappers and never double-wrap a primitive.
+ */
+export declare const WRAPPED_MARKER = "__sazabiBrowserWrapped";
+/** Best-effort idempotency marker on wrapper functions. */
+export declare const markWrapped: (fn: object) => void;
+export declare const isWrapped: (fn: unknown) => boolean;

package/dist/client-sdk-core/pointer.d.ts

@@ -0,0 +1,73 @@
+import { type RandomBytes } from "./random.js";
+import type { ClientEvent } from "./types.js";
+/**
+ * Pointer episodes: one row per contact from down to up, for mouse, touch,
+ * and pen alike. A binding feeds raw contacts in (DOM pointer events in the
+ * browser, the responder's touch arrays on mobile) and the tracker emits the
+ * episode rows plus the derived `click` and `rage_click` rows. Movement is
+ * sampled, never streamed: a position sample every `sampleIntervalMs` is
+ * packed into the row, and a contact that outlives `partialIntervalMs` emits
+ * a partial row at that cadence so a long scroll is not a blind spot.
+ */
+export type PointerType = "mouse" | "touch" | "pen";
+export interface PointerTarget {
+    /** Developer-authored name for the widget under the pointer, if any. */
+    name?: string;
+    /** Stable-ish identifier: a selector on the web, a component path on mobile. */
+    id?: string;
+    /** Element tag or component kind. */
+    tag?: string;
+    /** Whether a tap here is on something that should respond. */
+    interactive: boolean;
+}
+export interface PointerContact {
+    id: number | string;
+    type: PointerType;
+    primary: boolean;
+    x: number;
+    y: number;
+    pressure?: number;
+    /**
+     * The button that started a mouse contact (DOM `button`: 0 primary, 1
+     * auxiliary, 2 secondary). Absent for touch and pen. Only a primary-button
+     * contact can derive a click: a short right or middle press is an episode
+     * without a tap, matching the host's `contextmenu` and `auxclick`.
+     */
+    button?: number;
+    target?: PointerTarget;
+}
+export interface DerivedTap {
+    x: number;
+    y: number;
+    target?: PointerTarget;
+    /** Absent for a tap no contact produced (keyboard activation, script). */
+    gestureId?: string;
+}
+export interface PointerTrackerOptions {
+    emit(event: ClientEvent): void;
+    randomBytes: RandomBytes;
+    /** Spacing of packed position samples. Default 1000. */
+    sampleIntervalMs?: number;
+    /** Cadence of partial rows for long contacts. Default 10000. */
+    partialIntervalMs?: number;
+    /** Every derived tap, so a binding can run its own dead-tap detection. */
+    onTap?(tap: DerivedTap): void;
+}
+export interface PointerTracker {
+    down(contact: PointerContact): void;
+    move(id: number | string, x: number, y: number, pressure?: number): void;
+    up(id: number | string, x: number, y: number): void;
+    cancel(id: number | string): void;
+    /**
+     * A click that no pointer contact produced: keyboard activation or a
+     * script calling `click()`. Emits the `click` row and runs the same rage
+     * and dead-tap derivation, with no episode behind it.
+     */
+    tap(tap: {
+        x: number;
+        y: number;
+        target?: PointerTarget;
+    }): void;
+    teardown(): void;
+}
+export declare const createPointerTracker: (options: PointerTrackerOptions) => PointerTracker;

package/dist/client-sdk-core/random.d.ts

@@ -0,0 +1,11 @@
+export type RandomBytes = (length: number) => Uint8Array;
+/**
+ * Random bytes for session, trace, and gesture ids. Web Crypto where the host
+ * has it; a seeded fallback where it does not (React Native without a
+ * `crypto.getRandomValues` polyfill). The ids need uniqueness, not secrecy,
+ * so the fallback is acceptable there and is never used where crypto exists.
+ */
+export declare const createRandomBytes: () => RandomBytes;
+export declare const toHex: (bytes: Uint8Array) => string;
+export declare const randomHex: (randomBytes: RandomBytes, byteLength: number) => string;
+export declare const newPrefixedId: (randomBytes: RandomBytes, prefix: string) => string;

package/dist/client-sdk-core/sdk-health.d.ts

@@ -0,0 +1,37 @@
+import type { ClientEvent, EventAttributes } from "./types.js";
+/**
+ * What an `sdk_health` row reports: the SDK's own delivery trouble, so a
+ * misconfigured or unreachable app is visible to Sazabi before the customer
+ * reports it. Each value is a bounded enumeration, never free text.
+ *
+ *  - `intake_rejected`: the intake refused a batch for good (a 4xx other
+ *    than 408 and 429); `app.sdk.http_status` carries the status.
+ *  - `intake_unreachable`: uploads failed on the network (a dropped
+ *    connection, a timeout) and the intake later answered; `app.sdk.attempts`
+ *    is how many backoff windows the outage spanned (one per failed try,
+ *    with concurrent uploads failing together counted once).
+ *  - `outbox_discarded`: stored crash reports were dropped, by the caps or
+ *    because they were not valid reports; `app.sdk.outbox_discarded` counts
+ *    what is known lost, and `app.sdk.outbox_unsaved` what a saved queue had
+ *    left out at the caps (possible losses: their live upload may have
+ *    finished before the app was killed) (mobile only).
+ *  - `outbox_persist_failed`: the storage adapter refused a write of the
+ *    crash outbox or the saved queue (mobile only).
+ */
+export type SdkHealthDiagnostic = "intake_rejected" | "intake_unreachable" | "outbox_discarded" | "outbox_persist_failed";
+export interface SdkHealthReport {
+    diagnostic: SdkHealthDiagnostic;
+    /** The counters of the condition (`app.sdk.http_status`, `app.sdk.attempts`, ...). */
+    attributes?: EventAttributes;
+}
+export type SdkHealthReporter = (report: SdkHealthReport) => void;
+export declare const SDK_DIAGNOSTIC_KEY = "app.sdk.diagnostic";
+/**
+ * Turns health reports into `sdk_health` rows, at most one per diagnostic
+ * for the life of the reporter (one SDK session). The bound is what keeps
+ * the SDK from storming its own intake: a health row the intake refuses is
+ * a rejection like any other and is never reported again, and a flapping
+ * network produces one row per launch, not one per outage. Never throws
+ * into the host.
+ */
+export declare const createSdkHealthReporter: (emit: (event: ClientEvent) => void) => SdkHealthReporter;

package/dist/client-sdk-core/session.d.ts

@@ -0,0 +1,44 @@
+import { type RandomBytes } from "./random.js";
+/**
+ * Synchronous key-value access the session machine reads through on every
+ * call. A browser binding backs it with `localStorage` (so sibling tabs
+ * converge) and `sessionStorage`; a mobile binding backs it with an
+ * in-memory mirror hydrated from its storage adapter and written through.
+ */
+export interface SessionStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** A store that lives for the process only: the fallback on every host. */
+export declare const createMemoryStore: () => SessionStore;
+export interface SessionManager {
+    getSessionId(): string;
+    getWindowId(): string;
+    getDistinctId(): string | undefined;
+    /**
+     * Set the client-asserted identity. Switching from one identity directly
+     * to a different one rotates the session and window ids so two users on a
+     * shared device never thread into one timeline.
+     */
+    setDistinctId(distinctId: string): void;
+    /** Logout: clear identity and rotate both session and window ids. */
+    reset(): void;
+    /** Record user activity; may rotate the session on idle/max-age expiry. */
+    touch(): void;
+}
+export interface SessionManagerOptions {
+    /** Visit-scoped state: session id and identity. */
+    store: SessionStore;
+    /** Window-scoped state: one browser tab, or one app launch. */
+    windowStore: SessionStore;
+    randomBytes: RandomBytes;
+}
+/**
+ * Session identity. `session.id` is the visit (last-writer-wins on rotation
+ * races between windows; a split session is cosmetic, not data loss).
+ * `session.window_id` is this window. `session.distinct_id` is read through
+ * the store so identify/reset in one window is visible to siblings on their
+ * next event.
+ */
+export declare const createSessionManager: (options: SessionManagerOptions) => SessionManager;

package/dist/client-sdk-core/trace-context.d.ts

@@ -0,0 +1,33 @@
+import { type RandomBytes } from "./random.js";
+export interface RequestTraceContext {
+    /** Headers to inject (`traceparent`, and `tracestate` when present). */
+    headers: Record<string, string>;
+    traceId: string;
+    spanId: string;
+}
+export interface TraceContextManager {
+    /** Trace context for one outgoing request, minted at request time. */
+    forRequest(): RequestTraceContext;
+}
+/** The subset of an OTel SpanContext this module consumes. */
+export interface HostSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    traceState?: {
+        serialize(): string;
+    };
+}
+export declare const readHostSpanContext: () => HostSpanContext | undefined;
+/**
+ * W3C trace context for outgoing requests: hand-rolled header formatting
+ * (equivalence-tested against OTel's W3CTraceContextPropagator), zero
+ * runtime dependencies. If the host app runs its own OTel and has an active
+ * span, that span's context (including its flags and tracestate) is reused
+ * so we join the customer's trace instead of forking a new one; otherwise a
+ * fresh root is minted with the sampled flag defaulting to off (`-00`).
+ */
+export declare const createTraceContextManager: (options: {
+    sampledFlag: boolean;
+    randomBytes: RandomBytes;
+}) => TraceContextManager;

package/dist/client-sdk-core/transport.d.ts

@@ -0,0 +1,142 @@
+import type { SdkHealthReport } from "./sdk-health.js";
+import type { ClientEvent, EventAttributes, EventSeverity } from "./types.js";
+type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+};
+interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+export interface OtlpLogRecord {
+    timeUnixNano: string;
+    severityNumber: number;
+    severityText: EventSeverity;
+    body: {
+        stringValue: string;
+    };
+    attributes: OtlpKeyValue[];
+    /** OTLP/JSON encodes trace/span ids as hex (unlike proto3 JSON's base64). */
+    traceId?: string;
+    spanId?: string;
+}
+export declare const encodeLogRecord: (event: ClientEvent, baseAttributes: EventAttributes) => OtlpLogRecord;
+/**
+ * The slice of `fetch` the transport uses. Declared structurally so the core
+ * needs no DOM lib; every host's real `fetch` satisfies it.
+ */
+export type FetchLike = (url: string, init: {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+    keepalive: boolean;
+    /** An `AbortSignal` where the host has `AbortController`; aborts a timed-out upload. */
+    signal?: unknown;
+}) => Promise<unknown>;
+/**
+ * UTF-8 byte length of a string, without `TextEncoder` (Hermes has none).
+ * Request budgets are bytes on the wire; a string's `length` counts UTF-16
+ * units and undercounts non-ASCII text up to threefold.
+ */
+export declare const utf8Length: (text: string) => number;
+/** Stamped on the first row delivered after events were dropped: how many. */
+export declare const DROPPED_EVENTS_KEY = "app.sdk.dropped_events";
+/**
+ * Names the sending SDK on every upload, `<package>/<version>`: the input
+ * for the intake gateway's per-SDK request label (a separate change), which
+ * can then count a request by SDK even when it rejects it before the key is
+ * known. The gateway's CORS allow-list admits it, so a browser preflight
+ * passes.
+ */
+export declare const SDK_HEADER = "x-sazabi-sdk";
+export interface TransportOptions {
+    /** Full OTLP logs endpoint, e.g. `https://<key>.<region>.intake.<domain>/v1/logs`. */
+    url: string;
+    publicKey: string;
+    resourceAttributes: EventAttributes;
+    /** OTLP instrumentation scope: the emitting SDK's name and version. */
+    scope: {
+        name: string;
+        version: string;
+    };
+    /**
+     * The fetch to deliver with, captured before the SDK's network patch
+     * installs, so exporter traffic can never recurse through our own wrapper
+     * or appear in the captured event stream.
+     */
+    fetchImpl: FetchLike;
+    flushIntervalMs: number;
+    maxBatchBytes: number;
+    maxQueuedEvents: number;
+    /** Reports a dropped batch or a full queue; called once per reason. */
+    warn?(message: string): void;
+    /**
+     * The SDK's own delivery health: a batch the intake refused for good
+     * (`intake_rejected`, with the status) and uploads that failed on the
+     * network before one got through (`intake_unreachable`, with the number
+     * of failed tries). The binding turns these into `sdk_health` rows, once
+     * per condition per session.
+     */
+    onHealth?(report: SdkHealthReport): void;
+    /**
+     * Called when an upload settles with nothing queued, nothing in flight, and
+     * every row of the last `snapshotEnvelopes` delivered or refused for good:
+     * a saved row evicted from the full queue, or given up by `shutdown()`
+     * while the intake was unreachable, keeps it from firing until the next
+     * snapshot, so the host's saved copy stays.
+     */
+    onIdle?(): void;
+}
+export interface Transport {
+    enqueue(record: OtlpLogRecord): void;
+    /**
+     * Deliver everything queued. `keepalive: true` is for browser unload paths;
+     * each request body must stay inside the browser's ~64 KiB keepalive
+     * budget, which enqueue-side chunking guarantees via `maxBatchBytes`. Hosts
+     * without keepalive ignore the flag.
+     */
+    flush(options?: {
+        keepalive?: boolean;
+    }): Promise<void>;
+    /**
+     * Encode everything queued into standalone request bodies without sending,
+     * leaving the queue empty. The mobile crash outbox persists these and posts
+     * them on the next launch; `recordAttributes` are appended to every record
+     * (the outbox stamps its replay id there).
+     */
+    drainEnvelopes(recordAttributes?: EventAttributes): string[];
+    /**
+     * Encode everything queued into standalone request bodies and keep it
+     * queued. `recordAttributes` are stamped on the queued records themselves,
+     * so the live upload and the saved copy carry the same values (the mobile
+     * SDK saves its queue this way when the app leaves the foreground). Rows an
+     * earlier snapshot saved whose upload is still in flight are included as
+     * they were sent: the copy this one replaces held them.
+     */
+    snapshotEnvelopes(recordAttributes: EventAttributes): string[];
+    /**
+     * While held, `enqueue` never flushes on its own, neither on the byte
+     * budget nor by scheduling the timer: the mobile crash path holds the
+     * transport while it stamps the fatal row and everything buffered before
+     * it, then drains the whole batch into the outbox. Without this, a fatal
+     * row that tips the queue over the budget would be flushed out of the queue
+     * into a request the dying process never completes.
+     */
+    holdFlushes(hold: boolean): void;
+    /**
+     * Deliver a previously drained envelope. Resolves `true` once the envelope
+     * is settled: the intake accepted it (2xx) or refused it for good (a 4xx
+     * other than 408 and 429, dropped with a warning). Resolves `false` when it
+     * is worth sending again (408, 429, 5xx, a network failure, a timeout), and
+     * never rejects, so a persisted envelope is deleted only once settled.
+     */
+    sendEnvelope(body: string): Promise<boolean>;
+    shutdown(): Promise<void>;
+}
+export declare const createTransport: (options: TransportOptions) => Transport;
+export {};

package/dist/client-sdk-core/types.d.ts

@@ -0,0 +1,82 @@
+export type AttributeValue = string | number | boolean;
+export type EventAttributes = Record<string, AttributeValue | undefined>;
+export type EventSeverity = "DEBUG" | "INFO" | "WARN" | "ERROR";
+/**
+ * The shared `app.event_type` vocabulary. Every value means the same thing
+ * on every host; a binding that cannot produce one simply never emits it.
+ */
+export type ClientEventType = "navigation" | "pointer" | "click" | "rage_click" | "dead_click" | "input" | "network" | "error" | "custom" | "log" | "lifecycle"
+/** The SDK's own delivery health, one row per condition per session (`sdk-health.ts`). */
+ | "sdk_health";
+/** An SDK-internal semantic event, before OTLP encoding. */
+export interface ClientEvent {
+    type: ClientEventType;
+    body: string;
+    severity: EventSeverity;
+    timeUnixMs: number;
+    /** Set on network events when trace context was injected into the request. */
+    traceId?: string;
+    spanId?: string;
+    attributes: EventAttributes;
+}
+/**
+ * Runs on every event before it is queued. Return the event (edited or as
+ * given) to send it, or `null` to drop it. The hook sees the event's own
+ * attributes; the session and page fields are stamped afterwards.
+ */
+export type BeforeSend = (event: ClientEvent) => ClientEvent | null;
+export type ConsoleCaptureLevel = "error" | "warn" | "info" | "debug";
+export interface ConsoleCaptureConfig {
+    /** Mirror console output into the event stream. Default true. */
+    capture?: boolean;
+    /** Console levels to mirror. Default ["error", "warn"]. */
+    levels?: ConsoleCaptureLevel[];
+}
+export interface PointerCaptureConfig {
+    /** Emit one `pointer` episode per contact, plus derived taps. Default true. */
+    capture?: boolean;
+    /** Spacing of the position samples packed into an episode. Default 1000. */
+    sampleIntervalMs?: number;
+    /**
+     * A contact open longer than this emits a partial row at this cadence so a
+     * long scroll or drag is not a blind spot until release. Default 10000.
+     */
+    partialIntervalMs?: number;
+}
+/** Network options every binding shares; a binding may extend the shape. */
+export interface NetworkCaptureConfig {
+    /** Emit network events. Default true. */
+    capture?: boolean;
+    /** Inject W3C `traceparent` into allowlisted requests. Default true. */
+    propagateTraceContext?: boolean;
+    /**
+     * Response headers probed (in order) for a platform request id to attach
+     * as `app.network.request_id`, an exact join key against platform logs.
+     */
+    requestIdHeaders?: string[];
+    /**
+     * Requests eligible for `traceparent` injection. A string is a host
+     * (`api.example.com`), a domain with every subdomain (`.example.com`), or
+     * an origin with an optional path prefix (`https://api.example.com/v2`); a
+     * RegExp is tested against the full URL. An empty list falls back to the
+     * binding's default policy (same-origin in the browser, every request on
+     * mobile).
+     */
+    allowlist?: (string | RegExp)[];
+    /**
+     * Query parameter names whose values are replaced with `[redacted]` in
+     * every recorded URL: `url.full` of requests and navigations, the screen or
+     * page URL stamped on each event (`app.screen.url`), and in the browser the
+     * referrer (`app.navigation.from`). Beside the default list (token, access_token, refresh_token,
+     * id_token, api_key, apikey, key, secret, password, signature, sig,
+     * x-amz-signature, x-amz-credential, x-goog-signature, sentry_key,
+     * authorization, auth, session, sid, code). Strings match a name exactly,
+     * case-insensitively; RegExps are tested against the name.
+     */
+    redactQueryParams?: (string | RegExp)[];
+    /**
+     * Set the sampled flag (`-01`) on SDK-minted trace roots. Default false:
+     * the sampled bit steers customers' ParentBased backend samplers.
+     */
+    sampledFlag?: boolean;
+}