@scalebun-release/sdk-contracts 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleBun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bridge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @scalebun/sdk-contracts — Debug Bridge Types (optional)
+ *
+ * Pure types for the optional dev/desktop-debugger bridge (parity with the RN SDK's debug bridge).
+ * Not part of the ingestion protocol — that lives in @scalebun/protocol. Kept minimal for now;
+ * the web debug transport is not implemented yet.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface BaseMessage {
+    type: string;
+    ts: number;
+}
+export interface HelloMessage extends BaseMessage {
+    type: 'hello';
+    sdk: {
+        name: string;
+        version: string;
+    };
+    sessionId: string;
+}
+export interface PingMessage extends BaseMessage {
+    type: 'ping';
+}
+export interface PongMessage extends BaseMessage {
+    type: 'pong';
+}
+export type DebugMessage = HelloMessage | PingMessage | PongMessage;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC"}

package/dist/bridge.js

@@ -0,0 +1,9 @@
+/**
+ * @scalebun/sdk-contracts — Debug Bridge Types (optional)
+ *
+ * Pure types for the optional dev/desktop-debugger bridge (parity with the RN SDK's debug bridge).
+ * Not part of the ingestion protocol — that lives in @scalebun/protocol. Kept minimal for now;
+ * the web debug transport is not implemented yet.
+ */
+export {};
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/config.d.ts

@@ -0,0 +1,412 @@
+/**
+ * @scalebun/sdk-contracts — Config Types
+ *
+ * Pure type definitions for the public init config. Runtime defaults/validation live in
+ * @scalebun/web (core/config). Mirrors the RN SDK's config contract, adapted for the browser.
+ */
+import type { ErrorItem, Breadcrumb, NetworkItem } from '@scalebun/protocol';
+/** The features that can be toggled (all default ON except replay, which is lazy/opt-in). */
+export interface ScaleBunFeatures {
+    errors?: boolean;
+    network?: boolean;
+    console?: boolean;
+    webVitals?: boolean;
+    performance?: boolean;
+    journey?: boolean;
+    replay?: boolean;
+    bugReport?: boolean;
+    /** Web crash detection (ReportingObserver + session-liveness recovery). Default on. */
+    crash?: boolean;
+    /** Config & flags (feature flags / remote config / rollouts / experiments). Default on. */
+    config?: boolean;
+    /** Engage — surveys / NPS (in-app prompts, friction-triggered). Default on. */
+    engage?: boolean;
+    /** Product-analytics + revenue lane (track/trackPurchase → /batch Event). Default on. */
+    analytics?: boolean;
+    /** Web RUM — page-load (Navigation Timing) + FPS (rAF) + LoAF. Default on. */
+    webPerf?: boolean;
+    /** JS Self-Profiling flame graphs. Default OFF (CPU cost + needs Document-Policy: js-profiling). */
+    profiler?: boolean;
+    /** W5.2 — Resource Watchdog (continuous resource sampling + local incident detection). Default OFF. */
+    watchdog?: boolean;
+    /** Persistent Message Inbox / Notification Center (offline-first, delta-synced). Default OFF (until GA). */
+    inbox?: boolean;
+    /** IAM 2.0 in-app engine (schema-driven surfaces). Default false (opt-in). */
+    inapp2?: boolean;
+}
+/** Privacy controls. Mask-all-by-default is non-negotiable; these only narrow it. */
+export interface PrivacyConfig {
+    /** Capture network request/response bodies (redacted). Default false (denylist-by-default). */
+    captureNetworkBodies?: boolean;
+    /** Header/body keys always stripped before send. */
+    denylist?: string[];
+    /** CSS selectors whose text/inputs are masked (in addition to mask-all defaults). */
+    maskSelectors?: string[];
+    /**
+     * Mask ALL static text in session replay (default **false** — text is captured so replays are
+     * readable). Set true to mask every text node. Form input VALUES have their OWN flag (`maskInputs`).
+     */
+    maskReplayText?: boolean;
+    /**
+     * Mask form input VALUES in session replay. Default **true**, and **independent of
+     * `maskReplayText`** — typed input is the real PII exposure, so it stays masked even when static
+     * text is shown (the default). Password fields are ALWAYS blanked regardless of this flag.
+     *
+     * ⚠️ Setting this false captures real user input — only do this for internal/dev apps with no PII.
+     * For apps handling personal data (e.g. healthcare), keep it on.
+     */
+    maskInputs?: boolean;
+    /**
+     * Honor the user's **Global Privacy Control** / **Do-Not-Track** signal (default **false**). When
+     * true and the browser signals opt-out (`navigator.globalPrivacyControl` / `navigator.doNotTrack`),
+     * session replay does not record for that user. Recommended where GPC compliance (e.g. CCPA) matters.
+     */
+    respectDnt?: boolean;
+    /**
+     * Mask the TEXT LABEL on captured interaction events (default **false** — the real label is sent).
+     *
+     * Applies to two places, and only these two:
+     *   - `USER_ACTION.label` on the session lane (`button: Buy now`)
+     *   - `props.text` on `$autocapture` in the analytics lane
+     *
+     * This used to be unconditional, and it is why the Events explorer showed rows like `button: *** ***`:
+     * every non-whitespace character was replaced with `*`, which preserved the shape of the text and
+     * destroyed the only value that made one click distinguishable from another. Two different buttons
+     * with same-length text collapsed into ONE row, so per-element click analytics were not possible.
+     *
+     * The default matches `maskReplayText`, which has always been false — the SDK already captures visible
+     * replay text, so hard-masking the label of the very click that replay shows was inconsistent.
+     *
+     * ⚠️ With this off (the default) the element's visible text is captured. On a page whose button or
+     * link text contains personal data ("Delete account for ada@example.com"), turn it on, or exclude the
+     * subtree with `data-scalebun-no-capture`, or list it in `maskSelectors`. Input VALUES are never
+     * captured by either path regardless of this flag.
+     */
+    maskEventText?: boolean;
+}
+/**
+ * Engage options. Currently just the gamified-outcome resolver.
+ *
+ * The handler is typed loosely HERE and precisely at the call site (`features/engage/gameTypes`).
+ * Contracts is imported by every entry point, and pulling the eight-variant discriminated union in
+ * would put ~0 runtime bytes but a real maintenance edge in core's dependency graph — the request
+ * and result shapes belong with the code that builds and validates them. Hosts get full types by
+ * importing `InAppGameRequestHandler` from the SDK.
+ */
+export interface EngageOptions {
+    onInAppGameRequest?: (request: unknown) => Promise<unknown>;
+}
+/** Where the floating bug-report launcher sits. */
+export type BugReportPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/** Embeddable bug-report widget options. */
+export interface BugReportOptions {
+    /** Mount a floating launcher button. Default false (use ScaleBun.reportBug(...) programmatically). */
+    launcher?: boolean;
+    /** Launcher corner. Default 'bottom-right'. */
+    position?: BugReportPosition;
+    /** Launcher button label. Default 'Report a bug'. */
+    label?: string;
+}
+/** End-user identity attached to the session. */
+export interface ScaleBunUser {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/** Session-replay capture mode. See `ScaleBunInitConfig.replay`. */
+export type ReplayMode = 'off' | 'onError' | 'sampled' | 'always';
+/** Public init config consumers pass to ScaleBun.init(). */
+export interface ScaleBunInitConfig {
+    /** SaaS SDK key — sent as `x-scalebun-client-key`. */
+    clientKey: string;
+    /**
+     * Backend base URL, e.g. https://api.scalebun.com/api/v1. Optional — defaults
+     * to the ScaleBun cloud. Override only for staging or a self-hosted backend.
+     */
+    apiBaseUrl?: string;
+    environment?: string;
+    release?: string;
+    appVersion?: string;
+    /** Content-Security-Policy options. `nonce` is applied to every <style>/<script> the SDK injects, so
+     *  strict-CSP sites (style-src/script-src without 'unsafe-inline') work. Optional — absent = today's
+     *  behavior. On a <script>-tag install the SDK also auto-detects the nonce from its own tag. */
+    csp?: {
+        nonce?: string;
+    };
+    flushIntervalMs?: number;
+    /**
+     * Inactivity after which the next page load starts a NEW session (default 30 min).
+     *
+     * A session is persisted across document loads, so a refresh or a second tab CONTINUES the
+     * current session rather than starting another one; it ends only after this much idle time.
+     */
+    sessionTimeoutMs?: number;
+    /** Absolute cap on one session (default 24 h), so a permanently-open tab cannot report an
+     *  endless session. */
+    sessionMaxDurationMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    /**
+     * Session-replay sampling. Deterministic per-session decision (the SDK buckets the sessionId with
+     * the same fnv1a as flags/experiments, so the backend can re-derive it — no client trust).
+     *  - 'sampled' (DEFAULT): record the FULL session from the first frame for `sampleRate` of sessions
+     *    (default 1 = every session, like the mobile SDK). Dial `sampleRate` down to control volume.
+     *  - 'onError': record into a rolling pre-roll buffer, flush it only when an error/rage/report
+     *    signal fires (cost-saver — ships only sessions that hit a problem). `onErrorSampleRate` gates it.
+     *  - 'always': record every session from start, ignoring `sampleRate`. 'off': never record.
+     * A session that isn't sampled installs NOTHING (zero overhead).
+     */
+    replay?: {
+        mode?: ReplayMode;
+        sampleRate?: number;
+        onErrorSampleRate?: number;
+        /** Opt-in: mirror the pre-roll buffer to IndexedDB so a tab-killing crash still yields it on the
+         *  next load (an error-free clean close discards it). Default false. */
+        persistBuffer?: boolean;
+        /** 'strict' adds heuristic PII redaction (emails / card numbers / SSNs) to captured text — useful
+         *  when replay text is UNMASKED (privacy.maskReplayText:false). Default 'standard'. */
+        privacyLevel?: 'standard' | 'strict';
+    };
+    /** Opt-in: capture <canvas> pixels in replay (off by default — pixels can't be masked). */
+    replayCanvas?: boolean;
+    /**
+     * Upload a DOM replay frame’s payload straight to object storage instead of inline in the
+     * batch envelope. Off by default. Against a backend without the matching presign support the
+     * SDK is told storage is disabled and every frame goes inline, so enabling it early is inert
+     * rather than harmful.
+     */
+    replayDirectUpload?: boolean;
+    /** Opt-in: HMAC-sign session/replay batches too (the analytics lane always signs). Off by default —
+     *  signing multi-MB replay uploads re-enables server-side rawBody double-buffering. */
+    signSessionLane?: boolean;
+    /** Cross-origin replay stitching (F-IFR P2): origins the parent bridges + a child trusts. Both the
+     *  parent page and the cross-origin child must run the SDK with each other's origin listed. e.g.
+     *  parent lists ['https://embed.example.com'], child lists ['https://app.example.com']. Default []. */
+    replayFrameOrigins?: string[];
+    /** Autocapture DOM interactions as analytics events (on by default; text masked). Set false to opt out. */
+    autocapture?: boolean;
+    /** Inject a W3C `traceparent` into outbound requests for FE→BE trace correlation. Default true
+     *  (same-origin only — safe). Set false to disable entirely. */
+    tracePropagation?: boolean;
+    /** Cross-origin origins to ALSO propagate the traceparent to (the server must CORS-allow the
+     *  `traceparent` header). e.g. ['https://api.example.com']. Default []. */
+    tracePropagationOrigins?: string[];
+    /** Error capture tuning (F-ERR). All optional — defaults need no config. */
+    errors?: {
+        /** Drop errors whose MESSAGE matches (substring or RegExp). Merged with built-in benign noise
+         *  (e.g. "ResizeObserver loop…") — your list is appended, never replaces the defaults. */
+        ignoreErrors?: (string | RegExp)[];
+        /** Drop errors whose originating script URL matches (substring or RegExp) — silence noisy
+         *  third-party scripts (chrome-extension://, ad/analytics vendors, …). */
+        denyUrls?: (string | RegExp)[];
+        /** Capture failed resource loads (img/script/link/css) as 'resource' errors instead of dropping
+         *  them. Default false — they're usually noise, and never JS crashes. */
+        captureResourceErrors?: boolean;
+        /** Max breadcrumbs retained in the ring + attached to each error (the trail of console/network/
+         *  navigation/click events leading up to it). Default 50, max 200. */
+        maxBreadcrumbs?: number;
+        /** Cost lever for very-high-volume apps: fraction of SESSIONS (0–1) whose AUTO errors are captured
+         *  (deterministic per-session; manual captureError always fires). Default 1 = every session.
+         *  Prefer grouping / ignoreErrors / beforeSend first — sampling trades error completeness for cost. */
+        sampleRate?: number;
+        /** Last-mile hook: inspect/transform each error item before it's sent, or return null to DROP it
+         *  (e.g. scrub fields, drop by URL/tag). Throwing is safe — the original is kept. */
+        beforeSend?: (item: ErrorItem) => ErrorItem | null;
+        /** Hook: inspect/transform each breadcrumb before it enters the ring, or return null to drop it. */
+        beforeBreadcrumb?: (crumb: Breadcrumb) => Breadcrumb | null;
+    };
+    /** Network capture tuning (F-NET). All optional — defaults need no config. */
+    network?: {
+        /** Track WebSocket connection lifecycle + message/byte counters. Default true (lazy chunk). */
+        trackWebSocket?: boolean;
+        /** Track Server-Sent-Events (EventSource) lifecycle. Default true (lazy chunk). */
+        trackSse?: boolean;
+        /** Opt-in: capture request/response bodies + headers (redacted + capped). Default false (privacy). */
+        captureBodies?: boolean;
+        /** Hard cap on captured body bytes when captureBodies is on. Default 8192, ceiling-enforced. */
+        bodyMaxBytes?: number;
+        /** Content-types eligible for body capture. Default ['application/json','text/plain']. */
+        contentTypeAllowlist?: string[];
+        /** Base sample rate (0–1) for SUCCESSFUL requests — failed/slow are ALWAYS kept. Default 1. */
+        sampleRate?: number;
+        /** "slow" threshold in ms — requests at/over this are flagged + always kept. Default 2000. */
+        slowRequestMs?: number;
+        /** Never capture requests whose URL matches (substring or RegExp). */
+        denyUrls?: (string | RegExp)[];
+        /**
+         * Keep known telemetry beacons: analytics collectors, ad pixels, IP-enrichment calls.
+         *
+         * Default false -- they are dropped before they ever leave the browser. They are not the app,
+         * they cost the visitor upload bandwidth, and a beacon blocked by an ad blocker is a transport
+         * failure that used to count against the SESSION HEALTH score. Matching is by hostname only,
+         * never by path, so your own /collect route is never touched.
+         */
+        captureThirdParty?: boolean;
+        /** Replace the built-in beacon host list wholesale. Comma-joined hostname suffixes. */
+        thirdPartyHosts?: string;
+        /** Last-mile hook: transform the network item, or return null to DROP it. Throwing is safe. */
+        beforeSend?: (item: NetworkItem) => NetworkItem | null;
+    };
+    /** Performance / RUM tuning (transactions, spans). All optional — defaults need no config. */
+    performance?: {
+        /** Base sample rate (0–1) for transactions. SLOW/errored transactions are ALWAYS kept regardless;
+         *  this only thins the fast, clean ones. Deterministic per-transaction (re-derivable from traceId).
+         *  Default 1 = keep every transaction. */
+        tracesSampleRate?: number;
+        /** Duration (ms) at/over which a transaction is "slow" → always kept (the adaptive bias). Default 3000. */
+        slowTransactionMs?: number;
+    };
+    /** W5.2 — Resource Watchdog tuning (continuous resource sampling → local incidents). All optional. */
+    watchdog?: {
+        /** Per-session deterministic keep rate (0–1). Default 1. */
+        sampleRate?: number;
+        /** Event-loop-lag heartbeat cadence (ms). Default 1000, floored at 250. */
+        heartbeatMs?: number;
+        /** Health-rollup window (ms) — one resource_health item per window. Default 30000. */
+        rollupMs?: number;
+        /** Heap sample cadence (ms). Default 20000. */
+        memorySampleMs?: number;
+        /** Incident-threshold overrides (see the WatchdogThresholds keys). */
+        thresholds?: Record<string, number>;
+        /** 5.3 — capture a JS Self-Profiling window on an incident (no-op until the header + phase land). Default true. */
+        captureProfileOnIncident?: boolean;
+    };
+    /**
+     * #25 P2 — exit-intent scroll-reversal thresholds. All optional; omitted keys use REVERSAL_DEFAULTS.
+     *
+     * Host-tunable on purpose: every default is a guess until real `$exit_intent` distributions exist, and
+     * an SDK release is the slowest step in that loop. A site can retune from its own data without waiting
+     * for one. The event carries `velocity_px_ms` + `distance_px` so there is something to tune FROM.
+     *
+     * Note `minDistancePx` and `minVelocityPxMs` are not independent: at dt = windowMs the velocity floor
+     * binds and distance decides nothing. Raise them together.
+     */
+    exitIntent?: {
+        /** How far back to measure upward velocity (ms). Default 120. */
+        windowMs?: number;
+        /** Minimum upward travel across the window (px) — filters micro-corrections. Default 80. */
+        minDistancePx?: number;
+        /** Minimum upward velocity (px/ms). Default 0.7 (≈700 px/s) — a flick, not a drift. */
+        minVelocityPxMs?: number;
+        /** Engagement floor: minimum max scroll depth reached (%). Default 25. */
+        minDepthPct?: number;
+        /** Consecutive qualifying samples required (hysteresis vs scroll jitter). Default 3. */
+        sustainSamples?: number;
+        /**
+         * Pointer-exit band: how close to the top edge (px) the pointer must be when it leaves the page.
+         * Default 40.
+         *
+         * Belongs to the OTHER trigger, not scroll reversal. `mouseout` reports the last SAMPLED pointer
+         * position, and a fast flick toward the tab bar covers tens of pixels between samples — so a narrow
+         * band misses exactly the deliberate gestures it exists to catch. Raise it if pointer exits are
+         * under-reported; the event carries `exit_y` so you can tune from the real distribution.
+         */
+        topEdgePx?: number;
+    };
+    /** Product-analytics tuning. All optional — analytics works with none of this set. */
+    analytics?: {
+        /** A3 — optional typed tracking plan. Governs custom `track()` events (internal `$` events are
+         *  never governed): warns on unknown events / missing-required / type-mismatch props, and — in
+         *  `strict` mode — DROPS violations from both lanes. */
+        plan?: TrackingPlan;
+        /** A6 — analytics-lane sample rate (0–1, default 1 = keep all). Sampling is PER-USER + deterministic
+         *  (a stable subset of anonymous ids is kept in full, so funnels/retention stay intact). Identity
+         *  ($identify/$group/$alias) and revenue (purchase) events are NEVER thinned. */
+        sampleRate?: number;
+        /** A6 — set to share the anonymous id across sub-domains via a cookie (e.g. '.example.com'), so a
+         *  user is one profile across app./www./shop. When unset, the id is localStorage-scoped per origin. */
+        cookieDomain?: string;
+    };
+    /** Feature-flag / config options. */
+    flags?: {
+        /** F3 — bootstrap seed applied synchronously at init (SSR handoff) so the first paint uses real
+         *  values instead of defaults — no flash-of-default on a cold cache. Shape mirrors GET /config. */
+        bootstrap?: FlagsBootstrap;
+        /** F4 — subscribe to the realtime config stream (SSE) so a kill-switch flip / flag edit reaches
+         *  the client in seconds instead of waiting for the periodic refresh. Default true; set false to
+         *  rely on the foreground-poll refresh only (no persistent connection). */
+        realtime?: boolean;
+    };
+    features?: ScaleBunFeatures;
+    privacy?: PrivacyConfig;
+    /** Bug-report widget (F-BUG) options. The feature is enabled via features.bugReport; these tune
+     *  the optional embeddable launcher. Default: launcher off (programmatic reportBug() only). */
+    bugReportOptions?: BugReportOptions;
+    /**
+     * Engage options.
+     *
+     * `onInAppGameRequest` is how the EIGHT gamified in-app formats get their outcome. Deliberately
+     * NOT optional-with-a-default: the SDK has no randomness in it, because a browser that picks its
+     * own prize can be made to pick again. The host app's backend grants or reserves the reward and
+     * returns it; ScaleBun never holds prize inventory.
+     *
+     * Named to match the React Native SDK's provider prop exactly, so one handler serves both
+     * platforms. Without it, those formats render their unavailable state rather than a wrong prize.
+     */
+    engageOptions?: EngageOptions;
+    /**
+     * Web Push options.
+     *
+     * `softAsk` renders the SDK's own in-page prompt and calls `push.enable()` from its Allow button.
+     * That button click IS the user activation browsers require — which is why a host would otherwise
+     * have to wire up a gesture themselves just to be allowed to ask.
+     *
+     * ⚠️ Asking through this first is not politeness, it is protection: a "Not now" here is reversible,
+     * whereas a browser-level Block is permanent and unrecoverable by the SDK. Chrome also demotes
+     * sites with poor accept rates to a near-invisible prompt, so a badly-timed direct ask can cost a
+     * tenant the ability to ask at all.
+     *
+     * The implementation is loaded lazily and costs nothing when this is absent.
+     */
+    push?: {
+        softAsk?: {
+            trigger?: 'immediate' | {
+                afterMs: number;
+            } | {
+                onSelector: string;
+            };
+            title?: string;
+            body?: string;
+            allowText?: string;
+            denyText?: string;
+            /** Days before re-asking after a dismissal. Persisted, so it survives reloads. */
+            remindAfterDays?: number;
+            accent?: string;
+        };
+    };
+    /**
+     * Consent-mode (GDPR/CIPA). When true, the SDK captures + sends NOTHING until the host calls
+     * `ScaleBun.setConsent(true)` (typically from a CMP callback). Default false = capture immediately.
+     */
+    requireConsent?: boolean;
+    /** Pre-known consent (SSR/cookie) so a host can skip the wait. Default 'unknown' when gated. */
+    initialConsent?: 'granted' | 'denied' | 'unknown';
+    debug?: boolean;
+}
+/** F3 — the flags/config seed passed to `init({ flags: { bootstrap } })`. Structurally mirrors the
+ *  GET /config payload; typed loosely here so the contracts package stays independent of the web SDK's
+ *  concrete SdkConfigPayload (the SDK narrows it). */
+export interface FlagsBootstrap {
+    version?: string;
+    flags?: unknown[];
+    remoteConfig?: unknown[];
+    experiments?: unknown[];
+    rollouts?: unknown[];
+    entitlements?: Record<string, boolean>;
+}
+/** A3 — a typed tracking plan (Amplitude/Segment-Protocols style), enforced client-side. */
+export interface TrackingPlan {
+    /** Per-event contracts. An event absent from this map is "unknown" (see allowUnknownEvents). */
+    events?: Record<string, {
+        /** Property keys that must be present. */
+        required?: string[];
+        /** Expected primitive type per property key. */
+        props?: Record<string, 'string' | 'number' | 'boolean'>;
+    }>;
+    /** Allow events not declared in `events` (default true → warn only, never drop). */
+    allowUnknownEvents?: boolean;
+    /** Drop violating events from both lanes instead of only warning (default false). */
+    strict?: boolean;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Config Types
+ *
+ * Pure type definitions for the public init config. Runtime defaults/validation live in
+ * @scalebun/web (core/config). Mirrors the RN SDK's config contract, adapted for the browser.
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/events.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @scalebun/sdk-contracts — Context Types
+ *
+ * Pure context type definitions. The wire-level item/envelope schemas live in @scalebun/protocol;
+ * these are the in-SDK context shapes used while assembling those payloads.
+ */
+export interface UserContext {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface AppContext {
+    name?: string;
+    version?: string;
+    build?: string;
+    environment?: string;
+    release?: string;
+}
+export interface DeviceContext {
+    id: string;
+    model?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    locale?: string;
+}
+export interface SessionContext {
+    id: string;
+    startTime: number;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/events.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Context Types
+ *
+ * Pure context type definitions. The wire-level item/envelope schemas live in @scalebun/protocol;
+ * these are the in-SDK context shapes used while assembling those payloads.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/features.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @scalebun/sdk-contracts — Feature Contract
+ *
+ * Pure interface definitions for pluggable SDK features. No runtime implementation.
+ * Mirrors the RN SDK's fail-isolated IFeature/FeatureContext model.
+ */
+import type { Item, ErrorItem, NetworkItem } from '@scalebun/protocol';
+import type { ReplayMode, TrackingPlan, FlagsBootstrap } from './config.js';
+/** Context provided to features during setup. The narrow surface a feature is allowed to touch. */
+export interface FeatureContext {
+    /** The current session id (e.g. to correlate a recovered-crash signal to the dead session).
+     *  Always set by the bootstrap at runtime; optional so feature unit-test mocks stay terse. */
+    sessionId?: string;
+    /** Public client key (scalebun_ck_…) — a feature calling its own backend lane (e.g. config/flags) uses
+     *  it for `x-scalebun-client-key` auth. Set by the bootstrap; optional for terse test mocks. */
+    clientKey?: string;
+    /** Stable per-browser device id — deterministic flag/experiment bucketing keys off it (must match
+     *  the id used for capture so bucketing is stable). Set by the bootstrap; optional for test mocks. */
+    deviceId?: string;
+    /** App/release version (from init config). Read by Engage to send the config-query `appVersion` the
+     *  backend uses for minAppVersion targeting. Optional. */
+    appVersion?: string;
+    /**
+     * The currently IDENTIFIED user id, or undefined while anonymous.
+     *
+     * Read by Engage / IAM to send the config-query `endUserId`, which is what the backend needs to
+     * resolve segment targeting. Without it a segment-targeted campaign fails closed and is never
+     * served — the RN SDK has always sent it, web did not, so segment targeting was silently dead on
+     * web. A getter (not a value) because identity changes after the context is built: the host app
+     * typically calls identify() at login, long after setup().
+     */
+    getUserId?: () => string | undefined;
+    /** Enqueue a signal item onto the ONE unified pipeline. */
+    emit: (item: Item) => void;
+    /**
+     * File an item against a DIFFERENT session than the live one.
+     *
+     * Exists for exactly one situation: a signal that is ABOUT a session that already ended, produced
+     * after the next one began. Crash recovery is the case — a tab that dies hard cannot report its
+     * own death, so the following load finds the unfinished marker and reports it. Sent via `emit`,
+     * that crash landed on the freshly-opened session, which is how a healthy session came up already
+     * marked crashed at t≈0 while the session that actually died stayed clean. Verified against real
+     * rows: 4 of 4 recovered crashes were filed against the wrong session.
+     *
+     * Optional so mobile bootstraps and terse test mocks are unaffected; callers must fall back.
+     */
+    emitFor?: (sessionId: string, item: Item) => void;
+    /** Track a custom event (sugar over emit for a kind:'event' item). */
+    trackEvent: (name: string, props?: Record<string, unknown>) => void;
+    /** Current page lifecycle state. */
+    getAppState: () => 'active' | 'background' | 'inactive';
+    /** Debug logger (no-op unless debug is enabled). */
+    log: (...args: unknown[]) => void;
+    /** The SDK's own ingestion base URL — features use it to self-exclude their own traffic. */
+    apiBaseUrl: string;
+    /**
+     * Raise a capture signal ('error' | 'rage' | 'report' | …) — arms capture-on-signal features.
+     *
+     * `detail` is optional and additive: subscribers that only care about the reason ignore it, and every
+     * existing caller keeps working unchanged. It exists so a signal can carry the few fields a
+     * subscriber needs without the raiser having to reach into another feature — ErrorsFeature attaches
+     * the error's type/fingerprint so AnalyticsFeature can promote it to `$exception`.
+     */
+    signal: (reason: string, detail?: Record<string, unknown>) => void;
+    /** Subscribe to capture signals. Returns an unsubscribe fn. */
+    onSignal: (cb: (reason: string, detail?: Record<string, unknown>) => void) => () => void;
+    /** Opt-in flag for replay <canvas> pixel capture (read by ReplayFeature). Default off. */
+    replayCanvas?: boolean;
+    /** See ScaleBunInitConfig.replayDirectUpload. */
+    replayDirectUpload?: boolean;
+    /** F-IFR P2 — origin allowlist for cross-origin replay stitching (parent bridge + child satellite). */
+    replayFrameOrigins?: string[];
+    /** Autocapture DOM interactions as analytics events (read by AnalyticsFeature). Default on. */
+    autocapture?: boolean;
+    /** Resolved allowlist of origins to inject a W3C `traceparent` into (read by NetworkFeature).
+     *  Same-origin by default; empty = tracing off. */
+    traceOrigins?: string[];
+    /** Mask all text in replay (read by ReplayFeature → snapshot). Default true (privacy-safe). */
+    maskReplayText?: boolean;
+    /** CSS selectors whose subtree text is ALWAYS masked in replay, even when maskReplayText is off
+     *  (read by ReplayFeature → snapshot). `contenteditable` + `[data-scalebun-mask]` are masked
+     *  unconditionally in addition to these. */
+    maskSelectors?: string[];
+    /** Mask form input values in replay (read by ReplayFeature → snapshot). Default true; passwords
+     *  are always blanked regardless. */
+    maskInputs?: boolean;
+    /** Mask the text label on interaction events — `USER_ACTION.label` (JourneyFeature) and
+     *  `$autocapture` `props.text` (AnalyticsFeature). Default FALSE: the real label is sent, so clicks
+     *  group per element rather than collapsing into one row. */
+    maskEventText?: boolean;
+    /** Honor GPC / Do-Not-Track by not recording replay for opted-out users (read by ReplayFeature).
+     *  Default false (opt-in). */
+    respectDnt?: boolean;
+    /**
+     * Scroll-reversal thresholds for the exit-intent detector (read by ExitIntentFeature).
+     *
+     * Host-tunable because every default is a guess until real `$exit_intent` distributions exist, and an
+     * SDK release is the slowest step in that loop — a site can retune without waiting for one. Omitted
+     * keys fall back to REVERSAL_DEFAULTS. Shape is duplicated here rather than imported because
+     * sdk-contracts must not depend on the web package.
+     */
+    exitIntent?: {
+        windowMs?: number;
+        minDistancePx?: number;
+        minVelocityPxMs?: number;
+        minDepthPct?: number;
+        sustainSamples?: number;
+    };
+    /**
+     * Host resolver for the eight gamified in-app formats (`engageOptions.onInAppGameRequest`).
+     *
+     * Carried as an opaque function rather than the typed handler on purpose: the request/result
+     * contract lives in the engage chunk, and importing it here — into a module every entry point
+     * loads — would drag the eight-variant union into core's dependency graph for no runtime benefit.
+     * The engage RUNTIME (lazy) applies the precise types when it installs this.
+     */
+    onInAppGameRequest?: (request: unknown) => Promise<unknown>;
+    /** Replay sampling config (read by ReplayFeature → decideSampling, which applies defaults). */
+    replaySampling?: {
+        mode?: ReplayMode;
+        sampleRate?: number;
+        onErrorSampleRate?: number;
+        persistBuffer?: boolean;
+        privacyLevel?: 'standard' | 'strict';
+    };
+    /** Pipeline backpressure signal — items still pending egress. Replay's adaptive quality sheds
+     *  low-priority capture when this (or CPU) is high. Set by the bootstrap. */
+    egressPending?: () => number;
+    /** Cumulative items the pipeline has thrown away. Replay watches it for a rise: a shed drops a
+     *  whole frame chain, so the recorder must open a new one rather than keep emitting deltas that
+     *  reconstruct against frames the server will never receive. Set by the bootstrap. */
+    egressDropped?: () => number;
+    /** Error capture options (read by ErrorsFeature; defaults applied in-feature). Passthrough from
+     *  config.errors — keeps resolution out of the core bundle. */
+    errorsOptions?: {
+        ignoreErrors?: (string | RegExp)[];
+        denyUrls?: (string | RegExp)[];
+        captureResourceErrors?: boolean;
+        beforeSend?: (item: ErrorItem) => ErrorItem | null;
+        sampleRate?: number;
+    };
+    /** Network capture options (read by NetworkFeature; defaults applied in-feature). Passthrough from
+     *  config.network — keeps resolution out of the core bundle. */
+    networkOptions?: {
+        trackWebSocket?: boolean;
+        trackSse?: boolean;
+        captureBodies?: boolean;
+        bodyMaxBytes?: number;
+        contentTypeAllowlist?: string[];
+        sampleRate?: number;
+        slowRequestMs?: number;
+        denyUrls?: (string | RegExp)[];
+        /**
+         * Keep known telemetry beacons (analytics collectors, ad pixels, IP enrichment).
+         *
+         * Default false: they are dropped. They are not the app, they cost the visitor bandwidth, and
+         * a blocked one used to move the session health score. See features/network/thirdParty.ts.
+         */
+        captureThirdParty?: boolean;
+        /** Replace the built-in beacon host list wholesale (comma-joined hostname suffixes). */
+        thirdPartyHosts?: string;
+        beforeSend?: (item: NetworkItem) => NetworkItem | null;
+    };
+    /** Performance/RUM options (read by PerformanceFeature; defaults applied in-feature). */
+    performanceOptions?: {
+        tracesSampleRate?: number;
+        slowTransactionMs?: number;
+    };
+    /** W5.2 — Resource Watchdog options (read by WatchdogFeature; defaults applied in-feature). */
+    watchdogOptions?: {
+        sampleRate?: number;
+        heartbeatMs?: number;
+        rollupMs?: number;
+        memorySampleMs?: number;
+        thresholds?: Record<string, number>;
+        captureProfileOnIncident?: boolean;
+    };
+    /** A3/A6 — analytics options (read by AnalyticsFeature): tracking plan, sample rate, cookie domain. */
+    analyticsOptions?: {
+        plan?: TrackingPlan;
+        sampleRate?: number;
+        cookieDomain?: string;
+    };
+    /** F3 — flags/config bootstrap seed (read by ConfigFeature at setup). Passthrough from
+     *  config.flags.bootstrap; seeds evaluation before the network responds (no flash-of-default). */
+    flagsBootstrap?: FlagsBootstrap;
+    /** F4 — open the realtime config stream (SSE). Passthrough from config.flags.realtime (default on).
+     *  When false, ConfigFeature keeps only the foreground-poll refresh. */
+    flagsRealtime?: boolean;
+}
+/**
+ * Contract for SDK features (errors, network, performance, replay, …). Each feature implements
+ * this and registers with the FeatureRegistry.
+ */
+export interface IFeature {
+    /** Unique feature name (e.g. 'errors', 'network', 'replay'). */
+    readonly name: string;
+    /** Install interceptors / observers. May be async for features needing lazy chunks. */
+    setup(context: FeatureContext): void | Promise<void>;
+    /** Remove interceptors / observers. Must be safe to call multiple times. */
+    teardown(): void;
+    /** Whether the feature is currently active. */
+    readonly isActive: boolean;
+}
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"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"}

package/dist/features.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Feature Contract
+ *
+ * Pure interface definitions for pluggable SDK features. No runtime implementation.
+ * Mirrors the RN SDK's fail-isolated IFeature/FeatureContext model.
+ */
+export {};
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @scalebun/sdk-contracts — Barrel Export
+ *
+ * Single entry point for all shared TYPE contracts. This package contains ONLY pure TypeScript
+ * types and interfaces — no runtime code, no Zod schemas (those live in @scalebun/protocol).
+ */
+export type { ScaleBunInitConfig, ScaleBunFeatures, PrivacyConfig, ScaleBunUser, ReplayMode, TrackingPlan, FlagsBootstrap } from './config.js';
+export type { UserContext, AppContext, DeviceContext, SessionContext } from './events.js';
+export type { Session, SessionMetadata, SessionStatus, CaptureReason, CaptureMode, ReplayQuality, WebReplayFrame, PrivacyPolicy, SessionReplayConfig, } from './session.js';
+export type { IFeature, FeatureContext } from './features.js';
+export type { IPlatformInfo, IAppLifecycle, AppLifecycleState } from './platform.js';
+export type { ISessionBoundary, SessionStateValue } from './session-boundary.js';
+export type { BaseMessage, HelloMessage, PingMessage, PongMessage, DebugMessage, LogLevel } from './bridge.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG5I,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvF,YAAY,EACV,OAAO,EACP,eAAe,EACf,aAAa,EACb,aAAa,EACb,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG3D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGlF,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG9E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Barrel Export
+ *
+ * Single entry point for all shared TYPE contracts. This package contains ONLY pure TypeScript
+ * types and interfaces — no runtime code, no Zod schemas (those live in @scalebun/protocol).
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/platform.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @scalebun/sdk-contracts — Platform Abstractions
+ *
+ * Pure interfaces for platform information and app lifecycle. No runtime, no DOM access.
+ * Implementations live in @scalebun/web.
+ */
+/** Platform information abstraction (web binding fills this from navigator/UA). */
+export interface IPlatformInfo {
+    readonly os: 'android' | 'ios' | 'web';
+    readonly osVersion: string;
+    readonly browser?: string;
+    readonly browserVersion?: string;
+    readonly isBot?: boolean;
+}
+/** Normalized app/page lifecycle state. On web this maps to the Page Visibility API. */
+export type AppLifecycleState = 'active' | 'background' | 'inactive';
+export interface IAppLifecycle {
+    getCurrentState(): AppLifecycleState;
+    /** Add a listener for lifecycle changes. Returns an unsubscribe function. */
+    addListener(callback: (state: AppLifecycleState) => void): () => void;
+}
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,eAAe,IAAI,iBAAiB,CAAC;IACrC,6EAA6E;IAC7E,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACvE"}

package/dist/platform.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Platform Abstractions
+ *
+ * Pure interfaces for platform information and app lifecycle. No runtime, no DOM access.
+ * Implementations live in @scalebun/web.
+ */
+export {};
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/session-boundary.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @scalebun/sdk-contracts — Session Boundary
+ *
+ * Pure contract for when a session starts/ends (timeout, page-hide, manual).
+ *
+ * ⚠️ NOTHING IMPLEMENTS THIS. The header used to say "Implementation in @scalebun/web
+ * (features/session)"; that directory holds `sessionManager.ts` and `sessionStore.ts`, neither of
+ * which implements `ISessionBoundary`, and no other file in either SDK does either. The only thing
+ * bearing the name is a test file. Read as documentation of how the web SDK works, this shape is
+ * actively misleading — it describes an `'ending' → 'ended'` transition and a `'pagehide'` end reason
+ * that do not exist anywhere.
+ *
+ * How a web session ACTUALLY ends, for anyone arriving here looking for it:
+ *   - the id lives in `sessionStorage` and is resolved ONCE per document, in the `SessionManager`
+ *     constructor (`features/session/sessionStore.ts` → `resolveSession`);
+ *   - it therefore survives refreshes and same-tab navigations, and dies with the tab;
+ *   - an idle timeout (default 30 min) and an absolute cap (default 4 h) are evaluated at the NEXT
+ *     document load, not by a timer;
+ *   - the server closes the row: `IngestionService.reapStaleSessions`, a 5-minute cron.
+ *
+ * Before implementing this interface, read the warning on `HttpClient.finalize()`. The obvious
+ * reading of `end('pagehide')` — finalize the session when the page hides — corrupts every
+ * multi-page session, and the reasons are recorded there.
+ */
+export type SessionStateValue = 'idle' | 'active' | 'ending' | 'ended';
+export interface ISessionBoundary {
+    readonly state: SessionStateValue;
+    /** Start a new session boundary. */
+    begin(): void;
+    /** End the current session. */
+    end(reason: 'manual' | 'timeout' | 'pagehide'): void;
+    /** Subscribe to boundary transitions. Returns an unsubscribe fn. */
+    onChange(cb: (state: SessionStateValue) => void): () => void;
+}
+//# sourceMappingURL=session-boundary.d.ts.map

package/dist/session-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-boundary.d.ts","sourceRoot":"","sources":["../src/session-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,oCAAoC;IACpC,KAAK,IAAI,IAAI,CAAC;IACd,+BAA+B;IAC/B,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;IACrD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9D"}

package/dist/session-boundary.js

@@ -0,0 +1,26 @@
+/**
+ * @scalebun/sdk-contracts — Session Boundary
+ *
+ * Pure contract for when a session starts/ends (timeout, page-hide, manual).
+ *
+ * ⚠️ NOTHING IMPLEMENTS THIS. The header used to say "Implementation in @scalebun/web
+ * (features/session)"; that directory holds `sessionManager.ts` and `sessionStore.ts`, neither of
+ * which implements `ISessionBoundary`, and no other file in either SDK does either. The only thing
+ * bearing the name is a test file. Read as documentation of how the web SDK works, this shape is
+ * actively misleading — it describes an `'ending' → 'ended'` transition and a `'pagehide'` end reason
+ * that do not exist anywhere.
+ *
+ * How a web session ACTUALLY ends, for anyone arriving here looking for it:
+ *   - the id lives in `sessionStorage` and is resolved ONCE per document, in the `SessionManager`
+ *     constructor (`features/session/sessionStore.ts` → `resolveSession`);
+ *   - it therefore survives refreshes and same-tab navigations, and dies with the tab;
+ *   - an idle timeout (default 30 min) and an absolute cap (default 4 h) are evaluated at the NEXT
+ *     document load, not by a timer;
+ *   - the server closes the row: `IngestionService.reapStaleSessions`, a 5-minute cron.
+ *
+ * Before implementing this interface, read the warning on `HttpClient.finalize()`. The obvious
+ * reading of `end('pagehide')` — finalize the session when the page hides — corrupts every
+ * multi-page session, and the reasons are recorded there.
+ */
+export {};
+//# sourceMappingURL=session-boundary.js.map

package/dist/session-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-boundary.js","sourceRoot":"","sources":["../src/session-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/session.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @scalebun/sdk-contracts — Session Domain Types
+ *
+ * Pure type definitions for the unified session system (web). Runtime constants/helpers live in
+ * @scalebun/web (features/session). Mirrors the RN session contract; replay frame is DOM-shaped.
+ */
+export type SessionStatus = 'active' | 'ended' | 'timeout';
+export interface SessionMetadata {
+    appName?: string;
+    appVersion?: string;
+    environment?: string;
+    platform?: 'android' | 'ios' | 'web';
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    viewportWidth?: number;
+    viewportHeight?: number;
+}
+export interface Session {
+    sessionId: string;
+    deviceId: string;
+    startedAt: number;
+    endedAt?: number;
+    status: SessionStatus;
+    metadata: SessionMetadata;
+}
+export type CaptureReason = 'navigation' | 'interaction' | 'frequency' | 'manual' | 'error-context' | 'scroll';
+export type CaptureMode = 'continuous' | 'capture-on-signal';
+export type ReplayQuality = 'high' | 'normal' | 'low';
+/** A web replay frame is a DOM snapshot (keyframe) or a batch of mutations (delta). */
+export interface WebReplayFrame {
+    frameId: string;
+    sessionId: string;
+    ts: number;
+    frameType: 'keyframe' | 'delta';
+    captureReason: CaptureReason;
+    masked: boolean;
+}
+export interface PrivacyPolicy {
+    maskAllText: boolean;
+    maskAllInputs: boolean;
+    maskSelectors: string[];
+    blockSelectors: string[];
+}
+export interface SessionReplayConfig {
+    captureMode: CaptureMode;
+    quality: ReplayQuality;
+    maxFrames: number;
+    maxDurationMs: number;
+    privacyPolicy: PrivacyPolicy;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAID,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,eAAe,GAAG,QAAQ,CAAC;AAC/G,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;CAC9B"}

package/dist/session.js

@@ -0,0 +1,8 @@
+/**
+ * @scalebun/sdk-contracts — Session Domain Types
+ *
+ * Pure type definitions for the unified session system (web). Runtime constants/helpers live in
+ * @scalebun/web (features/session). Mirrors the RN session contract; replay frame is DOM-shaped.
+ */
+export {};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@scalebun-release/sdk-contracts",
+  "version": "2.0.3",
+  "description": "Pure TypeScript interface/type contracts for the ScaleBun web SDK. No runtime code, no Zod, no validators — the single source of truth for shared types.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../../scripts/fix-esm-extensions.mjs dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@scalebun/protocol": "npm:@scalebun-release/protocol@2.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalebun/scalebun-web-sdk.git",
+    "directory": "packages/sdk-contracts"
+  },
+  "homepage": "https://scalebun.com/docs/web-sdk",
+  "bugs": {
+    "url": "https://github.com/scalebun/scalebun-web-sdk/issues"
+  }
+}