@wireai/activation 0.14.3 → 0.15.0

package/AGENTS.md

@@ -81,7 +81,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 | `persistKey` | `string` | no | Override the storage key (default `wireai:session:<config.appId>`). Scope it per-user if one device runs onboarding for multiple accounts. Only meaningful with `storage`. |
 | `retainSessionOnComplete` | `boolean` | no | Opt IN: keep the persisted session seed alive ACROSS completion. A multi-stage or replay-after-complete re-entry within one signup (typically a `key=` remount) then resumes the SAME session instead of minting a fresh `metadata.sessionId`, which the backend adopts as a second `contextId` and double-counts as a `session_started`. Omitted or `false` clears the seed on completion, the legacy single-stage behavior, so leaving it unset changes nothing. When `true`, freshness comes from `sessionTtlMs` plus an explicit new-run signal (scope a new `persistKey`, e.g. a per-signup id). Only meaningful with `storage`. |
 | `userContext` | `Record<string, string \| number \| boolean>` | no | Host-injected, non-PII context (signup method, referral, plan tier, a hashed user id). Forwarded to the backend + client events for funnel segmentation. No raw PII. |
-| `autoJoinKey` | `boolean` | no | Opt OUT of the automatic join key. Default `true`. When `userContext` carries no `device_key` and `storage` is present and actually persists (a storage adapter that throws or rejects is treated exactly like no `storage`), the kit injects its own per-install key, the same id `createAnalytics` / `createWireActivation` mint and persist, so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` for a genuinely UNLINKED session: that restores the pre-0.12.2 behavior and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage`. |
+| `autoJoinKey` | `boolean` | no | Opt OUT of the automatic join key. Default `true`. When `userContext` carries no `device_key` and `storage` is present and actually persists (a storage adapter that throws or rejects is treated exactly like no `storage`), the kit injects its own per-install key, the same id `createAnalytics` / `createWireActivation` mint and persist, so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` for a genuinely UNLINKED session: that restores the pre-0.12.2 behavior and the dev warning fires again. It never overrides a `device_key` you actually supplied, and it cannot inject without `storage`. The kit counts yours as supplied only when it is a STRING WITH AT LEAST ONE NON-WHITESPACE CHARACTER (`resolveIdentity`); the `userContext` type also allows a number or a boolean, and a non-string or an all-whitespace `device_key` is not a usable join key, so it is treated as absent and the auto key is merged over it. |
 | `userId` | `string` | no | The host's OPAQUE PSEUDONYMOUS user id (not an email/name/phone), so onboarding sessions reconcile to real users. Late binding supported (mount, mid-session, or post-flow via `identifyOnboarding`). Capped at 128 chars. |
 
 ### `config` fields (`WireOnboardingConfig`)

package/CHANGELOG.md

@@ -3,6 +3,79 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.15.0] - 2026-08-19
+
+**MINOR, not patch, and only because of new API. Two exported surfaces each GAINED an optional
+member; nothing was lost or renamed.** `ReviewSubmission` gains an OPTIONAL `idempotency_key` and
+`buildReviewSubmission` gains an OPTIONAL `idempotencyKey` input. Both are additive and optional, so
+every existing call site compiles unchanged and sends a byte-identical body unless it opts in. A
+gained public member is still a MINOR under this changelog's own precedent: 0.14.0 was bumped MINOR
+for exactly this shape, an optional field added to an exported interface. Every behaviour change
+below is a bug fix.
+
+### Added
+
+- **The review gate can now reach the server's idempotent upsert path, so a recovery post merges
+  into the row it may already have written instead of adding a second one.** `POST /v1/reviews`
+  accepts an optional client-minted `idempotency_key` and derives the row id from it; the kit now
+  mints one per gate IMPRESSION and holds it across every post of that impression. This is a
+  CAPABILITY, not a guarantee, and the condition is load-bearing: the server honours the key only
+  when the post also carries a unit it can scope it to, and ignores it outright otherwise.
+- **Every review post now carries that unit.** The server resolves it as `meta.device_key`, else
+  `session_id`. The gate lives on the home feed, where a user legitimately has no onboarding
+  session, and the kit never put a `device_key` into a review `meta` — so the key alone would have
+  been discarded on the default wiring. The gate now fills in the kit's own per-install auto id,
+  and only when the host supplied none: **any non-empty string you pass in `meta.device_key` wins
+  verbatim.** The kit counts a value as host-supplied only when it is a string with at least one
+  non-whitespace character, so a non-string or an all-whitespace one is not a usable unit and is
+  replaced. **Overriding `meta` cannot remove the unit**: the injection tests the MERGED bucket, so
+  stripping `device_key` there only gets the auto id back. Exactly one post carries no unit at all,
+  the one where the kit cannot name an id honestly: two tenants registered in one process, which
+  leaves the per-install id space ambiguous and the auto id `undefined`. That post reaches the
+  server with no unit, the server ignores the idempotency key, and that path keeps the previous
+  behaviour.
+- The injected id is the SAME per-install id the analytics surfaces use, adopted from the process
+  registry rather than minted fresh, so the gate never opens a second id space for one install.
+
+### Unchanged on purpose
+
+- **The `rejected` verdict is still not retried.** Re-posting after a non-2xx is now safe wherever
+  the key is honoured, but it would also turn a genuine 4xx refusal into a retry needing its own
+  budget. That is a separate recovery decision and is deliberately not bundled here.
+- Questionnaire submissions are untouched. The server has no idempotency path for them, so every
+  statement in `src/questionnaire/` about there being no key on the wire remains true.
+
+### Fixed
+
+- **An ASYNC gate-storage adapter now fails CLOSED instead of misfiring the gates.** The sync gate
+  storage (`CoachmarkStorage`) silently accepted an async adapter — AsyncStorage handed straight to
+  `CoachmarkProvider` or a gate's `storage` prop. Its `getItem` returns a Promise, which is never
+  `=== "1"` and parses to `NaN`, so every seen-gate read "unseen" forever: coachmark tours and
+  showcases replayed on every open, and a review gate configured with `minSessions` 0/1 could
+  RE-FIRE its native prompt each open (the 2026-07-16 one-star incident class). A thenable probe on
+  first read (`validateGateStorage`, WeakSet-cached so each adapter pays for exactly one probe) now
+  substitutes a closed adapter: every gate reads "seen", nothing shows, nothing fires, and a
+  once-per-process dev warning names the fix (pass a sync adapter, e.g. a 3-line MMKV wrapper).
+  Never-fire is the only direction a once-per-user gate may err in. A rejecting probe promise is
+  detached, so a broken native store cannot surface as an unhandled rejection.
+  - Canary: `test/canary/asyncGateStorage.test.tsx` (6 tests, proven red with the probe neutered —
+    including the sync CONTROL that stays green) + the new
+    `@wireai/activation:asyncGateStorageWarned` latch registered in `globalSlotDiscipline`.
+
+### Docs
+
+- **The "a `device_key` you passed is never overridden" line is now qualified everywhere it ships**,
+  on the ONBOARDING join-key path as it already was on the reviews path. The bar is the same on both
+  and it is `resolveIdentity` / `hasDeviceKey`: a string with at least one non-whitespace character.
+  `userContext` also accepts numbers and booleans, so a non-string or an all-whitespace `device_key`
+  was never a usable join key — it reads as absent and the auto key is merged over it, which the
+  unqualified sentence denied. Corrected in `AGENTS.md`, `README.md` (both the props table and the
+  join-key rules), and the shipped JSDoc in `src/types.ts` + `src/WireOnboarding.tsx`. No behaviour
+  change: the predicate is unchanged, only the sentence describing it.
+- `README.md`'s tarball install line named `@wireai/activation-0.1.3.tgz`, a file `npm pack` has
+  never produced under any version (it emits `wireai-activation-<version>.tgz`, scope flattened), so
+  an agent following it hit `ENOENT`. Fixed there and in the two Distribution mentions.
+
 ## [0.14.3] - 2026-08-18
 
 **PATCH: no public surface gained, lost or renamed a member.** `SpotlightOverlay`, `GestureHint`

package/README.md

@@ -140,7 +140,7 @@ Install the package and wire Metro with the one-call helper:
 # from npm (public)
 npm install @wireai/activation
 # …or from a tarball (see Distribution below)
-npm install ./@wireai/activation-0.1.3.tgz
+npm install ./wireai-activation-0.15.0.tgz
 # …or over SSH
 npm install git+ssh://git@github.com/<org>/@wireai/activation.git
 ```
@@ -204,9 +204,9 @@ returns the same config. `options.appRoot` defaults to `process.cwd()`.
 ## Distribution
 
 `npm run pack:tarball` runs the build (via `prepack`) and produces
-`@wireai/activation-x.y.z.tgz` containing `dist` + `src` + `metro` + README +
+`wireai-activation-x.y.z.tgz` containing `dist` + `src` + `metro` + README +
 CHANGELOG. The primary channel is **npm** (`npm install @wireai/activation`); a
-tarball (`npm install ./@wireai/activation-x.y.z.tgz`) or a `git+ssh://…` install
+tarball (`npm install ./wireai-activation-x.y.z.tgz`) or a `git+ssh://…` install
 work too for pre-publish or pinned builds.
 
 ## Quick start
@@ -252,7 +252,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `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. |
 | `retainSessionOnComplete` | `boolean` | Opt IN: keep the persisted session seed alive across completion. A multi-stage signup that re-enters onboarding (typically a `key=` remount) then resumes the SAME session instead of minting a fresh `metadata.sessionId`, which the backend adopts as a second `contextId` and double-counts as a `session_started`. Omitted or `false` clears the seed on completion, the legacy single-stage behavior, so leaving it unset changes nothing. With `true`, freshness comes from `sessionTtlMs` plus an explicit new-run signal (scope a new `persistKey`, e.g. a per-signup id). With `storage` only. |
 | `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}`. If your app owns no device id, pass a working `storage` and leave this prop alone: the kit injects its own key, and only after it has confirmed the key actually persists. ⛔ Do not hand-build that key with `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, because `resolveAutoDeviceKey` is synchronous by contract (it hands back a fresh mint and adopts the persisted id a storage read later) and it cannot tell you whether the id survives the launch at all. Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other 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). |
-| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
+| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you actually supplied, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). The kit counts yours as supplied only when it is a string with at least one non-whitespace character, so a non-string or an all-whitespace `device_key` is treated as absent and the auto key is merged over it. |
 | `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)
@@ -378,6 +378,8 @@ 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.
 
+**The review gate is on that list too, even if it is the only surface you mount.** Since 0.15.0 `<ReviewGate>` stamps `meta.device_key` onto its `POST /v1/reviews` body when you passed none. That id is the unit the server scopes the review's idempotency key to, and a post without it gets the key discarded. The gate adopts whatever per-install id the analytics and activation surfaces already registered in this process, so it never opens a second id space. On a reviews-only host, where nothing else registered one, it mints its own instead. `<ReviewGate>` takes no `storage` prop, so that minted id is process-scoped: a fresh value on each launch, never persisted, rather than a stable per-install one. Either way it leaves the device inside a review payload. Declare it. Pass your own non-blank `meta.device_key` and it is forwarded verbatim instead.
+
 ### Do not pass `sessionId` to `createAnalytics`
 
 `CreateAnalyticsConfig.sessionId` is an opt-out knob, not a default. Set it and **every** event that
@@ -818,8 +820,10 @@ below) — nothing to rewire.
 **1. Mount the provider once, around your `NavigationContainer`.** It renders the
 overlay host as a root sibling so a ring can paint _above_ the bottom tab bar
 (which react-navigation draws over screen components). It takes a **synchronous**
-storage adapter — gate reads must not be async or a ring flashes before the
-"already seen" check resolves. An MMKV wrapper is three lines:
+storage adapter — gate reads resolve during render. An async adapter (e.g.
+AsyncStorage handed straight in) is caught by a probe and the gates FAIL CLOSED:
+coachmarks, showcases and the review/questionnaire gates all stay silent, and a
+dev-build warning names the fix. An MMKV wrapper is three lines:
 
 ```tsx
 import { CoachmarkProvider } from "@wireai/activation/coachmarks";
@@ -1245,7 +1249,7 @@ Skip the onboarding half and the purchase events are still valid on their own, t
 
 Three rules govern it:
 
-- **Your key always wins.** Any non-empty `device_key` you pass is forwarded verbatim and nothing is merged over it. Existing integrations see a byte-identical payload.
+- **Your key always wins.** A `device_key` you pass is forwarded verbatim, untrimmed, and nothing is merged over it — as long as it is a string with at least one non-whitespace character, which is the kit's entire test for "the host supplied one" (the trim is used only to decide presence). A non-string (the `userContext` type also allows numbers and booleans) or an all-whitespace value is not a usable join key: it is treated as absent and the auto key is merged over it. Existing integrations that pass a real key see a byte-identical payload.
 - **It needs `storage`.** Without persistence the kit's id is minted fresh on every launch, and a per-launch key is worse than no key: the server counts `min_sessions` by distinct app-opens grouped on `device_key`, so it corrupts the counter instead of leaving the join empty. With no `storage` the kit declines to inject and warns in dev.
 - **You can opt out.** `autoJoinKey={false}` restores the pre-0.12.2 behavior for a host that genuinely wants an unlinked session. The dev warning fires again there, naming the opt-out as the reason nothing was injected.
 

package/dist/analytics/index.d.mts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-j5gFfJhK.mjs';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CUvTOchb.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, 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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CUvTOchb.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-s5QxA-ci.mjs';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-orZy5p1e.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, 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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-orZy5p1e.mjs';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.mjs';
-import '../types-Cju-1_jT.mjs';
+import '../types-Byx306Kv.mjs';
 import '../types-BKfpdZzX.mjs';
-import '../types-BcmagF6K.mjs';
+import '../types-D_0B0yay.mjs';
 import 'react';
 import 'wireai-rn';
 import 'react-native';

package/dist/analytics/index.d.ts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-B_0SgCBe.js';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CW_5Mq4O.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, 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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CW_5Mq4O.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-xqqSFqxs.js';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CFSRZ2wg.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, 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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CFSRZ2wg.js';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.js';
-import '../types-h2BZvl1t.js';
+import '../types-tdATL5z0.js';
 import '../types-BKfpdZzX.js';
-import '../types-BcmagF6K.js';
+import '../types-D_0B0yay.js';
 import 'react';
 import 'wireai-rn';
 import 'react-native';