@scalebun-release/react-native 2.5.0

package/lib/typescript/features/engage/EngageTransport.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 { type DeviceTokenInput, type EngageAttachmentDraft, type EngageConfigContext, type EngageConfigResponse, type CoachConfigResponse, type EngageEventInput, type EngageResponseInput, type RatingFunnelEventInput, type SurveyImpressionInput } from './engageTypes';
+/** Voice notes are hard-capped < 30s — enforced at the recorder, here, and server-side. */
+export declare 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';
+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 declare class EngageTransport {
+    private readonly config;
+    private pendingResponses;
+    private pendingEvents;
+    private pendingTokens;
+    private pendingRatingEvents;
+    private pendingSurveyImpressions;
+    private flushTimer;
+    private destroyed;
+    /** Eager-flush thresholds (mirror the network/error lane batch sizes). */
+    private static readonly RESPONSES_BATCH_SIZE;
+    private static readonly EVENTS_BATCH_SIZE;
+    private static readonly RATING_EVENTS_BATCH_SIZE;
+    private static readonly SURVEY_IMPRESSIONS_BATCH_SIZE;
+    constructor(config: EngageTransportConfig);
+    /**
+     * 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.
+     */
+    fetchEngageConfig(context?: EngageConfigContext): Promise<EngageConfigResponse | null>;
+    /** Fetch published standalone coachmark tours from the same SDK-key-authenticated config lane. */
+    fetchCoachConfig(preview?: string): Promise<CoachConfigResponse | null>;
+    private _buildConfigQuery;
+    /**
+     * Enqueue a campaign response (§1.4). Client-stamps `responseId` (UUID),
+     * `schemaVersion`, `clientTs`. Dropped when not in SaaS mode (no clientKey).
+     */
+    uploadEngageResponse(input: EngageResponseInput): void;
+    /**
+     * [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.
+     */
+    submitResponseWithAttachments(input: EngageResponseInput, drafts: EngageAttachmentDraft[]): Promise<void>;
+    /**
+     * [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).
+     */
+    submitResponseConfirmed(input: EngageResponseInput, drafts: EngageAttachmentDraft[], opts: {
+        responseId: string;
+        onStage?: (stage: SubmitStage) => void;
+    }): Promise<void>;
+    private _enqueueResponse;
+    /**
+     * 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 _uploadAttachments;
+    /**
+     * Enqueue an in-app tracking event (§2.5). Client-stamps `eventId` (UUID),
+     * `schemaVersion`, `timestamp`. Dropped when not in SaaS mode.
+     */
+    uploadEngageEvent(input: EngageEventInput): void;
+    uploadSurveyImpression(input: SurveyImpressionInput): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Force-flush every Engage upload lane immediately (e.g. on app background). */
+    flushAll(): Promise<void>;
+    destroy(): void;
+    /**
+     * 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;
+    private _flushResponses;
+    /**
+     * 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;
+    private _flushEvents;
+    private _flushRatingEvents;
+    private _flushSurveyImpressions;
+    private _flushTokens;
+    private _startFlushTimer;
+    private _stopFlushTimer;
+    /** POST mirroring BackendSessionAdapter._post: same headers/timeout/abort/throw. */
+    private _post;
+    /** POST returning parsed JSON (presign lane). Mirrors BackendSessionAdapter._postReturning. */
+    private _postReturning;
+    /**
+     * 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 _putBytes;
+    /** Strip a leading `data:<mime>;base64,` prefix if the native layer included one. */
+    private _stripDataUri;
+}
+//# sourceMappingURL=EngageTransport.d.ts.map

package/lib/typescript/features/engage/EngageVariantContent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Native, composable content blocks for container-only in-app variants.
+ *
+ * Layout branches still own mounting. Interactive mechanics still live in the
+ * mechanic resolver. This module only turns heterogeneous registry `ext` data
+ * into a small set of reusable visual families.
+ */
+import { type ReactElement } from "react";
+import type { InAppBranchProps } from "./EngageInAppView";
+/** Resolve reusable content for a container variant, or null for generic/mechanic keys. */
+export declare function resolveVariantContent(variantKey?: string): ((props: InAppBranchProps) => ReactElement) | null;
+//# sourceMappingURL=EngageVariantContent.d.ts.map

package/lib/typescript/features/engage/attachmentCapture.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ScaleBun SDK — Engage attachment capture (P3-e)
+ *
+ * Screenshot attachments REUSE the replay capture pipeline rather than forking a
+ * second one: `bridgeAdapter.captureScreenshot` runs the native FrameCaptureManager,
+ * which applies PrivacyMaskProcessor (text inputs masked by default). So the bytes
+ * are ALREADY PII-masked — we never produce an unmasked screenshot here. The result
+ * is a base64 frame the EngageTransport presigns + PUTs direct to storage.
+ */
+import type { EngageAttachmentDraft } from './engageTypes';
+/**
+ * Capture a masked screenshot of the current screen as a feedback attachment.
+ * Returns null if the native capture is unavailable or fails (the prompt still
+ * submits without the attachment — capture is best-effort, never blocking).
+ */
+export declare function captureScreenshotAttachment(): Promise<EngageAttachmentDraft | null>;
+//# sourceMappingURL=attachmentCapture.d.ts.map

package/lib/typescript/features/engage/captureVoiceAttachment.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ScaleBun SDK — Engage voice-note capture (Slice D4)
+ *
+ * Voice notes REUSE the same presign→PUT→metadata pipeline as screenshots — the
+ * only new piece is the native mic recorder (AAC/.m4a, ≤30s hard-capped natively).
+ * On stop, transcription runs through the swappable `TranscriptionProvider` seam
+ * (default: on-device native STT, no network/creds). The returned transcript is a
+ * PREFILL: the caller shows it editable and only sets `transcriptApproved` after
+ * the user explicitly approves the final wording — nothing is sent before that.
+ *
+ * The 30s cap is enforced in THREE places (recorder UI auto-stop, native recorder
+ * setMaxDuration/forDuration, backend duration validation). This function trusts
+ * the native cap and surfaces the real recorded `durationMs`.
+ */
+import type { EngageAttachmentDraft } from './engageTypes';
+/** Hard cap mirrored from native recorders (Android 30000 / iOS 30000). */
+export declare const VOICE_MAX_DURATION_MS = 30000;
+/** Begin a voice note. Best-effort — native handles mic permission prompt. */
+export declare function startVoiceAttachment(): Promise<void>;
+/** Cancel an in-progress recording, discarding bytes. */
+export declare function cancelVoiceAttachment(): Promise<void>;
+/**
+ * Stop recording, run on-device transcription, and return a voice attachment draft
+ * (transcript NOT yet approved). Returns null if nothing was recorded or capture
+ * is unavailable (the prompt can still submit without a voice note).
+ *
+ * The returned `durationMs` is the REAL recorded duration; it is also clamped to
+ * the hard cap as a final SDK-side guard before the backend's own validation.
+ */
+export declare function stopVoiceAttachment(): Promise<EngageAttachmentDraft | null>;
+//# sourceMappingURL=captureVoiceAttachment.d.ts.map

package/lib/typescript/features/engage/engageCoachmarkTour.d.ts

@@ -0,0 +1,18 @@
+import type { InAppCoachmarkStep, InAppCta, InAppRenderSpec } from './engageTypes';
+/**
+ * Normalize the additive multi-step contract while keeping every legacy
+ * single-anchor campaign valid. Invalid authored rows are ignored; if no valid
+ * row remains, the legacy top-level fields are used as a one-step tour.
+ */
+export declare function normalizeCoachmarkSteps(spec: InAppRenderSpec): InAppCoachmarkStep[];
+/** Legacy anchored payload, intentionally ignoring `ext.steps` (plain tooltips never tour). */
+export declare function normalizeLegacyAnchoredStep(spec: InAppRenderSpec): InAppCoachmarkStep | null;
+export type AnchoredSurfaceKind = 'spotlight' | 'tooltip';
+/** Only the canonical coachmark variant owns a modal scrim/spotlight. */
+export declare function resolveAnchoredSurfaceKind(variantKey?: string): AnchoredSurfaceKind;
+export declare function resolveCoachmarkStepIndex(currentIndex: number, stepCount: number, direction: 'next' | 'back'): number;
+export declare const coachmarkAnchorError: (anchorKey: string) => string;
+export type CoachmarkFinishMode = 'cta' | 'complete';
+/** Link/custom actions remain clicks; an ordinary Finish is a completion. */
+export declare function resolveCoachmarkFinishMode(cta?: InAppCta): CoachmarkFinishMode;
+//# sourceMappingURL=engageCoachmarkTour.d.ts.map

package/lib/typescript/features/engage/engageGameLogic.d.ts

@@ -0,0 +1,34 @@
+import type { InAppGameAction, InAppGameRequest, InAppGameResult, InAppGameVariantKey, InAppRenderSpec } from "./engageTypes";
+export declare function isInAppGameVariant(value: unknown): value is InAppGameVariantKey;
+export declare function inAppGameActionFor(value: unknown): InAppGameAction | null;
+/** Presentation-declared ids are validation hints, never probability or grant logic. */
+export declare function inAppGameAllowedOutcomeIds(spec: InAppRenderSpec): string[];
+/** Build a correctly discriminated host request from the mounted game. */
+export declare function buildInAppGameRequest(input: {
+    campaignId: string;
+    gameKey: string;
+    variantKey: InAppGameVariantKey;
+    attemptId: string;
+    attempt: number;
+    payload?: Record<string, unknown>;
+    allowedOutcomeIds?: string[];
+}): InAppGameRequest;
+/** Reject malformed, mismatched, or presentation-incompatible backend results. */
+export declare function validateInAppGameResult(request: InAppGameRequest, value: unknown): InAppGameResult;
+/** Send Test/live preview only: normalize the dashboard's authored mock result. */
+export declare function authoredPreviewGameResult(request: InAppGameRequest, spec: InAppRenderSpec): InAppGameResult | null;
+export declare function boundedInt(value: unknown, fallback: number, min: number, max: number): number;
+export declare function scratchCellAt(x: number, y: number, width: number, height: number, columns: number, rows: number): number | null;
+export declare function addScratchedCell(cells: readonly number[], cell: number | null): number[];
+export declare function scratchProgress(cells: readonly number[], total: number): number;
+export declare function clampPage(offset: number, width: number, count: number): number;
+export declare function wheelTargetAngle(segmentCount: number, selectedIndex: number, fromAngle: number, minimumTurns?: number): number;
+export declare function toggleGameSelection(selected: readonly number[], index: number, multiple: boolean): number[];
+export declare function gradeGameAnswer(selected: readonly number[], correct: readonly number[]): boolean;
+export declare function scoreGameAnswer(currentScore: number, correct: boolean, alreadyLocked: boolean, totalQuestions: number): number;
+export interface SlotOutcome {
+    symbols: string[];
+    authored: boolean;
+}
+export declare function resolveSlotOutcome(reels: readonly (readonly string[])[], authoredSymbols: readonly string[]): SlotOutcome;
+//# sourceMappingURL=engageGameLogic.d.ts.map

package/lib/typescript/features/engage/engageMediaSizing.d.ts

@@ -0,0 +1,23 @@
+import type { InAppMediaSize, InAppRenderSpec } from "./engageTypes";
+type AuthoredInAppMediaSize = Exclude<InAppMediaSize, "auto">;
+/**
+ * Validate the untrusted wire value. `auto` intentionally resolves to
+ * `undefined`, just like an absent/unknown field, so callers apply no style
+ * override and legacy campaigns retain their exact historical layout.
+ */
+export declare function resolveInAppMediaSize(spec: Pick<InAppRenderSpec, "ext">): AuthoredInAppMediaSize | undefined;
+/** Return the validated scale, or no override for legacy/auto/invalid payloads. */
+export declare function resolveInAppMediaScale(spec: Pick<InAppRenderSpec, "ext">): number | undefined;
+/**
+ * Scale a fixed-height media block while respecting its surface-specific cap.
+ * Invalid dimensions are ignored rather than risking a broken host layout.
+ */
+export declare function resolveInAppMediaHeight(spec: Pick<InAppRenderSpec, "ext">, baseHeight: number, maxHeight?: number): number | undefined;
+/**
+ * Scale an aspect-ratio-driven hero vertically. Dividing the original ratio
+ * by the height multiplier keeps width responsive while making the block
+ * shorter/taller according to the selected preset.
+ */
+export declare function resolveInAppMediaAspectRatio(spec: Pick<InAppRenderSpec, "ext">, baseAspectRatio: number): number | undefined;
+export {};
+//# sourceMappingURL=engageMediaSizing.d.ts.map

package/lib/typescript/features/engage/engageMultiStepSheet.d.ts

@@ -0,0 +1,25 @@
+import type { InAppCta, InAppRenderSpec } from './engageTypes';
+export interface MultiStepSheetLabels {
+    back: string;
+    skip: string;
+    next: string;
+    finish: string;
+}
+/**
+ * Resolve the additive wizard labels without breaking older payloads that used
+ * `secondaryCta` as the first-step escape action.
+ */
+export declare function resolveMultiStepSheetLabels(spec: InAppRenderSpec): MultiStepSheetLabels;
+export declare function resolveMultiStepSheetIndex(currentIndex: number, stepCount: number, direction: 'next' | 'back'): number;
+export type MultiStepSheetTerminalAction = {
+    kind: 'dismiss';
+} | {
+    kind: 'cta';
+    cta: InAppCta;
+};
+/**
+ * A dismiss action remains local to the SDK. Link/custom actions are surfaced
+ * to the host through `onCta`, matching every other in-app CTA boundary.
+ */
+export declare function resolveMultiStepSheetTerminalAction(cta?: InAppCta): MultiStepSheetTerminalAction;
+//# sourceMappingURL=engageMultiStepSheet.d.ts.map

package/lib/typescript/features/engage/engageOutcome.d.ts

@@ -0,0 +1,38 @@
+import type { InAppCta, InAppOutcomeAction, InAppOutcomeIcon, InAppRenderSpec } from './engageTypes';
+export interface ResolvedInAppOutcomeConfig {
+    title: string;
+    body: string;
+    icon: InAppOutcomeIcon;
+    buttonLabel: string;
+    action?: InAppOutcomeAction;
+}
+export type InAppOutcomeTerminal = {
+    kind: 'cta';
+    cta: InAppCta;
+} | {
+    kind: 'dismiss';
+} | {
+    kind: 'complete';
+};
+export interface InAppOutcomeRequest {
+    /** Backend-owned display label only; it never changes the resolved outcome. */
+    resultLabel?: string;
+    /** Behavior to retain when the authored outcome action is set to inherit. */
+    fallback: InAppOutcomeTerminal;
+}
+/**
+ * Resolve the optional authored terminal card. Absence means legacy behavior:
+ * no popup and no changes to the existing renderer's completion path.
+ */
+export declare function resolveInAppOutcomeConfig(spec: Pick<InAppRenderSpec, 'ext'> | null | undefined): ResolvedInAppOutcomeConfig | null;
+export declare function inAppOutcomeIconGlyph(icon: InAppOutcomeIcon): string;
+/** Convert the existing primary CTA into a terminal fallback without executing it. */
+export declare function inAppOutcomeTerminalForCta(cta: InAppCta | null | undefined): InAppOutcomeTerminal;
+/** Outcome actions can navigate and close without emitting an in-app click. */
+export declare function shouldTrackInAppCta(cta: Pick<InAppCta, 'track'>): boolean;
+/**
+ * Resolve what the popup button does. An explicit authored outcome action wins;
+ * otherwise the original terminal action is inherited with the popup label.
+ */
+export declare function resolveInAppOutcomeTerminal(outcome: ResolvedInAppOutcomeConfig, fallback: InAppOutcomeTerminal): InAppOutcomeTerminal;
+//# sourceMappingURL=engageOutcome.d.ts.map

package/lib/typescript/features/engage/engagePushTokenBridge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ScaleBun SDK — Engage Push-Token Native Bridge (foundation)
+ *
+ * Wraps the `ScaleBunEngage` native module (Android Kotlin / iOS Swift). The native
+ * piece is the GENUINELY-native part of the Engage foundation (D4): obtaining the
+ * platform push token (FCM on Android, APNs on iOS) and surfacing a refresh stream.
+ *
+ * Native registers an `RCTEventEmitter`-style `ScaleBunEngageTokenRefresh` event; this
+ * bridge subscribes and hands every token (initial + rotations) to the JS upload
+ * layer via the supplied `onToken` callback, which routes through
+ * `EngageTransport.registerDeviceToken` (the existing outbox).
+ *
+ * Fail-soft: every call is a no-op when the native module is unavailable (JS-only
+ * env, host app without Firebase / push capability). Never throws, never crashes.
+ */
+export interface NativePushToken {
+    token: string;
+    platform: 'android' | 'ios';
+}
+/**
+ * Acquire the current push token from native. Returns null when the native module
+ * is unavailable or push is not enabled in the host app (fail-soft).
+ */
+export declare function getNativePushToken(): Promise<NativePushToken | null>;
+/**
+ * Subscribe to native token-refresh events (FCM rotation / APNs re-registration).
+ * Returns an unsubscribe function, or a no-op when the native module is absent.
+ */
+export declare function subscribeNativePushTokenRefresh(onToken: (token: NativePushToken) => void): () => void;
+//# sourceMappingURL=engagePushTokenBridge.d.ts.map

package/lib/typescript/features/engage/engageShakeBridge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ScaleBun SDK — Engage Shake Native Bridge (`shake_device` trigger).
+ *
+ * Wraps the native shake detector added to the `ScaleBunEngage` module (iOS CoreMotion
+ * accelerometer / Android SensorManager). Native emits a `ScaleBunEngageShake` event
+ * when total acceleration crosses a threshold; this bridge subscribes and routes
+ * each shake to `gestureTriggerDetector.reportShake()`, which emits the unified
+ * `$gesture` signal the Engage trigger engine listens for — the SAME path as
+ * rage_tap / dead_tap (no parallel pipeline).
+ *
+ * Fail-soft: a no-op when the native module / accelerometer is unavailable
+ * (JS-only env, simulator). Never throws, never crashes.
+ */
+/**
+ * Start native shake detection and route shakes to the gesture detector. Returns a
+ * teardown that stops native updates and removes the listener. No-op (returns a
+ * no-op teardown) when the native module is absent.
+ */
+export declare function installEngageShakeBridge(): () => void;
+//# sourceMappingURL=engageShakeBridge.d.ts.map

package/lib/typescript/features/engage/engageSignals.d.ts

@@ -0,0 +1,13 @@
+export interface SdkSignal {
+    name: string;
+    payload?: Record<string, unknown>;
+}
+export type SignalListener = (signal: SdkSignal) => void;
+declare class EngageSignalBus {
+    private listeners;
+    subscribe(listener: SignalListener): () => void;
+    emit(name: string, payload?: Record<string, unknown>): void;
+}
+export declare const engageSignals: EngageSignalBus;
+export {};
+//# sourceMappingURL=engageSignals.d.ts.map

package/lib/typescript/features/engage/engageStoreReviewBridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ScaleBun SDK — Engage Store-Review Native Bridge (D5)
+ *
+ * Wraps the native in-app review flow on both platforms via the `ScaleBunEngage`
+ * module: Play In-App Review (Play Core `ReviewManager`) on Android, and
+ * `SKStoreReviewController` on iOS. This is the GENUINELY-native leg of the
+ * rating funnel (D5) — JS cannot trigger the OS review sheet.
+ *
+ * The native `requestReview()` resolves a boolean: `true` once the OS review
+ * flow has been requested/resolved (a positive route completed), `false` when
+ * the platform suppressed it (quota, simulator, unavailable). The caller emits
+ * `store_redirect_clicked` ONLY on a `true` result (CONTRACT §1.1 — the event
+ * fires when the native store/Play review flow RESOLVES after a positive route).
+ *
+ * Fail-soft: every call is a no-op resolving `false` when the native module is
+ * unavailable (JS-only env, host app without the review capability). Never throws.
+ */
+/**
+ * Request the native in-app review sheet. Resolves `true` once the OS flow has
+ * resolved after a positive route, `false` when unavailable/suppressed (fail-soft).
+ */
+export declare function requestNativeStoreReview(): Promise<boolean>;
+//# sourceMappingURL=engageStoreReviewBridge.d.ts.map

package/lib/typescript/features/engage/engageTestSeenStore.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ScaleBun SDK — Test-Preview Seen Store (T1, one-shot test delivery)
+ *
+ * Persistent, restart-surviving record of test `testRunId`s this device has already
+ * DISPLAYED. A "Send Test" preview is a ONE-SHOT delivery: once the SDK successfully
+ * renders a testRunId, it must never be shown again on the same device — even across
+ * cold restarts (the user's repro: close/open the app and the old test re-appeared).
+ *
+ * Why a SEPARATE store from the throttle store:
+ *   - Production frequency/dismiss caps live in `EngageThrottleStore` and must NOT block
+ *     a new test (tests bypass them).
+ *   - Test dedupe must block an ALREADY-DISPLAYED testRunId regardless of production
+ *     caps. Mixing the two would either cap real campaigns or fail to dedupe tests.
+ *
+ * Backed by the same synchronous first-party StorageBackend used for the device id /
+ * throttle state (durable native store, memory only as an emergency fallback), so the
+ * seen set survives app restarts exactly like them.
+ * Entries are pruned past a TTL so the set can't grow unbounded (a testRunId only needs
+ * to be remembered while its server row could still be re-served — bounded by the 10-min
+ * server TTL, with generous slack).
+ */
+import { type StorageBackend } from '../../storage/StorageBackend';
+/**
+ * Persistent set of displayed test `testRunId`s. `has` is the pre-render guard; `markSeen`
+ * is called AFTER a successful render/impression so a failed render does not lose the test.
+ */
+export declare class EngageTestSeenStore {
+    private readonly backend;
+    constructor(backend?: StorageBackend);
+    private keyFor;
+    /** True if this testRunId was already displayed on this device (and not yet pruned). */
+    has(testRunId: string): boolean;
+    /** Record that this testRunId was displayed. Idempotent (overwrites the timestamp). */
+    markSeen(testRunId: string): void;
+    /**
+     * DEBUG/DEV reset — delete EVERY displayed-test record so a tester can see an
+     * already-dismissed testRunId again WITHOUT uninstalling. Backs the test half of
+     * `ScaleBun.engage.resetInAppState()`. Returns the number of cleared entries.
+     * The "block a dismissed test forever on this device" guarantee holds UNLESS this
+     * (the debug reset) is called — exactly the contract the renderer relies on.
+     */
+    clear(): number;
+    /** Drop stale entries past the TTL. Best-effort housekeeping, safe to call on mount. */
+    prune(): void;
+}
+//# sourceMappingURL=engageTestSeenStore.d.ts.map