@wireai/activation 0.1.0

package/dist/decision-Cl8OFYzu.d.mts

@@ -0,0 +1,228 @@
+import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
+import { C as CoachmarkStorage } from './types-GL_hQ0TN.mjs';
+import { W as WireFeatures, a as WireFeaturesConfig } from './types-CMuOexw0.mjs';
+
+/**
+ * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
+ * turns local rules into one of these; a server `{fire, reason}` (from
+ * GET /v1/reviews/decision) is the exact same shape and OVERRIDES the local one.
+ */
+interface ReviewDecision {
+    fire: boolean;
+    reason?: string;
+}
+/** Where to route a rating: 5 stars → the store, 1-4 → the feedback form. */
+type RatingRoute = "store" | "feedback";
+/**
+ * Configurable store targets for the 5-star fallback path (used when the native
+ * `expo-store-review` peer is absent or unavailable). At least one is recommended.
+ */
+interface ReviewStoreConfig {
+    /** Apple App Store numeric app id → itms-apps review deep link. */
+    iosAppId?: string;
+    /** Android package name → market:// details link. */
+    androidPackage?: string;
+    /** An explicit fallback URL (used when the platform-specific target is absent). */
+    storeUrl?: string;
+}
+/** Local firing rules — v1 of the decision, overridden by a server decision when present. */
+interface ReviewConfig {
+    /** Gate key. Seen/last-shown/session keys derive from it (`wire_review_<id>_*`). */
+    id: string;
+    /** Master local switch. Default true. */
+    enabled?: boolean;
+    /** Require at least this many sessions on the device before showing. Default 0. */
+    minSessions?: number;
+    /** Require at least this many tracked app events before showing. Default 0. */
+    minEvents?: number;
+    /** Suppress a re-prompt within this many days of the last shown. Default 0 (off). */
+    cooldownDays?: number;
+    /** Show at most once per app version (seen-gate keyed by `appVersion`). Default true. */
+    oncePerVersion?: boolean;
+    /** The current app version, for the once-per-version seen gate. */
+    appVersion?: string;
+    /**
+     * Client fallback ONLY: if no server decision arrives within this many ms of mount,
+     * fall back to the local rules. Null/absent → evaluate local rules immediately.
+     */
+    timeoutFallbackMs?: number | null;
+}
+/** The four analytics moments, mirrored on the coachmark callback convention (no PII). */
+type ReviewGateEventName = "review_prompt_shown" | "review_rating_selected" | "store_review_requested" | "review_feedback_submitted";
+/** One analytics moment. `stars` is present on `review_rating_selected`; never any free text. */
+interface ReviewGateEvent {
+    name: ReviewGateEventName;
+    /** The gate id (`config.id`). */
+    id: string;
+    /** The chosen rating, on `review_rating_selected`. */
+    stars?: number;
+}
+/** The POST body sent to `POST /v1/reviews` (mirrors the server `CreateReviewRequest`). */
+interface ReviewSubmission {
+    stars: number;
+    /** The optional "why this rating" answer (the free-text opinion box). */
+    feedback_text?: string;
+    /** The optional "what can you suggest" answer (the smaller suggestion box). */
+    suggestion?: string;
+    contact?: string;
+    session_id?: string;
+    source?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * How the prompt is presented:
+ *   • "modal"  (default) — a centered popup: dimmed backdrop, card in the middle of the
+ *     screen, spring/fade entrance. What Malik asked for after the bottom-anchored inline
+ *     card rendered half-hidden.
+ *   • "inline" — the bare card, positioned by wherever the host mounts it (the legacy path).
+ */
+type ReviewPresentation = "modal" | "inline";
+/** Where kit → server requests go (same tenant creds as the onboarding flow). */
+interface ReviewTarget {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`). */
+    serverUrl: string;
+    /** Tenant API key, sent as `Authorization: Bearer`. */
+    apiKey: string;
+}
+/** Props for the `ReviewGate` sentiment-gate component. */
+interface ReviewGateProps {
+    /** App name, woven into the neutral prompt ("Enjoying <app>?"). */
+    appName?: string;
+    /** Store targets for the 5-star fallback path when the native peer is unavailable. */
+    store?: ReviewStoreConfig;
+    /** Where to POST a 1-4 feedback submission. Omit to skip the network (callbacks still fire). */
+    target?: ReviewTarget;
+    /** The onboarding/session id correlated with the review, when known. */
+    sessionId?: string;
+    /** Small non-PII extras stored with the review (e.g. device_key, app_version). */
+    meta?: Record<string, unknown>;
+    /** Fired at each analytics moment (host wires it to its own analytics). No PII. */
+    onEvent?: (event: ReviewGateEvent) => void;
+    /** Called once the gate is resolved (rated + routed, or dismissed). */
+    onResolved?: () => void;
+    /** Called when the gate first renders to the user (also fires `review_prompt_shown`). */
+    onShown?: () => void;
+    /** Partial theme merged over the active onboarding theme. */
+    theme?: Partial<OnboardingTheme>;
+    /** Show a Skip/Not now control. Default true (never a dead end). */
+    dismissible?: boolean;
+    /**
+     * How the prompt renders. Default "modal" — a centered popup over a dimmed backdrop with
+     * a spring/fade entrance. Pass "inline" for the legacy host-positioned bare card.
+     */
+    presentation?: ReviewPresentation;
+    /** The gate id, forwarded onto emitted events. */
+    id?: string;
+}
+/** Options for `useReviewGate` — the WHEN decision. */
+interface UseReviewGateOptions {
+    config: ReviewConfig;
+    /** Server-provided decision (from GET /v1/reviews/decision). OVERRIDES local rules. */
+    decision?: ReviewDecision;
+    /** Current tracked app-event count (host-owned), for the `minEvents` rule. */
+    events?: number;
+    /** Sync gate storage. Defaults to the storage injected by CoachmarkProvider. */
+    storage?: CoachmarkStorage | null;
+    /** Testing override; defaults to the global `isTestingCoachmark` flag. */
+    isTesting?: boolean;
+    /**
+     * OPTIONAL feature-flag wiring — the review MASTER switch. When `flags.review.enabled` is false,
+     * the gate NEVER fires (`visible` stays false, verdict reason `feature_disabled`), whatever the
+     * local rules or a server decision say — it composes as an extra AND on top of the decision seam.
+     * Provide pre-resolved `features`, OR a `featuresConfig` to lazily fetch once, OR mount a
+     * `WireFeaturesProvider` above (context is read automatically). Omit all three and reviews stay
+     * on (fail-open), gated only by the existing rules.
+     */
+    features?: WireFeatures;
+    /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+    featuresConfig?: WireFeaturesConfig;
+}
+/** What `useReviewGate` returns. */
+interface ReviewGateController {
+    /** Whether the gate should be shown right now. */
+    visible: boolean;
+    /** The resolved verdict (local rules or the server override). For debugging/analytics. */
+    decision: ReviewDecision;
+    /** Persist the last-shown timestamp. Call when the gate becomes visible. */
+    markShown: () => void;
+    /** Write the once-per-version seen gate. Call when the gate is resolved. */
+    markResolved: () => void;
+}
+
+/**
+ * decision.ts — the pure decision logic for the review gate.
+ *
+ * `decideReview` is the AI seam, mirroring `selectTourSteps` exactly: ONE function that
+ * turns an optional injected decision into the live verdict. No injected decision → the
+ * local rules stand; a server decision present → it OVERRIDES them. Building the seam now
+ * is the whole cost of being AI-ready: today the host passes local rules only; later the
+ * Wire server computes `{fire, reason}` from the onboarding learnings and the host passes
+ * it straight in — zero app changes.
+ *
+ *   // v1 (local rules only)
+ *   const verdict = decideReview(evaluateGate(rules, signals));
+ *
+ *   // AI on (server-provided decision wins)
+ *   const verdict = decideReview(evaluateGate(rules, signals), serverDecision);
+ *
+ * `evaluateGate`, `routeRating`, and `buildReviewSubmission` are pure so the gate logic
+ * is verifiable in isolation (the kit has no test runner; correctness lives in these).
+ */
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides.
+ * Same contract philosophy as `selectTourSteps(catalog, selection?)`.
+ */
+declare const decideReview: (local: ReviewDecision, decision?: ReviewDecision) => ReviewDecision;
+/** The signals the local rules evaluate against (read from injected sync storage + host). */
+interface GateSignals {
+    /** Sessions observed on this device (incl. the current one). */
+    sessions: number;
+    /** Tracked app events observed (host-owned). */
+    events: number;
+    /** Epoch ms of the last time the gate was shown, or null if never. */
+    lastShownAt: number | null;
+    /** Whether the once-per-version gate is already satisfied. */
+    seen: boolean;
+    /** Current epoch ms (injected so the function stays pure). */
+    now: number;
+}
+/** The resolved local rules (defaults applied). */
+interface GateRules {
+    enabled: boolean;
+    minSessions: number;
+    minEvents: number;
+    cooldownDays: number;
+    oncePerVersion: boolean;
+}
+/** Fill a partial `ReviewConfig` with the rule defaults. */
+declare const resolveRules: (config: {
+    enabled?: boolean;
+    minSessions?: number;
+    minEvents?: number;
+    cooldownDays?: number;
+    oncePerVersion?: boolean;
+}) => GateRules;
+/**
+ * Deterministic v1 local decision. Order: disabled → once-gate → min-sessions →
+ * min-events → cooldown → fire. Reasons mirror the server evaluator's vocabulary.
+ */
+declare const evaluateGate: (rules: GateRules, s: GateSignals) => ReviewDecision;
+/**
+ * Route a rating. 5 stars → the native store review; 1-4 → the feedback form. The
+ * sentiment question itself is neutral — this is the ONLY place 5 is treated specially,
+ * never a button labeled "rate us 5 stars" (see the store-policy notes in the README).
+ */
+declare const routeRating: (stars: number) => RatingRoute;
+/** Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events. */
+declare const buildReviewSubmission: (input: {
+    stars: number;
+    feedbackText?: string;
+    suggestion?: string;
+    contact?: string;
+    sessionId?: string;
+    source?: string;
+    meta?: Record<string, unknown>;
+}) => ReviewSubmission;
+
+export { type GateRules as G, type ReviewGateProps as R, type UseReviewGateOptions as U, type GateSignals as a, type ReviewPresentation as b, type ReviewGateController as c, type ReviewDecision as d, evaluateGate as e, type ReviewStoreConfig as f, type ReviewTarget as g, type ReviewSubmission as h, type RatingRoute as i, type ReviewConfig as j, type ReviewGateEvent as k, type ReviewGateEventName as l, buildReviewSubmission as m, decideReview as n, routeRating as o, resolveRules as r };