@reopt-ai/data-sdk-client 0.1.1 → 0.1.3

package/dist/client-CW9DfTlm.d.ts

@@ -0,0 +1,571 @@
+import { ReoptBootstrap, DeviceCookieState, ConsentCookieState } from '@reopt-ai/data-contract/identity';
+
+/**
+ * Types shared by every runtime. Nothing here refers to `window`, `document`
+ * or a Node built-in — the runtime-specific pieces are injected through
+ * {@link ReoptRuntime}.
+ */
+/** Consent categories. `analytics` is the one whose refusal stops everything. */
+type ConsentCategory = "analytics" | "marketing" | "functional" | "performance";
+interface ConsentConfig {
+    /** Default decision for every configured category. Default: `true` (opt-out model). */
+    defaultConsent?: boolean;
+    /** Categories the integration recognises. Default: `["analytics"]`. */
+    categories?: ConsentCategory[];
+    /** Persist decisions through the runtime's storage. Default: `true`. */
+    persist?: boolean;
+}
+/** Minimal synchronous key/value store — `localStorage`-shaped on purpose. */
+interface StorageBackend {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface RetryConfig {
+    /** Attempts after the first. Default: 3. */
+    maxRetries?: number;
+    /** First back-off, milliseconds. Default: 1000. */
+    baseDelay?: number;
+    /** Back-off ceiling, milliseconds. Default: 30000. */
+    maxDelay?: number;
+    /** ± fraction of the delay. Default: 0.1. */
+    jitter?: number;
+}
+interface CircuitBreakerConfig {
+    /** Consecutive transient failures before the circuit opens. Default: 5. */
+    failureThreshold?: number;
+    /** How long the circuit stays open before one probe is allowed. Default: 60000. */
+    recoveryTimeout?: number;
+}
+interface BatchConfig {
+    /** Events per request. Default: 100. */
+    size?: number;
+    /** Milliseconds to wait for a batch to fill before sending. Default: 1000. */
+    intervalMs?: number;
+    /**
+     * Serialized bytes per request. Default: 400 000, under the server's
+     * 512 000 hard cap with room for the JSON envelope. A 413 is a 4xx, and 4xx
+     * drops the batch — so overshooting the cap loses every event in it.
+     */
+    maxBytes?: number;
+}
+/** Browser credentials — public, ships in the page. */
+interface WriteKeyAuth {
+    writeKey: string;
+}
+/** Server credentials — must never reach a client bundle. */
+interface ClientCredentialsAuth {
+    clientId: string;
+    clientSecret: string;
+}
+type ReoptAuth = WriteKeyAuth | ClientCredentialsAuth;
+type FetchLike = (input: string, init: FetchInit) => Promise<FetchResponseLike>;
+interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    keepalive?: boolean;
+}
+interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** Context the runtime fills in for a `$pageview` when the caller does not. */
+interface PageContext {
+    path?: string;
+    origin?: string;
+    title?: string;
+    referrer?: string;
+    utm?: UTMParams;
+    /** Extra properties the runtime derived from the page, e.g. a `normalizePath` hook's output. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Everything the engine needs from the world around it. The browser package
+ * fills this from cookies, `localStorage` and `window`; the server package
+ * from request cookies and headers; tests from plain objects.
+ */
+interface ReoptRuntime {
+    /** Resolved device id. Identity resolution is the runtime's job, not the engine's. */
+    deviceId: string;
+    /**
+     * Value for the `reopt-session-id` header — the `"<id>.<token>"` credential
+     * ingest handed back, if the runtime kept it. Unsigned values are ignored
+     * by ingest, so only send what came from `onSession`.
+     */
+    getSessionId?: () => string | null | undefined;
+    /** Ingest assigned (or confirmed) a session for this batch. The runtime persists it. */
+    onSession?: (credential: {
+        id: string;
+        token: string;
+    }) => void;
+    /** Durable store for the offline queue and consent. Absent = memory only. */
+    storage?: StorageBackend;
+    /** Clock. Defaults to `Date.now`; the browser package corrects for server skew. */
+    now?: () => number;
+    /** Id generator. Defaults to monotonic UUIDv7. */
+    createId?: () => string;
+    /** `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /**
+     * Subscribe to "the process is about to go away" signals (pagehide,
+     * visibilitychange, SIGTERM). The engine flushes on each signal. Returns
+     * the unsubscribe function.
+     */
+    onFlushSignal?: (flush: () => void) => () => void;
+    /**
+     * Last-chance delivery used when a flush signal fires, e.g. `sendBeacon`.
+     * Return `true` if the runtime accepted the payload; `false` falls back to
+     * keepalive fetch.
+     */
+    sendLastChance?: (url: string, body: string, headers: Record<string, string>) => boolean;
+    /** Defaults for `$pageview` properties. */
+    getPageContext?: () => PageContext;
+    /**
+     * Mint and persist a fresh device id. Called by `reset()`; without it a
+     * reset keeps the old device, which is wrong on a shared machine.
+     */
+    regenerateDeviceId?: () => string;
+}
+interface ReoptCoreConfig {
+    auth: ReoptAuth;
+    /** Origin of the reopt-data deployment, or a same-origin proxy prefix like `/ingest`. */
+    baseUrl: string;
+    runtime: ReoptRuntime;
+    debug?: boolean;
+    batch?: BatchConfig;
+    /** Upper bound on queued events; the oldest are dropped past it. Default: 10000. */
+    maxQueueSize?: number;
+    retry?: RetryConfig;
+    circuitBreaker?: CircuitBreakerConfig;
+    consent?: ConsentConfig;
+    /** Prefix for storage keys. Default: `reopt_`. */
+    storagePrefix?: string;
+    /** Persist the queue through `runtime.storage`. Default: `true` when storage exists. */
+    enableOfflineBuffer?: boolean;
+    /** Flush on runtime flush signals. Default: `true` when the runtime provides them. */
+    autoFlushOnUnload?: boolean;
+}
+/**
+ * Identity a single event was recorded under, when it differs from the
+ * runtime's. The server SDK uses this to file events from many requests
+ * through one engine: each request's device travels with its events and
+ * becomes that batch's `reopt-device-id`.
+ */
+interface EventIdentity {
+    deviceId?: string;
+    sessionId?: string | null;
+}
+interface TrackEventOptions {
+    /** File this event under another visitor than the runtime's. Server SDK use. */
+    identity?: EventIdentity;
+    name: string;
+    properties?: Record<string, unknown>;
+    profileId?: string | number;
+    /** Consent category this event belongs to. Default: `analytics`. */
+    consentCategory?: ConsentCategory;
+}
+interface IdentifyOptions {
+    /** File this event under another visitor than the runtime's. Server SDK use. */
+    identity?: EventIdentity;
+    profileId: string | number;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    avatar?: string;
+    properties?: Record<string, unknown>;
+    consentCategory?: ConsentCategory;
+}
+interface IncrementOptions {
+    /** File this event under another visitor than the runtime's. Server SDK use. */
+    identity?: EventIdentity;
+    profileId: string | number;
+    property: string;
+    value?: number;
+    consentCategory?: ConsentCategory;
+}
+interface DecrementOptions {
+    /** File this event under another visitor than the runtime's. Server SDK use. */
+    identity?: EventIdentity;
+    profileId: string | number;
+    property: string;
+    value?: number;
+    consentCategory?: ConsentCategory;
+}
+interface UTMParams {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+interface PageViewOptions {
+    /** File this event under another visitor than the runtime's. Server SDK use. */
+    identity?: EventIdentity;
+    path?: string;
+    /** Scheme + host. */
+    origin?: string;
+    title?: string;
+    referrer?: string;
+    properties?: Record<string, unknown>;
+    utm?: UTMParams;
+    consentCategory?: ConsentCategory;
+}
+type EventPayload = {
+    type: "track";
+    eventId: string;
+    timestamp: number;
+    payload: {
+        name: string;
+        properties?: Record<string, unknown>;
+        profileId?: string | number;
+    };
+} | {
+    type: "identify";
+    eventId: string;
+    timestamp: number;
+    payload: {
+        profileId: string | number;
+        firstName?: string;
+        lastName?: string;
+        email?: string;
+        avatar?: string;
+        properties?: Record<string, unknown>;
+    };
+} | {
+    type: "increment";
+    eventId: string;
+    timestamp: number;
+    payload: {
+        profileId: string | number;
+        property: string;
+        value?: number;
+    };
+} | {
+    type: "decrement";
+    eventId: string;
+    timestamp: number;
+    payload: {
+        profileId: string | number;
+        property: string;
+        value?: number;
+    };
+};
+type QueueDropReason = "tracking_paused" | "consent_denied" | "validation_failed" | "payload_too_large";
+interface QueueResult {
+    eventId: string;
+    queued: boolean;
+    reason?: QueueDropReason;
+    errors?: Array<{
+        field: string;
+        message: string;
+    }>;
+}
+interface FlushResult {
+    status: "idle" | "success" | "failed" | "skipped";
+    sent: number;
+    failed: number;
+    pending: number;
+}
+interface FlushOptions {
+    /** Ask the transport to outlive the page (keepalive fetch / beacon). */
+    keepalive?: boolean;
+    /** Keep sending until the queue is empty or no progress is made. */
+    drain?: boolean;
+}
+
+type ConsentState = Record<string, boolean>;
+
+interface BatchDelivery {
+    sent: number;
+    failed: number;
+    /** The signed session credential ingest returned, when it did. */
+    session?: {
+        id: string;
+        token: string;
+    };
+}
+interface SendOptions {
+    keepalive?: boolean;
+    /** Overrides the runtime's device/session for this request only. */
+    identity?: EventIdentity;
+}
+interface Transport {
+    readonly url: string;
+    headers(identity?: EventIdentity): Record<string, string>;
+    send(batch: EventPayload[], options?: SendOptions): Promise<BatchDelivery>;
+}
+
+/**
+ * The engine: queue → batch → transport, with retry, a circuit breaker and
+ * consent gates. Everything that differs between browser and server comes in
+ * through {@link ReoptRuntime}; the engine itself never touches `window`,
+ * `document`, `process` or a Node built-in.
+ */
+declare class ReoptCore {
+    protected readonly runtime: ReoptRuntime;
+    protected readonly transport: Transport;
+    private readonly queue;
+    private readonly consent;
+    private readonly breaker;
+    private readonly retry;
+    private readonly batch;
+    private readonly factory;
+    private readonly debug;
+    private deviceId;
+    private profileId;
+    private globalProperties;
+    private activeFlush;
+    private flushTimeout;
+    private removeFlushSignal;
+    private closed;
+    /** Bumped by `reset()`; a batch from an older generation is never requeued. */
+    private generation;
+    private lastFlushRequeued;
+    constructor(config: ReoptCoreConfig);
+    protected log(...args: unknown[]): void;
+    getDeviceId(): string;
+    /** Swap the device id, e.g. after a server bootstrap or a `reset()`. */
+    setDeviceId(deviceId: string): void;
+    setProfileId(profileId: string | number | null): void;
+    getProfileId(): string | number | null;
+    setConsent(category: ConsentCategory, allowed: boolean): void;
+    getConsent(category: ConsentCategory): boolean;
+    setAllConsent(allowed: boolean): void;
+    getConsentState(): ConsentState;
+    replaceConsentState(state: ConsentState): void;
+    pauseTracking(): void;
+    resumeTracking(): void;
+    /**
+     * Properties attached to every `track` event (and so every automatic
+     * event) from now on. An event's own properties win on conflict. This is
+     * how a host adds its breakdown axis — a `page_id`, a tenant — to
+     * `$web_vitals` and `$pageleave`, which the SDK otherwise stamps with
+     * only a path.
+     */
+    register(properties: Record<string, unknown>): void;
+    unregister(...keys: string[]): void;
+    getGlobalProperties(): Record<string, unknown>;
+    /**
+     * `options.identity` files the event under another visitor than the
+     * runtime's — the server SDK's way of serving many requests from one
+     * engine. Such an event never reads or writes the engine's own profile:
+     * that belongs to the runtime's visitor, not the request's.
+     */
+    track(options: TrackEventOptions): QueueResult;
+    identify(options: IdentifyOptions): QueueResult;
+    increment(options: IncrementOptions): QueueResult;
+    decrement(options: DecrementOptions): QueueResult;
+    pageView(options?: PageViewOptions): QueueResult;
+    screenView(screenName: string, properties?: Record<string, unknown>, identity?: EventIdentity): QueueResult;
+    get pending(): number;
+    private enqueue;
+    private scheduleFlush;
+    private clearScheduledFlush;
+    flush(options?: FlushOptions): Promise<FlushResult>;
+    /**
+     * The page (or process) is going away. Persist first so nothing is lost if
+     * the request never completes, then send what can be sent with keepalive.
+     */
+    private flushOnSignal;
+    /**
+     * The identity a batch is sent under, fixed when it leaves the queue. A
+     * `reset()` during a retry must not re-address the previous visitor's
+     * events to the new device.
+     */
+    private identityFor;
+    private flushExclusive;
+    private flushAll;
+    private flushOnce;
+    private continueOrSettle;
+    /**
+     * Forget who this is: profile, queued events and — when the runtime can
+     * mint one — the device id. A shared computer that logs out must not keep
+     * attributing the next person to the previous one.
+     */
+    reset(): void;
+    close(): Promise<FlushResult>;
+}
+
+/**
+ * The shape `next/web-vitals`' `useReportWebVitals` and the `web-vitals`
+ * package both produce. Declared here so the vanilla entry does not have to
+ * import either.
+ */
+interface WebVitalMetric {
+    id: string;
+    name: string;
+    value: number;
+    delta?: number;
+    rating?: "good" | "needs-improvement" | "poor";
+    navigationType?: string;
+}
+type WebVitalProperties = {
+    metric_name: string;
+    metric_id: string;
+    value: number;
+    delta?: number;
+    rating?: string;
+    navigation_type?: string;
+    path: string;
+};
+
+/**
+ * Rewrites a pathname before it is attached to an event, and may lift the
+ * parts it removed into properties so they stay available for breakdowns:
+ * `/workspace/8f3…/crm/customers/2a1…` → `{ path: "/workspace/:id/crm/customers/:id",
+ * properties: { workspace_id: "8f3…" } }`.
+ *
+ * Applied wherever the SDK fills in a path itself — the default `$pageview`
+ * path, `$pageleave`, `$web_vitals`, `$exception`. A `path` you pass to
+ * `pageView()` explicitly is used as-is, so run the same function on it
+ * yourself; two different rules would give one visit two different paths.
+ * Must be synchronous and pure. If it throws, the raw pathname is used.
+ */
+type NormalizePath = (pathname: string) => string | {
+    path: string;
+    properties?: Record<string, unknown>;
+};
+
+type IdentityStorageKind = "auto" | "cookie" | "localStorage" | "memory";
+interface IdentityConfig {
+    /**
+     * Where the device id lives. `auto` (default) prefers a cookie: Safari
+     * expires script-written `localStorage` after seven days of inactivity,
+     * which turns every returning visitor into a new device. A cookie the
+     * server also reads survives that, and lets server-side events join the
+     * same device.
+     */
+    storage?: IdentityStorageKind;
+    /** Cookie `Domain`; omit for host-only. Set to share across subdomains. */
+    cookieDomain?: string;
+    /** Cookie lifetime. Default 400 days (the longest Chrome honours). */
+    cookieMaxAgeSeconds?: number;
+}
+interface CaptureConfig {
+    /**
+     * Send `$pageview` on `init()`. Default `true` for the vanilla entry.
+     * The Next entry sets it to `false` because `<ReoptPageView />` owns page
+     * views there — including the first one.
+     */
+    pageview?: boolean;
+    /** Send `$pageleave` with time-on-page when the page is hidden or the route changes. Default `true`. */
+    pageleave?: boolean;
+    /** Attach max scroll depth to `$pageleave`. Default `true`. */
+    scrollDepth?: boolean;
+    /** Send `$exception` for uncaught errors and unhandled rejections. Default `false`. */
+    exceptions?: boolean;
+}
+interface ReoptClientConfig {
+    writeKey: string;
+    /** reopt-data origin, or the same-origin proxy prefix (e.g. `/ingest`) the Next.js proxy rewrites. */
+    baseUrl: string;
+    /** What the server already knows about this visitor. `null` = nothing. */
+    bootstrap?: ReoptBootstrap | null;
+    identity?: IdentityConfig;
+    capture?: CaptureConfig;
+    /**
+     * Hosts that receive the `reopt-device-id` header on outgoing `fetch`/XHR,
+     * so a server-side `track()` lands on the same device. `true` = the page's
+     * own hostname. **Default: off** — the trusted path is passing
+     * `getDeviceId()` to your server call explicitly; this patches `fetch`
+     * and loads as a separate chunk only when enabled.
+     */
+    tracingHeaders?: boolean | string[];
+    /** See {@link NormalizePath}. */
+    normalizePath?: NormalizePath;
+    /**
+     * Properties attached to every event from the very first one. Same as
+     * calling `register()` right after `init()`, except that nothing can
+     * slip out in between: web vitals arrive from a buffered
+     * `PerformanceObserver` and can fire the instant the client exists.
+     * Pass the page context the server already knows here; update it on
+     * client-side navigation with `register()`.
+     */
+    properties?: Record<string, unknown>;
+    consent?: ConsentConfig;
+    batch?: BatchConfig;
+    retry?: RetryConfig;
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Upper bound on queued events. Default 10 000. */
+    maxQueueSize?: number;
+    /** Overrides the store for the offline queue. Default `localStorage`. */
+    queueStorage?: StorageBackend;
+    /** Prefix for storage keys. Default `reopt_`. */
+    storagePrefix?: string;
+    /**
+     * Transport override. Tests hand in a recording function so a Playwright
+     * spec can assert on the exact payload the SDK built, without intercepting
+     * the network. Defaults to the page's `fetch` (captured at init, before the
+     * tracing patch, so the SDK's own requests are never tagged twice).
+     */
+    fetch?: FetchLike;
+    debug?: boolean;
+}
+interface ResolvedCaptureConfig {
+    pageview: boolean;
+    pageleave: boolean;
+    scrollDepth: boolean;
+    exceptions: boolean;
+}
+
+interface IdentityStore {
+    readonly kind: Exclude<IdentityStorageKind, "auto">;
+    readDevice(): DeviceCookieState | null;
+    writeDevice(state: DeviceCookieState): void;
+    clearDevice(): void;
+    readConsent(): ConsentCookieState | null;
+    writeConsent(state: ConsentCookieState): void;
+    /** Engine-facing backend for the consent key, so consent decisions land in the same place. */
+    consentBackend(): StorageBackend;
+}
+
+interface ReoptClientDefaults {
+    /** Whether `init()` sends the first `$pageview`. The Next entry says no. */
+    pageview: boolean;
+}
+/**
+ * The browser client: the shared engine plus everything that only makes
+ * sense in a document — cookie identity, tracing headers, page leave,
+ * scroll depth, exception capture, and a clock corrected against the
+ * server's.
+ */
+declare class ReoptClient extends ReoptCore {
+    readonly writeKey: string;
+    readonly capture: ResolvedCaptureConfig;
+    private readonly store;
+    private readonly pageLeave;
+    private readonly scroll;
+    private readonly uninstallers;
+    private torndown;
+    private readonly session;
+    private readonly normalize;
+    /** True when `writeKey` or `baseUrl` was missing: every call is a silent no-op. */
+    readonly disabled: boolean;
+    constructor(config: ReoptClientConfig, defaults?: ReoptClientDefaults);
+    /** Which store identity ended up in — `cookie`, `localStorage` or `memory`. */
+    get identityStorage(): IdentityStore["kind"];
+    pageView(options?: PageViewOptions): QueueResult;
+    identify(options: IdentifyOptions): QueueResult;
+    /** Feed a Web Vitals metric (from `next/web-vitals` or the `web-vitals` package). */
+    captureWebVital(metric: WebVitalMetric): QueueResult;
+    /** The page's path through `normalizePath`, for events the SDK stamps itself. */
+    private currentPath;
+    /** Report an error you caught yourself. */
+    captureException(error: unknown, properties?: Record<string, unknown>): QueueResult;
+    private trackException;
+    private emitPageLeave;
+    /**
+     * Log out: forget the profile and the queue, and become a new device.
+     * On a shared computer the next person must not inherit this one's
+     * history.
+     */
+    reset(): void;
+    close(): Promise<FlushResult>;
+}
+
+export { type BatchConfig as B, type ConsentCategory as C, type DecrementOptions as D, type EventIdentity as E, type FlushResult as F, type IdentifyOptions as I, type NormalizePath as N, type PageViewOptions as P, type QueueResult as Q, ReoptClient as R, type StorageBackend as S, type TrackEventOptions as T, type UTMParams as U, type WebVitalMetric as W, type ReoptClientConfig as a, type ReoptClientDefaults as b, type IncrementOptions as c, type CaptureConfig as d, type CircuitBreakerConfig as e, type ConsentConfig as f, type EventPayload as g, type FetchInit as h, type FetchLike as i, type FetchResponseLike as j, type IdentityConfig as k, type IdentityStorageKind as l, type QueueDropReason as m, type RetryConfig as n, type WebVitalProperties as o };

package/dist/index.cjs

@@ -822,10 +822,13 @@ function readIngestCounts(rawBody) {
   if (!record || record.status !== "ok" && record.status !== "accepted" || !count(record.accepted) || !count(record.duplicates) || !Array.isArray(record.rejected)) {
     throw new TransportError("Track response did not match contract: unexpected shape", 409, true);
   }
+  const session = record.session;
+  const credential = session && typeof session.id === "string" && typeof session.token === "string" ? { id: session.id, token: session.token } : void 0;
   return {
     accepted: record.accepted,
     duplicates: record.duplicates,
-    rejected: record.rejected.length
+    rejected: record.rejected.length,
+    ...credential ? { session: credential } : {}
   };
 }
 function resolveBaseUrl(value) {
@@ -883,7 +886,11 @@ function createTransport(options) {
     if (counts.accepted + counts.duplicates + counts.rejected !== batch.length) {
       throw new TransportError("Track response counts do not reconcile with the submitted batch", 409, true);
     }
-    return { sent: counts.accepted + counts.duplicates, failed: counts.rejected };
+    return {
+      sent: counts.accepted + counts.duplicates,
+      failed: counts.rejected,
+      ...counts.session ? { session: counts.session } : {}
+    };
   };
   return { url, headers, send };
 }
@@ -1193,6 +1200,9 @@ var ReoptCore = class {
         onRetry: (attempt, waitMs) => this.log("retry", attempt, Math.round(waitMs))
       });
       this.log("flushed", delivery.sent, delivery.failed);
+      if (delivery.session && !batch[0]?.identity) {
+        this.runtime.onSession?.(delivery.session);
+      }
       if (this.breaker.getState() === "half-open") this.log("breaker closed");
       this.breaker.recordSuccess();
       this.queue.settle();
@@ -1436,13 +1446,14 @@ function cookiesAvailable() {
 
 // src/identity/device.ts
 var LEGACY_DEVICE_KEY = "device_id";
-function localStorageOrNull() {
+function localStorageBackend() {
   try {
     if (typeof window === "undefined" || !window.localStorage) return null;
+    const storage = window.localStorage;
     const probe = "reopt_probe";
-    window.localStorage.setItem(probe, "1");
-    window.localStorage.removeItem(probe);
-    return window.localStorage;
+    storage.setItem(probe, "1");
+    storage.removeItem(probe);
+    return storage;
   } catch {
     return null;
   }
@@ -1481,7 +1492,7 @@ function createIdentityStore(writeKey, config) {
   if (kind === "cookie" || kind === "auto" && cookiesAvailable()) {
     return makeStore("cookie", writeKey, cookieBackend(cookie));
   }
-  const local = kind === "memory" ? null : localStorageOrNull();
+  const local = kind === "memory" ? null : localStorageBackend();
   if (local) return makeStore("localStorage", writeKey, local);
   return makeStore("memory", writeKey, memoryStorage());
 }
@@ -1492,7 +1503,7 @@ function resolveDeviceId(store, bootstrapDeviceId, storagePrefix) {
     store.writeDevice({ deviceId: bootstrapDeviceId });
     return { deviceId: bootstrapDeviceId, source: "bootstrap" };
   }
-  const local = localStorageOrNull();
+  const local = localStorageBackend();
   const legacy = local?.getItem(`${storagePrefix}${LEGACY_DEVICE_KEY}`);
   if ((0, import_identity3.isValidIdentityId)(legacy)) {
     store.writeDevice({ deviceId: legacy });
@@ -1512,19 +1523,6 @@ function regenerateDeviceId(store) {
 // src/client.ts
 var CLOCK_SKEW_THRESHOLD_MS = 3e4;
 var MAX_CLOCK_SKEW_MS = 24 * 60 * 60 * 1e3;
-function localStorageBackend() {
-  try {
-    if (typeof window === "undefined" || !window.localStorage) return null;
-    const storage = window.localStorage;
-    return {
-      getItem: (key) => storage.getItem(key),
-      setItem: (key, value) => storage.setItem(key, value),
-      removeItem: (key) => storage.removeItem(key)
-    };
-  } catch {
-    return null;
-  }
-}
 function routedStorage(consentKey, consent, rest) {
   const pick = (key) => key === consentKey ? consent : rest;
   return {
@@ -1565,6 +1563,7 @@ var ReoptClient = class extends ReoptCore {
   scroll;
   uninstallers = [];
   torndown = false;
+  session;
   normalize;
   /** True when `writeKey` or `baseUrl` was missing: every call is a silent no-op. */
   disabled;
@@ -1581,8 +1580,15 @@ var ReoptClient = class extends ReoptCore {
     const queueStorage = disabled ? memoryStorage() : config.queueStorage ?? localStorageBackend() ?? memoryStorage();
     const transportFetch = config.fetch ?? (typeof window !== "undefined" ? window.fetch.bind(window) : void 0);
     const box = {};
+    const session = { header: store.readDevice()?.sessionId ?? null };
     const runtime = {
       deviceId: identity.deviceId,
+      getSessionId: () => (0, import_identity5.parseSessionHeader)(session.header) ? session.header : null,
+      onSession: (credential) => {
+        session.header = (0, import_identity5.formatSessionHeader)(credential);
+        const current2 = store.readDevice();
+        store.writeDevice({ ...current2, deviceId: current2?.deviceId ?? identity.deviceId, sessionId: session.header });
+      },
       storage: routedStorage(`${storagePrefix}consent`, store.consentBackend(), queueStorage),
       now,
       fetch: transportFetch,
@@ -1620,6 +1626,7 @@ var ReoptClient = class extends ReoptCore {
     });
     this.writeKey = config.writeKey;
     this.disabled = disabled;
+    this.session = session;
     this.normalize = config.normalizePath;
     this.store = store;
     this.capture = resolveCapture(config.capture, defaults.pageview);
@@ -1715,6 +1722,7 @@ var ReoptClient = class extends ReoptCore {
    */
   reset() {
     super.reset();
+    this.session.header = null;
     this.store.writeDevice({ deviceId: this.getDeviceId() });
   }
   async close() {