@scalebun-release/react-native 2.5.0

package/src/features/engage/engageMediaSizing.ts

@@ -0,0 +1,76 @@
+import type { InAppMediaSize, InAppRenderSpec } from "./engageTypes";
+
+type AuthoredInAppMediaSize = Exclude<InAppMediaSize, "auto">;
+
+/**
+ * Relative to each renderer's existing medium/default media dimension.
+ * Keeping the multiplier contextual preserves the intentionally different
+ * shapes of carousel cards, full-screen heroes, and commerce posters.
+ */
+const MEDIA_SCALE: Readonly<Record<AuthoredInAppMediaSize, number>> = {
+  compact: 0.72,
+  medium: 1,
+  large: 1.35,
+  full: 1.7,
+};
+
+/**
+ * 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 function resolveInAppMediaSize(
+  spec: Pick<InAppRenderSpec, "ext">,
+): AuthoredInAppMediaSize | undefined {
+  const value = spec.ext?.mediaSize;
+  return value === "compact" ||
+    value === "medium" ||
+    value === "large" ||
+    value === "full"
+    ? value
+    : undefined;
+}
+
+/** Return the validated scale, or no override for legacy/auto/invalid payloads. */
+export function resolveInAppMediaScale(
+  spec: Pick<InAppRenderSpec, "ext">,
+): number | undefined {
+  const size = resolveInAppMediaSize(spec);
+  return size ? MEDIA_SCALE[size] : 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 function resolveInAppMediaHeight(
+  spec: Pick<InAppRenderSpec, "ext">,
+  baseHeight: number,
+  maxHeight = Number.POSITIVE_INFINITY,
+): number | undefined {
+  const scale = resolveInAppMediaScale(spec);
+  if (scale === undefined || !Number.isFinite(baseHeight) || baseHeight <= 0) {
+    return undefined;
+  }
+  const scaled = Math.round(baseHeight * scale);
+  return Number.isFinite(maxHeight) && maxHeight > 0
+    ? Math.min(scaled, Math.round(maxHeight))
+    : scaled;
+}
+
+/**
+ * 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 function resolveInAppMediaAspectRatio(
+  spec: Pick<InAppRenderSpec, "ext">,
+  baseAspectRatio: number,
+): number | undefined {
+  const scale = resolveInAppMediaScale(spec);
+  return scale !== undefined &&
+    Number.isFinite(baseAspectRatio) &&
+    baseAspectRatio > 0
+    ? baseAspectRatio / scale
+    : undefined;
+}

package/src/features/engage/engageMultiStepSheet.ts

@@ -0,0 +1,53 @@
+import type { InAppCta, InAppRenderSpec } from './engageTypes';
+
+const labelOf = (value: unknown): string | undefined => {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+};
+
+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 function resolveMultiStepSheetLabels(spec: InAppRenderSpec): MultiStepSheetLabels {
+    return {
+        back: labelOf(spec.ext?.backLabel) ?? 'Back',
+        skip: labelOf(spec.ext?.skipLabel) ?? labelOf(spec.secondaryCta?.label) ?? 'Skip',
+        next: labelOf(spec.ext?.nextLabel) ?? 'Next',
+        finish: labelOf(spec.ext?.finalLabel) ?? labelOf(spec.cta?.label) ?? 'Finish',
+    };
+}
+
+export function resolveMultiStepSheetIndex(
+    currentIndex: number,
+    stepCount: number,
+    direction: 'next' | 'back',
+): number {
+    if (stepCount <= 0) return 0;
+    const delta = direction === 'next' ? 1 : -1;
+    return Math.max(0, Math.min(currentIndex + delta, stepCount - 1));
+}
+
+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 function resolveMultiStepSheetTerminalAction(
+    cta?: InAppCta,
+): MultiStepSheetTerminalAction {
+    return cta && cta.action !== 'dismiss'
+        ? { kind: 'cta', cta }
+        : { kind: 'dismiss' };
+}

package/src/features/engage/engageOutcome.ts

@@ -0,0 +1,157 @@
+import type {
+    InAppCta,
+    InAppOutcomeAction,
+    InAppOutcomeConfig,
+    InAppOutcomeIcon,
+    InAppRenderSpec,
+} from './engageTypes';
+
+const OUTCOME_ICONS = new Set<InAppOutcomeIcon>([
+    'check',
+    'trophy',
+    'gift',
+    'star',
+    'sparkles',
+    'rocket',
+]);
+
+const OUTCOME_ICON_GLYPHS: Readonly<Record<InAppOutcomeIcon, string>> = {
+    check: '✓',
+    trophy: '🏆',
+    gift: '🎁',
+    star: '★',
+    sparkles: '✦',
+    rocket: '🚀',
+};
+
+const LINK_ACTIONS = new Set(['deep_link', 'url', 'screen']);
+
+const record = (value: unknown): Record<string, unknown> | null =>
+    value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : null;
+
+const text = (value: unknown): string | undefined =>
+    typeof value === 'string' && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+
+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 function resolveInAppOutcomeConfig(
+    spec: Pick<InAppRenderSpec, 'ext'> | null | undefined,
+): ResolvedInAppOutcomeConfig | null {
+    const raw = record(spec?.ext?.outcome);
+    if (!raw || raw.enabled === false) return null;
+
+    const rawIcon = text(raw.icon);
+    const icon = rawIcon && OUTCOME_ICONS.has(rawIcon as InAppOutcomeIcon)
+        ? rawIcon as InAppOutcomeIcon
+        : 'check';
+    const rawAction = record(raw.action);
+    const rawType = text(rawAction?.type);
+    const rawValue = text(rawAction?.value);
+    const actionLabel = text(rawAction?.label);
+    const buttonLabel = text(raw.buttonLabel) ?? actionLabel ?? 'Okay';
+    let action: InAppOutcomeAction | undefined;
+
+    if (rawType === 'dismiss') {
+        action = {
+            label: buttonLabel,
+            type: 'dismiss',
+            ...(typeof rawAction?.track === 'boolean' ? { track: rawAction.track } : {}),
+        };
+    } else if (rawType && LINK_ACTIONS.has(rawType) && rawValue) {
+        action = {
+            label: buttonLabel,
+            type: rawType as InAppOutcomeAction['type'],
+            value: rawValue,
+            ...(typeof rawAction?.track === 'boolean' ? { track: rawAction.track } : {}),
+        };
+    }
+
+    return {
+        title: text(raw.title) ?? 'Completed',
+        body: text(raw.body) ?? 'Your action completed successfully.',
+        icon,
+        buttonLabel,
+        ...(action ? { action } : {}),
+    };
+}
+
+export function inAppOutcomeIconGlyph(icon: InAppOutcomeIcon): string {
+    return OUTCOME_ICON_GLYPHS[icon];
+}
+
+/** Convert the existing primary CTA into a terminal fallback without executing it. */
+export function inAppOutcomeTerminalForCta(
+    cta: InAppCta | null | undefined,
+): InAppOutcomeTerminal {
+    return cta ? { kind: 'cta', cta } : { kind: 'dismiss' };
+}
+
+/** Outcome actions can navigate and close without emitting an in-app click. */
+export function shouldTrackInAppCta(
+    cta: Pick<InAppCta, 'track'>,
+): boolean {
+    return cta.track !== false;
+}
+
+/**
+ * Resolve what the popup button does. An explicit authored outcome action wins;
+ * otherwise the original terminal action is inherited with the popup label.
+ */
+export function resolveInAppOutcomeTerminal(
+    outcome: ResolvedInAppOutcomeConfig,
+    fallback: InAppOutcomeTerminal,
+): InAppOutcomeTerminal {
+    if (outcome.action?.type === 'dismiss') return { kind: 'dismiss' };
+    if (
+        outcome.action &&
+        LINK_ACTIONS.has(outcome.action.type) &&
+        outcome.action.value
+    ) {
+        return {
+            kind: 'cta',
+            cta: {
+                label: outcome.buttonLabel,
+                action: 'link',
+                deepLink: outcome.action.value,
+                ...(typeof outcome.action.track === 'boolean'
+                    ? { track: outcome.action.track }
+                    : {}),
+            },
+        };
+    }
+    if (fallback.kind !== 'cta') return fallback;
+    if (fallback.cta.action === 'dismiss') return { kind: 'dismiss' };
+    return {
+        kind: 'cta',
+        cta: {
+            ...fallback.cta,
+            label: outcome.buttonLabel,
+        },
+    };
+}

package/src/features/engage/engagePushTokenBridge.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+
+import { NativeModules, NativeEventEmitter, type EmitterSubscription } from 'react-native';
+import { logger } from '../../core/logger/internalLogger';
+
+export interface NativePushToken {
+    token: string;
+    platform: 'android' | 'ios';
+}
+
+interface ScaleBunEngageNativeModule {
+    /** Acquire the platform push token. Resolves null when push is unavailable. */
+    getPushToken(): Promise<NativePushToken | null>;
+    /** RCTEventEmitter plumbing (present on the native module). */
+    addListener?: (eventName: string) => void;
+    removeListeners?: (count: number) => void;
+}
+
+const TOKEN_REFRESH_EVENT = 'ScaleBunEngageTokenRefresh';
+
+function getEngageModule(): ScaleBunEngageNativeModule | null {
+    return (NativeModules?.ScaleBunEngage as ScaleBunEngageNativeModule | undefined) ?? null;
+}
+
+/**
+ * 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 async function getNativePushToken(): Promise<NativePushToken | null> {
+    try {
+        const mod = getEngageModule();
+        if (!mod?.getPushToken) {
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping push token');
+            return null;
+        }
+        const result = await mod.getPushToken();
+        if (!result?.token || !result?.platform) return null;
+        return result;
+    } catch (err: any) {
+        __DEV__ && logger.debug(`[Engage] getPushToken failed (fail-soft): ${err?.message}`);
+        return 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 function subscribeNativePushTokenRefresh(
+    onToken: (token: NativePushToken) => void,
+): () => void {
+    try {
+        const nativeModule = NativeModules?.ScaleBunEngage;
+        if (!nativeModule) {
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — no token-refresh listener');
+            return () => {};
+        }
+        const emitter = new NativeEventEmitter(nativeModule);
+        const subscription: EmitterSubscription = emitter.addListener(
+            TOKEN_REFRESH_EVENT,
+            (payload: NativePushToken) => {
+                if (payload?.token && payload?.platform) onToken(payload);
+            },
+        );
+        return () => subscription.remove();
+    } catch (err: any) {
+        __DEV__ && logger.debug(`[Engage] token-refresh subscription failed (fail-soft): ${err?.message}`);
+        return () => {};
+    }
+}

package/src/features/engage/engageShakeBridge.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+
+import { NativeModules, NativeEventEmitter, type EmitterSubscription } from 'react-native';
+import { logger } from '../../core/logger/internalLogger';
+import { gestureTriggerDetector } from './gestureTriggerDetector';
+import { AutoScreenDetector } from '../navigation/AutoScreenDetector';
+
+const SHAKE_EVENT = 'ScaleBunEngageShake';
+
+interface ScaleBunEngageShakeModule {
+    startShakeDetection?: () => Promise<boolean>;
+    stopShakeDetection?: () => Promise<boolean>;
+    addListener?: (eventName: string) => void;
+    removeListeners?: (count: number) => void;
+}
+
+function getModule(): ScaleBunEngageShakeModule | null {
+    return (NativeModules?.ScaleBunEngage as ScaleBunEngageShakeModule | undefined) ?? null;
+}
+
+/**
+ * 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 function installEngageShakeBridge(): () => void {
+    try {
+        const mod = getModule();
+        if (!mod?.startShakeDetection) {
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage shake detection unavailable — skipping');
+            return () => {};
+        }
+
+        const emitter = new NativeEventEmitter(NativeModules.ScaleBunEngage);
+        const subscription: EmitterSubscription = emitter.addListener(SHAKE_EVENT, () => {
+            let screen: string | undefined;
+            try {
+                screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+            } catch { /* no-throw */ }
+            gestureTriggerDetector.reportShake(screen);
+        });
+
+        void mod.startShakeDetection().catch(() => { /* fail-soft */ });
+
+        return () => {
+            subscription.remove();
+            try {
+                void mod.stopShakeDetection?.();
+            } catch { /* no-throw */ }
+        };
+    } catch (err: any) {
+        __DEV__ && logger.debug(`[Engage] shake bridge install failed (fail-soft): ${err?.message}`);
+        return () => {};
+    }
+}

package/src/features/engage/engageSignals.ts

@@ -0,0 +1,40 @@
+import { logger } from '../../core/logger/internalLogger';
+
+// Minimal in-process fan-out for SDK events the Engage trigger engine cares
+// about. This is NOT a parallel pipeline: `track()` already funnels every SDK
+// event ($crash, $network_request, $clear_user, custom names) through one place,
+// so we tap that single funnel here and let multiple subscribers observe it.
+// Reuse-before-build: no new capture, just an observer on the existing stream.
+
+export interface SdkSignal {
+    name: string;
+    payload?: Record<string, unknown>;
+}
+
+export type SignalListener = (signal: SdkSignal) => void;
+
+class EngageSignalBus {
+    private listeners: SignalListener[] = [];
+
+    subscribe(listener: SignalListener): () => void {
+        this.listeners.push(listener);
+        return () => {
+            const i = this.listeners.indexOf(listener);
+            if (i >= 0) this.listeners.splice(i, 1);
+        };
+    }
+
+    emit(name: string, payload?: Record<string, unknown>): void {
+        if (this.listeners.length === 0) return;
+        const signal: SdkSignal = { name, payload };
+        for (const l of this.listeners) {
+            try {
+                l(signal);
+            } catch (err) {
+                __DEV__ && logger.debug('[Engage] signal listener threw:', (err as Error)?.message);
+            }
+        }
+    }
+}
+
+export const engageSignals = new EngageSignalBus();

package/src/features/engage/engageStoreReviewBridge.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+
+import { NativeModules } from 'react-native';
+import { logger } from '../../core/logger/internalLogger';
+
+interface ScaleBunEngageReviewModule {
+    /** Trigger the native in-app review flow. Resolves true when it ran/resolved. */
+    requestReview(): Promise<boolean>;
+}
+
+function getEngageModule(): ScaleBunEngageReviewModule | null {
+    return (NativeModules?.ScaleBunEngage as ScaleBunEngageReviewModule | undefined) ?? null;
+}
+
+/**
+ * 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 async function requestNativeStoreReview(): Promise<boolean> {
+    try {
+        const mod = getEngageModule();
+        if (!mod?.requestReview) {
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping store review');
+            return false;
+        }
+        const ran = await mod.requestReview();
+        return ran === true;
+    } catch (err: any) {
+        __DEV__ && logger.debug(`[Engage] requestReview failed (fail-soft): ${err?.message}`);
+        return false;
+    }
+}

package/src/features/engage/engageTestSeenStore.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 { logger } from '../../core/logger/internalLogger';
+import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
+
+const STORAGE_PREFIX = 'scalebun_engage_test_seen:';
+/** Remember a displayed testRunId for 24h — far beyond the 10-min server preview TTL. */
+const SEEN_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 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 class EngageTestSeenStore {
+    private readonly backend: StorageBackend;
+
+    constructor(backend: StorageBackend = createStorageBackend()) {
+        this.backend = backend;
+    }
+
+    private keyFor(testRunId: string): string {
+        return `${STORAGE_PREFIX}${testRunId}`;
+    }
+
+    /** True if this testRunId was already displayed on this device (and not yet pruned). */
+    has(testRunId: string): boolean {
+        if (!testRunId) return false;
+        const raw = this.backend.get(this.keyFor(testRunId));
+        if (raw === undefined) return false;
+        const ts = Number(raw);
+        if (Number.isFinite(ts) && Date.now() - ts > SEEN_TTL_MS) {
+            // Past TTL — drop it lazily. The server row is long gone by now, so this only
+            // reclaims storage; it can never resurrect a test that's still being served.
+            this.backend.delete(this.keyFor(testRunId));
+            return false;
+        }
+        return true;
+    }
+
+    /** Record that this testRunId was displayed. Idempotent (overwrites the timestamp). */
+    markSeen(testRunId: string): void {
+        if (!testRunId) return;
+        this.backend.set(this.keyFor(testRunId), String(Date.now()));
+        __DEV__ && logger.debug(`[Engage] test ${testRunId} marked displayed (persisted)`);
+    }
+
+    /**
+     * 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 {
+        let n = 0;
+        for (const key of this.backend.getAllKeys()) {
+            if (!key.startsWith(STORAGE_PREFIX)) continue;
+            this.backend.delete(key);
+            n += 1;
+        }
+        return n;
+    }
+
+    /** Drop stale entries past the TTL. Best-effort housekeeping, safe to call on mount. */
+    prune(): void {
+        const now = Date.now();
+        for (const key of this.backend.getAllKeys()) {
+            if (!key.startsWith(STORAGE_PREFIX)) continue;
+            const ts = Number(this.backend.get(key));
+            if (!Number.isFinite(ts) || now - ts > SEEN_TTL_MS) {
+                this.backend.delete(key);
+            }
+        }
+    }
+}