@wireai/activation 0.1.0

package/dist/reviews/index.d.ts

@@ -0,0 +1,213 @@
+import React__default from 'react';
+import { R as ReviewGateProps, b as ReviewPresentation, U as UseReviewGateOptions, c as ReviewGateController, d as ReviewDecision, f as ReviewStoreConfig, g as ReviewTarget, h as ReviewSubmission } from '../decision-CFvGY6nP.js';
+export { G as GateRules, a as GateSignals, i as RatingRoute, j as ReviewConfig, k as ReviewGateEvent, l as ReviewGateEventName, m as buildReviewSubmission, n as decideReview, e as evaluateGate, r as resolveRules, o as routeRating } from '../decision-CFvGY6nP.js';
+export { C as ReviewModal, a as ReviewModalHandle, b as ReviewModalProps } from '../CenteredModal-Cdgns6--.js';
+import { c as OnboardingFonts } from '../types-BKfpdZzX.js';
+import '../types-GL_hQ0TN.js';
+import '../types-CMuOexw0.js';
+
+/**
+ * Runtime helpers for the review gate: the `wire_review_*` gate keys and small
+ * typed storage accessors. The gate reuses the SAME injected sync storage + global
+ * testing flag as the coachmark engine (see coachmarks/runtime), so a host that
+ * mounted CoachmarkProvider gets review gating for free — no second storage to wire.
+ */
+
+/** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
+declare const reviewSeenKey: (id: string, version?: string) => string;
+/** Last-shown timestamp key (epoch ms), for the cooldown rule. */
+declare const reviewLastShownKey: (id: string) => string;
+/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+declare const reviewSessionsKey: (id: string) => string;
+
+/**
+ * ReviewGate — the in-app review sentiment gate UI.
+ *
+ * A NEUTRAL prompt ("Enjoying <app>?") over five tappable stars. The honest split:
+ *   • 5 stars → the native store review (expo-store-review when available, else the
+ *     configured store URL). Fires `store_review_requested`.
+ *   • 1-4 stars → a feather-light feedback form: TWO optional inputs, the "why this
+ *     rating" opinion box (~4 lines) and a smaller "what can you suggest" box, POSTed
+ *     to the Wire server (`feedback_text` + `suggestion`). The rating is the only
+ *     mandatory action, so Send works with either box, both, or neither. Warm
+ *     thank-you state, never a dead end.
+ *
+ * The form NEVER asks for identity (no name / email / contact field): the host already
+ * identifies the user via `sessionId` + `meta` (e.g. user_id, device_key), which is all
+ * the POST body carries alongside the rating and the free text.
+ *
+ * Every visual value comes from the OnboardingTheme (useOnboardingTheme). Analytics are
+ * callback-based (mirroring the coachmark convention): the host wires `onEvent` to its own
+ * analytics. No PII in events — feedback text goes ONLY in the POST body.
+ *
+ * Store-policy: `requestReview` is quota'd and never guaranteed to show; it is called ONLY
+ * on the 5-star path, never from a "rate us 5 stars" button. See the README notes.
+ */
+
+declare const ReviewGate: React__default.FC<ReviewGateProps>;
+
+/**
+ * centeredModalMotion - the pure entrance spec for the content-agnostic CenteredModal shell.
+ *
+ * WHY split out: the shell UI (CenteredModal) is RN and cannot run under the kit's node:test
+ * runner, but the entrance math is pure and worth pinning. Keep the animation spec here so both
+ * the component and the tests read one source, and so any module (reviews, questionnaire) can
+ * reuse the shell without depending on another feature module.
+ *
+ * The centered popup uses RN's built-in `Animated` (native driver), the same idiom as
+ * CompletionView/CardHandoff, so the shell stays dependency-free (no reanimated).
+ *
+ * NOTE: `reviews/presentation.ts` re-exports these under their original names
+ * (`REVIEW_MODAL_ANIM`, `entranceFrame`) for back-compat with the reviews public API.
+ */
+/**
+ * The entrance spec for the centered popup. Values chosen to match the boilerplate's
+ * `animated-modal` feel (a springy zoom-in) with the kit's own native-driver idiom:
+ *   • backdrop fades 0 -> `backdropOpacity`
+ *   • card springs from `scaleFrom` -> 1 and fades 0 -> 1
+ */
+declare const CENTERED_MODAL_ANIM: {
+    /** Spring config for the card scale/opacity entrance (mirrors CompletionView's pop). */
+    readonly enterSpring: {
+        readonly friction: 7;
+        readonly tension: 80;
+    };
+    /** Exit timing in ms (fade + shrink back out before unmount). */
+    readonly exitMs: 160;
+    /** Card scale at rest (progress 0); grows to 1 at progress 1. */
+    readonly scaleFrom: 0.9;
+    /** Peak dim of the backdrop at progress 1. */
+    readonly backdropOpacity: 0.55;
+};
+/** A single frame of the entrance, for a progress value in [0..1] (clamped). Pure, testable. */
+declare const centeredModalFrame: (progress: number, backdropMax?: number) => {
+    cardOpacity: number;
+    cardScale: number;
+    backdropOpacity: number;
+};
+
+/**
+ * presentation.ts — the pure presentation + entrance-animation logic for the review gate.
+ *
+ * WHY split out: the gate UI (ReviewGate/ReviewModal) is RN and can't run under the kit's
+ * node:test runner, but the presentation DEFAULT and the entrance math are pure and worth
+ * pinning. Keep the animation spec here so both the component and the tests read one source.
+ *
+ * The centered popup uses RN's built-in `Animated` (native driver) — the same idiom as
+ * CompletionView/CardHandoff — so the reviews module stays dependency-free (no reanimated).
+ */
+
+/** Centered popup by default (Malik's ruling: the bottom-anchored inline card read as wrong). */
+declare const DEFAULT_PRESENTATION: ReviewPresentation;
+/** Resolve the presentation prop → the effective mode. Absent → the centered modal. */
+declare const resolvePresentation: (p?: ReviewPresentation) => ReviewPresentation;
+
+declare const useReviewGate: ({ config: configProp, decision: decisionProp, events, storage, isTesting, features, featuresConfig, }: UseReviewGateOptions) => ReviewGateController;
+
+/**
+ * equality.ts — tiny, dependency-free value-equality helpers used to STABILIZE
+ * references across renders.
+ *
+ * WHY this exists: real integrators pass inline objects — `config={{ id: 'x' }}`,
+ * `decision={{ fire: true }}` — whose IDENTITY changes every render even though
+ * their VALUES do not. If the review hook let those unstable references flow into
+ * a `useMemo`/`useEffect` dependency list (or handed a fresh verdict object back
+ * every render), a host that depends on the returned value would re-run its own
+ * effect forever → "Maximum update depth exceeded". A library must tolerate inline
+ * props without looping; these helpers are how the hook holds a stable reference
+ * whenever the underlying values are unchanged.
+ *
+ * Pure (no React import) so it runs under the kit's node:test runner.
+ */
+
+/**
+ * One-level value-equality of two plain objects (or primitives). Same-reference is
+ * equal; two objects are equal when they have the same keys and each value is
+ * `Object.is`-equal. Good enough for the flat `config` / `decision` shapes the gate
+ * accepts (all leaf values are primitives).
+ */
+declare const shallowEqual: (a: unknown, b: unknown) => boolean;
+/**
+ * Structural equality of two review verdicts by their contract fields (`fire`,
+ * `reason`). A `null`/`undefined` verdict equals only another absent one. Used to
+ * decide whether the hook can keep returning the SAME verdict object (so a host
+ * that lists `controller.decision` in an effect dep array never loops).
+ */
+declare const sameDecision: (a?: ReviewDecision | null, b?: ReviewDecision | null) => boolean;
+
+/**
+ * feedbackForm — pure sizing helpers for the 1–4★ feedback form, kept out of the
+ * React component so the "≈4 lines tall, capped at 5" rule is verifiable in
+ * isolation (the reviews module's correctness lives in these pure functions, the
+ * same convention as `decision.ts` / `presentation.ts`).
+ *
+ * Malik's ask: the feedback field should be a multiline box "around 3 to 5 lines"
+ * tall, not a single-line input. We size it from the theme's body line-height so
+ * it scales with the app's font config.
+ */
+
+/** Lines the box shows at rest, and the cap it can grow to. */
+declare const FEEDBACK_MIN_LINES = 4;
+declare const FEEDBACK_MAX_LINES = 5;
+interface FeedbackInputHeights {
+    /** Resting height — the box opens at ~4 lines so it reads as "write a few words". */
+    minHeight: number;
+    /** Growth cap — it never balloons past ~5 lines; scroll takes over beyond that. */
+    maxHeight: number;
+}
+/**
+ * Derive the multiline feedback box's min/max height from the theme's body
+ * line-height. `minHeight = MIN_LINES × lineHeight`, capped at
+ * `MAX_LINES × lineHeight`, plus the field's vertical padding (top + bottom) so
+ * the requested number of text lines is actually visible inside the padding.
+ */
+declare const feedbackInputHeights: (fonts: OnboardingFonts, verticalPadding?: number) => FeedbackInputHeights;
+
+/** The store deep-link for the current platform, or null if none is configured. */
+declare const storeUrl: (store: ReviewStoreConfig | undefined) => string | null;
+/** Open the configured store listing. Best-effort; resolves false if there was nothing to open. */
+declare const openStoreListing: (store: ReviewStoreConfig | undefined) => Promise<boolean>;
+/**
+ * Request the native in-app review when the optional peer is available; otherwise open the
+ * store listing. Returns the path taken so the caller can fire the right analytics.
+ */
+declare const requestStoreReview: (store?: ReviewStoreConfig) => Promise<"native" | "store_url" | "none">;
+
+/**
+ * transport.ts — kit → Wire server requests for the review module, all fire-and-forget
+ * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
+ * thin fetch wrapper, Bearer tenant key, swallow every error.
+ *
+ *   • submitReview        → POST {serverUrl}/v1/reviews   (the 1-4 feedback body)
+ *   • reportAppEvent      → POST {serverUrl}/v1/events    (generic app.* namespace)
+ *
+ * `reportAppEvent` is the strategic extension: it lets a host report arbitrary in-app
+ * events through the SAME transport (stored server-side as event_type='app_event',
+ * question_key=<name>), which is what the backend review-firing rules evaluate on — and
+ * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
+ */
+
+/**
+ * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
+ * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ */
+declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => void;
+/** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
+interface ReportAppEventOptions {
+    /** The onboarding/session id to correlate with, when known. */
+    sessionId?: string;
+    /** A stable, non-PII device id — the review-decision endpoint reads it for min-sessions. */
+    deviceKey?: string;
+    /** Small non-PII extras. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Report a generic in-app event through the existing events transport. Stored server-side
+ * as `event_type='app_event'`, `question_key=<name>`. Fire-and-forget. Keep `name` a short
+ * stable identifier and `meta` small + non-PII.
+ *
+ *   reportAppEvent(target, "content_share", { sessionId, deviceKey });
+ */
+declare const reportAppEvent: (target: ReviewTarget | undefined, name: string, options?: ReportAppEventOptions) => void;
+
+export { DEFAULT_PRESENTATION, FEEDBACK_MAX_LINES, FEEDBACK_MIN_LINES, type FeedbackInputHeights, CENTERED_MODAL_ANIM as REVIEW_MODAL_ANIM, type ReportAppEventOptions, ReviewDecision, ReviewGate, ReviewGateController, ReviewGateProps, ReviewPresentation, ReviewStoreConfig, ReviewSubmission, ReviewTarget, UseReviewGateOptions, centeredModalFrame as entranceFrame, feedbackInputHeights, openStoreListing, reportAppEvent, requestStoreReview, resolvePresentation, reviewLastShownKey, reviewSeenKey, reviewSessionsKey, sameDecision, shallowEqual, storeUrl, submitReview, useReviewGate };