@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/engage/EngageTransport.ts

@@ -1,668 +1,668 @@
-/**
- * ScaleBun SDK — Engage Transport (foundation)
- *
- * Transport layer for the Engage surface. Provides:
- *   - `fetchEngageConfig()` — a DIRECT GET of the versioned config-serve lane
- *     (§1.3). Not queued: the config is a one-shot read the renderer consumes.
- *   - `uploadEngageResponse()` / `uploadEngageEvent()` / `registerDeviceToken()`
- *     — offline-resilient UPLOADS that ride the SAME outbox/batch-flush pattern
- *     proven by `BackendSessionAdapter` (pending[] queues, interval flush,
- *     re-queue-on-failure, gated on `clientKey`, `x-scalebun-client-key` header).
- *
- * This does NOT fork a second HTTP stack — it mirrors `BackendSessionAdapter._post`
- * exactly (same headers, timeout, abort, re-queue semantics). Idempotency keys
- * (`responseId` / `eventId`, client UUIDs) are stamped here per the contract (D8).
- *
- * Render/overlay is OUT OF SCOPE this stage.
- */
-
-import { logger } from '../../core/logger/internalLogger';
-import { base64ToBytes } from '../../core/encoding/base64';
-import { ENDPOINTS } from '../../transport/http/endpoints';
-import { getDeviceId } from '../../core/id/deviceId';
-import {
-    ENGAGE_SCHEMA_VERSION,
-    type DeviceTokenInput,
-    type DeviceTokenRegistration,
-    type EngageAttachmentDraft,
-    type EngageAttachmentMeta,
-    type EngageAttachmentPresignResult,
-    type EngageConfigContext,
-    type EngageConfigResponse,
-    type CoachConfigResponse,
-    type EngageEventInput,
-    type EngageEventUpload,
-    type EngageResponse,
-    type EngageResponseInput,
-    type RatingFunnelEventInput,
-    type RatingFunnelEventUpload,
-    type SurveyImpressionInput,
-    type SurveyImpressionUpload,
-} from './engageTypes';
-
-/** Voice notes are hard-capped < 30s — enforced at the recorder, here, and server-side. */
-export const VOICE_MAX_DURATION_MS = 30000;
-
-/** Stages of a confirmed submit (Slice D5), surfaced to the in-prompt loading UI. */
-export type SubmitStage = 'uploading' | 'saving';
-
-/** Generate an RFC4122 v4 UUID (idempotency keys, D8). Matches the device-id scheme. */
-function uuidV4(): string {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
-
-export interface EngageTransportConfig {
-    /** Backend API base URL (e.g. https://api.scalebun.com). */
-    endpoint: string;
-    /** SaaS multi-tenant client key — gates upload lanes + x-scalebun-client-key header. */
-    clientKey?: string;
-    /** Auto-flush interval in ms. Default: 3000 (mirrors BackendSessionAdapter). */
-    flushIntervalMs?: number;
-    /** Request timeout in ms. Default: 15000. */
-    timeoutMs?: number;
-}
-
-export class EngageTransport {
-    private readonly config: Required<Omit<EngageTransportConfig, 'clientKey'>> & {
-        clientKey?: string;
-    };
-
-    // Outbox lanes (mirror BackendSessionAdapter's pending* arrays).
-    private pendingResponses: EngageResponse[] = [];
-    private pendingEvents: EngageEventUpload[] = [];
-    private pendingTokens: DeviceTokenRegistration[] = [];
-    private pendingRatingEvents: RatingFunnelEventUpload[] = [];
-    private pendingSurveyImpressions: SurveyImpressionUpload[] = [];
-    private flushTimer: ReturnType<typeof setInterval> | null = null;
-    private destroyed = false;
-
-    /** Eager-flush thresholds (mirror the network/error lane batch sizes). */
-    private static readonly RESPONSES_BATCH_SIZE = 10;
-    private static readonly EVENTS_BATCH_SIZE = 20;
-    private static readonly RATING_EVENTS_BATCH_SIZE = 20;
-    private static readonly SURVEY_IMPRESSIONS_BATCH_SIZE = 20;
-
-    constructor(config: EngageTransportConfig) {
-        this.config = {
-            flushIntervalMs: 3000,
-            timeoutMs: 15_000,
-            ...config,
-            clientKey: config.clientKey,
-        };
-        this._startFlushTimer();
-    }
-
-    // ─── Config serve (direct GET — NOT queued) ─────────────────────────────
-
-    /**
-     * Fetch the versioned Engage config (§1.3). Direct GET; returns the typed
-     * payload or null on any failure (never throws). The shared cross-platform JS
-     * overlay (D4) consumes this in a later slice.
-     */
-    async fetchEngageConfig(context?: EngageConfigContext): Promise<EngageConfigResponse | null> {
-        const query = this._buildConfigQuery(context);
-        const url = `${this.config.endpoint}${ENDPOINTS.ENGAGE_CONFIG(query)}`;
-
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.clientKey) {
-                headers['x-scalebun-client-key'] = this.config.clientKey;
-            }
-            // `cache: 'no-store'` — the config carries per-device test previews with a
-            // short TTL + consume-on-render lifecycle, so a stale cached body could show a
-            // consumed preview or hide a freshly-queued one. Always read live (T1).
-            const response = await fetch(url, {
-                method: 'GET',
-                headers,
-                cache: 'no-store',
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                logger.warn(`[Engage] config fetch HTTP ${response.status}`);
-                return null;
-            }
-            return (await response.json()) as EngageConfigResponse;
-        } catch (err: any) {
-            logger.warn(`[Engage] config fetch failed: ${err?.message}`);
-            return null;
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    /** Fetch published standalone coachmark tours from the same SDK-key-authenticated config lane. */
-    async fetchCoachConfig(preview?: string): Promise<CoachConfigResponse | null> {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.clientKey) headers['x-scalebun-client-key'] = this.config.clientKey;
-            const response = await fetch(`${this.config.endpoint}${ENDPOINTS.COACH_CONFIG(preview)}`, {
-                method: 'GET', headers, cache: 'no-store', signal: controller.signal,
-            });
-            if (!response.ok) return null;
-            return await response.json() as CoachConfigResponse;
-        } catch (err: any) {
-            logger.warn(`[Coachmarks] config fetch failed: ${err?.message}`);
-            return null;
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    private _buildConfigQuery(context?: EngageConfigContext): string {
-        if (!context) return '';
-        const params: string[] = [];
-        if (context.platform) params.push(`platform=${encodeURIComponent(context.platform)}`);
-        if (context.appVersion) params.push(`appVersion=${encodeURIComponent(context.appVersion)}`);
-        if (context.endUserId) params.push(`endUserId=${encodeURIComponent(context.endUserId)}`);
-        if (context.deviceId) params.push(`deviceId=${encodeURIComponent(context.deviceId)}`);
-        return params.join('&');
-    }
-
-    // ─── Upload lanes (ride the outbox) ─────────────────────────────────────
-
-    /**
-     * Enqueue a campaign response (§1.4). Client-stamps `responseId` (UUID),
-     * `schemaVersion`, `clientTs`. Dropped when not in SaaS mode (no clientKey).
-     */
-    uploadEngageResponse(input: EngageResponseInput): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        this._enqueueResponse({
-            ...input,
-            responseId: uuidV4(),
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-            clientTs: new Date().toISOString(),
-        });
-    }
-
-    /**
-     * [P3-e] Submit a response that carries native attachments (screenshot/voice).
-     * Mirrors the replay frame pipeline: presign → PUT bytes direct to storage →
-     * enqueue the response with key-only metadata (NEVER base64 in the response body,
-     * NEVER a duplicate of replay/session data — only the new attachment fact, linked
-     * by the shared responseId). Voice over the hard cap is dropped client-side
-     * (recorder + here + server all enforce it). Resolves after the response is queued.
-     */
-    async submitResponseWithAttachments(
-        input: EngageResponseInput,
-        drafts: EngageAttachmentDraft[],
-    ): Promise<void> {
-        if (this.destroyed || !this.config.clientKey) return;
-        const responseId = uuidV4();
-
-        const usable = drafts.filter(
-            (d) =>
-                !!d.base64 &&
-                !(
-                    d.kind === 'voice' &&
-                    typeof d.durationMs === 'number' &&
-                    d.durationMs >= VOICE_MAX_DURATION_MS
-                ),
-        );
-
-        let attachments: EngageAttachmentMeta[] | undefined;
-        if (usable.length > 0) {
-            attachments = await this._uploadAttachments(responseId, usable);
-        }
-
-        this._enqueueResponse({
-            ...input,
-            responseId,
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-            clientTs: new Date().toISOString(),
-            ...(attachments && attachments.length > 0 ? { attachments } : {}),
-        });
-    }
-
-    /**
-     * [Slice D5] CONFIRMED submit: resolve ONLY after the response (and any audio/
-     * screenshot bytes) are actually persisted server-side — not when the request is
-     * merely fired. Drives the reusable submitting→success→error UI: `onStage` reports
-     * real stages (`uploading` → `saving`), and the promise rejects on failure so the
-     * caller can show a retryable error.
-     *
-     * IDEMPOTENT: the caller owns `responseId` and passes the SAME one on retry. Both
-     * the response (skipDuplicates on responseId) and each attachment (stable id +
-     * skipDuplicates on attachmentId, same storage key) de-dupe server-side, so a retry
-     * after a partial failure can never create duplicate rows or objects (D8).
-     */
-    async submitResponseConfirmed(
-        input: EngageResponseInput,
-        drafts: EngageAttachmentDraft[],
-        opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
-    ): Promise<void> {
-        if (this.destroyed || !this.config.clientKey) {
-            throw new Error('engage transport unavailable');
-        }
-        const { responseId, onStage } = opts;
-
-        const usable = drafts.filter(
-            (d) =>
-                !!d.base64 &&
-                !(
-                    d.kind === 'voice' &&
-                    typeof d.durationMs === 'number' &&
-                    d.durationMs >= VOICE_MAX_DURATION_MS
-                ),
-        );
-
-        let attachments: EngageAttachmentMeta[] | undefined;
-        if (usable.length > 0) {
-            onStage?.('uploading');
-            // Stable per-response attachment ids → retry-safe (see _uploadAttachments).
-            attachments = await this._uploadAttachments(
-                responseId,
-                usable,
-                (i) => `${responseId}-att-${i}`,
-            );
-        }
-
-        onStage?.('saving');
-        // Direct POST (await real persistence) — NOT the batched outbox. Throws on
-        // non-2xx so the caller surfaces a retryable error.
-        await this._post(ENDPOINTS.ENGAGE_RESPONSES, {
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-            responses: [
-                {
-                    ...input,
-                    responseId,
-                    schemaVersion: ENGAGE_SCHEMA_VERSION,
-                    clientTs: new Date().toISOString(),
-                    ...(attachments && attachments.length > 0 ? { attachments } : {}),
-                },
-            ],
-        });
-    }
-
-    private _enqueueResponse(response: EngageResponse): void {
-        this.pendingResponses.push(response);
-        if (this.pendingResponses.length >= EngageTransport.RESPONSES_BATCH_SIZE) {
-            this._flushResponses().catch(() => {});
-        }
-    }
-
-    /**
-     * Presign → PUT each attachment's bytes → return key-only metadata. Returns []
-     * when storage is disabled server-side (the response still submits, sans media).
-     * Each attachment gets a client UUID for idempotent re-submit.
-     */
-    private async _uploadAttachments(
-        responseId: string,
-        drafts: EngageAttachmentDraft[],
-        idFor?: (index: number) => string,
-    ): Promise<EngageAttachmentMeta[]> {
-        // Idempotent path passes a STABLE id generator (derived from responseId) so a
-        // retry reuses the same attachmentId — backend `skipDuplicates` then no-ops the
-        // re-insert and the storage PUT overwrites the same key (no duplicate row/object).
-        const withIds = drafts.map((d, i) => ({ id: idFor ? idFor(i) : uuidV4(), draft: d }));
-        let presign: { enabled: boolean; attachments: EngageAttachmentPresignResult[] } | null = null;
-        try {
-            presign = await this._postReturning(ENDPOINTS.ENGAGE_ATTACHMENTS_PRESIGN, {
-                schemaVersion: ENGAGE_SCHEMA_VERSION,
-                attachments: withIds.map(({ id, draft }) => ({
-                    attachmentId: id,
-                    responseId,
-                    kind: draft.kind,
-                    contentType: draft.mime,
-                })),
-            });
-        } catch (err: any) {
-            logger.warn(`[Engage] attachment presign failed: ${err?.message}`);
-            return [];
-        }
-        if (!presign || presign.enabled === false) {
-            logger.warn('[Engage] object storage disabled — attachment not uploaded');
-            return [];
-        }
-
-        const byId = new Map(presign.attachments.map((p) => [p.attachmentId, p]));
-        const meta: EngageAttachmentMeta[] = [];
-        await Promise.all(
-            withIds.map(async ({ id, draft }) => {
-                const p = byId.get(id);
-                if (!p) return;
-                try {
-                    await this._putBytes(p.uploadUrl, draft.base64, p.contentType);
-                    meta.push({
-                        attachmentId: id,
-                        kind: draft.kind,
-                        storageKey: p.storageKey,
-                        mime: draft.mime,
-                        width: draft.width,
-                        height: draft.height,
-                        byteSize: draft.byteSize,
-                        durationMs: draft.durationMs,
-                        masked: draft.masked,
-                        ...(draft.kind === 'voice'
-                            ? {
-                                  transcript: draft.transcriptApproved ? (draft.transcript ?? '') : undefined,
-                                  transcriptApproved: draft.transcriptApproved ?? false,
-                              }
-                            : {}),
-                    });
-                } catch (err: any) {
-                    logger.warn(`[Engage] attachment PUT failed (${draft.kind}): ${err?.message}`);
-                }
-            }),
-        );
-        return meta;
-    }
-
-    /**
-     * Enqueue an in-app tracking event (§2.5). Client-stamps `eventId` (UUID),
-     * `schemaVersion`, `timestamp`. Dropped when not in SaaS mode.
-     */
-    uploadEngageEvent(input: EngageEventInput): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        const event: EngageEventUpload = {
-            ...input,
-            eventId: uuidV4(),
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-            timestamp: new Date().toISOString(),
-        };
-        this.pendingEvents.push(event);
-        if (this.pendingEvents.length >= EngageTransport.EVENTS_BATCH_SIZE) {
-            this._flushEvents().catch(() => {});
-        }
-    }
-
-    uploadSurveyImpression(input: SurveyImpressionInput): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        this.pendingSurveyImpressions.push({
-            ...input,
-            beaconId: uuidV4(),
-            clientTs: new Date().toISOString(),
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-        });
-        if (this.pendingSurveyImpressions.length >= EngageTransport.SURVEY_IMPRESSIONS_BATCH_SIZE) {
-            this._flushSurveyImpressions().catch(() => {});
-        }
-    }
-
-    /**
-     * Enqueue a rating-funnel tracking event (ratings-rebuild CONTRACT §1.2).
-     * Client-stamps `eventId` (UUID, D8 dedup) + `ts` (client clock). These are
-     * tracking FACTS feeding the Overview funnel — NOT campaign responses (D1), so
-     * they ride their own lane to `/ingestion/rating-events`. Dropped when not in
-     * SaaS mode (no clientKey).
-     */
-    uploadRatingEvent(input: RatingFunnelEventInput): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        const event: RatingFunnelEventUpload = {
-            ...input,
-            eventId: uuidV4(),
-            ts: new Date().toISOString(),
-        };
-        this.pendingRatingEvents.push(event);
-        if (this.pendingRatingEvents.length >= EngageTransport.RATING_EVENTS_BATCH_SIZE) {
-            this._flushRatingEvents().catch(() => {});
-        }
-    }
-
-    /**
-     * Enqueue a device-token registration (§2.2). `deviceId` defaults to the SDK
-     * device id; `platform` is the routing source of truth (D5). Idempotent
-     * upsert server-side on (environmentId, deviceId). Flushes eagerly — token
-     * registration is low-volume and latency-sensitive.
-     */
-    registerDeviceToken(input: DeviceTokenInput): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        const registration: DeviceTokenRegistration = {
-            schemaVersion: ENGAGE_SCHEMA_VERSION,
-            deviceId: input.deviceId ?? getDeviceId(),
-            pushToken: input.pushToken,
-            platform: input.platform,
-            tokenStatus: 'active',
-            ...(input.pushProvider ? { pushProvider: input.pushProvider } : {}),
-            ...(input.installationId ? { installationId: input.installationId } : {}),
-            ...(input.sdkVersion ? { sdkVersion: input.sdkVersion } : {}),
-        };
-        this.pendingTokens.push(registration);
-        this._flushTokens().catch(() => {});
-    }
-
-    /** Force-flush every Engage upload lane immediately (e.g. on app background). */
-    async flushAll(): Promise<void> {
-        await Promise.all([
-            this._flushResponses(),
-            this._flushEvents(),
-            this._flushRatingEvents(),
-            this._flushSurveyImpressions(),
-            this._flushTokens(),
-        ]);
-    }
-
-    // ─── Lifecycle ──────────────────────────────────────────────────────────
-
-    destroy(): void {
-        this.destroyed = true;
-        this._stopFlushTimer();
-        this.pendingResponses = [];
-        this.pendingEvents = [];
-        this.pendingRatingEvents = [];
-        this.pendingSurveyImpressions = [];
-        this.pendingTokens = [];
-    }
-
-    // ─── Internal: flush (re-queue on failure, mirrors BackendSessionAdapter) ─
-
-    /**
-     * Should a failed batch go back on the queue?
-     *
-     * NO for 4xx: the server has rejected this payload's SHAPE, and retrying an identical body
-     * can only produce the identical rejection. Because a rejected batch is unshifted onto the
-     * HEAD of the queue, re-queueing a 4xx blocks every later event behind it forever — one bad
-     * item silently stalls the whole lane for that install. (This is exactly what a missing
-     * event type in the backend's @IsIn allowlist did to in-app telemetry.)
-     *
-     * YES for 5xx, timeouts and network errors: those are transient and the payload is fine.
-     */
-    private static _shouldRequeue(err: unknown): boolean {
-        const status = (err as { status?: number } | null)?.status;
-        if (typeof status !== 'number') return true; // network/abort/unknown → transient
-        return status < 400 || status >= 500;
-    }
-
-    private async _flushResponses(): Promise<void> {
-        if (this.pendingResponses.length === 0 || !this.config.clientKey) return;
-        const batch = this.pendingResponses.splice(0, 50);
-        try {
-            await this._post(ENDPOINTS.ENGAGE_RESPONSES, {
-                schemaVersion: ENGAGE_SCHEMA_VERSION,
-                responses: batch,
-            });
-            logger.debug(`[Engage] flushed ${batch.length} response(s)`);
-        } catch (err) {
-            if (EngageTransport._shouldRequeue(err)) this.pendingResponses.unshift(...batch);
-            else logger.warn(`[Engage] dropped ${batch.length} response(s) — rejected by server`);
-        }
-    }
-
-    /**
-     * Force an immediate flush of queued in-app events instead of waiting for the
-     * batch threshold / flush timer. Used for the ONE-SHOT test-preview ACK
-     * (impression/dismiss carrying `previewId`): the backend must consume the preview
-     * row promptly so a fast "close → kill app → reopen" can't re-serve a still-
-     * `delivered` test. Best-effort, never throws (re-queues on failure like the timer).
-     */
-    flushEventsNow(): void {
-        this._flushEvents().catch(() => {});
-    }
-
-    private async _flushEvents(): Promise<void> {
-        if (this.pendingEvents.length === 0 || !this.config.clientKey) return;
-        const batch = this.pendingEvents.splice(0, 50);
-        try {
-            await this._post(ENDPOINTS.ENGAGE_EVENTS, {
-                schemaVersion: ENGAGE_SCHEMA_VERSION,
-                events: batch,
-            });
-            logger.debug(`[Engage] flushed ${batch.length} event(s)`);
-        } catch (err) {
-            if (EngageTransport._shouldRequeue(err)) this.pendingEvents.unshift(...batch);
-            else logger.warn(`[Engage] dropped ${batch.length} in-app event(s) — rejected by server`);
-        }
-    }
-
-    private async _flushRatingEvents(): Promise<void> {
-        if (this.pendingRatingEvents.length === 0 || !this.config.clientKey) return;
-        const batch = this.pendingRatingEvents.splice(0, 50);
-        try {
-            await this._post(ENDPOINTS.INGESTION_RATING_EVENTS, {
-                schemaVersion: ENGAGE_SCHEMA_VERSION,
-                events: batch,
-            });
-            logger.debug(`[Engage] flushed ${batch.length} rating-event(s)`);
-        } catch (err) {
-            if (EngageTransport._shouldRequeue(err)) this.pendingRatingEvents.unshift(...batch);
-            else logger.warn(`[Engage] dropped ${batch.length} rating-event(s) — rejected by server`);
-        }
-    }
-
-    private async _flushSurveyImpressions(): Promise<void> {
-        if (this.pendingSurveyImpressions.length === 0 || !this.config.clientKey) return;
-        const batch = this.pendingSurveyImpressions.splice(0, 50);
-        try {
-            await this._post(ENDPOINTS.ENGAGE_SURVEY_IMPRESSIONS, {
-                schemaVersion: ENGAGE_SCHEMA_VERSION,
-                impressions: batch,
-            });
-            logger.debug(`[Engage] flushed ${batch.length} survey impression(s)`);
-        } catch (err) {
-            if (EngageTransport._shouldRequeue(err)) this.pendingSurveyImpressions.unshift(...batch);
-            else logger.warn(`[Engage] dropped ${batch.length} survey impression(s) — rejected by server`);
-        }
-    }
-
-    private async _flushTokens(): Promise<void> {
-        if (this.pendingTokens.length === 0 || !this.config.clientKey) return;
-        // Token registration is a single-row upsert per contract — post one at a time
-        // so a retry re-queues only the failing token, not an unrelated batch.
-        const registration = this.pendingTokens.shift();
-        if (!registration) return;
-        try {
-            await this._post(ENDPOINTS.ENGAGE_DEVICE_TOKEN, registration);
-            logger.debug(`[Engage] registered device token (${registration.platform})`);
-        } catch (err) {
-            if (EngageTransport._shouldRequeue(err)) this.pendingTokens.unshift(registration);
-            else logger.warn('[Engage] dropped a device-token registration — rejected by server');
-        }
-    }
-
-    private _startFlushTimer(): void {
-        this._stopFlushTimer();
-        this.flushTimer = setInterval(() => {
-            this._flushResponses().catch(() => {});
-            this._flushEvents().catch(() => {});
-            this._flushRatingEvents().catch(() => {});
-            this._flushSurveyImpressions().catch(() => {});
-            this._flushTokens().catch(() => {});
-        }, this.config.flushIntervalMs);
-    }
-
-    private _stopFlushTimer(): void {
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
-        }
-    }
-
-    /** POST mirroring BackendSessionAdapter._post: same headers/timeout/abort/throw. */
-    private async _post(path: string, body: unknown): Promise<void> {
-        const url = `${this.config.endpoint}${path}`;
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.clientKey) {
-                headers['x-scalebun-client-key'] = this.config.clientKey;
-            }
-            const response = await fetch(url, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                logger.warn(`[Engage] HTTP ${response.status} from ${path}`);
-                // Carry the status on the error so flush lanes can tell "retry later" (5xx /
-                // network) from "this payload will never be accepted" (4xx). Re-queueing a 4xx
-                // is an infinite poison loop by construction.
-                throw Object.assign(new Error(`HTTP ${response.status}`), {
-                    status: response.status,
-                });
-            }
-        } catch (err: any) {
-            if (err?.name === 'AbortError') {
-                logger.warn(`[Engage] Timeout on ${path}`);
-            } else {
-                logger.warn(`[Engage] Failed ${path}: ${err?.message}`);
-            }
-            throw err;
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    /** POST returning parsed JSON (presign lane). Mirrors BackendSessionAdapter._postReturning. */
-    private async _postReturning<T>(path: string, body: unknown): Promise<T> {
-        const url = `${this.config.endpoint}${path}`;
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.clientKey) {
-                headers['x-scalebun-client-key'] = this.config.clientKey;
-            }
-            const response = await fetch(url, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
-            if (!response.ok) throw new Error(`HTTP ${response.status}`);
-            return (await response.json()) as T;
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    /**
-     * PUT raw bytes directly to a presigned storage URL. Decodes base64 to a binary
-     * Blob via a data-URI round-trip (RN-safe — a base64 string body would be stored
-     * verbatim and corrupt the file). No client-key header — the URL carries its auth.
-     */
-    private async _putBytes(uploadUrl: string, base64: string, contentType: string): Promise<void> {
-        // RN-safe base64→binary: decode to a Uint8Array and send that as the body.
-        // The `fetch('data:…').blob()` round-trip fails under the new architecture
-        // ("Network request failed"), so we never rely on it. RN's XHR sends a typed
-        // array as real binary bytes (it base64-transfers `.buffer` to native).
-        const bytes = base64ToBytes(this._stripDataUri(base64));
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const response = await fetch(uploadUrl, {
-                method: 'PUT',
-                headers: { 'Content-Type': contentType },
-                body: bytes,
-                signal: controller.signal,
-            });
-            if (!response.ok) throw new Error(`HTTP ${response.status}`);
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    /** Strip a leading `data:<mime>;base64,` prefix if the native layer included one. */
-    private _stripDataUri(s: string): string {
-        const comma = s.indexOf(',');
-        return s.startsWith('data:') && comma !== -1 ? s.slice(comma + 1) : s;
-    }
-}
+/**
+ * ScaleBun SDK — Engage Transport (foundation)
+ *
+ * Transport layer for the Engage surface. Provides:
+ *   - `fetchEngageConfig()` — a DIRECT GET of the versioned config-serve lane
+ *     (§1.3). Not queued: the config is a one-shot read the renderer consumes.
+ *   - `uploadEngageResponse()` / `uploadEngageEvent()` / `registerDeviceToken()`
+ *     — offline-resilient UPLOADS that ride the SAME outbox/batch-flush pattern
+ *     proven by `BackendSessionAdapter` (pending[] queues, interval flush,
+ *     re-queue-on-failure, gated on `clientKey`, `x-scalebun-client-key` header).
+ *
+ * This does NOT fork a second HTTP stack — it mirrors `BackendSessionAdapter._post`
+ * exactly (same headers, timeout, abort, re-queue semantics). Idempotency keys
+ * (`responseId` / `eventId`, client UUIDs) are stamped here per the contract (D8).
+ *
+ * Render/overlay is OUT OF SCOPE this stage.
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import { base64ToBytes } from '../../core/encoding/base64';
+import { ENDPOINTS } from '../../transport/http/endpoints';
+import { getDeviceId } from '../../core/id/deviceId';
+import {
+    ENGAGE_SCHEMA_VERSION,
+    type DeviceTokenInput,
+    type DeviceTokenRegistration,
+    type EngageAttachmentDraft,
+    type EngageAttachmentMeta,
+    type EngageAttachmentPresignResult,
+    type EngageConfigContext,
+    type EngageConfigResponse,
+    type CoachConfigResponse,
+    type EngageEventInput,
+    type EngageEventUpload,
+    type EngageResponse,
+    type EngageResponseInput,
+    type RatingFunnelEventInput,
+    type RatingFunnelEventUpload,
+    type SurveyImpressionInput,
+    type SurveyImpressionUpload,
+} from './engageTypes';
+
+/** Voice notes are hard-capped < 30s — enforced at the recorder, here, and server-side. */
+export const VOICE_MAX_DURATION_MS = 30000;
+
+/** Stages of a confirmed submit (Slice D5), surfaced to the in-prompt loading UI. */
+export type SubmitStage = 'uploading' | 'saving';
+
+/** Generate an RFC4122 v4 UUID (idempotency keys, D8). Matches the device-id scheme. */
+function uuidV4(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+
+export interface EngageTransportConfig {
+    /** Backend API base URL (e.g. https://api.scalebun.com). */
+    endpoint: string;
+    /** SaaS multi-tenant client key — gates upload lanes + x-scalebun-client-key header. */
+    clientKey?: string;
+    /** Auto-flush interval in ms. Default: 3000 (mirrors BackendSessionAdapter). */
+    flushIntervalMs?: number;
+    /** Request timeout in ms. Default: 15000. */
+    timeoutMs?: number;
+}
+
+export class EngageTransport {
+    private readonly config: Required<Omit<EngageTransportConfig, 'clientKey'>> & {
+        clientKey?: string;
+    };
+
+    // Outbox lanes (mirror BackendSessionAdapter's pending* arrays).
+    private pendingResponses: EngageResponse[] = [];
+    private pendingEvents: EngageEventUpload[] = [];
+    private pendingTokens: DeviceTokenRegistration[] = [];
+    private pendingRatingEvents: RatingFunnelEventUpload[] = [];
+    private pendingSurveyImpressions: SurveyImpressionUpload[] = [];
+    private flushTimer: ReturnType<typeof setInterval> | null = null;
+    private destroyed = false;
+
+    /** Eager-flush thresholds (mirror the network/error lane batch sizes). */
+    private static readonly RESPONSES_BATCH_SIZE = 10;
+    private static readonly EVENTS_BATCH_SIZE = 20;
+    private static readonly RATING_EVENTS_BATCH_SIZE = 20;
+    private static readonly SURVEY_IMPRESSIONS_BATCH_SIZE = 20;
+
+    constructor(config: EngageTransportConfig) {
+        this.config = {
+            flushIntervalMs: 3000,
+            timeoutMs: 15_000,
+            ...config,
+            clientKey: config.clientKey,
+        };
+        this._startFlushTimer();
+    }
+
+    // ─── Config serve (direct GET — NOT queued) ─────────────────────────────
+
+    /**
+     * Fetch the versioned Engage config (§1.3). Direct GET; returns the typed
+     * payload or null on any failure (never throws). The shared cross-platform JS
+     * overlay (D4) consumes this in a later slice.
+     */
+    async fetchEngageConfig(context?: EngageConfigContext): Promise<EngageConfigResponse | null> {
+        const query = this._buildConfigQuery(context);
+        const url = `${this.config.endpoint}${ENDPOINTS.ENGAGE_CONFIG(query)}`;
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.clientKey) {
+                headers['x-scalebun-client-key'] = this.config.clientKey;
+            }
+            // `cache: 'no-store'` — the config carries per-device test previews with a
+            // short TTL + consume-on-render lifecycle, so a stale cached body could show a
+            // consumed preview or hide a freshly-queued one. Always read live (T1).
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+                cache: 'no-store',
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                logger.warn(`[Engage] config fetch HTTP ${response.status}`);
+                return null;
+            }
+            return (await response.json()) as EngageConfigResponse;
+        } catch (err: any) {
+            logger.warn(`[Engage] config fetch failed: ${err?.message}`);
+            return null;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    /** Fetch published standalone coachmark tours from the same SDK-key-authenticated config lane. */
+    async fetchCoachConfig(preview?: string): Promise<CoachConfigResponse | null> {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.clientKey) headers['x-scalebun-client-key'] = this.config.clientKey;
+            const response = await fetch(`${this.config.endpoint}${ENDPOINTS.COACH_CONFIG(preview)}`, {
+                method: 'GET', headers, cache: 'no-store', signal: controller.signal,
+            });
+            if (!response.ok) return null;
+            return await response.json() as CoachConfigResponse;
+        } catch (err: any) {
+            logger.warn(`[Coachmarks] config fetch failed: ${err?.message}`);
+            return null;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    private _buildConfigQuery(context?: EngageConfigContext): string {
+        if (!context) return '';
+        const params: string[] = [];
+        if (context.platform) params.push(`platform=${encodeURIComponent(context.platform)}`);
+        if (context.appVersion) params.push(`appVersion=${encodeURIComponent(context.appVersion)}`);
+        if (context.endUserId) params.push(`endUserId=${encodeURIComponent(context.endUserId)}`);
+        if (context.deviceId) params.push(`deviceId=${encodeURIComponent(context.deviceId)}`);
+        return params.join('&');
+    }
+
+    // ─── Upload lanes (ride the outbox) ─────────────────────────────────────
+
+    /**
+     * Enqueue a campaign response (§1.4). Client-stamps `responseId` (UUID),
+     * `schemaVersion`, `clientTs`. Dropped when not in SaaS mode (no clientKey).
+     */
+    uploadEngageResponse(input: EngageResponseInput): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        this._enqueueResponse({
+            ...input,
+            responseId: uuidV4(),
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+            clientTs: new Date().toISOString(),
+        });
+    }
+
+    /**
+     * [P3-e] Submit a response that carries native attachments (screenshot/voice).
+     * Mirrors the replay frame pipeline: presign → PUT bytes direct to storage →
+     * enqueue the response with key-only metadata (NEVER base64 in the response body,
+     * NEVER a duplicate of replay/session data — only the new attachment fact, linked
+     * by the shared responseId). Voice over the hard cap is dropped client-side
+     * (recorder + here + server all enforce it). Resolves after the response is queued.
+     */
+    async submitResponseWithAttachments(
+        input: EngageResponseInput,
+        drafts: EngageAttachmentDraft[],
+    ): Promise<void> {
+        if (this.destroyed || !this.config.clientKey) return;
+        const responseId = uuidV4();
+
+        const usable = drafts.filter(
+            (d) =>
+                !!d.base64 &&
+                !(
+                    d.kind === 'voice' &&
+                    typeof d.durationMs === 'number' &&
+                    d.durationMs >= VOICE_MAX_DURATION_MS
+                ),
+        );
+
+        let attachments: EngageAttachmentMeta[] | undefined;
+        if (usable.length > 0) {
+            attachments = await this._uploadAttachments(responseId, usable);
+        }
+
+        this._enqueueResponse({
+            ...input,
+            responseId,
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+            clientTs: new Date().toISOString(),
+            ...(attachments && attachments.length > 0 ? { attachments } : {}),
+        });
+    }
+
+    /**
+     * [Slice D5] CONFIRMED submit: resolve ONLY after the response (and any audio/
+     * screenshot bytes) are actually persisted server-side — not when the request is
+     * merely fired. Drives the reusable submitting→success→error UI: `onStage` reports
+     * real stages (`uploading` → `saving`), and the promise rejects on failure so the
+     * caller can show a retryable error.
+     *
+     * IDEMPOTENT: the caller owns `responseId` and passes the SAME one on retry. Both
+     * the response (skipDuplicates on responseId) and each attachment (stable id +
+     * skipDuplicates on attachmentId, same storage key) de-dupe server-side, so a retry
+     * after a partial failure can never create duplicate rows or objects (D8).
+     */
+    async submitResponseConfirmed(
+        input: EngageResponseInput,
+        drafts: EngageAttachmentDraft[],
+        opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
+    ): Promise<void> {
+        if (this.destroyed || !this.config.clientKey) {
+            throw new Error('engage transport unavailable');
+        }
+        const { responseId, onStage } = opts;
+
+        const usable = drafts.filter(
+            (d) =>
+                !!d.base64 &&
+                !(
+                    d.kind === 'voice' &&
+                    typeof d.durationMs === 'number' &&
+                    d.durationMs >= VOICE_MAX_DURATION_MS
+                ),
+        );
+
+        let attachments: EngageAttachmentMeta[] | undefined;
+        if (usable.length > 0) {
+            onStage?.('uploading');
+            // Stable per-response attachment ids → retry-safe (see _uploadAttachments).
+            attachments = await this._uploadAttachments(
+                responseId,
+                usable,
+                (i) => `${responseId}-att-${i}`,
+            );
+        }
+
+        onStage?.('saving');
+        // Direct POST (await real persistence) — NOT the batched outbox. Throws on
+        // non-2xx so the caller surfaces a retryable error.
+        await this._post(ENDPOINTS.ENGAGE_RESPONSES, {
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+            responses: [
+                {
+                    ...input,
+                    responseId,
+                    schemaVersion: ENGAGE_SCHEMA_VERSION,
+                    clientTs: new Date().toISOString(),
+                    ...(attachments && attachments.length > 0 ? { attachments } : {}),
+                },
+            ],
+        });
+    }
+
+    private _enqueueResponse(response: EngageResponse): void {
+        this.pendingResponses.push(response);
+        if (this.pendingResponses.length >= EngageTransport.RESPONSES_BATCH_SIZE) {
+            this._flushResponses().catch(() => {});
+        }
+    }
+
+    /**
+     * Presign → PUT each attachment's bytes → return key-only metadata. Returns []
+     * when storage is disabled server-side (the response still submits, sans media).
+     * Each attachment gets a client UUID for idempotent re-submit.
+     */
+    private async _uploadAttachments(
+        responseId: string,
+        drafts: EngageAttachmentDraft[],
+        idFor?: (index: number) => string,
+    ): Promise<EngageAttachmentMeta[]> {
+        // Idempotent path passes a STABLE id generator (derived from responseId) so a
+        // retry reuses the same attachmentId — backend `skipDuplicates` then no-ops the
+        // re-insert and the storage PUT overwrites the same key (no duplicate row/object).
+        const withIds = drafts.map((d, i) => ({ id: idFor ? idFor(i) : uuidV4(), draft: d }));
+        let presign: { enabled: boolean; attachments: EngageAttachmentPresignResult[] } | null = null;
+        try {
+            presign = await this._postReturning(ENDPOINTS.ENGAGE_ATTACHMENTS_PRESIGN, {
+                schemaVersion: ENGAGE_SCHEMA_VERSION,
+                attachments: withIds.map(({ id, draft }) => ({
+                    attachmentId: id,
+                    responseId,
+                    kind: draft.kind,
+                    contentType: draft.mime,
+                })),
+            });
+        } catch (err: any) {
+            logger.warn(`[Engage] attachment presign failed: ${err?.message}`);
+            return [];
+        }
+        if (!presign || presign.enabled === false) {
+            logger.warn('[Engage] object storage disabled — attachment not uploaded');
+            return [];
+        }
+
+        const byId = new Map(presign.attachments.map((p) => [p.attachmentId, p]));
+        const meta: EngageAttachmentMeta[] = [];
+        await Promise.all(
+            withIds.map(async ({ id, draft }) => {
+                const p = byId.get(id);
+                if (!p) return;
+                try {
+                    await this._putBytes(p.uploadUrl, draft.base64, p.contentType);
+                    meta.push({
+                        attachmentId: id,
+                        kind: draft.kind,
+                        storageKey: p.storageKey,
+                        mime: draft.mime,
+                        width: draft.width,
+                        height: draft.height,
+                        byteSize: draft.byteSize,
+                        durationMs: draft.durationMs,
+                        masked: draft.masked,
+                        ...(draft.kind === 'voice'
+                            ? {
+                                  transcript: draft.transcriptApproved ? (draft.transcript ?? '') : undefined,
+                                  transcriptApproved: draft.transcriptApproved ?? false,
+                              }
+                            : {}),
+                    });
+                } catch (err: any) {
+                    logger.warn(`[Engage] attachment PUT failed (${draft.kind}): ${err?.message}`);
+                }
+            }),
+        );
+        return meta;
+    }
+
+    /**
+     * Enqueue an in-app tracking event (§2.5). Client-stamps `eventId` (UUID),
+     * `schemaVersion`, `timestamp`. Dropped when not in SaaS mode.
+     */
+    uploadEngageEvent(input: EngageEventInput): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        const event: EngageEventUpload = {
+            ...input,
+            eventId: uuidV4(),
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+            timestamp: new Date().toISOString(),
+        };
+        this.pendingEvents.push(event);
+        if (this.pendingEvents.length >= EngageTransport.EVENTS_BATCH_SIZE) {
+            this._flushEvents().catch(() => {});
+        }
+    }
+
+    uploadSurveyImpression(input: SurveyImpressionInput): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        this.pendingSurveyImpressions.push({
+            ...input,
+            beaconId: uuidV4(),
+            clientTs: new Date().toISOString(),
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+        });
+        if (this.pendingSurveyImpressions.length >= EngageTransport.SURVEY_IMPRESSIONS_BATCH_SIZE) {
+            this._flushSurveyImpressions().catch(() => {});
+        }
+    }
+
+    /**
+     * Enqueue a rating-funnel tracking event (ratings-rebuild CONTRACT §1.2).
+     * Client-stamps `eventId` (UUID, D8 dedup) + `ts` (client clock). These are
+     * tracking FACTS feeding the Overview funnel — NOT campaign responses (D1), so
+     * they ride their own lane to `/ingestion/rating-events`. Dropped when not in
+     * SaaS mode (no clientKey).
+     */
+    uploadRatingEvent(input: RatingFunnelEventInput): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        const event: RatingFunnelEventUpload = {
+            ...input,
+            eventId: uuidV4(),
+            ts: new Date().toISOString(),
+        };
+        this.pendingRatingEvents.push(event);
+        if (this.pendingRatingEvents.length >= EngageTransport.RATING_EVENTS_BATCH_SIZE) {
+            this._flushRatingEvents().catch(() => {});
+        }
+    }
+
+    /**
+     * Enqueue a device-token registration (§2.2). `deviceId` defaults to the SDK
+     * device id; `platform` is the routing source of truth (D5). Idempotent
+     * upsert server-side on (environmentId, deviceId). Flushes eagerly — token
+     * registration is low-volume and latency-sensitive.
+     */
+    registerDeviceToken(input: DeviceTokenInput): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        const registration: DeviceTokenRegistration = {
+            schemaVersion: ENGAGE_SCHEMA_VERSION,
+            deviceId: input.deviceId ?? getDeviceId(),
+            pushToken: input.pushToken,
+            platform: input.platform,
+            tokenStatus: 'active',
+            ...(input.pushProvider ? { pushProvider: input.pushProvider } : {}),
+            ...(input.installationId ? { installationId: input.installationId } : {}),
+            ...(input.sdkVersion ? { sdkVersion: input.sdkVersion } : {}),
+        };
+        this.pendingTokens.push(registration);
+        this._flushTokens().catch(() => {});
+    }
+
+    /** Force-flush every Engage upload lane immediately (e.g. on app background). */
+    async flushAll(): Promise<void> {
+        await Promise.all([
+            this._flushResponses(),
+            this._flushEvents(),
+            this._flushRatingEvents(),
+            this._flushSurveyImpressions(),
+            this._flushTokens(),
+        ]);
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────────
+
+    destroy(): void {
+        this.destroyed = true;
+        this._stopFlushTimer();
+        this.pendingResponses = [];
+        this.pendingEvents = [];
+        this.pendingRatingEvents = [];
+        this.pendingSurveyImpressions = [];
+        this.pendingTokens = [];
+    }
+
+    // ─── Internal: flush (re-queue on failure, mirrors BackendSessionAdapter) ─
+
+    /**
+     * Should a failed batch go back on the queue?
+     *
+     * NO for 4xx: the server has rejected this payload's SHAPE, and retrying an identical body
+     * can only produce the identical rejection. Because a rejected batch is unshifted onto the
+     * HEAD of the queue, re-queueing a 4xx blocks every later event behind it forever — one bad
+     * item silently stalls the whole lane for that install. (This is exactly what a missing
+     * event type in the backend's @IsIn allowlist did to in-app telemetry.)
+     *
+     * YES for 5xx, timeouts and network errors: those are transient and the payload is fine.
+     */
+    private static _shouldRequeue(err: unknown): boolean {
+        const status = (err as { status?: number } | null)?.status;
+        if (typeof status !== 'number') return true; // network/abort/unknown → transient
+        return status < 400 || status >= 500;
+    }
+
+    private async _flushResponses(): Promise<void> {
+        if (this.pendingResponses.length === 0 || !this.config.clientKey) return;
+        const batch = this.pendingResponses.splice(0, 50);
+        try {
+            await this._post(ENDPOINTS.ENGAGE_RESPONSES, {
+                schemaVersion: ENGAGE_SCHEMA_VERSION,
+                responses: batch,
+            });
+            logger.debug(`[Engage] flushed ${batch.length} response(s)`);
+        } catch (err) {
+            if (EngageTransport._shouldRequeue(err)) this.pendingResponses.unshift(...batch);
+            else logger.warn(`[Engage] dropped ${batch.length} response(s) — rejected by server`);
+        }
+    }
+
+    /**
+     * Force an immediate flush of queued in-app events instead of waiting for the
+     * batch threshold / flush timer. Used for the ONE-SHOT test-preview ACK
+     * (impression/dismiss carrying `previewId`): the backend must consume the preview
+     * row promptly so a fast "close → kill app → reopen" can't re-serve a still-
+     * `delivered` test. Best-effort, never throws (re-queues on failure like the timer).
+     */
+    flushEventsNow(): void {
+        this._flushEvents().catch(() => {});
+    }
+
+    private async _flushEvents(): Promise<void> {
+        if (this.pendingEvents.length === 0 || !this.config.clientKey) return;
+        const batch = this.pendingEvents.splice(0, 50);
+        try {
+            await this._post(ENDPOINTS.ENGAGE_EVENTS, {
+                schemaVersion: ENGAGE_SCHEMA_VERSION,
+                events: batch,
+            });
+            logger.debug(`[Engage] flushed ${batch.length} event(s)`);
+        } catch (err) {
+            if (EngageTransport._shouldRequeue(err)) this.pendingEvents.unshift(...batch);
+            else logger.warn(`[Engage] dropped ${batch.length} in-app event(s) — rejected by server`);
+        }
+    }
+
+    private async _flushRatingEvents(): Promise<void> {
+        if (this.pendingRatingEvents.length === 0 || !this.config.clientKey) return;
+        const batch = this.pendingRatingEvents.splice(0, 50);
+        try {
+            await this._post(ENDPOINTS.INGESTION_RATING_EVENTS, {
+                schemaVersion: ENGAGE_SCHEMA_VERSION,
+                events: batch,
+            });
+            logger.debug(`[Engage] flushed ${batch.length} rating-event(s)`);
+        } catch (err) {
+            if (EngageTransport._shouldRequeue(err)) this.pendingRatingEvents.unshift(...batch);
+            else logger.warn(`[Engage] dropped ${batch.length} rating-event(s) — rejected by server`);
+        }
+    }
+
+    private async _flushSurveyImpressions(): Promise<void> {
+        if (this.pendingSurveyImpressions.length === 0 || !this.config.clientKey) return;
+        const batch = this.pendingSurveyImpressions.splice(0, 50);
+        try {
+            await this._post(ENDPOINTS.ENGAGE_SURVEY_IMPRESSIONS, {
+                schemaVersion: ENGAGE_SCHEMA_VERSION,
+                impressions: batch,
+            });
+            logger.debug(`[Engage] flushed ${batch.length} survey impression(s)`);
+        } catch (err) {
+            if (EngageTransport._shouldRequeue(err)) this.pendingSurveyImpressions.unshift(...batch);
+            else logger.warn(`[Engage] dropped ${batch.length} survey impression(s) — rejected by server`);
+        }
+    }
+
+    private async _flushTokens(): Promise<void> {
+        if (this.pendingTokens.length === 0 || !this.config.clientKey) return;
+        // Token registration is a single-row upsert per contract — post one at a time
+        // so a retry re-queues only the failing token, not an unrelated batch.
+        const registration = this.pendingTokens.shift();
+        if (!registration) return;
+        try {
+            await this._post(ENDPOINTS.ENGAGE_DEVICE_TOKEN, registration);
+            logger.debug(`[Engage] registered device token (${registration.platform})`);
+        } catch (err) {
+            if (EngageTransport._shouldRequeue(err)) this.pendingTokens.unshift(registration);
+            else logger.warn('[Engage] dropped a device-token registration — rejected by server');
+        }
+    }
+
+    private _startFlushTimer(): void {
+        this._stopFlushTimer();
+        this.flushTimer = setInterval(() => {
+            this._flushResponses().catch(() => {});
+            this._flushEvents().catch(() => {});
+            this._flushRatingEvents().catch(() => {});
+            this._flushSurveyImpressions().catch(() => {});
+            this._flushTokens().catch(() => {});
+        }, this.config.flushIntervalMs);
+    }
+
+    private _stopFlushTimer(): void {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+
+    /** POST mirroring BackendSessionAdapter._post: same headers/timeout/abort/throw. */
+    private async _post(path: string, body: unknown): Promise<void> {
+        const url = `${this.config.endpoint}${path}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.clientKey) {
+                headers['x-scalebun-client-key'] = this.config.clientKey;
+            }
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                logger.warn(`[Engage] HTTP ${response.status} from ${path}`);
+                // Carry the status on the error so flush lanes can tell "retry later" (5xx /
+                // network) from "this payload will never be accepted" (4xx). Re-queueing a 4xx
+                // is an infinite poison loop by construction.
+                throw Object.assign(new Error(`HTTP ${response.status}`), {
+                    status: response.status,
+                });
+            }
+        } catch (err: any) {
+            if (err?.name === 'AbortError') {
+                logger.warn(`[Engage] Timeout on ${path}`);
+            } else {
+                logger.warn(`[Engage] Failed ${path}: ${err?.message}`);
+            }
+            throw err;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    /** POST returning parsed JSON (presign lane). Mirrors BackendSessionAdapter._postReturning. */
+    private async _postReturning<T>(path: string, body: unknown): Promise<T> {
+        const url = `${this.config.endpoint}${path}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.clientKey) {
+                headers['x-scalebun-client-key'] = this.config.clientKey;
+            }
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            return (await response.json()) as T;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    /**
+     * PUT raw bytes directly to a presigned storage URL. Decodes base64 to a binary
+     * Blob via a data-URI round-trip (RN-safe — a base64 string body would be stored
+     * verbatim and corrupt the file). No client-key header — the URL carries its auth.
+     */
+    private async _putBytes(uploadUrl: string, base64: string, contentType: string): Promise<void> {
+        // RN-safe base64→binary: decode to a Uint8Array and send that as the body.
+        // The `fetch('data:…').blob()` round-trip fails under the new architecture
+        // ("Network request failed"), so we never rely on it. RN's XHR sends a typed
+        // array as real binary bytes (it base64-transfers `.buffer` to native).
+        const bytes = base64ToBytes(this._stripDataUri(base64));
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const response = await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentType },
+                body: bytes,
+                signal: controller.signal,
+            });
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    /** Strip a leading `data:<mime>;base64,` prefix if the native layer included one. */
+    private _stripDataUri(s: string): string {
+        const comma = s.indexOf(',');
+        return s.startsWith('data:') && comma !== -1 ? s.slice(comma + 1) : s;
+    }
+}