@loxel.dev/pharos-browser 0.6.0

package/dist/index-c3taa3cg.js

@@ -0,0 +1,9 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import type { RecorderHandle } from "./replay/config";
+import type { ReplayUploadHandle, ReplayUploadOptions } from "./replay/wire";
+/** Context identifying who is asking, plus free-form targeting attributes. */
+export interface PharosContext {
+    contextKey: string;
+    application?: string;
+    release?: string;
+    sessionId?: string;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Minimal listener-registration surface auto-capture needs — matched by
+ * `window`/`globalThis` in a real browser, and by a plain fake in tests
+ * (bun test has no DOM, so `window` does not exist there).
+ */
+export interface ErrorListenerTarget {
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+    removeEventListener(type: string, listener: (event: unknown) => void): void;
+}
+export interface PharosConfig {
+    baseUrl: string;
+    clientKey: string;
+    context: PharosContext;
+    /**
+     * Injectable EventSource constructor, defaulting to the global
+     * `window.EventSource`. Exists so tests (and non-browser hosts) can
+     * supply a fake without a DOM.
+     */
+    eventSourceFactory?: (url: string) => EventSource;
+    /**
+     * Auto-capture uncaught errors (`window.onerror`) and unhandled promise
+     * rejections (`window.onunhandledrejection`) via `captureException`.
+     * Defaults to `true`; set `false` to only report via explicit
+     * `captureException` calls.
+     */
+    errors?: boolean;
+    /**
+     * Injectable event-listener target for auto-capture, defaulting to the
+     * global `window`/`globalThis`. Exists so tests (and non-browser hosts)
+     * can supply a fake without a DOM — mirrors `eventSourceFactory`.
+     */
+    errorTarget?: ErrorListenerTarget;
+}
+/** Options accepted by {@link PharosBrowserClient.captureException}. */
+export interface CaptureExceptionOptions {
+    /** Free-form label for where the error was caught (e.g. a route or component name). */
+    site?: string;
+    /** Extra scalar (or array-of-scalar) attributes to attach to this occurrence only. */
+    attributes?: Record<string, unknown>;
+}
+type PharosEvent = "change" | "error";
+type Listener = (payload: unknown) => void;
+export declare class PharosBrowserClient {
+    private baseUrl;
+    private clientKey;
+    private context;
+    private eventSourceFactory;
+    private flags;
+    private version;
+    private streamToken;
+    private eventSource;
+    private listeners;
+    private closed;
+    private reconnectTimer;
+    private errorsEnabled;
+    private errorTarget;
+    private replayHandle;
+    private replayTriggerKind;
+    private replayErrorListeners;
+    private onReplayError;
+    private onReplayRejection;
+    private constructor();
+    /** Bootstraps against the server, opens the live-update stream, and (by default) wires auto-capture. */
+    static init(config: PharosConfig): Promise<PharosBrowserClient>;
+    private bootstrap;
+    private connectStream;
+    /**
+     * EventSource auto-reconnects on transient drops. The one case it cannot
+     * recover from alone is an expired stream session (401 on the SSE
+     * request): the browser sees this as an error and keeps retrying the same
+     * dead token forever. Heuristic: when the source has settled into CLOSED
+     * (its terminal state — EventSource does not reach CLOSED on a retryable
+     * drop), re-bootstrap once after a short backoff to mint a fresh token,
+     * then reconnect the stream. This is intentionally simple — no queue, no
+     * exponential ramp — matching the brief's "don't over-engineer" guidance.
+     */
+    private maybeReconnect;
+    private onWindowError;
+    private onUnhandledRejection;
+    private registerErrorListeners;
+    private unregisterErrorListeners;
+    /**
+     * Reports one exception as a single-entry `/api/v1/errors` batch: message
+     * from `err.message ?? String(err)` (empty message becomes
+     * `"(no message)"`), `kind` from `err.name`, and `stack` parsed via
+     * {@link parseStack} when `err.stack` is a string. Every field is
+     * sanitized/truncated to the server's caps before sending — the server
+     * rejects the whole batch on any single field violating them, and this is
+     * most often called from uncaught-exception paths where the input isn't
+     * under the caller's control.
+     *
+     * Fire-and-forget: never throws, never returns a promise for the caller to
+     * await. A failed POST (network error, non-2xx) is reported via
+     * `on("error")`, matching the stream's existing error-reporting shape.
+     *
+     * A no-op after `close()`, matching `identify()`'s documented behavior —
+     * this client is terminal past `close()`.
+     */
+    captureException(err: unknown, opts?: CaptureExceptionOptions): void;
+    /**
+     * Routes this client's error paths into a running session recorder, so an
+     * error flushes a replay window around itself.
+     *
+     * The recorder is started SEPARATELY, by the application, via
+     * `startRecording()` — attaching a client never starts recording. That
+     * separation is the consent boundary: adding the SDK must not begin
+     * recording a user's screen.
+     *
+     * ONE RECORDER AT A TIME, ENFORCED BY THROWING. rrweb's `record` is a
+     * process singleton (`wrappedEmit`, `takeFullSnapshot`, `mirror` and the
+     * `recording` flag are all module-level in rrweb 2.1.1), so a second
+     * `startRecording()` silently takes the session over: the first recorder's
+     * observers begin emitting into the SECOND recorder's buffer while the
+     * first handle still reports healthy stats. This is the one place a client
+     * can observe two recorders at once, and it refuses rather than swapping —
+     * swapping would leave the caller holding a handle it believes is wired,
+     * and stopping the first for them would set rrweb's module-level
+     * `recording = false` and half-kill the survivor. Re-attaching the SAME
+     * handle is idempotent; deliberately swapping means `detachReplay()` first.
+     *
+     * Unhandled promise rejections are guaranteed triggers. With auto-capture
+     * on (the default) they already route through `captureException`, and no
+     * extra listener is added — a second listener would double-count one
+     * rejection. With `errors: false` the window listeners were never
+     * registered, so this registers REPLAY-ONLY listeners that trigger the
+     * recorder without reporting anything to the errors API, leaving the app's
+     * opt-out intact.
+     *
+     * TWO MISUSES, TWO DIFFERENT ANSWERS, ON PURPOSE. Attaching after `close()`
+     * is a SILENT no-op, because a closed client is terminal — the same answer
+     * `identify()` and `captureException()` give, and nothing is left running
+     * for the caller to be wrong about. Attaching a SECOND, different handle
+     * THROWS, because that is a live contract violation with a resource
+     * collision behind it: two recorders exist, one of them is already being
+     * taken over, and silence would leave the caller holding a handle it
+     * believes is wired.
+     *
+     * @throws if a DIFFERENT recorder is already attached.
+     */
+    attachReplay(handle: RecorderHandle): void;
+    /**
+     * TWO INDEPENDENTLY-MINTED VALUES UNDER ONE NAME (final review, Important 4).
+     *
+     * `PharosContext.sessionId` is what rides the errors envelope
+     * (`captureException` above) and what `error_store.lox` stores.
+     * `startReplayUpload` mints its OWN unless the host passes one. When they
+     * disagree, an error row and the replay window captured around that same
+     * error CANNOT BE JOINED — which is precisely the correlation slice B3's
+     * console exists to perform, and nothing anywhere would have said so.
+     *
+     * A WARNING, NOT A THROW, and not a silent repair. `attachReplay` throws for
+     * a second recorder because that is a live resource collision; this is a
+     * degraded-correlation wiring mistake on an already-working setup, and the
+     * app author is the only one who can decide which id is authoritative.
+     * Repairing it here would mean re-keying windows the recorder has already
+     * uploaded under the other id, which this client cannot do. `startReplay()`
+     * below is the version that cannot get it wrong.
+     */
+    private warnIfSessionIdsDisagree;
+    /**
+     * Starts a replay recorder wired to THIS client — same base URL, same client
+     * key, and THE SAME `sessionId` the errors envelope carries.
+     *
+     * The reason this exists rather than leaving every application to call
+     * `startReplayUpload` itself: the two session ids above are two independent
+     * values under one name, and an application that never noticed gets a
+     * replay pillar whose windows cannot be joined to the errors that produced
+     * them. Here there is one id by construction.
+     *
+     * Also attaches the handle (`attachReplay`), so an uncaught error triggers a
+     * window — the whole point of the pairing. A client that already has a
+     * different recorder attached throws, exactly as `attachReplay` does —
+     * except that by the time `attachReplay` can throw, THIS function has
+     * already started a live recorder `attachReplay` never gets to own:
+     * `handle`'s `visibilitychange`/`pagehide` listeners are attached, its
+     * start-up drain has already run, and no caller holds the reference needed
+     * to `stop()` any of that. So the throw here also stops the orphan first,
+     * which is not part of what `attachReplay` itself does or needs to do —
+     * `attachReplay` never allocates.
+     *
+     * `endpoint` and `appKey` are supplied and may not be overridden; every
+     * other `startReplayUpload` option passes through unchanged. Resolves to
+     * `null` after `close()`, matching `attachReplay`'s silent no-op on a
+     * terminal client — a handle recording into a closed client would be a
+     * recorder nothing triggers.
+     *
+     * ASYNC BECAUSE IT LOADS THE RECORDER ON DEMAND (0.6.0). rrweb is ~63 kB
+     * gzipped, and while this was synchronous it was reachable from the root
+     * entry and therefore bundled by every consumer — including the ones that
+     * never record. It is now a dynamic `import()`, so the recorder is a
+     * separate chunk fetched only when an application actually starts replay.
+     * The chunk still ships with the deployment, which is the point: enabling
+     * replay stays a pure configuration change (loxel#979), it just stops
+     * costing anything up front. Rejects only if the chunk itself cannot load.
+     */
+    startReplay(options?: Omit<ReplayUploadOptions, "endpoint" | "appKey">): Promise<ReplayUploadHandle | null>;
+    /** Stops routing errors into the recorder. Does not stop the recorder itself. */
+    detachReplay(): void;
+    /** Synchronous flag lookup; falls back to defaultValue for unknown keys. */
+    flag<T>(key: string, defaultValue: T): T;
+    /** Subscribes to "change" (a new flags payload was applied) or "error". Returns an unsubscribe function. */
+    on(event: PharosEvent, cb: Listener): () => void;
+    private emit;
+    /**
+     * Re-identifies as a new context: closes the current stream, re-bootstraps
+     * (a full round trip — flags plus a fresh streamToken), and reconnects.
+     */
+    identify(context: PharosContext): Promise<void>;
+    /** Closes the stream, stops any pending reconnect, and unregisters auto-capture. Terminal — construct a new client to resume. */
+    close(): void;
+}
+export { MASK_TOKEN, maskText } from './privacy/mask';
+export { EXCLUDE_CLASS, MASK_CLASS, shouldExclude, shouldMaskByMarker } from './privacy/markers';
+export { isSensitiveField } from './privacy/sensitivity';
+export { scrubAttribute, scrubUrl } from './privacy/attributes';
+export { decide, masksValue, type Decision } from './privacy/policy';
+export { collectRecordedStrings, type RecordedString } from './privacy/collect';
+export { MAX_BUFFER_BYTES, RECORDER_DEFAULTS, resolveConfig, type ActivationMode, type DegradationReason, type DegradationRecord, type RecorderHandle, type RecorderOptions, type RecorderStats, type ReplayWindow, type ResolvedRecorderConfig, type Sink, type TriggerInfo, type TriggerKind, type TriggerSource, } from './replay/config';
+export { ACTIVATION_EVENT_TAG } from './replay/interactions';
+export { beginsWithSnapshot } from './replay/buffer';
+export type { ReplayUploadHandle, ReplayUploadOptions } from './replay/wire';
+export { MAX_WINDOW_BYTES, createUploadSink, encodeWindow, envelopeMetaFor, postEnvelope, type PostTarget, type UploadEnvelopeMeta, type UploadOptions, } from './replay/upload';
+export { LOCAL_TTL_MS, clearPersisted, drainPersisted, persistWindow, quotaDroppedWindows, resetQuotaDroppedWindows, } from './replay/persist';
+export { createDropLedger, type DropLedger, type DropReason } from './replay/drops';
+export type { WindowDropReason } from './replay/config';