@scalebun-release/react-native 2.5.0

package/src/features/engage/EngageTransport.ts

@@ -0,0 +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/api/v1). */
+    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,
+            });
+            __DEV__ && 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,
+            });
+            __DEV__ && 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,
+            });
+            __DEV__ && 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,
+            });
+            __DEV__ && 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);
+            __DEV__ && 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;
+    }
+}