@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,576 @@
+/**
+ * ScaleBun SDK — Engage Surface Wire Types (foundation)
+ *
+ * Typed DTOs for the 7-screen Engage surface transport lanes, mirrored from the
+ * FROZEN `engage-build/CONTRACT.md` v1 (§1.3 config-serve, §1.4 response upload,
+ * §2.2 device-token registration, §2.4 in-app config, §2.5 event upload).
+ *
+ * All shared wire structures carry an explicit integer version (`configVersion`
+ * or `schemaVersion`) per D9. v1 freeze: `configVersion = 1`. Response schema is
+ * now `schemaVersion = 2` (P0): `EngageResponse` gained the OPTIONAL, ADDITIVE
+ * fields `screen` / `platform` / `appVersion` (`sessionId` already existed and is
+ * now populated). v1 payloads still validate — every new field is optional — and
+ * consumers MUST tolerate unknown fields/higher versions by ignoring them (D9).
+ *
+ * Render/overlay is OUT OF SCOPE for this stage — the shared cross-platform JS
+ * overlay (D4) consumes `fetchEngageConfig()` in a later slice.
+ */
+/** Schema/config version constant (D9). v2 = additive feedback-response fields (P0). */
+export declare const ENGAGE_SCHEMA_VERSION: 2;
+export interface QuestionSpec {
+    key: string;
+    prompt: string;
+    /**
+     * `single` = one choice from `choices`; `multi` = many choices; `scale` =
+     * numeric selector (0..`scaleMax`); `text` = free text; `emoji` = 5-point
+     * 😡🙁😐🙂😍 reaction (value 1..5); `boolean` = Yes/No (value 'Yes'|'No');
+     * `screenshot` = native masked-screenshot attach; `voice` = native mic note
+     * (auto-transcribed). `choice` is kept as an alias for `single` (§1.3).
+     */
+    kind: 'scale' | 'text' | 'choice' | 'single' | 'multi' | 'emoji' | 'boolean' | 'screenshot' | 'voice';
+    choices?: string[];
+    /** Upper bound for `scale` questions (inclusive). Defaults to 5 when omitted. */
+    scaleMax?: number;
+    /** Lower bound for a scale. NPS templates use 0; other scales default to 1. */
+    scaleMin?: number;
+    required?: boolean;
+    skipTo?: string;
+}
+/** One answer in a multi-question SURVEY response (mirrors §1.4 `answers[]`). */
+export interface SurveyAnswer {
+    /** Matches `QuestionSpec.key`. */
+    key: string;
+    /** Scalar answer (scale value, single choice, or text), or many for `multi`. */
+    value: string | number | string[];
+}
+export interface Targeting {
+    platforms?: ('android' | 'ios')[];
+    minAppVersion?: string;
+    segments?: string[];
+    userProps?: Record<string, unknown>;
+}
+export interface Throttle {
+    showOnce?: boolean;
+    cooldownHours?: number;
+    maxImpressions?: number;
+    /**
+     * Cap WITHIN one session (one app run), independent of the lifetime caps above. The in-app
+     * builder writes this on every campaign and `deriveInAppMirror` now carries it to the wire, so
+     * ignoring it here would be offering an authoring control that does nothing on this platform.
+     */
+    maxImpressionsPerSession?: number;
+    samplePct?: number;
+}
+export type EngageCampaignType = 'NPS' | 'CSAT' | 'CUSTOM' | 'FEEDBACK' | 'RATING_PROMPT' | 'RATINGS_PROMPT';
+export interface EngageCampaignConfig {
+    id: string;
+    type: EngageCampaignType;
+    name: string;
+    question: string;
+    questions?: QuestionSpec[];
+    scale?: number;
+    trigger?: string;
+    targetScreen?: string;
+    triggerConfig?: TriggerConfig;
+    targeting?: Targeting;
+    throttle?: Throttle;
+    startScreen?: string;
+    thankYouScreen?: string;
+    language?: string;
+    storeUrl?: string;
+    highRatingThreshold?: number;
+    routeLowToFeedback?: boolean;
+    /**
+     * Route this campaign's submission to BUG REPORTS instead of Engage responses.
+     *
+     * Engage responses and bug reports are different products: a survey response measures sentiment
+     * in aggregate, while a bug report is a single item that gets a status, a priority and an
+     * assignee on /diagnose/bug-reports. A FEEDBACK campaign triggered by `shake_device` is almost
+     * always the second kind — someone shook the phone because something is broken.
+     *
+     * Opt-IN per campaign rather than rerouting every FEEDBACK campaign, because rerouting would
+     * silently break existing sentiment surveys, and because the destination should be visible to
+     * whoever configures the campaign rather than inferred from its trigger.
+     *
+     * Absent/false keeps the existing behaviour exactly.
+     */
+    fileAsBugReport?: boolean;
+    enabled: boolean;
+}
+export interface TriggerConfig {
+    screen?: string;
+    seconds?: number;
+    sessions?: number;
+    event?: string;
+    action?: string;
+    slowMs?: number;
+    /**
+     * Seconds to wait AFTER the trigger fires before showing (authoring "Delay
+     * after trigger"). The trigger engine honors the REMAINING delay on replay so
+     * an event buffered during a cold-start config race still shows at trigger+delay,
+     * not late. Absent/0 ⇒ show immediately. Additive/optional.
+     */
+    delaySeconds?: number;
+}
+/** URL-backed assets lifted from the normalized in-app payload for SDK rendering. */
+export interface InAppRenderAssets {
+    icon?: string;
+    image?: string;
+    video?: string;
+    lottie?: string;
+    backgroundImage?: string;
+    avatar?: string;
+    calendar?: string;
+    document?: string;
+    qr?: string;
+    nfc?: string;
+    wallet?: string;
+    /** Structured commerce items preserved by the normalized payload mirror. */
+    products?: unknown[];
+    /** Structured geo metadata preserved by the normalized payload mirror. */
+    location?: Record<string, unknown>;
+}
+/**
+ * Authored size of a campaign's primary hero/poster media.
+ *
+ * The value is carried additively at `spec.ext.mediaSize`. Missing, `auto`, and
+ * unknown values preserve each renderer's historical dimensions.
+ */
+export type InAppMediaSize = 'auto' | 'compact' | 'medium' | 'large' | 'full';
+/** Semantic artwork options for the authored terminal result/confirmation card. */
+export type InAppOutcomeIcon = 'check' | 'trophy' | 'gift' | 'star' | 'sparkles' | 'rocket';
+/** Normalized action authored for the terminal result/confirmation button. */
+export type InAppOutcomeActionType = 'deep_link' | 'url' | 'screen' | 'dismiss';
+export interface InAppOutcomeAction {
+    label: string;
+    type: InAppOutcomeActionType;
+    value?: string;
+    track?: boolean;
+}
+/**
+ * Presentation-only terminal card configuration.
+ *
+ * This must never carry a game result. Reward identity/value remains exclusively
+ * in `InAppGameOutcome`, returned by the host's authenticated backend.
+ */
+export interface InAppOutcomeConfig {
+    enabled?: boolean;
+    title?: string;
+    body?: string;
+    icon?: InAppOutcomeIcon;
+    buttonLabel?: string;
+    action?: InAppOutcomeAction;
+}
+/** Open variant payload with shared cross-variant conventions typed explicitly. */
+export interface InAppRenderExt extends Record<string, unknown> {
+    mediaSize?: InAppMediaSize;
+    outcome?: InAppOutcomeConfig;
+}
+/** An authored in-app action. Coachmark steps reuse the same click contract. */
+export interface InAppCta {
+    label: string;
+    deepLink?: string;
+    action: 'dismiss' | 'link' | 'custom';
+    /** Set to false for authored actions that must execute without a click event. */
+    track?: boolean;
+}
+export type InAppCoachmarkPlacement = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+/** One ordered stop in a `coachmark_spotlight` tour (`spec.ext.steps`). */
+export interface InAppCoachmarkStep {
+    anchorKey: string;
+    title?: string;
+    body: string;
+    placement?: InAppCoachmarkPlacement;
+    /** Optional final-stop product action; navigation controls are supplied by the SDK. */
+    cta?: InAppCta;
+}
+export interface InAppRenderSpec {
+    title?: string;
+    body?: string;
+    /** Preview-lane compatibility; published configs also carry this at message level. */
+    variantKey?: string;
+    /** Preview-lane normalized payload version. */
+    payloadVersion?: number;
+    /** Preview-lane minimum SDK version. */
+    sdkMinVersion?: string;
+    imageUrl?: string;
+    cta?: InAppCta;
+    secondaryCta?: {
+        label: string;
+        action: 'dismiss';
+    };
+    /** Dark theme (matches the dashboard "Dark" preview toggle). */
+    dark?: boolean;
+    /** Right-to-left layout/text (dashboard "AR · RTL" toggle). */
+    rtl?: boolean;
+    /** Coupon code chip rendered under the body (dashboard "Reveal & copy coupon"). */
+    coupon?: string;
+    /** Legacy-only variant/mechanic hint. Canonical payloads dispatch by `variantKey`. */
+    archetype?: string;
+    /**
+     * Archetype-specific payload. Keys vary per archetype:
+     *   spin_wheel:       segments [{label,color?}], spinLabel?
+     *   countdown_offer:  expiryTime (ISO string), countdownUnits? (2|3)
+     *   scratch_card:     prize?, closedMessage?
+     *   slot_reward:      reels [{emoji}]
+     *   poll_card:        question, options [{label}], showResults?
+     *   nps_prompt:       question, scaleMax? (default 10), scaleLabels?
+     *   emoji_reaction_bar: reactions [emoji strings]
+     *   rating_request:   ratingScale? (default 5)
+     *   streak_reward:    filled (days done), total (total days), glyph?
+     *   checklist_progress: items [{label, done?}]
+     *   coupon_wallet:    code, couponLabel?
+     *   coachmark_spotlight: steps [{anchorKey,title,body,placement,cta?}]
+     */
+    ext?: InAppRenderExt;
+    /** Structured asset URLs supplied by the normalized in-app builder. */
+    assets?: InAppRenderAssets;
+    /**
+     * Normalized theme token overrides. Keys (all optional): accent, cardBg,
+     * titleColor, bodyColor, couponBg, couponFg, couponBorder, backdrop, ctaText.
+     * Unset tokens fall back to the dashboard-matching light/dark defaults — this is
+     * the SINGLE design contract; the SDK never hardcodes dashboard CSS per message.
+     */
+    style?: Record<string, string>;
+}
+/**
+ * Optional A/B experiment carried on an in-app campaign config (D8/J6). When
+ * `enabled`, the SDK deterministically buckets the current user/device into
+ * variant `A` (the message's base `spec`) or variant `B` (`variantB`), where
+ * `split` is the integer percentage (0–100) of traffic routed to variant B.
+ * Absent/`enabled:false` ⇒ everyone sees the base `spec` (no experiment).
+ * Additive + optional — older configs (no `experiment`) are unaffected.
+ */
+export interface InAppExperiment {
+    enabled: boolean;
+    /** Percentage (0–100) of traffic routed to variant B. */
+    split: number;
+    /** Variant B content. Variant A is the message's base `spec`. */
+    variantB: InAppRenderSpec;
+}
+/** Resolved experiment arm for the current user/device (client-side selection). */
+export type InAppVariantId = 'A' | 'B';
+export interface InAppMessageConfig {
+    id: string;
+    layout: 'modal' | 'fullscreen' | 'bottom_sheet' | 'top_banner' | 'bottom_banner' | 'tooltip' | 'toast';
+    trigger?: string;
+    /** Business/custom event name for `event` / `custom` triggers. */
+    eventName?: string;
+    /** Canonical screen name when the backend preserves it separately. */
+    screenName?: string;
+    /** Seconds to wait after the trigger fires before showing (see TriggerConfig.delaySeconds). */
+    delaySeconds?: number;
+    targetScreen?: string;
+    targeting?: Targeting;
+    throttle?: Throttle;
+    spec: InAppRenderSpec;
+    /** Canonical registry key used to select a mechanic renderer. */
+    variantKey?: string;
+    /** Version of the normalized in-app payload schema. */
+    payloadVersion?: number;
+    /** Minimum SDK version capable of rendering this payload. */
+    sdkMinVersion?: string;
+    /**
+     * Content revision / contentHash (server-computed from the campaign's stored
+     * content). Frequency-cap state is scoped to `id + revision`: when an author
+     * changes a published campaign's design/content/type, the backend serves a NEW
+     * revision, so old impression/showOnce/cooldown state no longer suppresses the
+     * updated message (the #1 "had to reinstall to see my change" cause). Absent on
+     * legacy configs ⇒ state behaves exactly as before (keyed by id alone).
+     */
+    revision?: string;
+    /**
+     * [T1] Unique id for ONE "Send Test" run (== previewId). Every Send Test mints a
+     * fresh testRunId, so a re-send is ALWAYS eligible and is never blocked by a prior
+     * test's dismissed/impression state. Rides lifecycle events (via `meta.testRunId`)
+     * so the dashboard can correlate a specific test send to its render/click/dismiss.
+     */
+    testRunId?: string;
+    /**
+     * [T1] Queue time of a test preview (ISO, server → SDK). When more than one pending
+     * test is served, the SDK sorts by this and renders only the LATEST. Absent on
+     * normal campaign messages.
+     */
+    createdAt?: string;
+    /**
+     * Optional A/B experiment (D8/J6). When present + `enabled`, the SDK picks
+     * variant A (`spec`) or B (`experiment.variantB`) deterministically for the
+     * current device. Optional/additive — absent ⇒ no experiment.
+     */
+    experiment?: InAppExperiment;
+    /**
+     * [T1] Test-preview flags (server → SDK). A message the backend queued via
+     * "Send Test" for THIS device carries `preview:true` + a `previewId`. The SDK
+     * renders it IMMEDIATELY — bypassing trigger/throttle/schedule/sample — and the
+     * resulting impression (carrying `previewId`/`isTest`) consumes it server-side.
+     * `isTest` marks the traffic so production KPIs exclude it. Absent on normal
+     * campaign messages (additive/optional — older configs are unaffected).
+     */
+    preview?: boolean;
+    previewId?: string;
+    isTest?: boolean;
+}
+/** Variants whose result/state must be resolved by the host app's backend. */
+export type InAppGameVariantKey = 'spin_wheel' | 'scratch_card' | 'slot_reward' | 'mystery_box' | 'progress_unlock' | 'streak_reward' | 'daily_check_in' | 'quiz_card';
+export type InAppGameAction = 'play' | 'load' | 'check_in' | 'submit_quiz';
+interface InAppGameRequestBase {
+    /** In-app campaign/message id from the served config. */
+    campaignId: string;
+    /** Stable customer-defined key authored in `spec.ext.gameKey`. */
+    gameKey: string;
+    /** Stable idempotency key. The SDK reuses it when the user retries this attempt. */
+    attemptId: string;
+    /** One-based play/check attempt number. State loads use 1. */
+    attempt: number;
+    /** Presentation-safe input only (for example quiz answer indexes and score). */
+    input?: Record<string, unknown>;
+    /** Authored outcome ids, when the presentation declares a closed set. */
+    allowedOutcomeIds?: string[];
+}
+/** Discriminated request passed to `onInAppGameRequest`. */
+export type InAppGameRequest = (InAppGameRequestBase & {
+    variantKey: 'spin_wheel' | 'scratch_card' | 'slot_reward' | 'mystery_box';
+    action: 'play';
+}) | (InAppGameRequestBase & {
+    variantKey: 'progress_unlock' | 'streak_reward';
+    action: 'load';
+}) | (InAppGameRequestBase & {
+    variantKey: 'daily_check_in';
+    action: 'check_in';
+}) | (InAppGameRequestBase & {
+    variantKey: 'quiz_card';
+    action: 'submit_quiz';
+});
+/** Presentation-safe result returned after the customer's backend grants/reserves it. */
+export interface InAppGameOutcome {
+    /** Stable backend outcome id; use a real id such as `no_reward` for non-winning plays. */
+    id: string;
+    label?: string;
+    /** Wheel segment id (preferred over a display index). */
+    segmentId?: string;
+    segmentIndex?: number;
+    /** Slot symbols, in reel order. */
+    symbols?: string[];
+    /** Progress/streak/check-in state consumed by those renderers. */
+    state?: Record<string, unknown>;
+    value?: string | number | boolean;
+    /** Customer receipt/grant id for reconciliation. Never treated as a reward by the SDK. */
+    receiptId?: string;
+}
+/** A host can return `unavailable`, or throw; both produce the same retry-safe UI. */
+export type InAppGameResult = {
+    attemptId: string;
+    status: 'resolved';
+    outcome: InAppGameOutcome;
+} | {
+    attemptId: string;
+    status: 'unavailable';
+    retryable?: boolean;
+    message?: string;
+};
+export type InAppGameRequestHandler = (request: InAppGameRequest) => Promise<InAppGameResult>;
+export interface EngageConfigResponse {
+    configVersion: number;
+    serverTime: string;
+    campaigns: EngageCampaignConfig[];
+    inAppMessages: InAppMessageConfig[];
+}
+export interface CoachTourStep {
+    id?: string;
+    anchorKey: string;
+    title?: string;
+    body: string;
+    placement?: InAppCoachmarkPlacement;
+    cta?: InAppCta;
+}
+export interface CoachTourConfig {
+    id: string;
+    name: string;
+    version: number;
+    preview?: boolean;
+    steps: CoachTourStep[];
+}
+export interface CoachConfigResponse {
+    tours: CoachTourConfig[];
+}
+/** Optional app/user context for server-side targeting/throttle (§1.3 query). */
+export interface EngageConfigContext {
+    platform?: 'android' | 'ios';
+    appVersion?: string;
+    endUserId?: string;
+    deviceId?: string;
+}
+export interface EngageResponse {
+    responseId: string;
+    surveyId: string;
+    schemaVersion: number;
+    score?: number;
+    text?: string;
+    tags?: string[];
+    sessionId?: string;
+    /** [v2] Originating screen the prompt was shown on (additive, optional). */
+    screen?: string;
+    /** [v2] Device platform for by-platform analytics (additive, optional). */
+    platform?: 'android' | 'ios';
+    /** [v2] Host app version for by-version analytics (additive, optional). */
+    appVersion?: string;
+    deviceId?: string;
+    endUserId?: string;
+    answers?: {
+        key: string;
+        value: string | number | string[];
+    }[];
+    /** [P3-e] Native attachment metadata (screenshot/voice). Bytes uploaded direct. */
+    attachments?: EngageAttachmentMeta[];
+    clientTs: string;
+}
+/** Closed, ordered funnel enum (CONTRACT §1.1). Producers never emit outside it. */
+export type RatingFunnelEventType = 'rating_prompt_eligible' | 'rating_prompt_shown' | 'rating_prompt_dismissed' | 'rating_selected' | 'store_redirect_clicked';
+/** Per-event breakdown dimensions (CONTRACT §1.2 `dims`). All optional/honest. */
+export interface RatingFunnelEventDims {
+    platform?: 'android' | 'ios' | 'web';
+    appVersion?: string;
+    build?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    country?: string;
+    locale?: string;
+    acquisitionSource?: string;
+}
+/** What a caller raises (no eventId/ts — the transport stamps those, D8). */
+export interface RatingFunnelEventInput {
+    type: RatingFunnelEventType;
+    sessionId?: string;
+    userId?: string;
+    promptId?: string;
+    triggerId?: string;
+    variantId?: string;
+    stars?: number;
+    dims?: RatingFunnelEventDims;
+}
+/** Wire shape after the transport stamps the idempotency key + client clock. */
+export interface RatingFunnelEventUpload extends RatingFunnelEventInput {
+    eventId: string;
+    ts: string;
+}
+export type EngageAttachmentKind = 'screenshot' | 'voice';
+/** Raw attachment captured on-device, before upload (carries bytes + dimensions). */
+export interface EngageAttachmentDraft {
+    kind: EngageAttachmentKind;
+    base64: string;
+    mime: string;
+    width?: number;
+    height?: number;
+    byteSize?: number;
+    durationMs?: number;
+    masked?: boolean;
+    /** voice only — on-device STT text, user-edited final wording (additive). */
+    transcript?: string;
+    /** voice only — user explicitly approved the transcript before send (additive). */
+    transcriptApproved?: boolean;
+}
+/** Attachment metadata sent on the response after the bytes are PUT to storage. */
+export interface EngageAttachmentMeta {
+    attachmentId: string;
+    kind: EngageAttachmentKind;
+    storageKey: string;
+    mime: string;
+    width?: number;
+    height?: number;
+    byteSize?: number;
+    durationMs?: number;
+    masked?: boolean;
+    /** voice only — approved final transcript text (additive). */
+    transcript?: string;
+    /** voice only — user approved before send (additive). */
+    transcriptApproved?: boolean;
+}
+/** Presign response item (backend → SDK). */
+export interface EngageAttachmentPresignResult {
+    attachmentId: string;
+    uploadUrl: string;
+    storageKey: string;
+    bucket: string;
+    contentType: string;
+}
+/** Caller-supplied response input — `responseId`/`schemaVersion`/`clientTs` stamped by transport. */
+export type EngageResponseInput = Omit<EngageResponse, 'responseId' | 'schemaVersion' | 'clientTs'>;
+export interface SurveyImpressionInput {
+    surveyId: string;
+    stage: 'shown' | 'started';
+    sessionId?: string;
+    deviceId?: string;
+    platform?: 'android' | 'ios';
+    appVersion?: string;
+    screen?: string;
+}
+export interface SurveyImpressionUpload extends SurveyImpressionInput {
+    beaconId: string;
+    clientTs: string;
+    schemaVersion: number;
+}
+export interface EngageEventUpload {
+    eventId: string;
+    campaignId?: string;
+    channel: 'inapp';
+    /**
+     * `impression` = prompt/message shown; `completion` = prompt submitted
+     * (P3-e #2, first-class submit signal); `click` = in-app CTA tap; `dismiss`
+     * = closed without submit. `rendered` = a test preview actually mounted (the
+     * signal that CONSUMES the preview server-side); `interaction` = a bounded,
+     * display-only mechanic transition in `meta` (never a client reward grant);
+     * `render_degraded` = a host placement was unavailable and the SDK used its
+     * authored/legacy fallback; `render_failed` = the SDK could not render a message
+     * (carries `meta.reason`); `cta_open_failed` = the
+     * host's deep-link sink rejected/was missing for a link CTA. Additive to §2.5 —
+     * backend EngageEvent.type is a free string, so older readers ignore new types (D9).
+     */
+    type: 'impression' | 'completion' | 'click' | 'dismiss' | 'interaction' | 'rendered' | 'render_degraded' | 'render_failed' | 'cta_open_failed';
+    deviceId?: string;
+    endUserId?: string;
+    timestamp: string;
+    schemaVersion: number;
+    /**
+     * [T1] Test/attribution tags (SDK → backend). `isTest` + `source:'test_preview'`
+     * + `previewId` mark a test-preview event so production KPIs exclude it and the
+     * matching preview row is consumed/advanced. `variantId` attributes an A/B arm.
+     * All optional/additive — normal campaign events omit them.
+     */
+    isTest?: boolean;
+    source?: string;
+    previewId?: string;
+    variantId?: string;
+    meta?: Record<string, unknown>;
+}
+/** Caller-supplied event input — `eventId`/`schemaVersion`/`timestamp` stamped by transport. */
+export type EngageEventInput = Omit<EngageEventUpload, 'eventId' | 'schemaVersion' | 'timestamp'>;
+export interface DeviceTokenRegistration {
+    schemaVersion: number;
+    deviceId: string;
+    pushToken: string;
+    platform: 'android' | 'ios';
+    /** Send-transport routing key: direct APNs (iOS) → 'apns'; Firebase → 'fcm'. */
+    pushProvider?: 'fcm' | 'apns';
+    tokenStatus?: 'active';
+    installationId?: string;
+    sdkVersion?: string;
+}
+/** Caller-supplied token input — `schemaVersion`/`tokenStatus` stamped by transport. */
+export interface DeviceTokenInput {
+    deviceId?: string;
+    pushToken: string;
+    platform: 'android' | 'ios';
+    pushProvider?: 'fcm' | 'apns';
+    installationId?: string;
+    sdkVersion?: string;
+}
+export interface EngageResponsesBatch {
+    schemaVersion: number;
+    responses: EngageResponse[];
+}
+export interface EngageEventsBatch {
+    schemaVersion: number;
+    events: EngageEventUpload[];
+}
+export {};
+//# sourceMappingURL=engageTypes.d.ts.map

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

@@ -0,0 +1,46 @@
+import type { InAppMessageConfig } from "./engageTypes";
+/** The 18 renderer families in the canonical in-app registry. */
+export type InAppArchetype = "modal" | "sheet" | "bannerToast" | "fullscreen" | "anchored" | "inline" | "spinWheel" | "scratchReveal" | "slotReward" | "carouselDeck" | "countdown" | "questionFlow" | "checklistProgress" | "qrNfc" | "videoCommerce" | "celebration" | "multiStepSheet" | "sideSheet";
+/** Interactive renderer families kept for the existing mechanic-only API. */
+export type InAppMechanicFamily = Extract<InAppArchetype, "spinWheel" | "scratchReveal" | "slotReward" | "carouselDeck" | "countdown" | "questionFlow" | "checklistProgress" | "qrNfc" | "videoCommerce" | "celebration">;
+/** How the SDK host physically attaches a presentation. */
+export type InAppMountModel = "overlay" | "sheet" | "banner" | "fullscreen" | "toast" | "bubble" | "anchored" | "inline";
+/** The original seven-layout transport contract used for graceful degradation. */
+export type InAppLegacyLayout = InAppMessageConfig["layout"];
+export interface InAppPresentationDefinition {
+    archetype: InAppArchetype;
+    mountModel: InAppMountModel;
+    legacyLayout: InAppLegacyLayout;
+}
+export declare const IN_APP_VARIANT_PRESENTATIONS: Readonly<Record<string, InAppPresentationDefinition>>;
+export type InAppPresentationSource = "variantKey" | "spec.variantKey" | "spec.archetype" | "layout";
+export type InAppPresentationFallbackReason = "preview_variant_key" | "legacy_archetype" | "unknown_variant_key" | "unknown_preview_variant_key" | "unknown_legacy_archetype" | "missing_variant_key";
+export interface InAppPresentationFallback {
+    reason: InAppPresentationFallbackReason;
+    /** The unrecognized key when degradation, rather than compatibility, occurred. */
+    requestedKey?: string;
+    degraded: boolean;
+}
+export interface ResolvedInAppPresentation extends InAppPresentationDefinition {
+    /** Canonical key when one resolved; null when the legacy layout had to render. */
+    variantKey: string | null;
+    source: InAppPresentationSource;
+    fallback: InAppPresentationFallback | null;
+}
+type PresentationMessage = Pick<InAppMessageConfig, "layout" | "spec" | "variantKey">;
+/**
+ * Resolve canonical identity first, retaining explicit metadata whenever a
+ * preview/legacy compatibility lane or graceful layout degradation was used.
+ */
+export declare function resolveInAppPresentation(message: PresentationMessage): ResolvedInAppPresentation;
+/**
+ * Resolve an in-app config to an interactive mechanic family.
+ *
+ * A present top-level `variantKey` remains authoritative. Older previews may
+ * carry the canonical key in `spec.variantKey`; hand-authored legacy payloads
+ * may instead use `spec.archetype`. `checklist_progress` remains a legacy-only
+ * alias and is deliberately absent from the canonical 100-key map.
+ */
+export declare function resolveInAppMechanic(message: Pick<InAppMessageConfig, "variantKey" | "spec">): InAppMechanicFamily | null;
+export {};
+//# sourceMappingURL=engageVariantResolver.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * Native safe-area/window insets for Engage screen-edge surfaces.
+ *
+ * No third-party safe-area package is required. The existing ScaleBunEngage module
+ * returns Android system-bar/display-cutout insets in dp and iOS safe-area
+ * insets in points, which are both React Native layout units. Older installed
+ * binaries simply resolve through this helper as null.
+ */
+export interface EngageWindowInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare const ZERO_ENGAGE_WINDOW_INSETS: EngageWindowInsets;
+/** Validate and normalize an untrusted native result. */
+export declare function normalizeWindowInsets(value: unknown): EngageWindowInsets | null;
+/** Read the current native insets, failing soft when the module/method is absent. */
+export declare function readNativeWindowInsets(relativeToContent?: boolean): Promise<EngageWindowInsets | null>;
+/**
+ * Read on mount, after layout-size changes, and periodically for immersive bar
+ * transitions that do not resize the React surface. Only the latest request wins.
+ */
+export declare function useEngageWindowInsets(relativeToContent?: boolean): EngageWindowInsets | null;
+//# sourceMappingURL=engageWindowInsets.d.ts.map

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

@@ -0,0 +1,20 @@
+export interface TapInfo {
+    x: number;
+    y: number;
+    hasTarget: boolean;
+    screen?: string;
+}
+declare class GestureTriggerDetector {
+    private recentTaps;
+    private lastRageFireTs;
+    private pendingDead;
+    private lastScreen?;
+    private lastScreenChangeTs;
+    /** Called on every committed tap from the JS touch layer. */
+    recordTap(info: TapInfo): void;
+    /** Native sensor bridge entrypoint for device shake. */
+    reportShake(screen?: string): void;
+}
+export declare const gestureTriggerDetector: GestureTriggerDetector;
+export {};
+//# sourceMappingURL=gestureTriggerDetector.d.ts.map