@edraj/sauron-browser 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,493 @@
+/**
+ * Sauron wire-contract types.
+ *
+ * These interfaces mirror the LOCKED envelope shape that the Rust ingest
+ * gateway and the Flutter SDK also emit/consume. Field names, nullability and
+ * ordering are load-bearing — do not "clean them up".
+ */
+/** Severity level. Matches the backend enum exactly. */
+type Level = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+/** Discriminant for an envelope item. */
+type ItemType = 'error' | 'event' | 'identify' | 'breadcrumb_batch' | 'transaction';
+/** Category of a performance transaction. Matches the backend enum exactly. */
+type TransactionOp = 'navigation' | 'http' | 'resource' | 'screen_load' | 'custom';
+/** A single normalized stack frame (raw, never symbolicated client-side). */
+interface Frame {
+    function: string | null;
+    filename: string | null;
+    lineno: number | null;
+    colno: number | null;
+    in_app: boolean;
+}
+/** How an exception reached the SDK. */
+interface Mechanism {
+    type: string;
+    handled: boolean;
+}
+/** The exception payload of an error item. */
+interface ExceptionValue {
+    type: string | null;
+    value: string | null;
+    mechanism: Mechanism;
+    stacktrace: Frame[];
+}
+/** A breadcrumb — a short trail-of-events entry. `data`/`message` may be null. */
+interface Breadcrumb {
+    type: string;
+    category: string;
+    message: string | null;
+    level: Level;
+    timestamp: string;
+    data: Record<string, unknown> | null;
+}
+/** An error item (uncaught error, rejection, or manual capture). */
+interface ErrorItem {
+    type: 'error';
+    /**
+     * Stable id the SDK mints for this report so callers can correlate it. Wire
+     * field `event_id`. Optional — the backend defaults one when omitted.
+     */
+    event_id?: string;
+    timestamp: string;
+    level: Level;
+    exception: ExceptionValue;
+    /** Optional human-readable summary alongside the exception. */
+    message?: string;
+    breadcrumbs: Breadcrumb[];
+    fingerprint: string[] | null;
+    /**
+     * Free-form indexed tags lifted from the current scope. Optional — omitted
+     * when the scope carries none (the backend defaults to `{}`).
+     */
+    tags?: Record<string, unknown>;
+    /**
+     * Dev-owned structured context blocks (e.g. `{ order: { id: 7 } }`). DISTINCT
+     * from the machine-owned `context` on the envelope — never overwrites it.
+     * Optional — omitted when empty (the backend defaults to `{}`).
+     */
+    contexts?: Record<string, unknown>;
+    /** Freeform JSON bag. Optional — omitted when empty (backend defaults `{}`). */
+    extra?: Record<string, unknown>;
+    /**
+     * Per-item user override (falls back to the envelope-context user). Optional
+     * — omitted when no identity is set on the scope.
+     */
+    user?: UserContext | null;
+    session_id?: string | null;
+    screen?: string | null;
+}
+/** A product-analytics event (PostHog-style `track`). */
+interface EventItem {
+    type: 'event';
+    name: string;
+    distinct_id: string | null;
+    session_id?: string | null;
+    screen?: string | null;
+    timestamp: string;
+    properties: Record<string, unknown>;
+    /** Scope+call tags lifted onto the event. Optional — omitted when empty. */
+    tags?: Record<string, unknown>;
+    /** Scope+call named context blocks. Optional — omitted when empty. */
+    contexts?: Record<string, unknown>;
+    /** Scope+call freeform JSON. Optional — omitted when empty. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * A performance transaction (navigation timing, an instrumented `fetch`, a
+ * screen load, ...). `duration_ms` is the wall-clock span; the `http_*`/`url`
+ * fields carry request metadata for `http` ops and are `null` otherwise.
+ */
+interface TransactionItem {
+    type: 'transaction';
+    name: string;
+    op: TransactionOp;
+    duration_ms: number;
+    status?: string | null;
+    http_method?: string | null;
+    http_status?: number | null;
+    url?: string | null;
+    distinct_id?: string | null;
+    session_id?: string | null;
+    timestamp: string;
+}
+/** An identity association (PostHog-style `identify`). */
+interface IdentifyItem {
+    type: 'identify';
+    distinct_id: string | null;
+    anonymous_id: string | null;
+    traits: Record<string, unknown>;
+}
+/** A standalone batch of breadcrumbs (used for periodic session trails). */
+interface BreadcrumbBatchItem {
+    type: 'breadcrumb_batch';
+    breadcrumbs: Breadcrumb[];
+}
+/** Any item that can appear in an envelope's `items` array. */
+type EnvelopeItem = ErrorItem | EventItem | IdentifyItem | BreadcrumbBatchItem | TransactionItem;
+interface DeviceContext {
+    /** Durable, persisted device identity (localStorage `sauron.device_id`). */
+    device_id: string;
+    family: string | null;
+    model: string | null;
+    arch: string | null;
+}
+interface OsContext {
+    name: string | null;
+    version: string | null;
+}
+interface AppContext {
+    version: string | null;
+    build: string | null;
+}
+interface RuntimeContext {
+    name: string | null;
+    version: string | null;
+}
+interface UserContext {
+    id: string | null;
+    email: string | null;
+    traits: Record<string, unknown>;
+}
+interface Context {
+    device: DeviceContext;
+    os: OsContext;
+    app: AppContext;
+    runtime: RuntimeContext;
+    user: UserContext;
+}
+interface SdkInfo {
+    name: string;
+    version: string;
+}
+interface EnvelopeHeader {
+    dsn: string;
+    sdk: SdkInfo;
+    sent_at: string;
+    environment: string;
+    release: string | null;
+}
+/** The complete, serializable envelope posted to the ingest gateway. */
+interface Envelope {
+    header: EnvelopeHeader;
+    context: Context;
+    items: EnvelopeItem[];
+}
+/** Loose hint bag passed through to `beforeSend` / `beforeBreadcrumb`. */
+type Hint = Record<string, unknown> & {
+    originalException?: unknown;
+    event?: unknown;
+    /** Per-call metadata overrides, merged over the current scope before send. */
+    tags?: Record<string, string>;
+    contexts?: Record<string, Record<string, unknown>>;
+    extra?: Record<string, unknown>;
+};
+/** Per-call metadata overrides accepted by captureException/captureMessage/track. */
+interface CaptureOptions {
+    tags?: Record<string, string>;
+    contexts?: Record<string, Record<string, unknown>>;
+    extra?: Record<string, unknown>;
+}
+/** Options accepted by `track` — {@link CaptureOptions} plus a screen override. */
+interface TrackOptions extends CaptureOptions {
+    screen?: string;
+}
+/** Value accepted by `setUser` — normalized into a `UserContext`. */
+type UserInput = (Partial<UserContext> & {
+    id?: string | null;
+    email?: string | null;
+}) | null;
+type BeforeSend = (item: EnvelopeItem, hint?: Hint) => EnvelopeItem | null;
+type BeforeBreadcrumb = (breadcrumb: Breadcrumb, hint?: Hint) => Breadcrumb | null;
+/** Transport tuning knobs. */
+interface TransportOptions {
+    /** How often the pending batch is flushed, in ms. Default 5000. */
+    flushIntervalMs?: number;
+    /** Max items per envelope before an eager flush. Default 30. */
+    maxBatch?: number;
+    /** Cap on the offline localStorage queue, in bytes. Default 1 MiB. */
+    maxQueueBytes?: number;
+}
+/** Options accepted by `Sauron.init`. */
+interface InitOptions {
+    /** `https://<public_key>@<host>/<project_id>` */
+    dsn: string;
+    environment?: string;
+    release?: string;
+    /** Error sample rate in [0, 1]. Default 1 (send everything). */
+    sampleRate?: number;
+    /** Ring-buffer size for breadcrumbs. Default 50. */
+    maxBreadcrumbs?: number;
+    beforeSend?: BeforeSend;
+    beforeBreadcrumb?: BeforeBreadcrumb;
+    transport?: TransportOptions;
+    /**
+     * Auto-capture performance transactions (navigation, fetch, SPA routes) by
+     * patching `fetch`/History. Opt-in — default `false`. Manual
+     * `trackTransaction()` works regardless.
+     */
+    performance?: boolean;
+    /** Seed the initial screen name. */
+    screen?: string;
+    /**
+     * Auto-track the current screen from History navigations (reuses the SPA
+     * route hook). Opt-in — default `false`. `setScreen()` works regardless.
+     */
+    screenTracking?: boolean;
+    /** Default tags seeded into the global scope (string→string). */
+    tags?: Record<string, string>;
+    /** Default named context blocks seeded into the global scope. */
+    contexts?: Record<string, Record<string, unknown>>;
+    /** Default freeform extra seeded into the global scope. */
+    extra?: Record<string, unknown>;
+    debug?: boolean;
+}
+/** Fully-resolved options with all defaults applied. */
+interface ResolvedOptions {
+    dsn: string;
+    environment: string;
+    release: string | null;
+    sampleRate: number;
+    maxBreadcrumbs: number;
+    beforeSend?: BeforeSend;
+    beforeBreadcrumb?: BeforeBreadcrumb;
+    transport: Required<TransportOptions>;
+    performance: boolean;
+    screen?: string;
+    screenTracking: boolean;
+    tags: Record<string, string>;
+    contexts: Record<string, Record<string, unknown>>;
+    extra: Record<string, unknown>;
+    debug: boolean;
+}
+
+/** Partial breadcrumb — missing fields are filled with sensible defaults. */
+interface BreadcrumbInput {
+    type?: string;
+    category?: string;
+    message?: string | null;
+    level?: Level;
+    timestamp?: string;
+    data?: Record<string, unknown> | null;
+}
+
+/** Loose (camelCase) input accepted by {@link trackTransaction}. */
+interface TransactionInput {
+    name: string;
+    op?: string;
+    durationMs: number;
+    status?: string | null;
+    httpMethod?: string | null;
+    httpStatus?: number | null;
+    url?: string | null;
+}
+
+/**
+ * DSN parsing.
+ *
+ * A DSN looks like `https://<public_key>@<host>/<project_id>`. The public key
+ * is a non-secret, write-only credential — it is safe to ship in client code.
+ */
+interface Dsn {
+    /** The raw DSN string (embedded verbatim into the envelope header). */
+    raw: string;
+    publicKey: string;
+    /** `host:port` — used for the infinite-loop denylist. */
+    host: string;
+    /** Hostname without port. */
+    hostname: string;
+    /** `https` or `http` (no trailing colon). */
+    protocol: string;
+    projectId: string;
+    /** `POST` target for the primary transport. */
+    envelopeUrl: string;
+    /** `POST` target for the `sendBeacon` fallback (key in query string). */
+    beaconUrl: string;
+}
+declare class DsnError extends Error {
+    constructor(message: string);
+}
+/** Parse and validate a DSN, deriving the transport URLs. */
+declare function parseDsn(dsn: string): Dsn;
+
+/**
+ * Mutable per-client state: the current user, a ring buffer of breadcrumbs and
+ * free-form tags. The breadcrumb buffer is capped at `maxBreadcrumbs`; the
+ * oldest entries fall off the front (FIFO).
+ */
+declare class Scope {
+    private user;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    readonly tags: Record<string, string>;
+    readonly contexts: Record<string, unknown>;
+    readonly extra: Record<string, unknown>;
+    constructor(maxBreadcrumbs?: number);
+    setMaxBreadcrumbs(max: number): void;
+    setUser(user: UserInput): void;
+    /** The user context for an envelope. Never null — defaults to an empty user. */
+    getUser(): UserContext;
+    /** True when an identifiable user has been set. */
+    hasUser(): boolean;
+    setTag(key: string, value: string): void;
+    /** Merge a batch of tags into the scope (last-write-wins per key). */
+    setTags(tags: Record<string, string>): void;
+    /** Set (replace) a named context block on the scope. */
+    setContext(name: string, block: Record<string, unknown>): void;
+    /** Set a single freeform extra value on the scope. */
+    setExtra(key: string, value: unknown): void;
+    addBreadcrumb(breadcrumb: Breadcrumb): void;
+    /** A defensive copy of the current breadcrumb trail. */
+    getBreadcrumbs(): Breadcrumb[];
+    clearBreadcrumbs(): void;
+    private trim;
+}
+
+/**
+ * The Sauron client singleton. Owns the resolved options, the scope
+ * (user + breadcrumbs), the transport, and the installed integrations.
+ */
+declare class SauronClient {
+    readonly options: ResolvedOptions;
+    readonly dsn: Dsn;
+    private readonly scope;
+    private readonly transport;
+    private readonly logger;
+    private readonly nativeFetch?;
+    private enabled;
+    private installed;
+    private anonymousId;
+    private beaconCleanup;
+    constructor(options: ResolvedOptions);
+    /** Install global handlers + auto-instrumentation and start the transport. */
+    install(): void;
+    getScope(): Scope;
+    isEnabled(): boolean;
+    /** The current distinct id: the user id when identified, else an anon id. */
+    getDistinctId(): string | null;
+    /** The anonymous id, or null if one was never needed. */
+    getAnonymousId(): string | null;
+    private ensureAnonymousId;
+    /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
+    makeEnvelope(items: EnvelopeItem[]): Envelope;
+    /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
+    addBreadcrumb(breadcrumb: Breadcrumb, hint?: Hint): void;
+    /**
+     * Reconcile an error item to the shared wire shape by filling the optional
+     * `event_id`/`message`/`tags`/`user` fields from the current scope and hint.
+     * Each field is left untouched when the item already sets it, and omitted
+     * entirely when there is nothing to attach (the backend defaults it) — only
+     * `event_id` is always minted so callers can correlate the report.
+     */
+    private enrichErrorItem;
+    /**
+     * Run an item through sampling (errors only) and `beforeSend`, then hand it to
+     * the transport. Returns silently when dropped.
+     */
+    captureItem(item: EnvelopeItem, hint?: Hint): void;
+    /** Flush pending events. Resolves false if `timeoutMs` elapses first. */
+    flush(timeoutMs?: number): Promise<boolean>;
+    /** Disable the client (called on 401/403). Stops accepting/sending events. */
+    disable(): void;
+    /** Restore all patched globals and stop timers/listeners. */
+    teardown(): void;
+    /** Flush then tear down. Resolves to the flush result. */
+    close(timeoutMs?: number): Promise<boolean>;
+}
+/** The active client, or null before `init`. */
+declare function getClient(): SauronClient | null;
+
+/**
+ * Assemble a canonical envelope. This is intentionally trivial — the shape is
+ * the contract, so keep it a pure, side-effect-free constructor that mirrors
+ * the golden JSON exactly (header, context, items, in that order).
+ */
+declare function buildEnvelope(header: EnvelopeHeader, context: Context, items: EnvelopeItem[]): Envelope;
+
+/**
+ * Heuristic for whether a frame belongs to first-party ("in app") code:
+ * same-origin URLs and bare/relative paths are in-app; cross-origin URLs
+ * (typically CDN or third-party scripts) and internal frames are not.
+ */
+declare function isInAppFrame(filename: string | null): boolean;
+/**
+ * Parse a raw `Error.stack` string into normalized frames (crash frame last).
+ * Non-frame lines (the `Error: message` header, `[native code]`, etc.) are
+ * skipped.
+ */
+declare function parseStackString(stack: string | undefined | null): Frame[];
+/** Parse an `Error`-like object's `.stack`. */
+declare function parseError(err: unknown): Frame[];
+
+/** Small dependency-free helpers shared across the SDK. */
+/** SDK identity, embedded in every envelope header. */
+declare const SDK_NAME = "sauron.javascript";
+declare const SDK_VERSION = "1.0.0";
+
+/**
+ * `@edraj/sauron-browser` — public API surface.
+ *
+ * Error reporting + product analytics for the browser. Import the named
+ * functions, or the `Sauron` facade / default export.
+ *
+ * ```ts
+ * import { Sauron } from '@edraj/sauron-browser';
+ * Sauron.init({ dsn: 'https://pk_test@localhost:8081/1', release: 'web@1.4.2' });
+ * Sauron.track('checkout_completed', { cart_value: 42.5 });
+ * ```
+ */
+
+/** Initialize the SDK. See {@link InitOptions}. */
+declare function init(options: InitOptions): SauronClient;
+/** Capture an exception (or any thrown value). */
+declare function captureException(err: unknown, hint?: Hint): void;
+/** Capture a plain message at the given `level` (default `info`). */
+declare function captureMessage(message: string, level?: Level, hint?: Hint): void;
+/** Record a product-analytics event, optionally with per-call tags/contexts/extra. */
+declare function track(name: string, properties?: Record<string, unknown>, options?: TrackOptions): void;
+/** Associate the session with a known user. */
+declare function identify(id: string, traits?: Record<string, unknown>): void;
+/** Record a performance transaction (navigation, http, screen load, ...). */
+declare function trackTransaction(input: TransactionInput): void;
+/** Set the current screen (emits a `$screen` view on change). */
+declare function setScreen(name: string): void;
+/** The current screen name, or null. */
+declare function getScreen(): string | null;
+/** Record a breadcrumb. */
+declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
+/** Set (or clear, with `null`) the current user. */
+declare function setUser(user: UserInput): void;
+/** Set a single scope tag (lifted onto later errors/events). */
+declare function setTag(key: string, value: string): void;
+/** Merge a batch of scope tags (last-write-wins per key). */
+declare function setTags(tags: Record<string, string>): void;
+/** Set (replace) a named scope context block. */
+declare function setContext(name: string, block: Record<string, unknown>): void;
+/** Set a single freeform scope extra value. */
+declare function setExtra(key: string, value: unknown): void;
+/** Flush pending events. Resolves `false` if `timeoutMs` elapses first. */
+declare function flush(timeoutMs?: number): Promise<boolean>;
+/** Flush and tear down the SDK, restoring all patched globals. */
+declare function close(timeoutMs?: number): Promise<boolean>;
+
+/** Grouped facade + default export. */
+declare const Sauron: {
+    init: typeof init;
+    captureException: typeof captureException;
+    captureMessage: typeof captureMessage;
+    track: typeof track;
+    trackTransaction: typeof trackTransaction;
+    identify: typeof identify;
+    addBreadcrumb: typeof addBreadcrumb;
+    setUser: typeof setUser;
+    setTag: typeof setTag;
+    setTags: typeof setTags;
+    setContext: typeof setContext;
+    setExtra: typeof setExtra;
+    setScreen: typeof setScreen;
+    getScreen: typeof getScreen;
+    flush: typeof flush;
+    close: typeof close;
+    getClient: typeof getClient;
+};
+
+export { type AppContext, type BeforeBreadcrumb, type BeforeSend, type Breadcrumb, type BreadcrumbBatchItem, type BreadcrumbInput, type CaptureOptions, type Context, type DeviceContext, type Dsn, DsnError, type Envelope, type EnvelopeHeader, type EnvelopeItem, type ErrorItem, type EventItem, type ExceptionValue, type Frame, type Hint, type IdentifyItem, type InitOptions, type ItemType, type Level, type Mechanism, type OsContext, type ResolvedOptions, type RuntimeContext, SDK_NAME, SDK_VERSION, Sauron, SauronClient, type SdkInfo, type TrackOptions, type TransactionInput, type TransactionItem, type TransactionOp, type TransportOptions, type UserContext, type UserInput, addBreadcrumb, buildEnvelope, captureException, captureMessage, close, Sauron as default, flush, getClient, getScreen, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, setContext, setExtra, setScreen, setTag, setTags, setUser, track, trackTransaction };