@scalebun-release/react-native 2.5.0

package/src/features/engage/engageTypes.ts

@@ -0,0 +1,712 @@
+/**
+ * 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 const ENGAGE_SCHEMA_VERSION = 2 as const;
+
+// ─── §1.3 Config-serve payload (backend → SDK) ───────────────────────────────
+
+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'
+    // Contract §1.3 spells the app-store funnel `RATINGS_PROMPT`; kept as an
+    // accepted alias so a config payload using either string renders the stars.
+    | 'RATINGS_PROMPT';
+
+export interface EngageCampaignConfig {
+    id: string;
+    type: EngageCampaignType;
+    name: string;
+    question: string;
+    questions?: QuestionSpec[];
+    scale?: number;
+    trigger?: string;
+    targetScreen?: string;
+    // Per-trigger config (CONTRACT §2.10.3 `needs`). Carries the extra parameter a
+    // behavioral trigger matches on: `event` (custom_event), `action` (failed_action),
+    // `seconds` (time_in_app), `sessions` (n_sessions), `slowMs` (slow_screen). Absent
+    // for parameter-less triggers (after_crash, before_logout, shake_device, …).
+    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;
+}
+
+// ─── §2.4 In-app message config (rides the SAME config lane) ──────────────────
+
+/** 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;
+}
+
+// ─── Customer-owned gamified result contract ──────────────────────────────────────
+
+/** 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;
+}
+
+// ─── §1.4 Response payload (SDK → backend) ───────────────────────────────────
+
+export interface EngageResponse {
+    responseId: string; // UUID, client-generated (D8 dedup key)
+    surveyId: string;
+    schemaVersion: number;
+    score?: number; // NPS 0-10; CSAT 1-5; FEEDBACK omit/null
+    text?: string;
+    tags?: string[];
+    sessionId?: string; // [v2] canonical replay session id → /sessions/:id linkage
+    /** [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; // ISO event time
+}
+
+// ─── Rating-funnel event lane (ratings-rebuild CONTRACT §1.1–1.2) ────────────
+// First-class, dimensioned, deduped tracking facts feeding the Overview funnel.
+// NOT a campaign response (D1) — these never count as a "rating response".
+
+/** 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; // ISO-2
+    locale?: string;
+    acquisitionSource?: string; // "Unknown" until attribution SDK wired (honest)
+}
+
+/** What a caller raises (no eventId/ts — the transport stamps those, D8). */
+export interface RatingFunnelEventInput {
+    type: RatingFunnelEventType;
+    sessionId?: string;
+    userId?: string; // null => server flags invalidReason='missing_user'
+    promptId?: string;
+    triggerId?: string;
+    variantId?: string;
+    stars?: number; // only on rating_selected
+    dims?: RatingFunnelEventDims;
+}
+
+/** Wire shape after the transport stamps the idempotency key + client clock. */
+export interface RatingFunnelEventUpload extends RatingFunnelEventInput {
+    eventId: string; // client UUID (D8 dedup)
+    ts: string; // ISO client clock
+}
+
+// ─── §P3-e Feedback attachments (screenshot + voice) ─────────────────────────
+
+export type EngageAttachmentKind = 'screenshot' | 'voice';
+
+/** Raw attachment captured on-device, before upload (carries bytes + dimensions). */
+export interface EngageAttachmentDraft {
+    kind: EngageAttachmentKind;
+    base64: string; // raw bytes, base64 (PUT direct to storage)
+    mime: string;
+    width?: number;
+    height?: number;
+    byteSize?: number;
+    durationMs?: number; // voice only; hard cap < 30000ms enforced upstream
+    masked?: boolean; // PII-masking active at capture
+    /** 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;
+}
+
+// ─── §2.5 Tracking-event upload (SDK → backend, in-app legs) ─────────────────
+
+export interface EngageEventUpload {
+    eventId: string; // client UUID -> dedup
+    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; // ISO
+    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'
+>;
+
+// ─── §2.2 Device-token registration (SDK → backend, push) ────────────────────
+
+export interface DeviceTokenRegistration {
+    schemaVersion: number;
+    deviceId: string;
+    pushToken: string;
+    platform: 'android' | 'ios'; // routing source of truth (D5)
+    /** Send-transport routing key: direct APNs (iOS) → 'apns'; Firebase → 'fcm'. */
+    pushProvider?: 'fcm' | 'apns';
+    tokenStatus?: 'active';
+    installationId?: string; // stable per-install id, survives token rotation
+    sdkVersion?: string;
+}
+
+/** Caller-supplied token input — `schemaVersion`/`tokenStatus` stamped by transport. */
+export interface DeviceTokenInput {
+    deviceId?: string; // defaults to the SDK device id when omitted
+    pushToken: string;
+    platform: 'android' | 'ios';
+    pushProvider?: 'fcm' | 'apns';
+    installationId?: string;
+    sdkVersion?: string;
+}
+
+// ─── Batched upload envelopes (mirror the existing ingestion lane shapes) ─────
+
+export interface EngageResponsesBatch {
+    schemaVersion: number;
+    responses: EngageResponse[];
+}
+
+export interface EngageEventsBatch {
+    schemaVersion: number;
+    events: EngageEventUpload[];
+}