@wireai/activation 0.10.0 → 0.12.0

package/AGENTS.md

@@ -50,6 +50,8 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 - `themeFromBrand({ primary })`: derive a full theme from one brand color.
 - `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
 - `defaultIllustrations`: dependency-free fallback art; spread your own over 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. Read the RevenueCat section before you use it.
 - Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
 
 ## `<WireOnboarding>` props
@@ -131,6 +133,55 @@ 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
+stream as onboarding. The kit does NOT depend on `react-native-purchases` (it is a native module and
+the kit never forces a rebuild); the adapter types the RevenueCat objects structurally, so you pass
+the real ones you already have.
+
+```tsx
+import { createAnalytics, createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+
+revenuecat.paywallShown(offering, { source: variant });
+revenuecat.checkoutStarted(pkg, { source: variant });
+const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+revenuecat.purchaseFailed(error, pkg, { source: variant });
+revenuecat.purchasesRestored(customerInfo);
+revenuecat.syncPlanTier(customerInfo);   // at launch, writes plan_tier with no event
+```
+
+Canonical names (they are also the `question_key` strings a firing trigger matches on):
+`wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`, `wire_purchase_failed`,
+`wire_purchase_restored`.
+
+**The join key is `user_context.device_key`, never `session_id`.** An onboarding session id is the
+A2A `contextId` and an app-event session id is the per-open id; the two live in separate spaces on
+purpose, so intersecting them returns nothing. Put the SAME device key on both sides: the analytics
+and activation surfaces auto-mint and stamp it on every event, and onboarding gets it from
+`<WireOnboarding userContext={activationJoinContext(deviceKey)} ... />`. Never hand-write
+`userContext={{ deviceKey }}`, because the server's device lookup reads `device_key` and a
+misspelled bucket produces an empty funnel instead of an error.
+
+**If the host owns no device id, read the kit's.** Do not leave the onboarding side blank.
+`resolveAutoDeviceKey({ appId, storage })` returns the exact id `createAnalytics` /
+`createWireActivation` auto-mint and persist for this install, so both halves of the join agree:
+
+```tsx
+import { resolveAutoDeviceKey, activationJoinContext } from "@wireai/activation";
+
+const deviceKey = resolveAutoDeviceKey({ appId, storage });   // the SAME id the analytics side stamps
+<WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+```
+
+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.
+
 ## Gotchas (do not miss)
 
 - **EAS / cloud builds:** install via **git URL or registry**, never a local `file:` path *outside the app repo* (EAS won't resolve it).

package/CHANGELOG.md

@@ -3,7 +3,117 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
-## [Unreleased]
+## [0.12.0] — 2026-07-27
+
+The release Myelino 2.2.0 pins. Ships the RevenueCat path (#52), the identity/counting audit,
+the session-id fallback contract, and the transport/config fixes behind a silently dead lifecycle
+stream (a consumer's `first_open` read 6 all-time while the emitting code was deployed).
+
+### Added
+
+- **RevenueCat path (`createRevenueCatBridge`).** The purchase funnel is now a first-class, documented
+  path instead of glue every consumer writes itself. New ROOT exports: `createRevenueCatBridge`,
+  `WIRE_PURCHASE_EVENTS` (`wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`,
+  `wire_purchase_failed`, `wire_purchase_restored`), the pure mappers (`activeEntitlement`,
+  `resolvePlanTier`, `describePackage`, `describeEntitlement`, `isUserCancelled`, `describeFailure`),
+  `PLAN_TIER_CONTEXT_KEY`, and the structural RevenueCat types. The bridge reports through the
+  `createAnalytics` or `createWireActivation` instance the host already holds (a compile-time check in
+  `revenueCatBridge.ts` keeps both assignable), writes `plan_tier` (paid / trial / free) to the bound
+  user context, drops the store's localized error `message` and keeps only the stable RevenueCat
+  `code`, and reports a store-confirmed purchase that granted no entitlement as
+  `wire_purchase_failed` with `reason: "not_entitled"` rather than swallowing it. **No new dependency:
+  `react-native-purchases` is a native module and is never imported**, so the RevenueCat objects are
+  typed structurally and the host passes its real ones.
+- **`activationJoinContext(deviceKey)`.** The `userContext` value that joins an onboarding session to
+  the app's later events. The join key is `user_context.device_key` and NEVER `session_id`: an
+  onboarding session id is the A2A `contextId`, an app-event session id is the per-open id, and
+  intersecting the two id spaces returns zero rows every time. This helper exists so the wire spelling
+  (`device_key`) is decided in one place; a hand-written `userContext={{ deviceKey }}` builds a bucket
+  the server's device lookup does not read, which produces a silently empty funnel rather than an
+  error. `src/revenuecat/joinKey.test.ts` locks both sides against each other.
+- **One shared auto `device_key` per install.** `createAnalytics` and `createWireActivation` each
+  minted their OWN id and raced a storage read, so a host building both (the documented wiring)
+  stamped two different `device_key`s on one install — splitting the key that `min_sessions`, A/B arm
+  stickiness and the purchase-to-onboarding join all read. Now ONE id lives in a `globalThis` slot
+  keyed by `Symbol.for(...)` (the `currentSession` pattern). `useLifecycleEvents` now stamps the
+  shared key on lifecycle events too (storage-gated, so a per-launch id never corrupts the counter),
+  and `resolveAutoDeviceKey` is exported from the root and `./analytics` barrels.
+
+### Fixed
+
+- **Every event carries a `session_id`, or the server eats it.** `POST /v1/events` validates per
+  event inside a try/except that counts the failure as "skipped" and returns HTTP 200 anyway, so an
+  event without a session id was accepted by the wire and discarded. `ensureCurrentSessionId()`
+  returns the registered per-open id when there is one and otherwise mints one, REGISTERS it so later
+  events join the same session, and warns once per process in `__DEV__` (mount `useLifecycleEvents`
+  at the app root). Closes the `reportAppEvent(target, "screen", { deviceKey })` hole and
+  `wire.track()`'s refusal to send without a registered open.
+- **`config.sessionId` on `createAnalytics` now warns in dev.** Passing it pins EVERY event from the
+  instance to that one frozen id and opts out of the live per-open session — the exact footgun that
+  flatlined a consumer's lifecycle metrics. The JSDoc and README now state the freeze semantics
+  honestly; omitting it is the correct default.
+- **The persistent transport paths read the `/v1/events` ACK body.** A 200 was never a receipt: the
+  server reports discarded events only as `skipped` in the body. The event queue and
+  `reportSessionStart` now warn in dev with the skipped count. Log-only — retry/dequeue semantics
+  unchanged.
+- **`user_context.app_version` falls back to `detectAppVersion()`** when the host passes nothing, so
+  version attribution on the facade path no longer depends on the host forwarding its own version.
+
+## [0.11.0] — 2026-07-21
+
+Architecture-audit fixes (#50/#51). One BEHAVIOR CHANGE, called out below.
+
+### Changed (BEHAVIOR) — review gate no longer fires on the first session
+
+- **`ReviewConfig.minSessions` now defaults to `2` (was `0`).** An unconfigured host with no server
+  decision used to fire the review prompt on the FIRST mount (`resolveRules` defaulted the floor to
+  0, so `local_rules_met` was immediate). That is the shape of the 2026-07-16 incident where a
+  first-session user got prompted and left 1 star. The local floor is now 2, so the client rules
+  need a second session before they can fire. A server `decision` (from `fetchReviewDecision`) still
+  overrides everything, and a host that genuinely wants first-session prompting sets
+  `minSessions: 1` (or `0`) explicitly.
+
+### Added
+
+- **Logout / reset.** `analytics.reset()` on the `createAnalytics` surface unbinds the user
+  (clears the in-memory `boundUserId`, strips `userId` / `userEmail` / `extra` from the bound
+  `WireUserContext`, keeps the non-PII `device_key`, and removes the persisted
+  `wireai:analytics:userId:<appId>` key). New top-level **`clearUserContext({ storage, appId })`**
+  covers the `createWireActivation` / `wire` path (recreate the instance without the user's context
+  after calling it). Fixes shared-device attribution of user B's events to user A. Also exported:
+  `clearPiiFromContext`, `analyticsUserIdStorageKey`.
+- **Email-shape guard on `identify`.** `identify(id)` and `setUserContext({ userId })` now refuse to
+  bind an email-shaped id (a raw email in the opaque `user_id` is a PII leak, it belongs in
+  `userContext.userEmail`) and warn in dev. Opt out with `allowEmailAsUserId: true` on
+  `createAnalytics`. New exported helper `looksLikeEmail`. Non-breaking.
+- **Client event timestamp.** `ClientEvent` gains an optional additive `ts`. The offline queue stamps
+  it at enqueue time so two byte-identical events fired seconds apart (a genuine repeat) are no
+  longer collapsed by the identical-JSON de-dup, while two same-instant re-enqueues still collapse.
+
+### Fixed
+
+- **`first_open` phantom session.** `useLifecycleEvents` now mints ONE per-open `session_id` on mount
+  and hands it to BOTH `app.first_open` and `app.session_started`, so `first_open` no longer carries
+  a session id the server never saw a `session_started` for (which the server back-filled into a
+  phantom session, inflating session counts). A later foreground open still mints its own fresh id.
+- **Questionnaire decision guard.** `fetchQuestionnaireDecision` now returns `null` for a body
+  without a boolean `fire` (mirrors `fetchReviewDecision`), instead of letting `{}` through as a
+  truthy "decision" whose `fire === undefined` reads as a silent "never fire".
+
+### Internal
+
+- **Unified the `/v1/events` POST builders.** `buildEventsRequest` (in `reportClientEvent.ts`) is now
+  exported and is the ONE description of the events endpoint (url + headers + body). The offline
+  queue (`postBatch`, keeping its abort-timeout), `reportAppEvent` (reviews transport), and the
+  lifecycle direct-POST fallback all route through it instead of hand-rolling the request.
+- **Docs truth pass.** New README "Rich user context & PII" section (raw `userEmail` by default +
+  `hashEmail`, `reset` / `clearUserContext` on logout, the auto per-install `device_key` and its
+  store-declaration implications). The blanket "No PII / nothing identifies a device" claims are
+  scoped to the onboarding `userContext` prop + the `collectDeviceContext()` snapshot. `llms.txt`
+  now lists the `/analytics`, `/reviews`, `/questionnaire` subpath surfaces.
+- Added the `session/sessionIdentity.integration.test.ts` dist-canary (PR #47/#48).
+
+## [0.10.0] - 2026-07-20
 
 ### Added: `wire.track` + `useWireActivation` (fire a gate off an in-app action)
 

package/INTEGRATION_PROMPT.md

@@ -53,7 +53,19 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    `useQuestionnaireGate` the same way), and at the action site call `await track("journal_done")`.
    Do NOT hand-roll the session id or the POST; `wire.track` owns both and revalidates the gate on
    a successful 2xx.
-9. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+9. RevenueCat (only if my app sells subscriptions through `react-native-purchases`): wire my paywall
+   to the same event stream with `createRevenueCatBridge({ analytics, entitlementId: "<my
+   entitlement, e.g. pro>" })` from `@wireai/activation`. Do NOT add or import
+   `react-native-purchases` in the kit path; the adapter types the RevenueCat objects structurally,
+   so pass my real `PurchasesOffering` / `PurchasesPackage` / `CustomerInfo` straight in. Replace my
+   hand-rolled paywall analytics calls with `paywallShown` / `checkoutStarted` / `purchaseCompleted`
+   / `purchaseFailed` / `purchasesRestored`, and call `syncPlanTier(customerInfo)` once at launch.
+   THE JOIN KEY: pass the SAME device key to the analytics instance AND to onboarding via
+   `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`, because purchases join to
+   onboarding on `user_context.device_key` and never on `session_id` (those are separate id spaces
+   and intersecting them returns zero rows). If my app has no single stable device key yet, say so
+   instead of inventing one.
+10. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -246,7 +246,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `storage` | `WireOnboardingStorage` | Host-injected storage (AsyncStorage-compatible `getItem/setItem/removeItem`) for **session-id persistence**: an app KILL mid-onboarding resumes the SAME backend session instead of minting a new one, so the funnel's `started` count stays honest (no phantom drops). Pass AsyncStorage as-is, or a 3-line MMKV wrapper. Omit for the previous per-mount behavior. Persists the kit's own correlation seed only — answers stay the host's job via `onComplete`. |
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
-| `userContext` | `Record<string, string \| number \| boolean>` | Host-injected, non-PII context the app already knows (signup method, referral, plan, a HASHED user id). Forwarded on session metadata + client events for funnel segmentation. **No PII** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). |
+| `userContext` | `Record<string, string \| number \| boolean>` | Host-injected, non-PII context the app already knows (signup method, referral, plan, a HASHED user id). Forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
 ## Helpers (the reusable substrate)
@@ -274,7 +274,7 @@ You rarely hand-roll config, gating, analytics, or attribution — the kit ships
 Two optional, host-injected inputs let onboarding analytics segment the funnel by device and by what your app already knows about the user. The kit collects the device snapshot itself (no dependency added); everything else you pass.
 
 - **`config.appVersion`** (string): your app version, e.g. `Constants.expoConfig?.version`. The kit reads nothing to get it, so it stays dependency-free; you inject it.
-- **`userContext`** (`Record<string, string | number | boolean>`): non-PII context the app already has, like signup method, referral source, plan tier, or a hashed user id. Same host-injection idea as `storage`. Do not put raw emails, names, or phone numbers here; pass a hash if you need a user key. Values are primitives only, and the server caps key count/size and drops deep nesting.
+- **`userContext`** (`Record<string, string | number | boolean>`): non-PII context the app already has, like signup method, referral source, plan tier, or a hashed user id. Same host-injection idea as `storage`. Do not put raw emails, names, or phone numbers here; pass a hash if you need a user key. Values are primitives only, and the server caps key count/size and drops deep nesting. This is the **onboarding** prop specifically. The analytics/activation surface takes a richer object with an opt-in raw email field; see [Rich user context & PII](#rich-user-context--pii).
 
 Both ride the A2A session-start metadata AND every client event (`dropped`, `client_fallback`). Old servers ignore the extra fields, so it is backward compatible.
 
@@ -296,7 +296,9 @@ Only React Native built-ins and the standard `Intl` global, each read defensivel
 
 ### No tracking (privacy-label-neutral)
 
-No advertising IDs (no IDFA/GAID), no `getUniqueId`, no fingerprinting APIs. Nothing here identifies a user or device uniquely, so adopting it does not change your App Privacy or Data Safety declarations, and it adds zero dependencies. On the backend the server derives a coarse country from the sent locale/timezone only, and never processes or stores IP addresses.
+No advertising IDs (no IDFA/GAID), no `getUniqueId`, no fingerprinting APIs. **The `collectDeviceContext()` snapshot described in this section** carries no unique identifier, so adopting it alone does not change your App Privacy or Data Safety declarations, and it adds zero dependencies. On the backend the server derives a coarse country from the sent locale/timezone only, and never processes or stores IP addresses.
+
+> ⚠️ **The analytics façade is different.** `createAnalytics` / `useWireActivation` auto-mint a stable, persisted, per-install `device_key` (a first-party correlation id, the privacy category of a first-party cookie) that rides on every event. It is not a hardware id and cannot be joined across apps, but it IS a per-install identifier, so if you adopt that surface, declare it accordingly. See [Rich user context & PII](#rich-user-context--pii).
 
 ## User identity
 
@@ -339,7 +341,52 @@ await identifyOnboarding({ config, userId: newUser.id, contextId: contextIdRef.c
 
 If you passed `storage` to `<WireOnboarding>`, you can omit `contextId` and hand `identifyOnboarding` the same `storage` (plus `appId` or `persistKey`) and it recovers the persisted session id itself. That works while the session is still persisted (before completion clears it), so the captured-`contextId` path above is the safe one post-completion. `identifyOnboarding` is fire-and-forget and never throws; it resolves `true` when it dispatched an `identify` and `false` when it could not (no user id, no server url, or no resolvable session).
 
-**No PII.** `userId` is length-bound only; the kit cannot detect an email for you. Keep it opaque, the same rule as `userContext`.
+**No PII.** The onboarding `userId` prop is length-bound only; the kit cannot detect an email for you. Keep it opaque, the same rule as the onboarding `userContext` prop.
+
+## Rich user context & PII
+
+The onboarding props above are non-PII by contract. The **analytics and activation surfaces** (`createAnalytics(...)` / `useAnalytics`, `createWireActivation(...)` / `useWireActivation`) take a richer `WireUserContext` object that CAN carry PII, so it needs its own privacy rules. Three things to know:
+
+**1. `userEmail` sends a RAW email by default.** `WireUserContext.userEmail` lands in its own `user_context.user_email` field (never mixed into the opaque `userId`). It is opt-in: the kit never auto-collects it, and you pass it only with the user's consent (for EU users, treat it as personal data). By default it is sent **as-is**. For a non-reversible form, set `hashEmail: true` and the kit folds it with a dependency-free hash and stamps `user_context.user_email_hashed: true`. For a cryptographic digest, hash it host-side (e.g. SHA-256 via `expo-crypto`) and pass the digest as `userEmail` with `hashEmail` falsy.
+
+```tsx
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId });
+analytics.setUserContext({ userId: user.id, userEmail: user.email, hashEmail: true }); // opt-in, folded
+```
+
+**Email-shape guard.** `identify(id)` (and `setUserContext({ userId })`) refuse to bind an id that looks like an email and warn in dev, because a raw email in the opaque `user_id` is a PII leak, it belongs in `userEmail`. If your internal user id genuinely IS an email, set `allowEmailAsUserId: true` on `createAnalytics` to opt out of the guard.
+
+**2. Clear the user on logout.** On a shared device, a persisted user binding would attribute user B's events to user A. Two ways to clear it:
+
+- Hold the analytics instance: call **`analytics.reset()`**. It unbinds the in-memory user, strips the PII fields (`userId`, `userEmail`, `extra`) from the bound context, and removes the persisted `wireai:analytics:userId:<appId>` key. The non-PII `device_key` is kept (it groups a device, not a user).
+- The `wire` / `createWireActivation` path captures its config immutably, so call the standalone **`clearUserContext({ storage, appId })`** to purge the persisted binding, and RECREATE the instance without the user's `userContext` so no further events carry their identity.
+
+```tsx
+import { clearUserContext } from "@wireai/activation";
+// on sign-out:
+analytics.reset();                          // if you hold the analytics instance
+await clearUserContext({ storage, appId }); // the wire/activation path (then recreate without PII)
+```
+
+**3. The auto `device_key` is a per-install identifier.** When you supply no `deviceKey`, the analytics and activation surfaces auto-mint a stable per-install `device_key`, persist it via `storage` (`wireai:analytics:deviceKey:<appId>`), and stamp it on every event so the server's review/questionnaire gating and A/B stickiness work out of the box. It carries no hardware id, no IDFA/GAID, and cannot be joined across apps (the privacy category of a first-party cookie), but it IS a persistent per-install id. If you adopt these surfaces, declare it in your App Privacy / Data Safety accordingly. Supply your own `deviceKey` to override it.
+
+### Do not pass `sessionId` to `createAnalytics`
+
+`CreateAnalyticsConfig.sessionId` is an opt-out knob, not a default. Set it and **every** event that
+instance sends (including `identify`) is pinned to that one frozen id, and the instance stops
+following the live per-open session the kit registers from `app.session_started` (see
+[Session mapping](#session-mapping-know-when-a-user-opens-the-app-again)). Lifecycle analytics then
+collapse onto a single device-scoped id: one "first open" for the life of the install, however many
+times the user comes back. The kit warns about it in dev builds.
+
+```tsx
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId });  // ✅ follows each app-open
+const analytics = createAnalytics({ serverUrl, apiKey, sessionId: myId }); // ⚠️ frozen for good
+```
+
+Omit it. Pass one only if your host runs its own session lifecycle and owns the id the server should
+correlate on. This is a different field from the per-open `sessionId` that `useWireActivation` and
+`reportAppEvent` READ (that one is the live id, and reading it is always fine).
 
 ## Session mapping (know when a user opens the app again)
 
@@ -936,6 +983,61 @@ If you are outside React (a service, a saga), `createWireActivation(config)` is
 factory. It returns `{ track, sessionId, subscribeRevalidation, getRevalidationVersion }`: the
 same `track`, plus the raw pub/sub the hook wraps for you.
 
+## RevenueCat (the purchase funnel)
+
+If you sell subscriptions with [RevenueCat](https://www.revenuecat.com/), the paywall is the other end of the funnel onboarding starts. `createRevenueCatBridge` wires the two together: one constructor, then your existing paywall call sites.
+
+The kit does **not** depend on `react-native-purchases`, and it never will. That package is a native module, and the kit's whole promise is that it never puts a native rebuild in your way. So the adapter types the RevenueCat objects structurally instead, which means you hand it the real `CustomerInfo` / `PurchasesPackage` / `PurchasesOffering` you already have. Nothing new gets installed.
+
+```tsx
+import { createAnalytics, createRevenueCatBridge } from "@wireai/activation";
+
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+```
+
+Then five call sites, all fire-and-forget, none of which can throw at your paywall:
+
+```tsx
+revenuecat.paywallShown(offering, { source: variant });        // offering_id + packages_count
+revenuecat.checkoutStarted(pkg, { source: variant });          // package, product, price, currency
+
+const { customerInfo } = await Purchases.purchasePackage(pkg);
+if (revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant })) navigateOn();
+
+revenuecat.purchaseFailed(error, pkg, { source: variant });    // reason: "cancelled" | "error"
+revenuecat.purchasesRestored(await Purchases.restorePurchases());
+revenuecat.syncPlanTier(await Purchases.getCustomerInfo());    // at launch, no event
+```
+
+**The names are canonical**, the same way `WIRE_ONBOARDING_EVENTS` standardizes the onboarding funnel: `wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`, `wire_purchase_failed`, `wire_purchase_restored`. They are `app_event` `question_key` values on the wire, so they are also the exact strings a review or questionnaire firing trigger matches on.
+
+**What the bridge decides for you.** The entitlement check lives in one place instead of being copy-pasted at the purchase site and the restore site. `plan_tier` (`paid` / `trial` / `free`) is written to the bound user context on every entitlement change, so the whole funnel can be sliced paid versus free. The store's error `message` is dropped and only the stable RevenueCat `code` rides the event, because that message is localized, unbounded, and occasionally names the account it failed for. And a purchase the store confirmed that granted **no** entitlement fires `wire_purchase_failed` with `reason: "not_entitled"` rather than returning quietly, which is the usual shape of a broken product-to-entitlement mapping.
+
+### The join key: `device_key`, never `session_id`
+
+A purchase event is worth nothing unless you can join it to the same user's onboarding. Get this wrong and you do not get a wrong number, you get a permanent zero, which is far harder to notice.
+
+`session_id` is not that key. The onboarding session id is the A2A `contextId`, the app-event session id gets minted per app-open, and the kit keeps those two id spaces apart on purpose. Intersect them and you get no rows. Ever.
+
+The key is **`user_context.device_key`**, and you have to put it on both sides:
+
+```tsx
+import { activationJoinContext } from "@wireai/activation";
+
+// Purchase side: createAnalytics / createWireActivation auto-mint and persist a device_key
+// and stamp it on every event. Supply your own to override it.
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+
+// Onboarding side: forward the SAME key. The kit passes userContext verbatim into the A2A
+// session-start metadata, and the server records it on the session's session_started event.
+<WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} onComplete={persist} />
+```
+
+`activationJoinContext(deviceKey)` exists because the wire key is `device_key` and the prop-facing name is `deviceKey`. Hand-writing `userContext={{ deviceKey }}` produces a bucket the server's device lookup does not read, and you get the silent-zero funnel instead of an error. This is the one place that spelling is decided.
+
+Skip the onboarding half and the purchase events are still valid on their own, they just cannot be attributed back to an onboarding.
+
 ## Feature controls (per-module kill switches)
 
 Every activation surface has a switch you can flip from the dashboard "in case of something":

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-Bzb-bcB2.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DdDkprpM.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-DdDkprpM.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DsSDHqor.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-DsSDHqor.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
@@ -33,7 +33,12 @@ interface ScreenTrackerOptions {
         serverUrl: string;
         apiKey: string;
     };
-    /** The onboarding/session id to correlate screen views with, when known. */
+    /**
+     * The onboarding/session id to correlate screen views with, when known. Omitting it no longer
+     * means the view goes out WITHOUT a `session_id` (the server requires one and drops the event
+     * behind an HTTP 200 — that is why screen tracking silently produced nothing for a host that
+     * never mounted the lifecycle hook). `reportAppEvent` falls back to the current per-open id.
+     */
     sessionId?: string;
     /** A stable, non-PII device id — groups a device's sessions server-side. */
     deviceKey?: string;
@@ -103,8 +108,14 @@ type CreateAnalyticsConfig = {
     /** Tenant API key; sent as `Authorization: Bearer`. */
     apiKey: string;
     /**
-     * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-     * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+     * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+     * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+     * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+     * analytics then collapse onto a single device-scoped session — one "first open", forever.
+     *
+     * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+     * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
+     * your host runs its own session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
@@ -131,6 +142,14 @@ type CreateAnalyticsConfig = {
      * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
      */
     userContext?: WireUserContext;
+    /**
+     * ESCAPE HATCH for the email-shape guard. By default `identify(id)` and a `setUserContext({ userId })`
+     * REFUSE to bind an id that looks like an email (`local@domain.tld`) and warn in dev — because a
+     * raw email in the opaque `user_id` is a PII leak; an email belongs in the opt-in
+     * `userContext.userEmail` field. Set `true` ONLY if your real internal user id genuinely IS an
+     * email address and you accept it as the pseudonymous key. Default `false` (guard on).
+     */
+    allowEmailAsUserId?: boolean;
 };
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
 type AnalyticsOptions = Partial<Pick<EventQueueOptions, "maxSize" | "batchSize" | "baseBackoffMs" | "maxBackoffMs" | "maxRetries">>;
@@ -152,6 +171,16 @@ type Analytics = {
      * binds like {@link identify}. Takes effect on subsequent events. Fire-and-forget.
      */
     setUserContext(partial: Partial<WireUserContext>): void;
+    /**
+     * LOGOUT: unbind the current user so a shared device never attributes user B's events to user A.
+     * Clears the in-memory `boundUserId`, strips the PII / pseudonymous fields (`userId`, `userEmail`,
+     * `extra`) from the bound {@link WireUserContext} (keeping the non-PII `device_key` + `appVersion`,
+     * which group a DEVICE not a user), and removes the persisted `wireai:analytics:userId:<appId>`
+     * key so it cannot be rehydrated on the next launch. Subsequent events are anonymous until the
+     * next `identify` / `setUserContext`. Fire-and-forget; mirrors the `reset()` convention on the
+     * screen tracker. The standalone `clearUserContext({ storage, appId })` covers the `wire` path.
+     */
+    reset(): void;
     /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
     flush(): void;
     /** Host reconnect signal: reset backoff and drain now. Fire-and-forget. */

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-B31G0Cib.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D0Vq7_VE.js';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-D0Vq7_VE.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D6RiVtc8.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-D6RiVtc8.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
@@ -33,7 +33,12 @@ interface ScreenTrackerOptions {
         serverUrl: string;
         apiKey: string;
     };
-    /** The onboarding/session id to correlate screen views with, when known. */
+    /**
+     * The onboarding/session id to correlate screen views with, when known. Omitting it no longer
+     * means the view goes out WITHOUT a `session_id` (the server requires one and drops the event
+     * behind an HTTP 200 — that is why screen tracking silently produced nothing for a host that
+     * never mounted the lifecycle hook). `reportAppEvent` falls back to the current per-open id.
+     */
     sessionId?: string;
     /** A stable, non-PII device id — groups a device's sessions server-side. */
     deviceKey?: string;
@@ -103,8 +108,14 @@ type CreateAnalyticsConfig = {
     /** Tenant API key; sent as `Authorization: Bearer`. */
     apiKey: string;
     /**
-     * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-     * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+     * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+     * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+     * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+     * analytics then collapse onto a single device-scoped session — one "first open", forever.
+     *
+     * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+     * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
+     * your host runs its own session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
@@ -131,6 +142,14 @@ type CreateAnalyticsConfig = {
      * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
      */
     userContext?: WireUserContext;
+    /**
+     * ESCAPE HATCH for the email-shape guard. By default `identify(id)` and a `setUserContext({ userId })`
+     * REFUSE to bind an id that looks like an email (`local@domain.tld`) and warn in dev — because a
+     * raw email in the opaque `user_id` is a PII leak; an email belongs in the opt-in
+     * `userContext.userEmail` field. Set `true` ONLY if your real internal user id genuinely IS an
+     * email address and you accept it as the pseudonymous key. Default `false` (guard on).
+     */
+    allowEmailAsUserId?: boolean;
 };
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
 type AnalyticsOptions = Partial<Pick<EventQueueOptions, "maxSize" | "batchSize" | "baseBackoffMs" | "maxBackoffMs" | "maxRetries">>;
@@ -152,6 +171,16 @@ type Analytics = {
      * binds like {@link identify}. Takes effect on subsequent events. Fire-and-forget.
      */
     setUserContext(partial: Partial<WireUserContext>): void;
+    /**
+     * LOGOUT: unbind the current user so a shared device never attributes user B's events to user A.
+     * Clears the in-memory `boundUserId`, strips the PII / pseudonymous fields (`userId`, `userEmail`,
+     * `extra`) from the bound {@link WireUserContext} (keeping the non-PII `device_key` + `appVersion`,
+     * which group a DEVICE not a user), and removes the persisted `wireai:analytics:userId:<appId>`
+     * key so it cannot be rehydrated on the next launch. Subsequent events are anonymous until the
+     * next `identify` / `setUserContext`. Fire-and-forget; mirrors the `reset()` convention on the
+     * screen tracker. The standalone `clearUserContext({ storage, appId })` covers the `wire` path.
+     */
+    reset(): void;
     /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
     flush(): void;
     /** Host reconnect signal: reset backoff and drain now. Fire-and-forget. */