@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,180 @@
+/**
+ * ScaleBun SDK — Engage Prompt Throttle + Decision Logic
+ *
+ * Pure, presentation-free logic that the shared cross-platform JS overlay (D4)
+ * uses to decide WHICH campaign (if any) to render from a fetched
+ * `EngageConfigResponse`, honoring each campaign's `throttle`/`Throttle` rules
+ * (§1.3) so a user is never re-prompted on every render.
+ *
+ * State (per-campaign impression count + last-shown timestamp) is persisted via
+ * the same synchronous KV backend used for the device id, so frequency capping
+ * survives app restarts. No React, no `any`, no network — this is the testable
+ * core of the renderer's Open/Closed decision seam.
+ */
+import { type StorageBackend } from '../../storage/StorageBackend';
+import type { EngageCampaignConfig, InAppMessageConfig, InAppRenderSpec, InAppVariantId } from './engageTypes';
+/** Persisted frequency-capping state for a single campaign. */
+export interface CampaignThrottleState {
+    /** Number of times this campaign has been shown (impressions). */
+    impressions: number;
+    /** Epoch ms of the last impression — drives `cooldownHours`. */
+    lastShownAt: number;
+    /** Set once a response was submitted — hard stop for `showOnce`. */
+    completed: boolean;
+    /**
+     * Content revision this state was recorded against. When the live config carries
+     * a NEWER revision (author changed the campaign's design/content/type), the prior
+     * impression/showOnce/cooldown state is stale and must NOT suppress the updated
+     * message — see `passesThrottle`. Absent on legacy state ⇒ revision check is skipped.
+     */
+    revision?: string;
+}
+/**
+ * Persistent, restart-surviving store for per-campaign throttle state. Backed by
+ * the shared first-party StorageBackend (durable native store, memory only as an
+ * emergency fallback), so frequency caps hold across sessions exactly like the
+ * device id.
+ */
+export declare class EngageThrottleStore {
+    private readonly backend;
+    /**
+     * Shows in THIS session, backing `maxImpressionsPerSession`.
+     *
+     * Deliberately in-memory rather than persisted: on mobile a session is an app run, and this
+     * store is constructed once per provider mount, so the map's lifetime already is the session's.
+     * Persisting it would outlive the session it is meant to bound.
+     */
+    private readonly sessionShows;
+    constructor(backend?: StorageBackend);
+    /** How many times this surface has been shown in the current session. */
+    sessionShowCount(campaignId: string): number;
+    private keyFor;
+    /** Read the persisted state for a campaign (zeroed default when absent). */
+    get(campaignId: string): CampaignThrottleState;
+    /** Delete one campaign's persisted throttle state (debug/dev reset, or per-id clear). */
+    clearOne(campaignId: string): void;
+    /**
+     * Delete ALL persisted in-app/campaign throttle state (every `scalebun_engage_throttle:*`
+     * key). Backs the public `ScaleBun.engage.resetInAppState()` debug reset — clears
+     * dismissed/impression/cooldown/showOnce so a tester sees messages again WITHOUT an
+     * uninstall. Does NOT touch the device id (a separate key) — identity is preserved.
+     */
+    clearAll(): number;
+    private write;
+    /**
+     * Record that a campaign was shown (bumps impressions + last-shown time). When a
+     * `revision` is supplied and differs from the stored one, the prior counters are a
+     * stale (pre-edit) generation and reset to a single fresh impression — so changing a
+     * campaign's content never inherits the old cap.
+     */
+    recordImpression(campaignId: string, now?: number, revision?: string): void;
+    /**
+     * Mark a campaign as completed (response submitted, or an in-app message closed) — a hard stop.
+     *
+     * The `revision` MUST be carried through. This wrote the record without one, which silently
+     * disabled the revision check in `passesThrottle` for the rest of that campaign's life on the
+     * device: that check only fires when BOTH the live config and the stored state carry a revision,
+     * so a state stamped `undefined` can never be invalidated. The result was the exact opposite of
+     * the web bug — once a user closed an in-app message, editing the campaign could never bring the
+     * new version back to them. Callers that know the served revision pass it; legacy callers that
+     * don't keep whatever was already stored rather than erasing it.
+     */
+    markCompleted(campaignId: string, now?: number, revision?: string): void;
+}
+/**
+ * Decide whether a single campaign is eligible to show right now, given its
+ * `throttle` rules and the persisted impression state. Pure: no side effects.
+ */
+export declare function isCampaignEligible(campaign: EngageCampaignConfig, state: CampaignThrottleState, now?: number, sessionShows?: number): boolean;
+/**
+ * Decide whether a single in-app message is eligible to show right now. In-app
+ * messages have no `enabled` flag (the config-serve lane only returns active ones,
+ * §2.4) — eligibility is purely the SHARED throttle/frequency-cap rules. So an
+ * impression-capped message is never re-shown, exactly like a campaign.
+ */
+export declare function isInAppEligible(message: InAppMessageConfig, state: CampaignThrottleState, now?: number, sessionShows?: number): boolean;
+/**
+ * Pick the FIRST eligible campaign from a config payload, optionally filtered by
+ * a campaign type whitelist (e.g. `['NPS']` for the NPS-first slice) and/or a
+ * `targetScreen`. This is the renderer's config→render decision: config drives
+ * which prompt shows, throttle decides whether it shows at all.
+ */
+export declare function selectCampaignToRender(campaigns: EngageCampaignConfig[], store: EngageThrottleStore, options?: {
+    types?: EngageCampaignConfig['type'][];
+    screen?: string;
+    /**
+     * When set, only campaigns whose `trigger` equals this value match — the
+     * behavioral-trigger path (e.g. `'screen_exit'`). Omitted ⇒ trigger-agnostic
+     * (the manual `showEngagePrompt()` path fires any eligible campaign).
+     */
+    trigger?: string;
+    /**
+     * Event name for the `custom_event` trigger (and `after_purchase`). When set,
+     * only campaigns whose `triggerConfig.event` matches are eligible.
+     */
+    event?: string;
+    /**
+     * Action label for the `failed_action` trigger (Payment/Login/…). When set,
+     * only campaigns whose `triggerConfig.action` matches are eligible.
+     */
+    action?: string;
+    /** Exact fired `time_in_app` timer threshold. */
+    seconds?: number;
+    now?: number;
+}): EngageCampaignConfig | null;
+/**
+ * Pick the FIRST eligible in-app message from a config payload (`inAppMessages[]`,
+ * §2.4), optionally filtered by `targetScreen`. Mirrors `selectCampaignToRender`:
+ * config drives which message shows, the SHARED throttle decides whether it shows
+ * at all (an impression-capped message isn't reshown).
+ */
+export declare function selectInAppToRender(messages: InAppMessageConfig[], store: EngageThrottleStore, options?: {
+    screen?: string;
+    trigger?: string;
+    event?: string;
+    action?: string;
+    seconds?: number;
+    now?: number;
+}): InAppMessageConfig | null;
+/** Dashboard trigger aliases normalized onto the SDK signal names. */
+export declare function normalizeInAppTrigger(trigger?: string): string | undefined;
+/** Resolve the one-shot dedupe key for a test preview (testRunId → previewId → id). */
+export declare function testRunIdOf(message: InAppMessageConfig): string;
+/**
+ * [T1] Pure one-shot test-preview selection — the testable core of the renderer's
+ * "show the latest UNSEEN test, never re-show a dismissed/displayed one" rule.
+ *
+ * From a fetched config's messages it:
+ *   1. keeps only test previews (`preview` / `isTest`),
+ *   2. de-dupes by `testRunId` (the SAME run served twice collapses to one),
+ *   3. drops any already DISPLAYED-or-DISMISSED run (persistent `seen`, survives cold
+ *      restart) or closed-this-session run (`consumed`, in-memory),
+ *   4. returns the LATEST remaining by `createdAt` (so old tests never stack up).
+ *
+ * `seen`/`consumed` are injected predicates (the provider passes its persistent
+ * `EngageTestSeenStore` and its session `Set`), so this stays React-free and unit-
+ * testable. Returns `null` when nothing eligible remains.
+ */
+export declare function selectLatestUnseenTest(messages: InAppMessageConfig[], deps: {
+    seen: (runId: string) => boolean;
+    consumed: (key: string) => boolean;
+}): InAppMessageConfig | null;
+/**
+ * Resolve the A/B experiment arm for an in-app message (D8/J6). Minimal,
+ * deterministic, side-effect-free — NOT a general experimentation framework.
+ *
+ * - No experiment, disabled, or no `variantB` ⇒ variant `A` (the base `spec`).
+ * - Otherwise the user/device is bucketed 0–99 by a STABLE hash of
+ *   `messageId + ':' + deviceId`, so the same device always sees the same arm
+ *   for a given message (and the message id salts the hash so a device is not
+ *   pinned to the same arm across every experiment). Buckets `< split` get
+ *   variant B; the rest get variant A. `split<=0`⇒all A, `split>=100`⇒all B.
+ *
+ * Returns both the chosen `variant` id (for event attribution) and the `spec`
+ * to render, so callers never re-derive which arm won.
+ */
+export declare function selectInAppVariant(message: InAppMessageConfig, deviceId: string): {
+    variant: InAppVariantId;
+    spec: InAppRenderSpec;
+};
+//# sourceMappingURL=engageThrottle.d.ts.map

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

@@ -0,0 +1,16 @@
+import { type StorageBackend } from '../../storage/StorageBackend';
+import type { EngageConfigResponse } from './engageTypes';
+import type { ShowEngagePromptOptions } from './EngagePromptProvider';
+export interface EngageTriggerEngineDeps {
+    /** Fire a behavioral trigger through the shared prompt path. */
+    fire: (options: ShowEngagePromptOptions) => void;
+    /** Fetch the current Engage config (for threshold-aware triggers). */
+    fetchConfig: () => Promise<EngageConfigResponse | null>;
+    storage?: StorageBackend;
+}
+/**
+ * Wire every JS-reusable behavioral trigger to its existing producer. Returns a
+ * teardown that detaches all subscriptions/timers.
+ */
+export declare function installEngageTriggerEngine(deps: EngageTriggerEngineDeps): () => void;
+//# sourceMappingURL=engageTriggerEngine.d.ts.map