@scalebun-release/react-native 2.5.0

package/src/specs/NativeScaleBunOta.ts

@@ -0,0 +1,154 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for OTA bundle management.
+ *
+ * Manages on-disk bundle slots (current/next/previous), boot-guard markers,
+ * and atomic bundle application. All heavy lifting (download, verify, apply)
+ * is driven from JS via the OtaOrchestrator; the native module owns the
+ * filesystem layout and the boot-guard marker that operates below JS.
+ *
+ * Sprint 1: scaffold with no-op methods that return safe defaults.
+ * Sprint 2-3: real implementations (Android Kotlin + iOS Swift).
+ *
+ * Slot layout (see docs/ota-native-design.md):
+ *   {appFilesDir}/scalebun_ota/current/  — active bundle
+ *   {appFilesDir}/scalebun_ota/next/     — staged downloaded bundle
+ *   {appFilesDir}/scalebun_ota/previous/ — rollback target
+ */
+export interface Spec extends TurboModule {
+  /**
+   * Returns the absolute path to the active JS bundle, or null if using the
+   * default Metro/RN bundle. Called by the native app entry point to resolve
+   * the bundle URL at launch.
+   */
+  getActiveBundle(): string | null;
+
+  /**
+   * JSON array (string) of the trusted key IDs embedded in the app package, e.g.
+   * `["production-2026-01"]`. Reported on OTA check-in for SDK trust coverage
+   * (CICDPAGE §12) so the dashboard can measure key-rotation adoption. This is
+   * telemetry ONLY — the server never trusts a key because a device claims it.
+   * Empty array when no keys are embedded.
+   */
+  getTrustedKeyIds(): string;
+
+  /** JSON array of root/jailbreak indicator strings; [] when none found. */
+  getDeviceIntegrity(): string;
+
+  /**
+   * Returns JSON with current slot state:
+   * { current: { bundleId, version, sha256, installedAt } | null,
+   *   next: ... | null, previous: ... | null,
+   *   bootMarkerPresent: boolean }
+   */
+  getSlotState(): string;
+
+  /**
+   * Write a downloaded bundle from `sourcePath` to the 'next' slot.
+   * Verifies the sha256 before finalizing. Returns success boolean.
+   */
+  stageBundle(sourcePath: string, sha256: string): Promise<boolean>;
+
+  /**
+   * Sprint 7 (S7-NAT-1): Apply a binary patch to the current bundle,
+   * producing a new bundle in the 'next' slot.
+   *
+   * @param patchUrl - URL to download the patch file
+   * @param patchSha256 - SHA-256 of the patch file itself
+   * @param expectedSha256 - SHA-256 of the resulting full bundle after patching
+   * @returns true if patch was applied and the result matches expectedSha256
+   *
+   * If this returns false, the caller should fall back to full-bundle download.
+   * The native implementation uses bspatch (or equivalent) to apply the diff
+   * to the current bundle, then verifies the output hash.
+   */
+  stagePatch(patchUrl: string, patchSha256: string, expectedSha256: string): Promise<boolean>;
+
+  /**
+   * Atomically promote 'next' -> 'current' (and current -> previous).
+   * Sets the boot-guard marker. Returns success boolean.
+   */
+  applyUpdate(): Promise<boolean>;
+
+  /**
+   * Mark the current bundle as healthy (clears the boot-guard marker).
+   * Called by the OtaOrchestrator after the app has run successfully for
+   * a configurable duration post-update.
+   */
+  markHealthy(): void;
+
+  /**
+   * Revert to 'previous' slot (boot-guard triggered rollback).
+   * Called by native code when the boot-guard marker is still present
+   * at cold start, BEFORE JS loads.
+   */
+  revertToPrevious(): Promise<boolean>;
+
+  /**
+   * Restart the React Native runtime so the applied bundle loads NOW.
+   *
+   * Exists because `DevSettings.reload()` is a silent no-op in RELEASE builds
+   * (verified live: "Triggering app restart…" logged, nothing happened, same
+   * process, old bundle still running). That made IMMEDIATE / ON_NEXT_RESUME /
+   * `autoRestart` / the CodePush shim's restart all fiction in production.
+   * Android: `ReactHost.reload()` (bridgeless) or
+   * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
+   */
+  restartApp(): void;
+
+  /**
+   * Verify a SB-OTA-RSA-SHA256-V1 release envelope in NATIVE code, with no side
+   * effects. `envelopeJson` is the JSON `{ protocol, keyId, signedPayload,
+   * signature, downloadUrl? }` from the check response. Verification uses the
+   * trusted RSA public keys EMBEDDED in the app package (never a key from JS or
+   * the server) and platform `SHA256withRSA` (present on every supported API
+   * level — no API-33 floor).
+   *
+   * Resolves a verdict JSON string: `{ ok: boolean, code?: string, message?,
+   * keyId?, releaseId?, bundleId?, releaseSequence?, artifactSha256?,
+   * artifactSize?, resultArtifactSha256?, fingerprint? }`. A failed check is
+   * `ok:false` with a stable `code`; a rejected promise is machinery failure and
+   * the caller must treat it as a failure, never as valid.
+   */
+  verifyRelease(envelopeJson: string): Promise<string>;
+
+  /**
+   * Native-ENFORCED install: verify the RSA signature (as `verifyRelease`), then
+   * download the artifact, enforce the SIGNED size + SHA-256, and stage it into
+   * the `next` slot — all natively. JavaScript cannot stage bytes that were not
+   * proven authentic (once trusted keys are embedded, the legacy `stageBundle`
+   * path refuses). Does not activate; call `applyUpdate` to promote per the
+   * install mode. Resolves the same verdict JSON as `verifyRelease` (`ok:true`
+   * once staged).
+   */
+  verifyAndStageRelease(envelopeJson: string): Promise<string>;
+
+  /**
+   * Native-ENFORCED install from a PATCH (signed releases).
+   *
+   * Verifies the envelope exactly as `verifyAndStageRelease`; takes the expected
+   * size, hash and sequence ONLY from that verified payload; reads the current
+   * bundle under the slot lock and requires it to have come through the signed
+   * path with its recorded hash intact; downloads the patch (`patchJson`:
+   * `{url,size,sha256,baseBundleId,baseSha256?}`), rebuilds with size limits,
+   * and stages only if the result matches the SIGNED size and SHA-256. The patch
+   * bytes themselves are unsigned — the signed result hash is what anchors them.
+   *
+   * Resolves the same verdict JSON as `verifyAndStageRelease`, plus
+   * `patchUsed: true` on success. Any failure resolves `ok:false`; the caller
+   * falls back to `verifyAndStageRelease`. Absent from native builds that predate
+   * it — callers feature-detect (`typeof … === 'function'`).
+   */
+  verifyAndStagePatch(envelopeJson: string, patchJson: string): Promise<string>;
+}
+
+/**
+ * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when
+ * the native module is unavailable (web/SSR, Jest, an app that hasn't rebuilt
+ * native yet) — it returns `null` and OtaOrchestrator disables itself with a
+ * single warning. On the Old Architecture the registry transparently bridges
+ * to the legacy `NativeModules.ScaleBunOta`.
+ */
+export default TurboModuleRegistry.get<Spec>('ScaleBunOta');

package/src/specs/NativeScaleBunPerformance.ts

@@ -0,0 +1,34 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for the native performance module (`ScaleBunPerformance`).
+ *
+ * Declares the New Architecture (TurboModule) **method** surface. The native
+ * performance events (`ScaleBunPerformance_FrameMetrics`, `ScaleBunPerformance_UiHang`)
+ * are delivered via the device event emitter and consumed with
+ * `NativeEventEmitter`, independent of the TurboModule and identical on both
+ * architectures. `addListener` / `removeListeners` satisfy `NativeEventEmitter`.
+ *
+ * Method names/shapes mirror the existing native module exactly. `getAppStartInfo`
+ * resolves a generic `Object` (or `null` when not yet available).
+ *
+ * iOS note: this module subclasses `RCTEventEmitter` and is served via the
+ * interop layer on iOS (the JS resolver falls back to `NativeModules`); only
+ * Android registers it as a pure TurboModule today.
+ */
+export interface Spec extends TurboModule {
+  initialize(): Promise<boolean>;
+  getAppStartInfo(): Promise<Object>;
+  startFrameMetrics(intervalMs: number): Promise<boolean>;
+  stopFrameMetrics(): Promise<boolean>;
+  startHangDetection(thresholdMs: number): Promise<boolean>;
+  stopHangDetection(): Promise<boolean>;
+  destroy(): Promise<boolean>;
+
+  // NativeEventEmitter contract.
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('ScaleBunPerformance');

package/src/specs/NativeScaleBunProfiler.ts

@@ -0,0 +1,41 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for the native profiler module (`ScaleBunProfiler`).
+ *
+ * Declares the New Architecture (TurboModule) **method** surface. Native
+ * profiling events (`ScaleBunProfiler_SampleBatch`, `_Incident`, `_ThreadSnapshot`,
+ * `_StateChanged`, `_Capabilities`) continue to be delivered via the device
+ * event emitter and consumed with `NativeEventEmitter` — independent of the
+ * TurboModule, and identical on both architectures. `addListener` /
+ * `removeListeners` are required by `NativeEventEmitter`.
+ *
+ * Method names/shapes mirror the existing native module exactly. Codegen has a
+ * limited type system, so config/result maps are generic `Object`.
+ *
+ * iOS note: on iOS this module subclasses `RCTEventEmitter` and is served via
+ * the interop layer (the JS bridge falls back to `NativeModules`); only Android
+ * registers it as a pure TurboModule today.
+ */
+export interface Spec extends TurboModule {
+  startProfiler(config: Object): Promise<boolean>;
+  stopProfiler(): Promise<boolean>;
+  pauseProfilerStream(): Promise<boolean>;
+  resumeProfilerStream(): Promise<boolean>;
+  captureProfilerSnapshot(): Promise<Object>;
+  setProfilerConfig(config: Object): Promise<boolean>;
+  markProfilerSpan(spanName: string, spanId: string, metadata?: Object): Promise<boolean>;
+  endProfilerSpan(spanId: string): Promise<boolean>;
+  markProfilerInteraction(interactionId: string, interactionName: string): Promise<boolean>;
+  flushProfilerExport(): Promise<Object>;
+  getProfilerCapabilities(): Promise<Object>;
+  setCurrentScreen(screenName: string): Promise<boolean>;
+  setSessionId(sessionId: string): Promise<boolean>;
+
+  // NativeEventEmitter contract.
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('ScaleBunProfiler');

package/src/specs/NativeScaleBunStorage.ts

@@ -0,0 +1,59 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for the first-party durable key-value store
+ * (`ScaleBunStorage`).
+ *
+ * This is the SDK's OWN persistence backend — it requires NO third-party storage
+ * library. App developers install nothing: the native module ships inside
+ * `@scalebun/react-native` and persists data to an app-private file
+ * (Android `filesDir/scalebun_kv.json`, iOS Application Support).
+ *
+ * DESIGN — synchronous mirror + async write-through:
+ *   The JS `StorageBackend` contract is synchronous (it is read at module-load
+ *   time, e.g. the device id). RN has no synchronous durable storage in core, so
+ *   this module exposes ONE synchronous method, `getAllSync()`, used exactly
+ *   once during `createStorageBackend()` to hydrate an in-memory mirror. All
+ *   subsequent reads hit that mirror synchronously; writes are mirrored in
+ *   memory and flushed to disk asynchronously through `setItems`/`removeItems`.
+ *   Disk writes are coalesced + atomic (temp-file + rename) on the native side.
+ *
+ * Codegen note: `getAllSync` returns `string` (a JSON object of all key→value
+ * pairs) and is therefore generated as a SYNCHRONOUS JSI method on the New
+ * Architecture; on the Old Architecture it is a blocking synchronous bridge
+ * method. The write methods return `Promise<void>` so they never block the JS
+ * thread.
+ */
+export interface Spec extends TurboModule {
+  /**
+   * Synchronously return ALL persisted entries as a JSON object string
+   * (`{"<key>":"<value>", ...}`). Returns `"{}"` when the store is empty or
+   * cannot be read. Called once at init to hydrate the JS mirror.
+   */
+  getAllSync(): string;
+
+  /**
+   * Merge a batch of entries (JSON object string `{"<key>":"<value>"}`) into the
+   * store and schedule an atomic disk flush. Async — fire-and-forget from JS.
+   */
+  setItems(entriesJson: string): Promise<void>;
+
+  /**
+   * Delete a batch of keys (JSON array string `["<key>", ...]`) and schedule an
+   * atomic disk flush. Async — fire-and-forget from JS.
+   */
+  removeItems(keysJson: string): Promise<void>;
+
+  /** Delete every persisted entry and remove the backing file. Async. */
+  clear(): Promise<void>;
+}
+
+/**
+ * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when
+ * the native module is unavailable (web/SSR, Jest, an app that hasn't rebuilt
+ * native yet) — it returns `null` and the storage layer falls back to an
+ * in-memory backend with a single honest warning. On the Old Architecture the
+ * registry transparently bridges to the legacy `NativeModules.ScaleBunStorage`.
+ */
+export default TurboModuleRegistry.get<Spec>('ScaleBunStorage');

package/src/storage/StorageBackend.ts

@@ -0,0 +1,272 @@
+/**
+ * ScaleBun SDK — Storage Backend Abstraction
+ *
+ * Pluggable, synchronous key-value storage interface used by the PersistentQueue,
+ * the Engage throttle/test-seen stores, the event tracker identifiers, and the
+ * device id. It is the SDK's single storage seam — no feature talks to a storage
+ * implementation directly.
+ *
+ * DEFAULT BACKEND — first-party, zero third-party dependency:
+ * The default React Native backend (`NativeKVBackend`) is backed by the SDK's
+ * OWN native module (`ScaleBunStorage`), which persists to an app-private file
+ * (Android `filesDir/scalebun_kv.json`, iOS Application Support). App developers
+ * install NOTHING — the native module ships inside `@scalebun/react-native`.
+ *
+ * Because this interface is synchronous (it is read at module-load time) but
+ * native file IO is asynchronous, `NativeKVBackend` keeps a synchronous in-memory
+ * mirror that is hydrated ONCE from the native store via the synchronous
+ * `getAllSync()` method, then kept in sync with the disk through asynchronous,
+ * coalesced write-through (`setItems` / `removeItems`).
+ *
+ * FALLBACK:
+ * If the native module is unavailable (e.g. the app has not rebuilt native code,
+ * web/SSR, or a unit-test environment), the factory falls back to `MemoryBackend`
+ * and logs exactly ONE honest warning per app launch. Data will not survive a
+ * restart in that mode — but the SDK keeps functioning.
+ */
+
+import { logger } from '../core/logger/internalLogger';
+import ScaleBunStorage from '../specs/NativeScaleBunStorage';
+
+// ─── Interface ──────────────────────────────────────────────────────────────
+
+/**
+ * Minimal synchronous key-value storage interface for the persistent queue and
+ * the SDK's small identifiers/state.
+ *
+ * All operations are synchronous. The default native backend satisfies this with
+ * an in-memory mirror over an app-private file (hydrated once at init, written
+ * back asynchronously). Implementations must never throw.
+ */
+export interface StorageBackend {
+    /** Read a value by key. Returns undefined if not found. */
+    get(key: string): string | undefined;
+
+    /** Write a value by key. Overwrites if key exists. */
+    set(key: string, value: string): void;
+
+    /** Delete a key. No-op if key doesn't exist. */
+    delete(key: string): void;
+
+    /**
+     * Return all keys currently stored.
+     * Used during leftover drain to discover entries from previous runs.
+     */
+    getAllKeys(): string[];
+}
+
+// ─── MemoryBackend ──────────────────────────────────────────────────────────
+
+/**
+ * In-memory storage backend. Data does NOT survive app restarts.
+ *
+ * Used for:
+ * - Unit tests (no native deps)
+ * - Emergency fallback when the native durable store is unavailable
+ * - Environments where persistence is explicitly disabled
+ */
+export class MemoryBackend implements StorageBackend {
+    private data = new Map<string, string>();
+
+    get(key: string): string | undefined {
+        return this.data.get(key);
+    }
+
+    set(key: string, value: string): void {
+        this.data.set(key, value);
+    }
+
+    delete(key: string): void {
+        this.data.delete(key);
+    }
+
+    getAllKeys(): string[] {
+        return Array.from(this.data.keys());
+    }
+}
+
+// ─── NativeKVBackend ────────────────────────────────────────────────────────
+
+/**
+ * Minimal shape of the native `ScaleBunStorage` module this backend depends on.
+ * Declared structurally (not imported as the codegen `Spec`) so tests can inject
+ * a plain fake and so the backend never hard-depends on the generated type.
+ */
+export interface NativeKVModule {
+    getAllSync(): string;
+    setItems(entriesJson: string): Promise<void> | void;
+    removeItems(keysJson: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+
+/**
+ * Durable, first-party storage backed by the SDK's own `ScaleBunStorage` native
+ * module. Data survives app restarts, crashes, and force-kills (modulo the small
+ * window of the most-recent un-flushed write — see below).
+ *
+ * Strategy:
+ *   - On construction, `getAllSync()` loads the entire persisted namespace into a
+ *     synchronous in-memory `Map` (the mirror).
+ *   - Reads (`get` / `getAllKeys`) serve the mirror synchronously.
+ *   - Writes (`set` / `delete`) update the mirror immediately, then enqueue a
+ *     pending change that is flushed to the native store on a microtask. Pending
+ *     sets/deletes for the same key are coalesced; ordering is preserved per key.
+ *
+ * Durability window: a write is in the mirror immediately but reaches disk on the
+ * next flush. A process kill in that sub-millisecond window can lose the most
+ * recent write(s). This matches any async-persistence store and is the price of
+ * not blocking the JS thread on every event. Everything already on disk is safe
+ * and atomically written by the native side.
+ */
+export class NativeKVBackend implements StorageBackend {
+    private readonly native: NativeKVModule;
+    private readonly mirror: Map<string, string>;
+
+    /** Keys whose latest value still needs to be pushed to the native store. */
+    private pendingSets = new Map<string, string>();
+    /** Keys whose deletion still needs to be pushed to the native store. */
+    private pendingDeletes = new Set<string>();
+    private flushScheduled = false;
+
+    constructor(native: NativeKVModule) {
+        this.native = native;
+        this.mirror = this._hydrate();
+    }
+
+    /** Load the full persisted namespace synchronously into the mirror. */
+    private _hydrate(): Map<string, string> {
+        const map = new Map<string, string>();
+        try {
+            const raw = this.native.getAllSync();
+            if (raw) {
+                const obj = JSON.parse(raw) as Record<string, unknown>;
+                for (const k of Object.keys(obj)) {
+                    const v = obj[k];
+                    if (typeof v === 'string') map.set(k, v);
+                }
+            }
+        } catch (e) {
+            // A corrupt/unreadable store must not break init — start empty and
+            // let the native side overwrite with the next atomic flush.
+            logger.warn('[StorageBackend] Native store hydrate failed; starting empty this run:', (e as Error)?.message);
+        }
+        return map;
+    }
+
+    get(key: string): string | undefined {
+        return this.mirror.get(key);
+    }
+
+    set(key: string, value: string): void {
+        this.mirror.set(key, value);
+        this.pendingSets.set(key, value);
+        this.pendingDeletes.delete(key);
+        this._scheduleFlush();
+    }
+
+    delete(key: string): void {
+        this.mirror.delete(key);
+        this.pendingDeletes.add(key);
+        this.pendingSets.delete(key);
+        this._scheduleFlush();
+    }
+
+    getAllKeys(): string[] {
+        return Array.from(this.mirror.keys());
+    }
+
+    /** Coalesce pending writes and flush them to the native store on a microtask. */
+    private _scheduleFlush(): void {
+        if (this.flushScheduled) return;
+        this.flushScheduled = true;
+        // Microtask: batch every synchronous set/delete in the current tick into a
+        // single native round-trip, so a popBatch() of 50 entries is one flush.
+        Promise.resolve().then(() => this._flush());
+    }
+
+    private _flush(): void {
+        this.flushScheduled = false;
+        try {
+            if (this.pendingSets.size > 0) {
+                const obj: Record<string, string> = {};
+                for (const [k, v] of this.pendingSets) obj[k] = v;
+                this.pendingSets.clear();
+                void Promise.resolve(this.native.setItems(JSON.stringify(obj)))?.catch?.(() => {});
+            }
+            if (this.pendingDeletes.size > 0) {
+                const keys = Array.from(this.pendingDeletes);
+                this.pendingDeletes.clear();
+                void Promise.resolve(this.native.removeItems(JSON.stringify(keys)))?.catch?.(() => {});
+            }
+        } catch {
+            // Native write-through failure is non-fatal; the mirror remains correct
+            // for this session and the next flush retries newer writes.
+        }
+    }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the SDK's native KV module, or null if it isn't present in this
+ * runtime (web/SSR, Jest, or an app that hasn't rebuilt native after upgrading).
+ */
+function getNativeModule(): NativeKVModule | null {
+    const mod = ScaleBunStorage as unknown as NativeKVModule | null | undefined;
+    if (mod && typeof mod.getAllSync === 'function') return mod;
+    return null;
+}
+
+/**
+ * Shared singleton — `createStorageBackend()` must return the SAME instance to
+ * every caller so the in-memory mirror, the pending-write queue, and the
+ * one-time fallback warning are not duplicated across features.
+ */
+let sharedBackend: StorageBackend | null = null;
+
+/**
+ * Create (once) and return the shared storage backend for the current
+ * environment.
+ *
+ * Selection order:
+ *   1. `NativeKVBackend` over the first-party `ScaleBunStorage` native module
+ *      (durable, app-private file — the default for React Native).
+ *   2. `MemoryBackend` (emergency fallback — no persistence), with exactly ONE
+ *      honest warning per launch. The warning never mentions any third-party
+ *      library.
+ *
+ * Idempotent: subsequent calls return the cached instance.
+ */
+export function createStorageBackend(): StorageBackend {
+    if (sharedBackend) return sharedBackend;
+
+    const native = getNativeModule();
+    if (native) {
+        try {
+            sharedBackend = new NativeKVBackend(native);
+            __DEV__ && logger.debug('[StorageBackend] Using native durable backend (ScaleBunStorage)');
+            return sharedBackend;
+        } catch (e) {
+            logger.warn('[StorageBackend] Native durable store failed to initialize; ' +
+                'using in-memory storage for this launch — events may not survive an app restart:', (e as Error)?.message);
+            sharedBackend = new MemoryBackend();
+            return sharedBackend;
+        }
+    }
+
+    logger.warn(
+        '[StorageBackend] Native durable store unavailable; using in-memory storage ' +
+        'for this launch — events may not survive an app restart. ' +
+        'Rebuild the app with the ScaleBun native module to enable disk persistence.',
+    );
+    sharedBackend = new MemoryBackend();
+    return sharedBackend;
+}
+
+/**
+ * TEST-ONLY: reset the shared backend singleton so each test can exercise the
+ * factory's selection logic from a clean slate.
+ */
+export function __resetStorageBackendForTests(): void {
+    sharedBackend = null;
+}

package/src/transport/auth/sdkSession.ts

@@ -0,0 +1,27 @@
+export class SdkSessionManager {
+    private token?: string;
+    private expiresAt?: number;
+
+    setSession(token: string, expiresIn: number) {
+        this.token = token;
+        this.expiresAt = Date.now() + expiresIn * 1000;
+    }
+
+    getToken(): string | undefined {
+        if (this.token && this.expiresAt && Date.now() < this.expiresAt) {
+            return this.token;
+        }
+        return undefined;
+    }
+
+    isExpired(): boolean {
+        return !this.getToken();
+    }
+
+    clear() {
+        this.token = undefined;
+        this.expiresAt = undefined;
+    }
+}
+
+export const sdkSession = new SdkSessionManager();

package/src/transport/backoff/exponentialJitter.ts

@@ -0,0 +1,9 @@
+/**
+ * Exponential backoff with jitter.
+ */
+export function getDelayWithJitter(attempt: number, base = 1000): number {
+    const cap = 30000;
+    const delay = Math.min(cap, base * Math.pow(2, attempt));
+    const jitter = delay * 0.2 * Math.random();
+    return delay + jitter;
+}

package/src/transport/http/endpoints.ts

@@ -0,0 +1,33 @@
+export const ENDPOINTS = {
+    // Legacy replay endpoints (backward compat)
+    SESSIONS: '/sdk/sessions',
+    EVENTS: '/sdk/events',
+    // SaaS ingestion endpoints
+    INGESTION_START: '/ingestion/sessions',
+    INGESTION_IDENTIFY: (id: string) => `/ingestion/sessions/${id}/identify`,
+    INGESTION_FRAMES: (id: string) => `/ingestion/sessions/${id}/frames`,
+    INGESTION_FRAMES_PRESIGN: (id: string) => `/ingestion/sessions/${id}/frames/presign`,
+    INGESTION_EVENTS: (id: string) => `/ingestion/sessions/${id}/events`,
+    INGESTION_NETWORK: (id: string) => `/ingestion/sessions/${id}/network`,
+    INGESTION_LOGS: (id: string) => `/ingestion/sessions/${id}/logs`,
+    INGESTION_ERRORS: (id: string) => `/ingestion/sessions/${id}/errors`,
+    INGESTION_PERFORMANCE: (id: string) => `/ingestion/sessions/${id}/performance`,
+    INGESTION_FINALIZE: (id: string) => `/ingestion/sessions/${id}/finalize`,
+    INGESTION_RATING: (id: string) => `/ingestion/sessions/${id}/rating`,
+    INGESTION_RATING_STANDALONE: '/ingestion/ratings',
+    // Rating-funnel event lane (ratings-rebuild CONTRACT §1.2). Batch POST of the
+    // 5 closed funnel events; deduped server-side on client eventId (D8).
+    INGESTION_RATING_EVENTS: '/ingestion/rating-events',
+    // Engage surface (CONTRACT.md §1.3 / §3) — config serve + upload lanes.
+    // Config is a function so app/user context can be passed as query params for
+    // server-side targeting/throttle evaluation; uploads are plain POST constants.
+    ENGAGE_CONFIG: (query?: string) => `/sdk/engage/config${query ? `?${query}` : ''}`, // GET (D3 serve lane)
+    COACH_CONFIG: (preview?: string) => `/sdk/coach/config${preview ? `?preview=${encodeURIComponent(preview)}` : ''}`,
+    ENGAGE_RESPONSES: '/sdk/engage/responses', // POST (campaign responses)
+    ENGAGE_EVENTS: '/sdk/engage/events', // POST (in-app impression/click/dismiss)
+    ENGAGE_SURVEY_IMPRESSIONS: '/sdk/engage/surveys/impressions', // POST (shown/started funnel beacons)
+    ENGAGE_DEVICE_TOKEN: '/sdk/engage/device-token', // POST (push-token registration)
+    ENGAGE_ATTACHMENTS_PRESIGN: '/sdk/engage/attachments/presign', // POST (screenshot/voice presign)
+    // OTA (Over-the-Air Updates) — check endpoint for bundle availability.
+    OTA_CHECK: '/sdk/ota/check', // POST (Sprint 1: returns { action: 'NONE' })
+};