@wireai/activation 0.8.0 → 0.9.1

package/src/reviews/transport.ts

@@ -3,15 +3,16 @@
  * (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)
+ *   • submitReview         → POST {serverUrl}/v1/reviews          (the review row)
+ *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
+ *   • 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.
  */
-import type { ReviewSubmission, ReviewTarget } from "./types";
+import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
 /**
  * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
@@ -38,6 +39,121 @@ export const submitReview = (
   }
 };
 
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
+export interface FetchReviewDecisionOptions {
+  /**
+   * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
+   * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
+   * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+   * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+   * this required here.)
+   */
+  sessionId?: string;
+  /**
+   * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+   * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+   * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+   * param the route does not declare.
+   */
+  deviceKey?: string;
+}
+
+/**
+ * Best-effort fetch of the SERVER's review firing decision. The mirror of
+ * `fetchQuestionnaireDecision`, and the primitive whose absence caused a live incident.
+ *
+ * ── WHY THIS LIVES IN THE KIT (Malik, 2026-07-16) ────────────────────────────────────────
+ *
+ * The questionnaire module has always had its decision fetch; reviews never did. So a host
+ * hand-rolled one, and got it subtly wrong: its helper collapsed an explicit `{fire:false}`
+ * into `undefined`. `decideReview` is `(local, decision) => decision ?? local`, so `undefined`
+ * means "the server has no opinion, use the local rules" — and the local timer fired. The
+ * server could therefore only ever turn review prompts ON, never OFF. A real user was asked to
+ * rate the app ~3 minutes into their FIRST session, having seen nothing yet, and left 1 star.
+ *
+ * The bug was not that the host was careless. It was that the kit made every host invent this.
+ * So the primitive moves here and hosts keep a thin call site.
+ *
+ * ── THE CONTRACT THAT MATTERS ────────────────────────────────────────────────────────────
+ *
+ *   • 2xx  → the FULL `{fire, reason, arm}`, INCLUDING `fire:false`. Never collapse a false
+ *            into null. That collapse IS the bug: a false must reach `decideReview` intact so
+ *            it can override the local rules and keep the gate shut.
+ *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
+ *            the one case where falling back to local rules is correct.
+ *
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
+ *
+ *   const decision = await fetchReviewDecision(target, { deviceKey });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
+ */
+export const fetchReviewDecision = async (
+  target: ReviewTarget | undefined,
+  options: FetchReviewDecisionOptions = {},
+): Promise<ReviewDecisionResponse | null> => {
+  if (!target?.serverUrl) return null;
+  try {
+    const base = target.serverUrl.replace(/\/$/, "");
+    const params = new URLSearchParams();
+    if (options.sessionId) params.set("session_id", options.sessionId);
+    if (options.deviceKey) params.set("device_key", options.deviceKey);
+    const qs = params.toString();
+    const url = `${base}/v1/reviews/decision${qs ? `?${qs}` : ""}`;
+    const headers: Record<string, string> = {};
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    const res = await fetch(url, { headers });
+    if (!res || !res.ok) return null;
+    const json = (await res.json()) as ReviewDecisionResponse | null;
+    // A body without a boolean `fire` is not a decision. Guard it explicitly rather than
+    // letting `{}` through as a truthy object that `decideReview` would treat as a verdict
+    // (`{}.fire === undefined` is falsy, so it would silently read as "never fire").
+    if (!json || typeof json.fire !== "boolean") return null;
+    return json;
+  } catch {
+    /* unreachable / non-2xx / bad JSON / missing-fetch → the server has no opinion */
+    return null;
+  }
+};
+
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 export interface ReportAppEventOptions {
   /** The onboarding/session id to correlate with, when known. */

package/src/reviews/types.ts

@@ -19,6 +19,19 @@ export interface ReviewDecision {
   reason?: string;
 }
 
+/**
+ * The `GET /v1/reviews/decision` response: `ReviewDecision` plus the additive `arm`.
+ *
+ * `arm` is the firing experiment's sticky assignment for this device/session. Echo it back in
+ * the submission's `meta.firing_arm` and the server keeps it verbatim (`_stamp_firing_arm`:
+ * "an arm the kit already echoed is left as-is"); omit it and the server recomputes from the
+ * sticky hash. Echoing is what makes per-arm attribution survive a later reweighting of the
+ * experiment, so a host running one should pass it through.
+ */
+export interface ReviewDecisionResponse extends ReviewDecision {
+  arm?: string | null;
+}
+
 /** Where to route a rating: 5 stars → the store, 1-4 → the feedback form. */
 export type RatingRoute = "store" | "feedback";
 

package/src/session/persistedSession.ts

@@ -39,7 +39,7 @@ export const DEFAULT_SESSION_TTL_MS = 3_600_000;
 /** Ceiling on the storage read — a hung adapter degrades to a fresh mint, never a stuck gate. */
 const READ_TIMEOUT_MS = 1_500;
 
-/** Storage key for an app's cached session, e.g. `wireai:session:myelino`. */
+/** Storage key for an app's cached session, e.g. `wireai:session:acme`. */
 export const sessionStorageKey = (appId: string): string => `wireai:session:${appId}`;
 
 type PersistedSession = { id: string; ts: number };

package/src/session-analytics/lifecycle.ts

@@ -44,7 +44,7 @@ import { reportSessionStart, SESSION_STARTED_EVENT } from "./reportSessionStart"
  *  {@link SESSION_STARTED_EVENT}; a trigger keys off this exact string. */
 export const FIRST_OPEN_EVENT = "app.first_open" as const;
 
-/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:acme`. Mirrors the
  *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
 export const firstOpenStorageKey = (appId: string): string => `wireai:first_open:${appId}`;
 

package/src/session-analytics/useSessionStart.ts

@@ -1,7 +1,7 @@
 /**
  * useSessionStart — the optional convenience hook that fires {@link reportSessionStart} for you.
  *
- * Two firing moments, mirroring the Myelino/Morrow session-counter semantics:
+ * Two firing moments, mirroring the reference apps' session-counter semantics:
  *   • ON MOUNT — the app opened (cold start or the provider first rendered).
  *   • ON FOREGROUND after a real background — when AppState returns to `active` having been
  *     backgrounded for at least {@link BACKGROUND_SESSION_MS} (30 min), that's a NEW open, so a
@@ -10,7 +10,7 @@
  * Each firing mints its OWN per-open `session_id` (held in a ref so a re-render never re-fires),
  * so grouping over time is by `deviceKey`/`userId`, never by session_id (see reportSessionStart).
  *
- * The hook is OPTIONAL. A host that already owns a session counter (Myelino/Morrow do) can skip
+ * The hook is OPTIONAL. A host that already owns a session counter (most hosts do) can skip
  * the hook and call `reportSessionStart(...)` directly from its own "app opened" path — BOTH
  * paths are first-class. This hook is the batteries-included option for a host that has none.
  *

package/src/showcase/FeatureShowcase.tsx

@@ -135,7 +135,7 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   // Calm the large image/hero panel. The package's `background.primary` is a
   // SINGLE key that fills the primary button, the intro highlight AND this hero
   // panel — painting it `accent` (correct for the button) also flooded the first
-  // slide with the app color (Malik, Myelino, 0.3.1). The package exposes a
+  // slide with the app color (0.3.1). The package exposes a
   // `background` render prop that REPLACES that panel fill outright, so we keep
   // the button accent (via `colors`) and paint the panel a calm surface + faint
   // accent tint here. See showcasePanelBackground.

package/src/showcase/showcaseColors.ts

@@ -63,7 +63,7 @@ export const showcaseColorsFromTheme = (
  * Opacity of the accent tint layered over the theme surface for the showcase's
  * image hero panel. Kept in a calm 8–12% band so the panel reads as a subtle
  * brand wash — a hint of the accent, never the full-bleed flood that `accent`
- * as a solid fill produced (the 0.3.1 → 0.3.2 bug Malik saw in Myelino).
+ * as a solid fill produced (the 0.3.1 → 0.3.2 bug seen in a host app).
  */
 export const SHOWCASE_PANEL_TINT_OPACITY = 0.1;
 

package/src/theme/mergeThemeOver.ts

@@ -0,0 +1,27 @@
+/**
+ * mergeThemeOver — merge a partial theme over an ARBITRARY base theme.
+ *
+ * Sibling of `mergeTheme` (defaultTheme.ts), which merges over the DEFAULT theme only.
+ * Gates need the other shape: a `theme` prop merged over whatever the host's active
+ * ThemeContext currently is. That helper was copy-pasted verbatim into ReviewGate and
+ * QuestionnaireGate; it lives here once instead, so a new theme section can never be
+ * added to one gate and forgotten in the other.
+ *
+ * Two levels deep, matching `mergeTheme`: the theme is intentionally shallow, so each
+ * known sub-object is merged and scalars overwrite.
+ */
+import type { OnboardingTheme } from "./types";
+
+export const mergeThemeOver = (
+  base: OnboardingTheme,
+  override?: Partial<OnboardingTheme>,
+): OnboardingTheme => {
+  if (!override) return base;
+  return {
+    colors: { ...base.colors, ...override.colors },
+    fonts: { ...base.fonts, ...override.fonts },
+    radius: { ...base.radius, ...override.radius },
+    spacing: { ...base.spacing, ...override.spacing },
+    button: { ...base.button, ...override.button },
+  };
+};

package/src/types.ts

@@ -108,6 +108,14 @@ export type WireOnboardingProps = {
    * via `illustration`; the kit slots the matching node (keeping itself dependency-free).
    */
   illustrations?: Record<string, import("react").ReactNode>;
+  /**
+   * App-supplied ICON nodes, keyed by the semantic vocabulary name the AI emits (e.g.
+   * `{ instagram: <BrandIg/> }`). Checked FIRST, so a host can override any icon with its own
+   * brand mark, supply icons without installing `@expo/vector-icons`, or extend the vocabulary
+   * with names of its own. Anything not listed falls back to `@expo/vector-icons` when that
+   * optional peer is present, and to no icon at all when it isn't — never a crash.
+   */
+  icons?: Record<string, import("react").ReactNode>;
   /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
   validators?: Record<string, StepValidator>;
   /** Fired once the flow reaches its terminal StatusCard. */

package/dist/transport-BeO_Brcu.d.mts

@@ -1,40 +0,0 @@
-import { j as ReviewTarget, i as ReviewSubmission } from './types-A6pTxIZV.mjs';
-
-/**
- * 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 { type ReportAppEventOptions as R, reportAppEvent as r, submitReview as s };

package/dist/transport-DLpd1v5_.d.ts

@@ -1,40 +0,0 @@
-import { j as ReviewTarget, i as ReviewSubmission } from './types-BhpXJGlg.js';
-
-/**
- * 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 { type ReportAppEventOptions as R, reportAppEvent as r, submitReview as s };