@wireai/activation 0.11.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,10 +3,65 @@
 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
 
-Architecture-audit fixes. The next release that ships these MUST be at least **0.11.0** (0.10.0 is
-published and immutable). One BEHAVIOR CHANGE, called out below.
+- **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
 

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

@@ -370,6 +370,24 @@ await clearUserContext({ storage, appId }); // the wire/activation path (then re
 
 **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)
 
 Onboarding runs once, on the first launch. Session mapping is the other half: every time the
@@ -965,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-BGW9uXZJ.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-C0_odnIW.mjs';
-export { A as AnalyticsEvent, C as ClearUserContextOptions, a as ClientEvent, b as ClientEventTarget, c as ClientEventType, d as ContextEnvelope, e as ContextEnvelopeInput, f as EnvelopeSource, g as EventQueue, h as WIRE_ONBOARDING_EVENTS, i as WireOnboardingEventName, j as analyticsUserIdStorageKey, k as buildContextEnvelope, l as clearPiiFromContext, m as clearUserContext, n as createEventQueue, o as getCurrentSessionId, p as looksLikeEmail, q as makeSessionId, r as reportClientEvent, s as reportClientEventAwait, t as reportClientEvents, u as reportClientEventsAwait, v as resetCurrentSessionId, w as setCurrentSessionId, x as toAnalyticsEvent } from '../currentSession-C0_odnIW.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>`). */

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-jUJd5kxu.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DdnUq2HQ.js';
-export { A as AnalyticsEvent, C as ClearUserContextOptions, a as ClientEvent, b as ClientEventTarget, c as ClientEventType, d as ContextEnvelope, e as ContextEnvelopeInput, f as EnvelopeSource, g as EventQueue, h as WIRE_ONBOARDING_EVENTS, i as WireOnboardingEventName, j as analyticsUserIdStorageKey, k as buildContextEnvelope, l as clearPiiFromContext, m as clearUserContext, n as createEventQueue, o as getCurrentSessionId, p as looksLikeEmail, q as makeSessionId, r as reportClientEvent, s as reportClientEventAwait, t as reportClientEvents, u as reportClientEventsAwait, v as resetCurrentSessionId, w as setCurrentSessionId, x as toAnalyticsEvent } from '../currentSession-DdnUq2HQ.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>`). */

package/dist/analytics/index.js

@@ -413,6 +413,23 @@ var buildEventsRequest = (target, events) => {
     return null;
   }
 };
+var warnOnSkippedEvents = (res) => {
+  try {
+    const json = res == null ? void 0 : res.json;
+    if (typeof json !== "function") return;
+    void Promise.resolve(json.call(res)).then((body) => {
+      const skipped = body == null ? void 0 : body.skipped;
+      if (typeof skipped !== "number" || skipped <= 0) return;
+      if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+        console.warn(
+          `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) (skipped in the response body) \u2014 they are gone, not retried. The usual cause is an event with a missing or empty session_id.`
+        );
+      }
+    }).catch(() => {
+    });
+  } catch {
+  }
+};
 var reportClientEvents = (target, events) => {
   try {
     const req = buildEventsRequest(target, events);
@@ -435,15 +452,54 @@ var reportClientEventsAwait = async (target, events) => {
 };
 var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
 
+// src/analytics/currentSession.ts
+var CURRENT_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
+  "@wireai/activation:currentSessionId"
+);
+var globalSlot = globalThis;
+var setCurrentSessionId = (id) => {
+  if (typeof id === "string" && id.length > 0) {
+    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  }
+};
+var getCurrentSessionId = () => globalSlot[CURRENT_SESSION_ID_SLOT];
+var resetCurrentSessionId = () => {
+  globalSlot[CURRENT_SESSION_ID_SLOT] = void 0;
+};
+var warnInDev = (message) => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+    return true;
+  }
+  return false;
+};
+var MINT_WARNING = "[wireai] No app-open session was registered, so a session id was minted for this event (the server drops an event that has no session_id, and still answers 200). Mount useLifecycleEvents at your app root so events correlate to a real app-open.";
+var MINT_WARNED_SLOT = /* @__PURE__ */ Symbol.for(
+  "@wireai/activation:currentSessionIdMintWarned"
+);
+var warnSlot = globalThis;
+var ensureCurrentSessionId = () => {
+  const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
+  if (typeof existing === "string" && existing.length > 0) return existing;
+  const minted = makeSessionId();
+  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
+    warnSlot[MINT_WARNED_SLOT] = true;
+  }
+  return minted;
+};
+
 // src/reviews/transport.ts
 var reportAppEvent = (target, name2, options = {}) => {
+  var _a2;
   if (!(target == null ? void 0 : target.serverUrl) || !name2) return;
   try {
+    const supplied = (_a2 = options.sessionId) != null ? _a2 : "";
     const event = {
       event_type: "app_event",
-      question_key: name2
+      question_key: name2,
+      session_id: supplied.trim().length > 0 ? supplied : ensureCurrentSessionId()
     };
-    if (options.sessionId) event.session_id = options.sessionId;
     if (options.deviceKey) event.user_context = { device_key: options.deviceKey };
     if (options.meta && Object.keys(options.meta).length > 0) {
       event.meta = JSON.stringify(options.meta);
@@ -879,6 +935,7 @@ var createEventQueue = (options) => {
     const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), 15e3);
     try {
       const res = await fetch(req.url, { ...req.init, signal: controller == null ? void 0 : controller.signal });
+      warnOnSkippedEvents(res);
       return !!(res && res.ok);
     } catch {
       return false;
@@ -957,21 +1014,6 @@ var createEventQueue = (options) => {
   return { enqueue, flush, notifyOnline, size };
 };
 
-// src/analytics/currentSession.ts
-var CURRENT_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
-  "@wireai/activation:currentSessionId"
-);
-var globalSlot = globalThis;
-var setCurrentSessionId = (id) => {
-  if (typeof id === "string" && id.length > 0) {
-    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
-  }
-};
-var getCurrentSessionId = () => globalSlot[CURRENT_SESSION_ID_SLOT];
-var resetCurrentSessionId = () => {
-  globalSlot[CURRENT_SESSION_ID_SLOT] = void 0;
-};
-
 // src/identity/userIdentity.ts
 var USER_ID_MAX_LENGTH = 128;
 var sanitizeUserId = (raw) => {
@@ -1068,9 +1110,50 @@ var mintDeviceId = () => {
   const time = Date.now().toString(36);
   return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
 };
+var AUTO_DEVICE_KEY_SLOT = /* @__PURE__ */ Symbol.for("@wireai/activation:autoDeviceKeys");
+var deviceKeyGlobal = globalThis;
+var autoDeviceKeyRegistry = () => {
+  const existing = deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT];
+  if (existing) return existing;
+  const created = { keys: /* @__PURE__ */ new Map(), hydrating: /* @__PURE__ */ new Set() };
+  deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT] = created;
+  return created;
+};
+var resolveAutoDeviceKey = (opts = {}) => {
+  var _a2, _b;
+  const registry = autoDeviceKeyRegistry();
+  const appId = (_a2 = opts.appId) != null ? _a2 : "default";
+  let id = registry.keys.get(appId);
+  if (!id) {
+    id = mintDeviceId();
+    registry.keys.set(appId, id);
+  }
+  const storage = opts.storage;
+  if (storage && !registry.hydrating.has(appId)) {
+    registry.hydrating.add(appId);
+    const slot = deviceIdStorageKey(appId);
+    const minted = id;
+    try {
+      void Promise.resolve(storage.getItem(slot)).then((saved) => {
+        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : void 0;
+        if (persisted) registry.keys.set(appId, persisted);
+        else void Promise.resolve(storage.setItem(slot, minted)).catch(() => {
+        });
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  return (_b = registry.keys.get(appId)) != null ? _b : id;
+};
+var resetAutoDeviceKeys = () => {
+  const registry = autoDeviceKeyRegistry();
+  registry.keys.clear();
+  registry.hydrating.clear();
+};
 
 // src/analytics/analyticsFacade.ts
-var warnInDev = (message) => {
+var warnInDev2 = (message) => {
   if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
     console.warn(message);
   }
@@ -1082,20 +1165,20 @@ var createAnalytics = (config, options = {}) => {
     var _a3, _b2;
     return (_b2 = (_a3 = config.sessionId) != null ? _a3 : getCurrentSessionId()) != null ? _b2 : instanceSessionId;
   };
+  if (config.sessionId) {
+    warnInDev2(
+      "[wireai] createAnalytics({ sessionId }) PINS every event from this instance to that one frozen id and opts out of the live per-open session (app.session_started) \u2014 lifecycle analytics collapse onto a single device-scoped id. Remove it unless your host runs its own session lifecycle."
+    );
+  }
+  const detectedAppVersion = detectAppVersion();
   let userContext = { ...(_b = config.userContext) != null ? _b : {} };
   const hostDeviceKeyAtInit = typeof ((_c = config.userContext) == null ? void 0 : _c.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
-  let autoDeviceKey = mintDeviceId();
-  if (config.storage && !hostDeviceKeyAtInit) {
-    const storage = config.storage;
-    const deviceKey = deviceIdStorageKey(config.appId);
-    void storage.getItem(deviceKey).then((saved) => {
-      const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : void 0;
-      if (persisted) autoDeviceKey = persisted;
-      else void storage.setItem(deviceKey, autoDeviceKey).catch(() => {
-      });
-    }).catch(() => {
-    });
-  }
+  const autoDeviceKeyOptions = {
+    appId: config.appId,
+    // A host-supplied deviceKey opts out of minting AND persisting (unchanged contract).
+    storage: hostDeviceKeyAtInit ? void 0 : config.storage
+  };
+  if (!hostDeviceKeyAtInit) resolveAutoDeviceKey(autoDeviceKeyOptions);
   const envelope = () => {
     var _a3;
     return buildContextEnvelope({
@@ -1121,20 +1204,21 @@ var createAnalytics = (config, options = {}) => {
     });
   }
   const applyContext = (event) => {
-    var _a3;
+    var _a3, _b2;
     const hostDeviceKey = typeof userContext.deviceKey === "string" && userContext.deviceKey.trim() ? userContext.deviceKey : void 0;
     const resolved = resolveUserContext(
-      { ...userContext, deviceKey: hostDeviceKey != null ? hostDeviceKey : autoDeviceKey },
-      { autoAppVersion: config.appVersion }
+      // `??` is lazy on purpose: a host-supplied key must never even touch the auto registry.
+      { ...userContext, deviceKey: hostDeviceKey != null ? hostDeviceKey : resolveAutoDeviceKey(autoDeviceKeyOptions) },
+      { autoAppVersion: (_a3 = config.appVersion) != null ? _a3 : detectedAppVersion }
     );
     if (resolved.userContext) {
-      event.user_context = { ...resolved.userContext, ...(_a3 = event.user_context) != null ? _a3 : {} };
+      event.user_context = { ...resolved.userContext, ...(_b2 = event.user_context) != null ? _b2 : {} };
     }
     if (boundUserId && !event.user_id) event.user_id = boundUserId;
   };
   const guardUserId = (clean) => {
     if (config.allowEmailAsUserId || !looksLikeEmail(clean)) return clean;
-    warnInDev(
+    warnInDev2(
       "[wireai] identify() was called with an email-shaped id. A raw email must NOT be the opaque user_id (PII leak) \u2014 pass it as userContext.userEmail instead. Binding was skipped. Set allowEmailAsUserId:true on createAnalytics if your user id genuinely is an email."
     );
     return void 0;
@@ -1217,6 +1301,7 @@ var createAnalytics = (config, options = {}) => {
   };
 };
 var useAnalytics = (config, options = {}) => {
+  var _a2;
   const ref = react.useRef(void 0);
   const prevKeys = react.useRef("");
   const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
@@ -1224,9 +1309,15 @@ var useAnalytics = (config, options = {}) => {
     prevKeys.current = currentKeys;
     ref.current = createAnalytics(config, options);
   }
+  const hostDeviceKey = typeof ((_a2 = config.userContext) == null ? void 0 : _a2.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
+  react.useEffect(() => {
+    var _a3;
+    if (hostDeviceKey) (_a3 = ref.current) == null ? void 0 : _a3.setUserContext({ deviceKey: hostDeviceKey });
+  }, [hostDeviceKey]);
   return ref.current;
 };
 
+exports.AUTO_DEVICE_ID_PREFIX = AUTO_DEVICE_ID_PREFIX;
 exports.WIRE_ONBOARDING_EVENTS = WIRE_ONBOARDING_EVENTS;
 exports.analyticsUserIdStorageKey = analyticsUserIdStorageKey;
 exports.buildContextEnvelope = buildContextEnvelope;
@@ -1235,6 +1326,8 @@ exports.clearUserContext = clearUserContext;
 exports.createAnalytics = createAnalytics;
 exports.createEventQueue = createEventQueue;
 exports.createScreenTracker = createScreenTracker;
+exports.deviceIdStorageKey = deviceIdStorageKey;
+exports.ensureCurrentSessionId = ensureCurrentSessionId;
 exports.getActiveRouteName = getActiveRouteName;
 exports.getCurrentSessionId = getCurrentSessionId;
 exports.looksLikeEmail = looksLikeEmail;
@@ -1244,7 +1337,9 @@ exports.reportClientEvent = reportClientEvent;
 exports.reportClientEventAwait = reportClientEventAwait;
 exports.reportClientEvents = reportClientEvents;
 exports.reportClientEventsAwait = reportClientEventsAwait;
+exports.resetAutoDeviceKeys = resetAutoDeviceKeys;
 exports.resetCurrentSessionId = resetCurrentSessionId;
+exports.resolveAutoDeviceKey = resolveAutoDeviceKey;
 exports.screenTrackingHandler = screenTrackingHandler;
 exports.setCurrentSessionId = setCurrentSessionId;
 exports.toAnalyticsEvent = toAnalyticsEvent;