@wireai/activation 0.1.0

package/src/questionnaire/index.ts

@@ -0,0 +1,54 @@
+/**
+ * wireai-onboarding/questionnaire - the skippable pre-onboarding questionnaire popup.
+ *
+ * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free. The gate
+ * asks one mandatory question ("what do you think about the app") plus two optional boxes,
+ * POSTs the answers to the Wire server, and decides WHEN to show via local rules OR a
+ * server-provided decision (the AI seam), gated by the `questionnaire` master switch and shown
+ * at most once per user per questionnaire id. It reuses the shared `CenteredModal` shell (never
+ * importing reviews/ internals for UI).
+ *
+ *   import { QuestionnaireGate, useQuestionnaireGate } from "wireai-onboarding/questionnaire";
+ */
+
+// ─── The popup UI ───────────────────────────────────────────────────────────────
+export { QuestionnaireGate } from "./QuestionnaireGate";
+
+// ─── The WHEN decision (local rules + the server-decision override) ─────────────
+export { useQuestionnaireGate } from "./useQuestionnaireGate";
+
+// ─── The AI seam + pure gate logic (verifiable in isolation) ────────────────────
+export {
+  decideQuestionnaire,
+  evaluateGate,
+  resolveRules,
+  buildQuestionnaireSubmission,
+} from "./decision";
+export type { GateSignals, GateRules } from "./decision";
+
+// ─── Server transport: submit a response + best-effort fetch the decision ───────
+export { submitQuestionnaireResponse, fetchQuestionnaireDecision } from "./transport";
+export type { FetchQuestionnaireDecisionOptions } from "./transport";
+
+// ─── Gate-key helpers (shared coachmark storage singleton) ──────────────────────
+export {
+  questionnaireSeenKey,
+  questionnaireLastShownKey,
+  questionnaireSessionsKey,
+} from "./runtime";
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+export type {
+  QuestionnaireDecision,
+  QuestionnaireDefinition,
+  QuestionnaireAnswers,
+  QuestionnaireMeta,
+  QuestionnaireSubmission,
+  QuestionnaireDecisionResponse,
+  QuestionnaireTarget,
+  QuestionnaireGateProps,
+  QuestionnaireGateEvent,
+  QuestionnaireGateEventName,
+  UseQuestionnaireGateOptions,
+  QuestionnaireGateController,
+} from "./types";

package/src/questionnaire/runtime.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime helpers for the questionnaire gate: the `wire_questionnaire_*` gate keys. The
+ * gate reuses the SAME injected sync storage + global testing flag as the coachmark engine
+ * (via `resolveStorage`/`readInt`/`writeInt`, re-exported from the reviews runtime), so a
+ * host that mounted CoachmarkProvider gets questionnaire gating for free - no second storage
+ * to wire. Once-per-user is keyed on the questionnaire `id`.
+ */
+export { resolveStorage, readInt, writeInt } from "../reviews/runtime";
+
+/** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
+export const questionnaireSeenKey = (id: string, version?: string): string =>
+  version ? `wire_questionnaire_${id}_${version}_seen` : `wire_questionnaire_${id}_seen`;
+
+/** Last-shown timestamp key (epoch ms), for the cooldown rule. */
+export const questionnaireLastShownKey = (id: string): string =>
+  `wire_questionnaire_${id}_last`;
+
+/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+export const questionnaireSessionsKey = (id: string): string =>
+  `wire_questionnaire_${id}_sessions`;

package/src/questionnaire/transport.ts

@@ -0,0 +1,83 @@
+/**
+ * transport.ts - kit → Wire server requests for the questionnaire module, all fire-and-forget
+ * (a pre-onboarding questionnaire must NEVER break the app). Mirrors `submitReview`: a thin
+ * fetch wrapper, Bearer tenant key, swallow every error.
+ *
+ *   • submitQuestionnaireResponse → POST {serverUrl}/v1/questionnaires/{id}/responses
+ *   • fetchQuestionnaireDecision  → GET  {serverUrl}/v1/questionnaires/decision  (best-effort)
+ *
+ * The decision fetch is HARD fail-open on the "never show" side: an unreachable endpoint, a
+ * non-2xx (incl. 404), a missing `fetch`, or bad JSON all resolve to null, so a host wiring
+ * pure server-directed firing simply shows nothing - exactly the reviews decision seam.
+ */
+import type {
+  QuestionnaireDecisionResponse,
+  QuestionnaireSubmission,
+  QuestionnaireTarget,
+} from "./types";
+
+/**
+ * POST a questionnaire response. Fire-and-forget: a missing target, a missing id, a build
+ * error, a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ */
+export const submitQuestionnaireResponse = (
+  target: QuestionnaireTarget | undefined,
+  id: string,
+  submission: QuestionnaireSubmission,
+): void => {
+  if (!target?.serverUrl || !id) return;
+  try {
+    const base = target.serverUrl.replace(/\/$/, "");
+    const url = `${base}/v1/questionnaires/${encodeURIComponent(id)}/responses`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(submission),
+    }).catch(() => {
+      /* best-effort, swallow */
+    });
+  } catch {
+    /* URL/JSON/missing-fetch - swallow */
+  }
+};
+
+/** Options for the best-effort decision fetch. `deviceKey` groups a device's sessions server-side. */
+export interface FetchQuestionnaireDecisionOptions {
+  /** The onboarding/session id to correlate with, when known. */
+  sessionId?: string;
+  /** A stable, non-PII device id - the decision endpoint reads it for min-sessions. */
+  deviceKey?: string;
+}
+
+/**
+ * Best-effort fetch of the server firing decision. Returns the parsed
+ * `{ fire, reason, questionnaire }` on a 2xx, else null. NEVER throws - any failure resolves
+ * to null (fail-safe: the host shows nothing). The kit does not call this internally; a host
+ * that wants server-directed firing awaits it and passes the result to `useQuestionnaireGate`
+ * (the same AI seam the reviews gate uses).
+ */
+export const fetchQuestionnaireDecision = async (
+  target: QuestionnaireTarget | undefined,
+  options: FetchQuestionnaireDecisionOptions = {},
+): Promise<QuestionnaireDecisionResponse | 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/questionnaires/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 QuestionnaireDecisionResponse | null;
+    return json ?? null;
+  } catch {
+    /* unreachable / non-2xx / bad JSON / missing-fetch - never show */
+    return null;
+  }
+};

package/src/questionnaire/types.ts

@@ -0,0 +1,182 @@
+/**
+ * Shared types for the questionnaire module (the skippable pre-onboarding popup).
+ *
+ * The gate asks a short set of questions in a centered popup: ONE mandatory free-text
+ * "what do you think about the app" (the opinion), plus two OPTIONAL boxes ("help us
+ * improve" + "suggestions"). WHEN the gate shows is decided by local rules OR a
+ * server-provided decision (the AI seam), gated by the `questionnaire` master switch and
+ * shown at most once per user per questionnaire `id`. Dependency-free type surface.
+ */
+import type { CoachmarkStorage } from "../coachmarks/types";
+import type { WireFeatures, WireFeaturesConfig } from "../features/types";
+
+/**
+ * The firing verdict - the SAME contract on both sides of the seam. `decideQuestionnaire`
+ * turns local rules into one of these; a server `{fire, reason}` (from
+ * GET /v1/questionnaires/decision) is the exact same shape and OVERRIDES the local one.
+ */
+export interface QuestionnaireDecision {
+  fire: boolean;
+  reason?: string;
+}
+
+/**
+ * The questionnaire the kit renders. Comes from the server decision (`questionnaire`
+ * field) or a local literal. `id` is required (the once-gate + keys derive from it); the
+ * labels and title are optional (sensible defaults render when absent). The optional
+ * firing-rule fields are the LOCAL fallback the decision hook evaluates when no server
+ * decision is passed, mirroring `ReviewConfig`.
+ */
+export interface QuestionnaireDefinition {
+  /** Gate key. Seen/last-shown/session keys derive from it (`wire_questionnaire_<id>_*`). */
+  id: string;
+  /** Popup heading. Defaults to a neutral prompt when absent. */
+  title?: string;
+  /** Label for the MANDATORY opinion box ("what do you think about the app"). */
+  opinion_label?: string;
+  /** Label for the first OPTIONAL box ("help us improve"). */
+  improve_label?: string;
+  /** Label for the second OPTIONAL box ("suggestions"). */
+  suggestions_label?: string;
+
+  // ── Local fallback firing rules (used only when no server decision is passed) ──
+  /** 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 user's three answers. `opinion` is the only mandatory one. */
+export interface QuestionnaireAnswers {
+  /** The mandatory "what do you think about the app" free text. */
+  opinion: string;
+  /** The optional "help us improve" free text. */
+  improve?: string;
+  /** The optional "suggestions" free text. */
+  suggestions?: string;
+}
+
+/** Non-PII correlation extras sent with a submission (the `meta` bucket in the POST body). */
+export interface QuestionnaireMeta {
+  user_id?: string | null;
+  device_key?: string | null;
+  session_count?: number | null;
+}
+
+/**
+ * The POST body sent to `POST /v1/questionnaires/{id}/responses` (mirrors the server
+ * contract). `opinion` is always present; `improve`/`suggestions` are null when empty.
+ */
+export interface QuestionnaireSubmission {
+  session_id: string | null;
+  answers: {
+    opinion: string;
+    improve: string | null;
+    suggestions: string | null;
+  };
+  meta: QuestionnaireMeta;
+}
+
+/**
+ * The GET /v1/questionnaires/decision response. `fire` gates showing; `questionnaire` is
+ * the definition to render when firing. Hard fail-open on the transport: an unreachable
+ * endpoint or a 404 resolves to null so the host simply never shows the gate.
+ */
+export interface QuestionnaireDecisionResponse {
+  fire: boolean;
+  reason?: string;
+  questionnaire?: QuestionnaireDefinition | null;
+}
+
+/** The analytics moments, mirrored on the coachmark callback convention (no PII, no free text). */
+export type QuestionnaireGateEventName =
+  | "questionnaire_prompt_shown"
+  | "questionnaire_submitted"
+  | "questionnaire_dismissed";
+
+/** One analytics moment. Carries the gate id only; answers ride ONLY in the POST body. */
+export interface QuestionnaireGateEvent {
+  name: QuestionnaireGateEventName;
+  /** The gate id (`questionnaire.id`). */
+  id: string;
+}
+
+/** Where kit → server requests go (same tenant creds as the onboarding flow). */
+export interface QuestionnaireTarget {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`). */
+  serverUrl: string;
+  /** Tenant API key, sent as `Authorization: Bearer`. */
+  apiKey: string;
+}
+
+/** Props for the `QuestionnaireGate` popup component. */
+export interface QuestionnaireGateProps {
+  /** The questionnaire to render (title + labels + id). */
+  questionnaire: QuestionnaireDefinition;
+  /** Where to POST the submission. Omit to skip the network (callbacks still fire). */
+  target?: QuestionnaireTarget;
+  /** The onboarding/session id correlated with the response, when known. */
+  sessionId?: string | null;
+  /** Small non-PII extras stored with the response (user_id, device_key, session_count). */
+  meta?: QuestionnaireMeta;
+  /** Fired at each analytics moment (host wires it to its own analytics). No PII. */
+  onEvent?: (event: QuestionnaireGateEvent) => void;
+  /** Called once the gate is resolved (submitted or dismissed). */
+  onResolved?: () => void;
+  /** Called when the gate first renders to the user (also fires `questionnaire_prompt_shown`). */
+  onShown?: () => void;
+  /** Partial theme merged over the active onboarding theme. */
+  theme?: Partial<import("../theme/types").OnboardingTheme>;
+  /** Show a Skip/Not now control. Default true (always skippable, never a dead end). */
+  dismissible?: boolean;
+}
+
+/** Options for `useQuestionnaireGate` - the WHEN decision. */
+export interface UseQuestionnaireGateOptions {
+  /** The questionnaire definition (id + local firing rules). */
+  config: QuestionnaireDefinition;
+  /** Server-provided decision (from GET /v1/questionnaires/decision). OVERRIDES local rules. */
+  decision?: QuestionnaireDecision;
+  /** 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 questionnaire MASTER switch. When
+   * `flags.questionnaire.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 the questionnaire stays on (fail-open).
+   */
+  features?: WireFeatures;
+  /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+  featuresConfig?: WireFeaturesConfig;
+}
+
+/** What `useQuestionnaireGate` returns. */
+export interface QuestionnaireGateController {
+  /** Whether the gate should be shown right now. */
+  visible: boolean;
+  /** The resolved verdict (local rules or the server override). For debugging/analytics. */
+  decision: QuestionnaireDecision;
+  /** Persist the last-shown timestamp. Call when the gate becomes visible. */
+  markShown: () => void;
+  /** Write the once-per-user seen gate. Call when the gate is resolved. */
+  markResolved: () => void;
+}

package/src/questionnaire/useQuestionnaireGate.ts

@@ -0,0 +1,159 @@
+/**
+ * useQuestionnaireGate - owns WHEN the questionnaire gate shows.
+ *
+ * v1 decision = local rules from `config` (enabled / minSessions / minEvents / cooldownDays
+ * / oncePerVersion), evaluated against the same injected sync storage as the coachmark
+ * engine (`wire_questionnaire_*` keys). The AI seam: pass a server-provided `decision` and it
+ * OVERRIDES the local rules (see decideQuestionnaire). The whole cost of being AI-ready is
+ * passing that object straight through - mirroring `useReviewGate` exactly.
+ *
+ * Fallback chain (matches the server design): (1) a server `decision` wins immediately;
+ * (2) no decision → after `timeoutFallbackMs` the local rules take over; (3) the once-gate
+ * (`wire_questionnaire_<id>_seen`) always applies locally, so a server bug can never re-spam
+ * the popup. The global `isTestingCoachmark` flag force-shows the gate for QA replay, and the
+ * `questionnaire` master switch (a disabled tenant) wins over everything.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { hasSeenGate, isCoachmarkTesting, markSeenGate } from "../coachmarks/runtime";
+import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { sameDecision, shallowEqual } from "../reviews/equality";
+import { decideQuestionnaire, evaluateGate, resolveRules } from "./decision";
+import {
+  questionnaireLastShownKey,
+  questionnaireSeenKey,
+  questionnaireSessionsKey,
+  readInt,
+  resolveStorage,
+  writeInt,
+} from "./runtime";
+import type {
+  QuestionnaireDecision,
+  QuestionnaireGateController,
+  UseQuestionnaireGateOptions,
+} from "./types";
+
+/**
+ * Hold a stable reference for a value while its CONTENT is unchanged. Integrators pass inline
+ * `config` / `decision` objects (idiomatic React) whose identity flips every render; feeding
+ * those straight into the deps below would recompute the verdict - and mint a fresh verdict
+ * object - on every render, which loops any host that lists the returned verdict in its own
+ * effect. Comparing by value here keeps the reference (and everything derived from it) stable.
+ */
+const useStableValue = <T,>(value: T, isEqual: (a: T, b: T) => boolean): T => {
+  const ref = useRef(value);
+  if (!isEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+};
+
+export const useQuestionnaireGate = ({
+  config: configProp,
+  decision: decisionProp,
+  events = 0,
+  storage,
+  isTesting,
+  features,
+  featuresConfig,
+}: UseQuestionnaireGateOptions): QuestionnaireGateController => {
+  // Tolerate inline-identity props: only adopt a new reference on a real value change.
+  const config = useStableValue(configProp, shallowEqual);
+  const decision = useStableValue(decisionProp, (a, b) => sameDecision(a, b));
+
+  // The questionnaire MASTER switch. Disabled → the gate never fires, composing as an extra
+  // AND over the local rules + the server decision seam below (fail-open: defaults to enabled).
+  const featureEnabled = useResolvedFeatures({ flags: features, config: featuresConfig })
+    .questionnaire.enabled;
+
+  const testing = isTesting ?? isCoachmarkTesting();
+  const seenKey = questionnaireSeenKey(
+    config.id,
+    config.oncePerVersion === false ? undefined : config.appVersion,
+  );
+  const lastKey = questionnaireLastShownKey(config.id);
+  const sessionsKey = questionnaireSessionsKey(config.id);
+
+  // Read (and bump) the session counter ONCE per mount: this mount is a new session.
+  const sessions = useState(() => {
+    const store = resolveStorage(storage);
+    const next = readInt(store, sessionsKey) + 1;
+    writeInt(store, sessionsKey, next);
+    return next;
+  })[0];
+
+  // Gate the local rules behind an optional client-side timeout, so a reachable server gets a
+  // window to answer first. A present `decision` bypasses the wait entirely.
+  const hasServerDecision = decision != null;
+  const timeoutMs = config.timeoutFallbackMs;
+  const waits = !hasServerDecision && timeoutMs != null && timeoutMs > 0;
+  const [elapsed, setElapsed] = useState(!waits);
+  useEffect(() => {
+    if (!waits) {
+      setElapsed(true);
+      return;
+    }
+    const timer = setTimeout(() => setElapsed(true), timeoutMs as number);
+    return () => clearTimeout(timer);
+  }, [waits, timeoutMs]);
+
+  const { visible, verdict } = useMemo(() => {
+    // Master kill switch wins over everything, including QA replay: a tenant that turned the
+    // questionnaire OFF must never see it, whatever the rules, the server decision, or testing say.
+    if (!featureEnabled)
+      return {
+        visible: false,
+        verdict: { fire: false, reason: "feature_disabled" } as QuestionnaireDecision,
+      };
+
+    // QA replay: force-show, bypassing rules + gates (safe: only via __DEV__ && bool).
+    if (testing)
+      return {
+        visible: true,
+        verdict: { fire: true, reason: "testing" } as QuestionnaireDecision,
+      };
+
+    const store = resolveStorage(storage);
+    const local = evaluateGate(resolveRules(config), {
+      sessions,
+      events,
+      lastShownAt: readInt(store, lastKey) || null,
+      seen: hasSeenGate(seenKey, storage, isTesting),
+      now: Date.now(),
+    });
+    const resolved = decideQuestionnaire(local, decision);
+    // (3) the once-gate always wins locally, even over a server "fire".
+    const alreadySeen = hasSeenGate(seenKey, storage, isTesting);
+    const ready = hasServerDecision || elapsed;
+    return { visible: ready && resolved.fire && !alreadySeen, verdict: resolved };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    featureEnabled,
+    testing,
+    config,
+    decision,
+    events,
+    sessions,
+    elapsed,
+    hasServerDecision,
+    seenKey,
+    lastKey,
+    storage,
+    isTesting,
+  ]);
+
+  // Stable callbacks + a stable controller object, so a host can safely list any of them in its
+  // own effect deps without the effect re-firing every render.
+  const shownRef = useRef(false);
+  const markShown = useCallback(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    writeInt(resolveStorage(storage), lastKey, Date.now());
+  }, [storage, lastKey]);
+  const markResolved = useCallback(() => {
+    markSeenGate(seenKey, storage, isTesting);
+  }, [seenKey, storage, isTesting]);
+
+  return useMemo<QuestionnaireGateController>(
+    () => ({ visible, decision: verdict, markShown, markResolved }),
+    [visible, verdict, markShown, markResolved],
+  );
+};