@scalebun-release/react-native 2.5.0

package/lib/typescript/features/replay/transport/ReplayTransport.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Session Replay SDK — Replay Transport Interface
+ *
+ * Abstract transport contract for sending replay data.
+ * Implementations:
+ *   - DesktopReplayTransport: streams to desktop tool via WebSocket (DebugTransport)
+ *   - BackendReplayTransport: uploads to backend API via HTTP
+ *   - CompositeReplayTransport: fans out to multiple child transports
+ */
+export interface ReplaySessionStartPayload {
+    sessionId: string;
+    startedAt: number;
+    device: {
+        platform: string;
+        osVersion: string;
+        screenWidth: number;
+        screenHeight: number;
+        deviceModel?: string;
+        appName?: string;
+        appVersion?: string;
+        bundleId?: string;
+    };
+    config: {
+        captureMode: string;
+        quality: string;
+        privacyEnabled: boolean;
+    };
+}
+export interface ReplayFramePayload {
+    frameId: string;
+    sessionId: string;
+    timestamp: number;
+    sequenceNumber: number;
+    screenName: string;
+    trigger: string;
+    format: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    masked: boolean;
+}
+export interface ReplayEventPayload {
+    eventId: string;
+    sessionId: string;
+    type: string;
+    timestamp: number;
+    screenName: string;
+    label: string;
+    frameId?: string;
+    data?: Record<string, unknown>;
+}
+export interface ReplaySessionEndPayload {
+    sessionId: string;
+    endedAt: number;
+    durationMs: number;
+    totalFrames: number;
+    totalEvents: number;
+    finalState: string;
+}
+export interface ReplayTransport {
+    /** Send session start notification */
+    sendSessionStart(payload: ReplaySessionStartPayload): void;
+    /** Send a captured frame (metadata + base64 image data) */
+    sendFrame(frame: ReplayFramePayload, imageData: string): void;
+    /** Send a timeline event */
+    sendEvent(event: ReplayEventPayload): void;
+    /** Send session end notification */
+    sendSessionEnd(payload: ReplaySessionEndPayload): void;
+    /** Cleanup transport resources */
+    destroy(): void;
+}
+//# sourceMappingURL=ReplayTransport.d.ts.map

package/lib/typescript/features/session/BackendSessionAdapter.d.ts

@@ -0,0 +1,528 @@
+/**
+ * ScaleBun SDK — Backend Session Adapter
+ *
+ * Implements the SessionTransport interface (System A) and bridges
+ * session/frame/event data to the backend API via HTTP.
+ *
+ * This is the ADAPTER that connects the existing SessionManager
+ * (which only has DesktopSessionTransport) to the backend.
+ *
+ * Design:
+ * - Uses the same endpoint contract as BackendReplayTransport
+ *   (POST /v1/replay/sessions, /frames, /events, /finalize)
+ * - Batches frames and events with auto-flush
+ * - Never throws — all errors are caught and logged
+ * - Behind config flag: only constructed when backendUpload is enabled
+ *
+ * This does NOT duplicate the existing BackendReplayTransport.
+ * It exists because SessionManager uses a different interface
+ * (SessionTransport from sessionTypes.ts) than ReplayTransport
+ * (from features/replay/transport/ReplayTransport.ts).
+ * The payload shapes differ, so this adapter maps between them.
+ *
+ * MVP/dev-only: base64 frames are sent inline in JSON body.
+ */
+import type { StorageBackend } from '../../storage/StorageBackend';
+import type { SessionTransport, Session, SessionMetadata, JourneyEvent, ReplayFrame } from './sessionTypes';
+export interface BackendSessionConfig {
+    /** Backend API base URL (e.g. http://localhost:3001/api) */
+    endpoint: string;
+    /** Batch size for frames before auto-flush. Default: 5 */
+    batchSize?: number;
+    /** Auto-flush interval in ms. Default: 3000 */
+    flushIntervalMs?: number;
+    /** Request timeout in ms. Default: 15000 */
+    timeoutMs?: number;
+    /** SaaS multi-tenant client key — enables ingestion endpoints and x-scalebun-client-key header */
+    clientKey?: string;
+    /**
+     * Upload frame bytes directly to object storage via presigned PUT instead of
+     * inline base64 in the JSON body. Default false → legacy inline path. Flip on
+     * after the backend presign endpoint is deployed. Falls back to inline
+     * automatically if the backend reports storage is not configured.
+     */
+    useObjectStorage?: boolean;
+    /**
+     * Route telemetry lanes (events/network/errors/performance/logs) through the
+     * durable NATIVE file outbox instead of JS-side HTTP. Only takes effect when BOTH
+     * this and `nativeOutboxUploadEnabled` are true AND the native module exposes the
+     * outbox methods — otherwise the existing JS upload path is used unchanged. When
+     * active, the native uploader owns delivery (no duplicate JS POST). Default false.
+     */
+    enableNativeFileOutbox?: boolean;
+    /** Native outbox actually uploads (vs. capture/store-only). Gates telemetry routing. */
+    nativeOutboxUploadEnabled?: boolean;
+    /**
+     * Additive native-outbox tuning flags (retry interval, attempt caps, Retry-After,
+     * byte/age GC bounds, etc.) forwarded verbatim to the native `initOutbox` dict.
+     * Native parses both `nativeOutbox*` and bare `outbox*` keys and applies its own
+     * defaults for anything omitted — so an empty object changes nothing.
+     */
+    nativeOutboxTuning?: Record<string, unknown>;
+    /** Idle-gap threshold (ms) the SDK recorded with; persisted on the session row. */
+    idleThresholdMs?: number;
+    /**
+     * Durable key-value store used to persist the unflushed frame buffer across a
+     * process kill. On background the in-flight frames are snapshotted here; on the
+     * next launch they are re-uploaded and linked to the PRIOR session. Omitted →
+     * frame-kill recovery is disabled (in-memory only, prior behavior).
+     */
+    storage?: StorageBackend;
+}
+/**
+ * One platform-agnostic log line for the logs lane. The queue forwards whatever it is
+ * given — `source`/`platform` are neutral string hints set by the PRODUCER (console
+ * tags 'console'/'js'; a future native producer tags its own values onto this SAME
+ * shape). `level` is free-text. Nothing here is JS-specific.
+ */
+export interface LogQueueItem {
+    level: string;
+    message: string;
+    source: string;
+    platform: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class BackendSessionAdapter implements SessionTransport {
+    private config;
+    /** Durable store for cross-kill frame recovery (null → recovery disabled). */
+    private readonly _frameStore;
+    /** Storage key for the snapshotted unflushed frame buffer (see persistPendingFrames). */
+    private static readonly PENDING_FRAMES_KEY;
+    /**
+     * Byte budget for the cross-kill frame snapshot (see `_selectFramesToPersist`).
+     *
+     * Replaces a flat 10-frame cap. A count could not bound the KV write at all — these frames carry
+     * base64 screenshots, so ten of them is anywhere from ~200 KB to several MB depending on device
+     * resolution, and an oversized value is exactly what fails on the background transition where
+     * this write happens.
+     *
+     * 2 MB is deliberately modest: this is a last-resort snapshot for frames that never reached the
+     * network, not a mirror of the session. Enough for a keyframe plus a run of deltas on any device;
+     * small enough that writing it cannot itself be the reason backgrounding stalls.
+     */
+    private static readonly MAX_PERSIST_BYTES;
+    /**
+     * Frames the backend accepts in ONE request — `'Max 100 frames per batch'`
+     * (`IngestionService.uploadFrames`). Exceeding it is a 4xx, which this SDK classifies as
+     * permanent.
+     *
+     * This has to exist alongside the byte budget, not instead of it. The budget alone cannot bound
+     * the COUNT, and the count is what the server checks: measured on real traffic, mobile keyframes
+     * average ~16 KB, so a 2 MB snapshot is around 128 frames — over the cap by construction. The old
+     * flat 10-frame rule was under it by construction, which is why this failure could not happen
+     * before and can now.
+     */
+    private static readonly MAX_FRAMES_PER_BATCH;
+    private objectStorageActive;
+    private readonly nativeOutboxEnabled;
+    private _nativeOutboxReady;
+    private currentSessionId;
+    private readonly _startedSessionIds;
+    private readonly _pendingStartPayloads;
+    private _startRetryInFlight;
+    private pendingFrames;
+    private pendingEvents;
+    private pendingNetworkRequests;
+    private pendingErrors;
+    private pendingPerformanceMetrics;
+    private pendingLogs;
+    private flushTimer;
+    private destroyed;
+    /**
+     * Latch for `sdk_replay_capture_failed` — reported once per adapter, not once per rejected batch.
+     *
+     * A session whose row was never created rejects EVERY frame batch, so an unlatched report would
+     * emit one analytics event per flush for as long as the app stays open, on the same lane it is
+     * trying to report through.
+     */
+    private _captureFailureReported;
+    private static readonly ANALYTICS_BUFFER_CAP;
+    /** Logs lane: queue length that triggers an eager flush (mirrors the network lane). */
+    private static readonly LOGS_BATCH_SIZE;
+    /** Logs lane: max rows posted per flush (server caps at 200/batch). */
+    private static readonly LOGS_FLUSH_MAX;
+    private _analyticsSessionId;
+    private pendingAnalyticsEvents;
+    private analyticsFlushTimer;
+    private _pendingFinalizeId;
+    /** Unsubscribe from quotaState (set in the constructor, released in destroy). */
+    private _quotaUnsub;
+    /**
+     * Sessions whose INGESTION_START was refused with `quota_exceeded` (feature `sessions`). No row
+     * will ever exist for them, so every child lane for that id is dropped rather than buffered
+     * behind a row-ready gate that can never open.
+     */
+    private readonly _refusedSessionIds;
+    /** Unregister this adapter as the native sessions-refusal handler. */
+    private _nativeRefusedUnsub;
+    /** Host hook (SessionManager) to end a recording whose session start was refused. */
+    private _onSessionRefused;
+    constructor(config: BackendSessionConfig);
+    /**
+     * §11 gate: true only when the current recording session's INGESTION_START row is
+     * confirmed on the backend. Child telemetry lanes consult this before flushing so they
+     * never race ahead of session creation (which would 404). Null id → not ready.
+     */
+    private _sessionRowReady;
+    /**
+     * The session live errors go to: the recording session when one runs, else the always-on
+     * analytics session.
+     *
+     * Errors used to require `currentSessionId` — the RECORDING lane — so on any device where replay
+     * was not recording (sampled out, `record: false`, between recordings) not one error left the
+     * phone, and a recovered crash drained at launch waited for a recording that might never start.
+     * The analytics session has a backend row from the moment it opens, which is all an error needs.
+     */
+    private _errorsSessionId;
+    /** Lazy: nativeCrashBridge → CrashReporter → SessionManager → this file would be a cycle. */
+    private _publishNativeSession;
+    /** True when the current recording session's START was refused for quota (no row, ever). */
+    private _currentSessionRefused;
+    /** Register the host's reaction to a refused session start (SessionManager ends the recording). */
+    setSessionRefusedHandler(fn: ((sessionId: string) => void) | null): void;
+    /**
+     * A limited feature's block started or ended.
+     *
+     * Started: everything queued for it is PURGED (in memory, the cross-kill frame snapshot, and the
+     * native outbox lane), because the server will refuse it and a retry is exactly what the contract
+     * forbids. Capture itself is stopped by the owners of capture (SessionManager for frames,
+     * NetworkFeature/EventTracker gate at their entry points); this adapter also refuses new items at
+     * its own entry points, so a producer that was not told still cannot leak through.
+     *
+     * Ended: nothing is replayed — what was purged is gone. The native lanes follow via the sync
+     * listener registered in the constructor (it fires after every transition too).
+     */
+    private _onQuotaChange;
+    /**
+     * A session START came back 402 `quota_exceeded` (feature `sessions`). Drop the session: no row
+     * will be created, so nothing may queue behind it and the start is never retried.
+     */
+    private _refuseSession;
+    /** True when an HTTP error carried a recorded quota refusal. */
+    private static _isQuotaRefusal;
+    sendSessionStart(session: Session): void;
+    sendSessionEnd(session: Session): void;
+    /** Public: the always-on analytics session id, or null before it opens. */
+    get analyticsSessionId(): string | null;
+    /**
+     * Open the always-on analytics ingestion session. Sets the analytics id,
+     * starts the analytics flush timer, replays any pre-ready buffered events,
+     * and POSTs INGESTION_START. Mirrors sendSessionStart's body builder but
+     * never touches currentSessionId (recording lane).
+     */
+    startAnalyticsSession(session: {
+        sessionId: string;
+        deviceId: string;
+        startedAt: number;
+        metadata?: SessionMetadata;
+        /** Idle-gap threshold (ms) the SDK declares for this session; echoed by the
+         *  backend so the dashboard uses the same value to draw idle bands. */
+        idleThresholdMs?: number;
+    }): Promise<void>;
+    /**
+     * Re-attempt any INGESTION_START whose POST failed (offline app launch). Runs on every
+     * flush tick of BOTH lanes — cheap no-op when the map is empty, single-flight guarded.
+     * On ack: opens the row-ready gate and drains whichever lane the id belongs to, which is
+     * exactly what un-sticks a replay that started offline once connectivity returns.
+     */
+    private _retryPendingStarts;
+    /**
+     * Enqueue a user track() event. Buffers (bounded, drop-oldest) when the
+     * analytics session is not yet open; flushes at >=20 once it is.
+     */
+    trackEvent(event: JourneyEvent): void;
+    /**
+     * Emit an app-lifecycle boundary marker (APP_BACKGROUND / APP_FOREGROUND) onto
+     * the analytics lane so the dashboard can shade the backgrounded span on the
+     * replay timeline and exclude it from the active duration. Timestamp is captured
+     * at the transition (accurate even if delivery is deferred until the next
+     * foreground on iOS). No-op when no analytics session is open. The sessionId is
+     * (re)stamped at flush time, so passing the current id here is only a placeholder.
+     */
+    emitLifecycleMarker(type: 'APP_BACKGROUND' | 'APP_FOREGROUND', payload?: Record<string, unknown>): void;
+    /**
+     * Public: force-flush queued analytics events immediately. Called on
+     * APP_BACKGROUND so the lifecycle marker (and any buffered track events) reach
+     * the backend before the OS suspends the flush timer. Best-effort on iOS, where
+     * the POST may not resolve until the next foreground — the events stay buffered
+     * with accurate timestamps and flush then.
+     */
+    flushAnalytics(): Promise<void>;
+    /**
+     * Flush queued analytics events. Mirrors _flushEvents (recording) byte for
+     * byte on the wire map, but gates on _analyticsSessionId and STAMPS that id
+     * into every event so endpoint id == body sessionId by construction.
+     */
+    private _flushAnalyticsEvents;
+    /** Flush remaining analytics events, finalize the session, stop its timer. */
+    finalizeAnalyticsSession(): Promise<void>;
+    /**
+     * Close any analytics session left open by a suspended background finalize.
+     * Called on the NEXT foreground (SDKBootstrapper app-state 'active') BEFORE a new
+     * analytics session is opened. JS is live on foreground, so this POST completes.
+     * No-op when there is no pending id. Idempotent with the background finalize: the
+     * marker is cleared on a confirmed background ACK, so this only fires when the
+     * background POST was NOT confirmed; if that suspended POST later also lands, the
+     * server must treat a repeat INGESTION_FINALIZE for the same id as a no-op.
+     */
+    reconcilePendingFinalize(): Promise<void>;
+    private _startAnalyticsFlushTimer;
+    private _stopAnalyticsFlushTimer;
+    sendEvent(event: JourneyEvent): void;
+    sendFrame(frame: ReplayFrame, imageData: string): void;
+    queueNetworkRequest(data: {
+        method: string;
+        url: string;
+        statusCode?: number;
+        duration?: number;
+        screenName?: string;
+        error?: string;
+        requestSize?: number;
+        responseSize?: number;
+        requestHeaders?: Record<string, string>;
+        responseHeaders?: Record<string, string>;
+        requestBody?: string;
+        responseBody?: string;
+    }): void;
+    /** App version resolved at session start; errors stamp it so regression
+     *  detection has a version to work with (D8). Null until a session starts. */
+    private _cachedAppVersion;
+    private _appVersion;
+    queueError(data: {
+        type: string;
+        message: string;
+        stack?: string;
+        screenName?: string;
+        platform?: string;
+        appVersion?: string;
+        isFatal?: boolean;
+        metadata?: Record<string, unknown>;
+        /** Target session. Set ONLY by a recovered native crash; absent means the current session. */
+        sessionId?: string;
+        /** Stable idempotency key. Set ONLY by a recovered crash; the backend dedupes on it. */
+        clientId?: string;
+    }): void;
+    /**
+     * Public: force-flush queued errors immediately (handled-error delivery).
+     *
+     * @returns whether the batch was DURABLY accepted. Crash recovery deletes its on-disk record on
+     *          this answer, so it must reflect the backend and not merely that the call returned.
+     */
+    flushErrors(): Promise<boolean>;
+    /** The last errors flush — the answer an empty queue gives. Starts true: nothing owed. */
+    private _errorsFlushTail;
+    /**
+     * Public: flush ALL recording-lane queues immediately. Called on APP_BACKGROUND
+     * so the server-side reaper computes endedAt from the freshest data even when
+     * the OS suspends the flush timer right after backgrounding.
+     */
+    flushAll(): Promise<void>;
+    queuePerformanceMetric(data: {
+        type: string;
+        screenName?: string;
+        duration?: number;
+        value?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Queue one log line onto the platform-agnostic logs lane. Mirrors
+     * queueNetworkRequest: drop when not in SaaS mode (no clientKey) or destroyed,
+     * batch-flush at LOGS_BATCH_SIZE. The producer supplies source/platform/level —
+     * this method makes NO assumptions about them, so a native producer reuses it as-is.
+     */
+    queueLog(data: {
+        level: string;
+        message: string;
+        source: string;
+        platform: string;
+        timestamp?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /** Stable client-generated idempotency id (matches journeyManager id scheme). */
+    private _clientId;
+    /**
+     * Hand a telemetry batch to the durable native outbox. Returns true if native
+     * accepted it (native uploader now owns delivery — caller must NOT also POST).
+     * Returns false on any miss (flag off, no session, old binary, native error) so
+     * the caller falls back to the JS HTTP path with the batch intact.
+     */
+    private _enqueueNative;
+    /**
+     * Bootstrap the native outbox once. In SaaS mode the native module's full
+     * `initialize()` (which builds a SessionManager) is never called, so the
+     * NativeOutbox/uploader would not exist. `initOutbox` constructs only the
+     * durable outbox from clientKey/apiBaseUrl/flags. Idempotent + cached so it
+     * runs at most once; resolves false on old binaries (caller falls back to JS).
+     */
+    private _ensureNativeOutbox;
+    /**
+     * Public readiness gate for the native frame outbox path (used by the frame
+     * capture adapter). Resolves true only when both outbox flags are on, a session
+     * exists, the native binary exposes the bridge, and `initOutbox` succeeded.
+     * Resolves false otherwise so the frame pipeline falls back to `captureScreenshot`.
+     */
+    ensureNativeOutboxReady(): Promise<boolean>;
+    /** Best-effort: close native segments and drain the native uploader. Never throws. */
+    private _triggerNativeFlush;
+    destroy(): void;
+    /** Wire metadata for a frame — real format/sizeBytes from native (no hardcoded literals). */
+    private _frameMeta;
+    /**
+     * P2-4: build the lean (v2) wire payload for one event. Drops redundant/empty
+     * fields at the source while NEVER dropping fields the dashboard/analytics depend
+     * on (eventId, type, timestamp, sessionId). `label` is omitted when it equals
+     * `type` (the server defaults it back). `screenName` omitted when empty. `data`
+     * is pruned of null/''/undefined leaves (one level). The `v:2` marker lets the
+     * backend/dashboard pick the lean decoder; legacy (v1/no-marker) events still
+     * decode unchanged. See P2_CONTRACT.md §4.
+     */
+    private _leanEvent;
+    /** Shallow-prune null/undefined/'' leaves from a payload object. */
+    private _pruneEmpty;
+    private _flushFrames;
+    /**
+     * Report frames the SDK gave up on, on the analytics lane.
+     *
+     * SAME EVENT NAME AS THE WEB SDK (`sdk_replay_capture_failed`) with platform-specific `reason`
+     * values, so one dashboard breakdown reads both platforms without a concept-map alias — the two
+     * SDKs share no event vocabulary otherwise (`$pageview` vs `screen_viewed`), and adding a second
+     * name here would need an entry in `event-concepts.ts` for no benefit.
+     *
+     * Latched to once per session: a session whose row was never created rejects every batch, and an
+     * unlatched report would emit one event per flush for as long as the app is open.
+     *
+     * Best-effort and never throws — a diagnostic must not be able to break the capture path it
+     * describes.
+     */
+    private _reportCaptureFailure;
+    /**
+     * Post frames in BACKEND-SAFE CHUNKS, and return the ones that were not durably accepted.
+     *
+     * WHY THIS EXISTS. `_postFrameBatch` issues exactly one request for whatever array it is handed,
+     * and both callers could hand it more than the server's 100-frame cap — the live flush via
+     * `config.batchSize`, and cross-kill recovery via the 2 MB persistence budget (~128 frames at the
+     * measured 16 KB average). The result was a 4xx, classified permanent, and on the recovery path
+     * that meant `_clearPersistedFrames()` — the ENTIRE cross-kill snapshot deleted because it was
+     * one frame too big to send in a single request it never needed to be sent in.
+     *
+     * THE RETURN VALUE IS THE POINT. The caller must be able to delete exactly what landed and keep
+     * exactly what did not, so this reports the survivors rather than throwing:
+     *   - chunk accepted            → dropped from the result (it is durably stored)
+     *   - chunk PERMANENTLY refused → dropped, and reported once. Re-sending identical bytes cannot
+     *                                 succeed, and holding it would wedge every future launch on the
+     *                                 same poison chunk. Only that chunk is abandoned; the rest still
+     *                                 gets its chance, which is the whole difference from before.
+     *   - chunk TRANSIENTLY failed  → that chunk AND every chunk after it are kept, in order. We stop
+     *                                 on the first transient failure rather than pressing on, because
+     *                                 the usual cause is the network being gone and the rest would
+     *                                 fail identically.
+     */
+    private _postFramesChunked;
+    /**
+     * POST one frame batch under an EXPLICIT sessionId (object-storage path when
+     * active, else legacy inline base64). Used by both the live flush and cross-kill
+     * recovery — recovery passes the PRIOR session's id so orphaned frames relink to
+     * it. Throws on transient error so the caller can re-queue; frame writes are
+     * idempotent server-side (upsert by frameId), so a double-send is harmless.
+     */
+    private _postFrameBatch;
+    /**
+     * Snapshot the current unflushed frame buffer to durable storage so it survives
+     * a process kill. Called on APP_BACKGROUND before the (possibly-suspended)
+     * network flush. Synchronous mirror write — reaches disk on the native store's
+     * next coalesced flush. No-op if recovery storage is absent or nothing pending.
+     */
+    persistPendingFrames(): void;
+    /**
+     * Choose which unflushed frames survive a process kill.
+     *
+     * WHY THIS IS NOT `slice(-10)`.
+     *
+     * The old rule kept the ten most RECENT frames, which is the wrong end of the buffer for replay.
+     * A delta reconstructs against its base keyframe, so ten trailing deltas whose keyframe was
+     * dropped are unplayable on their own — they arrive as `orphaned`, the state the dashboard flags
+     * as a capture defect. Keeping the keyframe and fewer deltas yields a SHORTER replay; keeping the
+     * deltas and no keyframe yields NO replay. That asymmetry is the whole decision.
+     *
+     * So: every keyframe is kept, then the most recent deltas fill whatever byte budget is left. This
+     * mirrors the web SDK's `capBytes` policy (which sheds deltas first and never the keyframe), so
+     * the two platforms lose the same thing under pressure instead of two different things.
+     *
+     * BYTES, not a frame count. A count is a poor proxy here: these carry base64 screenshots, so ten
+     * frames may be 200 KB or 4 MB depending on device resolution — and this write goes to a KV store
+     * on the background transition, where an oversized value is the thing most likely to fail and
+     * lose the snapshot entirely. `imageData.length` is the base64 length, which is within ~1% of the
+     * serialized cost and needs no extra pass.
+     */
+    private static _selectFramesToPersist;
+    /** Drop the persisted frame snapshot (after successful delivery). Never throws. */
+    private _clearPersistedFrames;
+    /**
+     * On cold launch: if a prior run left an unflushed frame snapshot, re-upload it
+     * linked to that PRIOR session, then clear it. Runs independently of the new
+     * session (uses the stored id + a direct POST, bypassing the row-ready gate —
+     * the prior session row already exists server-side). Best-effort; on transient
+     * failure the snapshot is kept for the next launch.
+     */
+    recoverPersistedFrames(): Promise<void>;
+    /**
+     * Upload a batch via object storage. Returns 'sent' on success, 'disabled' if
+     * the backend reports storage is not configured (caller falls back to inline).
+     * Throws on transient error so the caller re-queues the batch.
+     */
+    private _uploadFramesViaStorage;
+    private _flushEvents;
+    private _flushNetwork;
+    /**
+     * D11: deliver a bug report to the SAME ingest the web SDK uses
+     * (`POST /ingestion/sessions/:id/bug-reports`). Fire-and-forget with one
+     * retry deferral: RN previously had NO path to this endpoint at all —
+     * `reportBug()` emitted an analytics event no handler consumed, so the
+     * bug-reports page was empty forever for every RN app.
+     */
+    submitBugReport(report: {
+        message: string;
+        title?: string;
+        email?: string;
+    }): void;
+    /**
+     * @returns TRUE only when every group in this batch was DURABLY accepted — an HTTP 2xx, or a
+     *          handoff to the native outbox, which is itself a persistent retrying queue.
+     *
+     * The return value is not cosmetic: `drainNativeCrash` deletes the on-disk crash record on the
+     * strength of it. This method used to return `void` and swallow its own errors in the catch
+     * below, so "the promise resolved" meant nothing at all — a failed POST looked exactly like a
+     * successful one, and the caller would have deleted the only durable copy of a crash that never
+     * arrived. Anything less than a real acknowledgement here reintroduces the loss this whole
+     * change exists to prevent.
+     */
+    private _flushErrors;
+    private _flushPerformance;
+    private _flushLogs;
+    private _startFlushTimer;
+    private _stopFlushTimer;
+    private static _isPermanentHttpError;
+    private _post;
+    /**
+     * Read an ingestion response for a quota refusal (contract v1 §2a) and record it in quotaState.
+     * Only a 402 or a 2xx can carry one; anything else is not read. Never throws.
+     */
+    private static _noteQuota;
+    /**
+     * POST that parses and returns the JSON response body. Mirrors _post's headers
+     * and timeout handling; used by the object-storage presign request, which needs
+     * the returned upload URLs (the void _post discards the body).
+     */
+    private _postReturning;
+    /**
+     * PUT raw image bytes directly to a presigned storage URL. The caller decodes the base64 frame
+     * payload once (RN-safe: a Uint8Array body — the `fetch('data:…').blob()` round-trip fails under
+     * the new architecture) so the bytes PUT are exactly the `sizeBytes` declared at presign, whose
+     * Content-Length the URL is signed for. No client key header — the URL carries its own auth.
+     */
+    private _putBytes;
+    /** Strip a leading `data:<mime>;base64,` prefix if the native layer included one. */
+    private _stripDataUri;
+}
+//# sourceMappingURL=BackendSessionAdapter.d.ts.map

package/lib/typescript/features/session/DesktopSessionTransport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ScaleBun SDK — Desktop Session Transport
+ *
+ * Implements SessionTransport by wrapping the existing DebugTransport.
+ * Maps unified domain objects → protocol EventMessages with category 'session'.
+ *
+ * imageRef is an artifact reference; this transport resolves it to
+ * base64 at the transport boundary when sending frames.
+ *
+ * Never leaks Electron/IPC/Desktop implementation details into the domain layer.
+ */
+import type { DebugTransport } from '../../debug/transport';
+import type { SessionTransport, Session, JourneyEvent, ReplayFrame } from './sessionTypes';
+export declare class DesktopSessionTransport implements SessionTransport {
+    private transport;
+    constructor(transport: DebugTransport);
+    sendSessionStart(session: Session): void;
+    sendSessionEnd(session: Session): void;
+    sendEvent(event: JourneyEvent): void;
+    /**
+     * Send a replay frame to desktop.
+     * imageData (base64) is resolved at this transport boundary —
+     * the domain frame only carries an artifact reference (imageRef).
+     */
+    sendFrame(frame: ReplayFrame, imageData: string): void;
+    private _send;
+}
+//# sourceMappingURL=DesktopSessionTransport.d.ts.map