@wireai/activation 0.15.0 → 0.16.0

package/AGENTS.md

@@ -32,7 +32,7 @@ Everything an integration needs lives on the ROOT import (`@wireai/activation`).
 subpaths are optional secondary feature modules; import one only if you use it.
 
 - `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the device-only event reporters (`reportClientEvent`, `makeSessionId`, `WIRE_ONBOARDING_EVENTS`, see "App events" below).
-- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`, `wireDoctor`. Except for `clearUserContext`, these are NOT root exports; importing them from the root does not compile. `clearUserContext` IS also a root export (`import { clearUserContext } from "@wireai/activation"`), which is the form the README teaches for the sign-out purge. `wireDoctor({ target, storage })` is the DEV-ONLY integration self-check: it resolves `{ok, checks:[{name, ok, detail}]}`, never throws, and posts one `dry_run` probe event so a broken integration is caught on the first run instead of in a funnel report. It is dev-gated on `__DEV__` (a release build makes no network call), it reports the apiKey's SHAPE and never its value, and its verdict is read from the ack body, never from the status code. See the README "Verify your integration" section.
+- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`, `wireDoctor`. Except for `clearUserContext`, these are NOT root exports; importing them from the root does not compile. `clearUserContext` IS also a root export (`import { clearUserContext } from "@wireai/activation"`), which is the form the README teaches for the sign-out purge. `wireDoctor({ target, storage, join })` is the DEV-ONLY integration self-check: it resolves `{ok, checks:[{name, ok, detail}]}`, never throws, and posts one `dry_run` probe event so a broken integration is caught on the first run instead of in a funnel report. It is dev-gated on `__DEV__` (a release build makes no network call), it reports the apiKey's SHAPE and never its value, and its verdict is read from the ack body, never from the status code. **Read the scope of a green report.** The five checks are `target`, `reachability`, `storage`, `round_trip`, `join_key`. `join_key` needs the `join: { appId, userContext, autoJoinKey }` argument, the same values you pass `<WireOnboarding>` (and OMITTING it fails the check rather than skipping it, because a report that never looked at the join has not earned a green). It is strictly read-only: it mints no key, writes no identity registry and persists nothing. None of the five checks that the lifecycle hook is mounted, and none checks `min_sessions`, so an integration that skipped step 8 reports all-green while its `activated` funnel stays permanently at zero. A green doctor means "events reach the server and can be joined", not "the funnel works". See the README "Verify your integration" section.
 - `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
 - `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
 - `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`, `useReviewGate`, `fetchReviewDecision`).
@@ -44,7 +44,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 - `WireOnboarding`: the component (props below).
 - `DemoOnboarding`: dev/QA modal trigger to run the flow on demand (no account, re-runnable; place in a `__DEV__` Settings row). Props: `config` (or `null`), `theme`, `illustrations`, `label?`, `onComplete?`, `renderTrigger?`.
 - `wireConfigFromEnv({ appId })`: build `config` from `EXPO_PUBLIC_WIREAI_*` env; returns `null` if keys missing (use as your gate).
-- `isOnboardingEnabled({ remote? })`: the standard entry gate (transport present: `apiKey` + `serverUrl`, plus an optional host-passed kill switch).
+- `isOnboardingEnabled({ remote?, config? })`: the standard entry gate (transport present: `apiKey` + `serverUrl`, plus an optional host-passed kill switch). `config` forwards `WireConfigOverrides` (a programmatic apiKey/serverUrl) to the transport-present check; usually omitted.
 - `themeFromBrand({ primary })`: derive a full theme from one brand color.
 - `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
 - `defaultIllustrations`: dependency-free fallback art; spread your own over it.
@@ -52,8 +52,8 @@ subpaths are optional secondary feature modules; import one only if you use it.
 - `createRevenueCatBridge({ analytics, entitlementId })`: the RevenueCat purchase funnel (see "RevenueCat" below).
 - `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Every `<WireOnboarding>` needs it (see step 7).
 - `resolveAutoDeviceKey({ appId, storage })`: the kit's own per-install `device_key`, read synchronously. Use it for a stamp on an ordinary event, never as the cross-launch join key on `<WireOnboarding>` (it cannot tell you whether the id persists, see the join-key section). `hydrateDeviceIdentity({ appId, storage })` is the awaited, durability-reporting sibling.
-- `useLifecycleEvents(config, options)`: the app-root lifecycle hook (see step 8). `useSessionStart` / `reportSessionStart` are the counter-owning alternatives.
-- Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
+- `useLifecycleEvents(lifecycleConfig, options)`: the app-root lifecycle hook (see step 8). `useSessionStart` / `reportSessionStart` are the counter-owning alternatives.
+- Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`, `WireOnboardingStorage` (the AsyncStorage-compatible subset the `storage` prop takes), `LifecycleConfig` (the first argument of `useLifecycleEvents`, step 8). Both of the last two are exported and you need them to type the props documented above; the review/questionnaire gates take a DIFFERENT, synchronous storage (`CoachmarkStorage`, from `@wireai/activation/coachmarks`).
 
 ## `<WireOnboarding>` props
 
@@ -88,7 +88,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `apiKey` | `string` | yes | Tenant key (`wai_…`); resolves the app server-side. Get it from the getwireai console / `register_<app>.py`. |
+| `apiKey` | `string` | yes | Tenant key (`wai_…`); resolves the app server-side. Get it from the console: sign up at https://getwireai.com/signup (app name + email, then confirm by email and set a password, which is the step that actually creates the app and its key), then copy it from that app's Integrate tab. |
 | `serverUrl` | `string` | yes | Base server URL; the kit appends `/a2a`. |
 | `appId` | `string` | yes | Passed as the A2A `model` (informational; the key resolves the app). |
 | `metadata` | `Record<string, unknown>` | no | Merged into every A2A request (e.g. install attribution). The kit reserves `sessionId` + `supportedComponents`; do not override them. |
@@ -106,22 +106,92 @@ FACADE (`createAnalytics` and friends) is a different surface and lives on `@wir
 
 ## Integration steps (ordered)
 
-1. **Tenant key**: create the app in the getwireai console (or run `register_<app>.py`) → `wai_…` key + server URL. Nothing renders without both.
-2. **Install**: `npm install @wireai/activation wireai-rn` (react + react-native are peers). A tarball or `git+ssh://…` works for pre-publish/pinned builds.
+1. **Tenant key**: get BOTH the `wai_…` key and the server URL from the console. Sign up at https://getwireai.com/signup (app name + email; the confirmation link is where you choose a password, and that one step creates your first app and its key and lands you in the console already signed in), then open that app's **Integrate** tab (`https://getwireai.com/console/<app-id>/integrate`): the key is a copy field, and the server URL is the `serverUrl` line of the init snippet on that same tab. (⚠️ the tab's **Add MCP** dialog also shows a copy field called "Server URL"; that one is the MCP endpoint on a different host, not this value.) The key stays readable there on every visit. Sign back in later at https://getwireai.com/login; register FURTHER apps at https://getwireai.com/console/register. Nothing renders without both. A key's label IS its environment (dev / prod / staging / custom), so use a different key in dev than in prod; the tab's **Keys and environments** section lists them and can revoke one, but issuing a new key is not self-serve yet, so ask support for an extra environment.
+2. **Install**: `npm install @wireai/activation wireai-rn zod react-native-safe-area-context` (react + react-native are peers). A tarball or `git+ssh://…` works for pre-publish/pinned builds.
 3. **Metro**: `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` (from `@wireai/activation/metro`); pins one React/RN/wireai-rn/zod copy.
 4. **Config**: set `EXPO_PUBLIC_WIREAI_API_KEY` / `_SERVER_URL` / `_APP_ID`; build via `wireConfigFromEnv({ appId })`.
 5. **Fonts**: host must load the font families named in `theme.fonts.regular/medium/bold` (e.g. `expo-font`), else text falls back to system font.
 6. **Theme**: `themeFromBrand({ primary })` or a full `Partial<OnboardingTheme>`; for dark/light, pick the theme by the app's theme state.
 7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate. Pass the join key: `userContext={activationJoinContext(deviceKey)}`, or, when the app owns no device id, pass a working `storage` and leave `userContext` alone so the kit injects its own (never hand-build it from `resolveAutoDeviceKey`, see the join-key section). Skipping both leaves the `activated` funnel permanently empty and reports no error.
-8. **Lifecycle (do not skip)**: mount `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` ONCE at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id that `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. That last part needs storage that actually persists: since 0.14.0 an adapter that throws or rejects is treated exactly like no storage, so the events fire with no auto key rather than a per-launch one that corrupts the count. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and since 0.14.0 `useSessionStart` follows the same auto-key rule.
+8. **Lifecycle (do not skip)**: mount `useLifecycleEvents({ serverUrl, apiKey, appId, storage }, { deviceKey, sessionCount, userId })` ONCE at the app root, before anything else touches analytics. Its first argument is a `LifecycleConfig`, not the `WireOnboardingConfig` from step 4: pass the fields explicitly (`wireConfigFromEnv` returns `null` when the env is unset, and `storage` is not a config field). It is the only path that emits `app.first_open`, it registers the per-open session id that `createAnalytics` / `wire.track` / the gates all correlate to, and with a `storage` adapter in that first argument it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. That last part needs storage that actually persists: since 0.14.0 an adapter that throws or rejects is treated exactly like no storage, so the events fire with no auto key rather than a per-launch one that corrupts the count. `sessionCount` in the second argument is YOURS to own: a counter you persist and increment once per app open, starting at 1 on the first launch. A hardcoded `1` compiles, ships, and pins every user at `returning: false` forever, silently. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and since 0.14.0 `useSessionStart` follows the same auto-key rule.
 9. **Gate**: wrap behind a flag (env for dev, remote config for prod) **AND** `config != null`; fall through to existing onboarding when off/unconfigured. Decide who sees it (e.g. new signups only) in host nav logic.
 
 ## Review firing (do not hand-roll the decision fetch)
 
 If you gate the review prompt on the server, call **`fetchReviewDecision(target, { deviceKey })`**
-from `@wireai/activation/reviews` and pass the result to `useReviewGate({ config, decision })`.
-`config` is REQUIRED (the hook reads `config.id`); `decision` alone does not compile. Never
-write your own fetch.
+from `@wireai/activation/reviews` and pass the result to `useReviewGate`. Three things are
+mandatory here and **every one of them fails silently** when you get it wrong: the code compiles
+or runs, and the prompt simply never appears (or never stops appearing).
+
+**1. The gate needs SYNCHRONOUS storage.** `useReviewGate` counts app opens through a
+`CoachmarkStorage`, whose `getItem(key)` returns `string | null`, **not** a Promise. Pass it as the
+hook's `storage` option, or mount `CoachmarkProvider` with one above the gate. This is a DIFFERENT
+shape from `<WireOnboarding storage>`, which takes the AsyncStorage-style adapter. With no sync
+storage, the kit's own source states the outcome: "No storage pins the counter at 1 forever, so the
+fail-closed `minSessions` rule can never be met and the gate silently never fires"
+(`src/reviews/runtime.ts`). Handing it an **async** adapter reaches the same dead end by another
+route: the kit probes the adapter, sees the thenable, and substitutes a fail-closed store rather
+than feed Promises to the counter. Both cases warn once under `__DEV__` and are invisible in a
+release build. `minSessions` defaults to 2, so there is no version of this you can ignore.
+
+**2. `config` is the GATE's config, not the kit transport config.** It needs an `id`. Handing over
+`wireConfigFromEnv(...)`'s value does not compile (`Property 'id' is missing in type
+'WireOnboardingConfig'`). Write `useReviewGate({ config: { id: "post_win" }, decision: decision ?? undefined, storage: gateStorage })`.
+
+**3. The `?? undefined` is not optional.** The fetch resolves `ReviewDecisionResponse | null` and
+the hook option is `decision?: ReviewDecision`, so handing the `null` straight over does not
+compile (`Type 'ReviewDecisionResponse | null' is not assignable to type 'ReviewDecision | undefined'`).
+
+### Wiring `<ReviewGate>`
+
+`<ReviewGate>` has **no `gate` prop**, so the obvious first attempt (handing the controller
+straight to the component) does not compile. The connection is the controller `useReviewGate`
+returns: render on `visible`, and hand `markShown` / `markResolved` to `onShown` / `onResolved`.
+That last pair is load-bearing and is the easiest thing in this package to leave out. They are what
+writes the cooldown timestamp and the once-per-version seen gate.
+Omit them and it compiles, the prompt shows, and it re-prompts the same user on every single open.
+
+```tsx
+import { useEffect, useState } from "react";
+import { useWireActivation } from "@wireai/activation";
+import type { CoachmarkStorage } from "@wireai/activation/coachmarks";
+import { ReviewGate, fetchReviewDecision, useReviewGate } from "@wireai/activation/reviews";
+import type { ReviewDecisionResponse } from "@wireai/activation/reviews";
+
+// SYNCHRONOUS by contract: getItem returns the value, never a Promise. MMKV, a memory map, or
+// any store you can read without awaiting. AsyncStorage is NOT this shape.
+const gateStorage: CoachmarkStorage = {
+  getItem: (key) => mmkv.getString(key) ?? null,
+  setItem: (key, value) => mmkv.set(key, value),
+};
+
+export function HomeScreen() {
+  // `track` comes off the same hook; call `await track("journal_done")` at your action site and it
+  // bumps `revalidation`, which re-runs the fetch below so the gate can fire off that action.
+  const { revalidation } = useWireActivation({ serverUrl, apiKey, appId, deviceKey });
+  const [served, setServed] = useState<ReviewDecisionResponse | null>(null);
+
+  useEffect(() => {
+    void fetchReviewDecision({ serverUrl, apiKey }, { deviceKey }).then(setServed);
+  }, [revalidation]);
+
+  const gate = useReviewGate({
+    config: { id: "post_win", minSessions: 2, appVersion },
+    decision: served ?? undefined,
+    storage: gateStorage,
+  });
+
+  return gate.visible ? (
+    <ReviewGate
+      appName="My App"
+      target={{ serverUrl, apiKey }}
+      meta={{ device_key: deviceKey, firing_arm: served?.arm }}
+      onShown={gate.markShown}
+      onResolved={gate.markResolved}
+    />
+  ) : null;
+}
+```
 
 - It returns the FULL `{ fire, reason, arm }` on 2xx, and `null` ONLY when the server is
   unreachable / non-2xx / sends bad JSON. It never throws.
@@ -130,8 +200,10 @@ write your own fetch.
   this and prompted a real user for a review 3 minutes into their first session (1 star).
 - `sessionId` is OPTIONAL: the gate usually lives on the home feed, where there is no onboarding
   session. `deviceKey` is the identity that matters. Pass `sessionId` only when you have one.
-- Running a firing experiment? Echo the returned `arm` back as `meta.firing_arm` on the review
-  submission so per-arm attribution survives a reweighting.
+- Running a firing experiment? Echo the `arm` **from `fetchReviewDecision`'s response** back as
+  `meta.firing_arm` on the review submission, so per-arm attribution survives a reweighting. Read
+  it off the fetched `ReviewDecisionResponse`, not off `gate.decision`: the controller's `decision`
+  is the resolved `ReviewDecision` (`{ fire, reason }`) and carries no `arm`.
 - **Fire the gate off an in-app action.** `useWireActivation({ serverUrl, apiKey, deviceKey })`
   (ROOT export) returns `{ track, sessionId, revalidation }`. `await track(name, meta?)` POSTs an
   `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps
@@ -140,6 +212,7 @@ write your own fetch.
   `createWireActivation(config)`. This is the kit-owned replacement for hand-rolling
   session-id + await-POST + revalidate.
 
+
 ## RevenueCat (the purchase funnel)
 
 The app sells subscriptions through `react-native-purchases`? Wire the paywall to the same event
@@ -185,9 +258,10 @@ import { activationJoinContext } from "@wireai/activation";
 // The app owns a device id: pass it.
 <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
 
-// The app owns none: pass `storage` and leave `userContext` alone. The kit injects the same id the
-// analytics side stamps, after awaiting the storage read AND confirming the id actually persists.
-<WireOnboarding config={{ ...config, storage }} ... />
+// The app owns none: pass `storage` (a PROP of <WireOnboarding>, never a field of the config) and
+// leave `userContext` alone. The kit injects the same id the analytics side stamps, after awaiting
+// the storage read AND confirming the id actually persists.
+<WireOnboarding config={config} storage={storage} ... />
 ```
 
 ⛔ Do NOT hand-build that key with `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`.
@@ -200,7 +274,8 @@ should do the same rather than the sync call.
 Always pass `storage`. Without it the id is per-LAUNCH, not per-install, and a per-launch key makes
 every open look like a new device, which breaks `min_sessions` and A/B arm stickiness as surely as
 no key breaks the join. The same rule governs the lifecycle wiring: `useLifecycleEvents` falls back
-to this id for `app.session_started` / `app.first_open` ONLY when `config.storage` is present.
+to this id for `app.session_started` / `app.first_open` ONLY when its own first argument carries a
+`storage` adapter.
 
 ## Gotchas (do not miss)
 
@@ -212,6 +287,6 @@ to this id for `app.session_started` / `app.first_open` ONLY when `config.storag
 
 ## Fastest path
 
-Run the **`wire-rn-integration`** Claude skill. It performs all the steps above
-automatically (detect conventions → register tenant → install → Metro → theme →
-scaffold screen → wire navigation + fallback → typecheck).
+Paste [`INTEGRATION_PROMPT.md`](./INTEGRATION_PROMPT.md) into your coding agent. It ships in this
+package and drives the same steps end to end (detect conventions → register tenant → install →
+Metro → theme → scaffold screen → wire navigation + fallback → typecheck).