@wireai/activation 0.11.0 → 0.12.0

package/src/context/deviceId.ts

@@ -41,3 +41,112 @@ export const mintDeviceId = (): string => {
   const time = Date.now().toString(36);
   return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
 };
+
+// ── The ONE auto device key per install ──────────────────────────────────────────────────────
+//
+// WHY A REGISTRY AND NOT A `let` PER FACTORY: `createAnalytics` and `createWireActivation` each
+// used to mint their OWN id synchronously and then race a storage read to overwrite it. A host that
+// creates BOTH (the documented wiring: a façade for `track`/`screen`, an activation instance for the
+// gate-firing `wire.track`) therefore had TWO auto ids for ONE install. Every event carried whichever
+// id its own surface minted, so the `device_key` the server groups a device's sessions under — the
+// key `min_sessions`, A/B arm stickiness, and the purchase↔onboarding join all read — SPLIT in two.
+// On a first run both also wrote their own id to the same storage slot, so which one survived was a
+// coin flip. Same failure class as joining two event families on disjoint id spaces: no error, just
+// halved counts and a join that misses.
+//
+// The fix is the pattern this repo already uses for `currentSession` and `activation revalidation`:
+// ONE value in a `globalThis` slot keyed by `Symbol.for(...)`, so every inlined copy of this module
+// (tsup duplicates modules across the `.` / `./analytics` bundles) addresses the SAME registry.
+// Keyed by `appId` so two tenants in one process never share an id.
+//
+// RESIDUAL WINDOW (documented, not fixed here): the storage read is async, so events emitted in the
+// milliseconds before hydration completes still carry the freshly minted id rather than the persisted
+// one. The registry makes every surface agree on WHICH id that is; it does not make the read sync.
+
+/** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
+const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
+
+/** The shared registry: the live id per `appId`, plus the set of appIds whose hydration already ran. */
+type AutoDeviceKeyRegistry = { keys: Map<string, string>; hydrating: Set<string> };
+
+type GlobalWithDeviceKeys = typeof globalThis & {
+  [AUTO_DEVICE_KEY_SLOT]?: AutoDeviceKeyRegistry;
+};
+
+const deviceKeyGlobal = globalThis as GlobalWithDeviceKeys;
+
+const autoDeviceKeyRegistry = (): AutoDeviceKeyRegistry => {
+  const existing = deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT];
+  if (existing) return existing;
+  const created: AutoDeviceKeyRegistry = { keys: new Map(), hydrating: new Set() };
+  deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT] = created;
+  return created;
+};
+
+/** The persistence subset {@link resolveAutoDeviceKey} needs (a strict subset of `WireOnboardingStorage`). */
+export type DeviceKeyStorage = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+};
+
+/** Options for {@link resolveAutoDeviceKey}. Omitting `storage` gives a PROCESS-scoped id, not a
+ *  per-install one — see the caller notes: a caller with no persistence must decide whether a
+ *  per-launch id is better or worse than no id for its metric. */
+export interface ResolveAutoDeviceKeyOptions {
+  /** Tenant/app id — namespaces both the registry entry and the storage slot. */
+  appId?: string;
+  /** Host persistence. Present → the id survives launches. Absent → process-scoped only. */
+  storage?: DeviceKeyStorage;
+}
+
+/**
+ * The ONE auto-minted `device_key` for an install, shared by every kit surface.
+ *
+ * SYNCHRONOUS by contract (a fire-and-forget event path cannot await): returns the current live id
+ * immediately, minting one on first call. When `storage` is supplied it also kicks off a SINGLE
+ * hydration per `appId` that adopts the persisted id (or persists the freshly minted one). Callers
+ * should call this per EVENT rather than caching the return value, so an event built after hydration
+ * carries the persisted id.
+ *
+ * A host-supplied `deviceKey` always wins — callers must short-circuit before reaching this.
+ * Never throws: a missing, hung, or rejecting storage adapter degrades to the in-memory id.
+ */
+export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): string => {
+  const registry = autoDeviceKeyRegistry();
+  const appId = opts.appId ?? "default";
+
+  let id = registry.keys.get(appId);
+  if (!id) {
+    id = mintDeviceId();
+    registry.keys.set(appId, id);
+  }
+
+  const storage = opts.storage;
+  // Single-flight: the FIRST caller with storage owns hydration for this appId; later callers just
+  // read whatever the registry currently holds.
+  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() : undefined;
+          if (persisted) registry.keys.set(appId, persisted);
+          else void Promise.resolve(storage.setItem(slot, minted)).catch(() => {});
+        })
+        .catch(() => {});
+    } catch {
+      // A storage adapter that throws synchronously — degrade to the in-memory id.
+    }
+  }
+
+  return registry.keys.get(appId) ?? id;
+};
+
+/** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
+export const resetAutoDeviceKeys = (): void => {
+  const registry = autoDeviceKeyRegistry();
+  registry.keys.clear();
+  registry.hydrating.clear();
+};

package/src/context/userContext.ts

@@ -207,6 +207,24 @@ export const clearUserContext = async (opts: ClearUserContextOptions = {}): Prom
   }
 };
 
+/**
+ * The `userContext` value to hand `<WireOnboarding userContext={...} />` so an onboarding session
+ * and the app's later events (purchases, actions, screens) share ONE join key.
+ *
+ * WHY it exists as a named function instead of an inline object literal: the wire key is
+ * `device_key`, the prop-facing name is `deviceKey`, and the analytics surfaces auto-mint the value
+ * for you. A host that hand-writes `userContext={{ deviceKey }}` produces a bucket the server's
+ * device lookup does not read, and the resulting funnel is silently EMPTY rather than wrong. This is
+ * the one place that spelling is decided.
+ *
+ * Pass the SAME `deviceKey` you gave `createAnalytics` / `createWireActivation`. `session_id` is not
+ * a join key across those two families: an onboarding session id is the A2A `contextId` and an
+ * app-event session id is the per-open id, so intersecting them returns nothing.
+ */
+export const activationJoinContext = (
+  deviceKey: string,
+): Record<string, string | number | boolean> => resolveUserContext({ deviceKey }).userContext ?? {};
+
 /** Options for {@link resolveUserContext}. */
 export interface ResolveUserContextOptions {
   /**

package/src/index.ts

@@ -153,6 +153,7 @@ export {
   clearUserContext,
   clearPiiFromContext,
   analyticsUserIdStorageKey,
+  activationJoinContext,
   RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
@@ -162,11 +163,27 @@ export type {
   ResolveUserContextOptions,
   ClearUserContextOptions,
 } from "./context/userContext";
-export { mintDeviceId, deviceIdStorageKey, AUTO_DEVICE_ID_PREFIX } from "./context/deviceId";
+export {
+  mintDeviceId,
+  deviceIdStorageKey,
+  AUTO_DEVICE_ID_PREFIX,
+  // `resolveAutoDeviceKey` is the id `createAnalytics` / `createWireActivation` auto-mint and persist.
+  // It MUST be public: the documented purchase↔onboarding join is
+  // `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`, and a host that owns NO device
+  // id of its own had no way to obtain the key the analytics side was already stamping — so its
+  // purchase events carried `wdev_*` while its onboarding session carried no `device_key` at all, and
+  // the join returned the silent zero the README warns about.
+  resolveAutoDeviceKey,
+  resetAutoDeviceKeys,
+} from "./context/deviceId";
+export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "./context/deviceId";
 
 // ─── Current per-open session registry (identify/app-events reuse the live session) ───
 export {
   getCurrentSessionId,
+  // Returns the registered per-open id, minting + registering one when no app-open has been
+  // registered yet — so no wire path can emit the empty `session_id` the server drops behind a 200.
+  ensureCurrentSessionId,
   setCurrentSessionId,
   resetCurrentSessionId,
 } from "./analytics/currentSession";
@@ -189,6 +206,33 @@ export {
   resetActivationRevalidation,
 } from "./activation";
 
+// ─── RevenueCat (purchase funnel → the same events stream, joined on device_key) ──
+export {
+  createRevenueCatBridge,
+  WIRE_PURCHASE_EVENTS,
+  PLAN_TIER_CONTEXT_KEY,
+  activeEntitlement,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  isUserCancelled,
+  resolvePlanTier,
+} from "./revenuecat";
+export type {
+  RevenueCatBridge,
+  RevenueCatBridgeConfig,
+  PurchaseProps,
+  WirePurchaseEventName,
+  PlanTier,
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatErrorLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatProductLike,
+  RevenueCatSink,
+} from "./revenuecat";
+
 // ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
 export {
   reportSessionStart,

package/src/questionnaire/runtime.ts

@@ -5,7 +5,13 @@
  * host that mounted CoachmarkProvider gets questionnaire gating for free - no second storage
  * to wire. Once-per-user is keyed on the questionnaire `id`.
  */
-export { resolveStorage, readInt, writeInt } from "../reviews/runtime";
+export {
+  resolveStorage,
+  readInt,
+  writeInt,
+  bumpSessionCount,
+  currentOpenId,
+} from "../reviews/runtime";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
 export const questionnaireSeenKey = (id: string, version?: string): string =>
@@ -15,6 +21,10 @@ export const questionnaireSeenKey = (id: string, version?: string): string =>
 export const questionnaireLastShownKey = (id: string): string =>
   `wire_questionnaire_${id}_last`;
 
-/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+/** Session-count key, incremented once per APP-OPEN (not per mount), for the min-sessions rule. */
 export const questionnaireSessionsKey = (id: string): string =>
   `wire_questionnaire_${id}_sessions`;
+
+/** Companion key holding the open id the counter was LAST incremented for (see `bumpSessionCount`). */
+export const questionnaireSessionOpenKey = (id: string): string =>
+  `wire_questionnaire_${id}_open`;

package/src/questionnaire/useQuestionnaireGate.ts

@@ -20,8 +20,10 @@ import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { sameDecision, shallowEqual } from "../reviews/equality";
 import { decideQuestionnaire, evaluateGate, resolveRules } from "./decision";
 import {
+  bumpSessionCount,
   questionnaireLastShownKey,
   questionnaireSeenKey,
+  questionnaireSessionOpenKey,
   questionnaireSessionsKey,
   readInt,
   resolveStorage,
@@ -71,14 +73,14 @@ export const useQuestionnaireGate = ({
   );
   const lastKey = questionnaireLastShownKey(config.id);
   const sessionsKey = questionnaireSessionsKey(config.id);
+  const sessionOpenKey = questionnaireSessionOpenKey(config.id);
 
-  // Read (and bump) the session counter ONCE per mount: this mount is a new session.
-  const sessions = useState(() => {
-    const store = resolveStorage(storage);
-    const next = readInt(store, sessionsKey) + 1;
-    writeInt(store, sessionsKey, next);
-    return next;
-  })[0];
+  // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount — see the same note
+  // in `useReviewGate`; `bumpSessionCount` keys off the live per-open session id, so a remount or a
+  // StrictMode double-invoke of this initializer reads the same number back instead of inflating it.
+  const sessions = useState(() =>
+    bumpSessionCount(resolveStorage(storage), sessionsKey, sessionOpenKey),
+  )[0];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server gets a
   // window to answer first. A present `decision` bypasses the wait entirely.

package/src/revenuecat/index.ts

@@ -0,0 +1,55 @@
+/**
+ * revenuecat - the drop-in RevenueCat to Wire activation path.
+ *
+ * Re-exported from the main `@wireai/activation` barrel (no separate subpath): it is a pure,
+ * dependency-free mapping layer with no UI, so it costs an analytics-only consumer nothing.
+ *
+ * Adopting it is a constructor plus your existing paywall call sites:
+ *
+ *   import { createAnalytics, createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+ *
+ *   const analytics = createAnalytics({ serverUrl, apiKey, storage, 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 });
+ *
+ * And the join that makes the numbers real, on the onboarding side:
+ *
+ *   <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+ *
+ * See `revenueCatBridge.ts` for why that key is `device_key` and never `session_id`.
+ */
+
+// ─── The bridge (the thing you wire) ──────────────────────────────────────────
+export { createRevenueCatBridge } from "./revenueCatBridge";
+export type {
+  RevenueCatBridge,
+  RevenueCatBridgeConfig,
+  PurchaseProps,
+} from "./revenueCatBridge";
+
+// ─── Canonical purchase-funnel names + the pure mappers behind the bridge ─────
+export {
+  WIRE_PURCHASE_EVENTS,
+  PLAN_TIER_CONTEXT_KEY,
+  activeEntitlement,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  isUserCancelled,
+  resolvePlanTier,
+} from "./purchaseEvents";
+export type { WirePurchaseEventName, PlanTier } from "./purchaseEvents";
+
+// ─── Structural mirrors of the react-native-purchases shapes (no native dep) ──
+export type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatErrorLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatProductLike,
+  RevenueCatSink,
+} from "./types";

package/src/revenuecat/purchaseEvents.ts

@@ -0,0 +1,167 @@
+/**
+ * purchaseEvents - the canonical Wire names for a subscription funnel, plus the PURE mappers that
+ * turn a RevenueCat snapshot into small, non-PII event props.
+ *
+ * Same job `analyticsEvent.ts` does for the onboarding funnel: every app was naming these events
+ * itself (`PURCHASE`, `purchase_success`, `AI_PAYWALL_VIEW`), so the same funnel read differently
+ * per tenant and no cross-app report was possible. These are the ONE set of names; the mappers are
+ * the ONE definition of which RevenueCat fields are safe to send.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`, no transport.
+ * Every function tolerates a malformed or absent snapshot and returns a defined value instead of
+ * throwing, because a paywall must never break on an analytics mapping.
+ */
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatPackageLike,
+} from "./types";
+
+/**
+ * The canonical purchase-funnel event names. These are `app_event` `question_key` values on the
+ * wire, so they are ALSO the exact strings a review / questionnaire firing trigger matches on.
+ * Never rename one: a rename silently unfires every trigger configured against the old string.
+ */
+export const WIRE_PURCHASE_EVENTS = {
+  /** The paywall became visible (offerings loaded). */
+  paywallShown: "wire_paywall_shown",
+  /** The user tapped buy; the store sheet is about to open. */
+  checkoutStarted: "wire_checkout_started",
+  /** The store confirmed the purchase AND the entitlement is now active. */
+  purchased: "wire_purchase_completed",
+  /** The purchase did not land: a user cancel or a real store/network error (see `reason`). */
+  purchaseFailed: "wire_purchase_failed",
+  /** A restore ran (whether or not it produced an entitlement; see `plan_tier`). */
+  restored: "wire_purchase_restored",
+} as const;
+
+export type WirePurchaseEventName =
+  (typeof WIRE_PURCHASE_EVENTS)[keyof typeof WIRE_PURCHASE_EVENTS];
+
+/**
+ * The user-context key the bridge writes the tier to. It lands NAMESPACED as
+ * `user_context["custom.plan_tier"]` (host extras are always prefixed), which is the flattened
+ * dimension the server report can break the funnel down by.
+ */
+export const PLAN_TIER_CONTEXT_KEY = "plan_tier";
+
+/** The three tiers the kit models. Anything richer belongs in the host's own analytics. */
+export type PlanTier = "paid" | "trial" | "free";
+
+/** Read a plain record field defensively (the snapshot comes from a native bridge). */
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/**
+ * The ACTIVE entitlement matching `entitlementId`, or `undefined`. Returns `undefined` for a
+ * missing key, an explicitly inactive entry, and any malformed snapshot.
+ */
+export const activeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): RevenueCatEntitlementLike | undefined => {
+  const active = asRecord(asRecord(asRecord(info)?.entitlements)?.active);
+  const found = active?.[entitlementId];
+  const entitlement = asRecord(found) as RevenueCatEntitlementLike | undefined;
+  if (!entitlement) return undefined;
+  // `isActive` is always present on the real type; treat an explicit `false` as not entitled and a
+  // missing value as entitled, because the key only appears in `entitlements.active` at all when
+  // RevenueCat considers it granted.
+  return entitlement.isActive === false ? undefined : entitlement;
+};
+
+/** True when RevenueCat says this entitlement is a free trial rather than a paid period. */
+const isTrial = (entitlement: RevenueCatEntitlementLike): boolean =>
+  typeof entitlement.periodType === "string" && entitlement.periodType.toUpperCase() === "TRIAL";
+
+/** `paid` / `trial` / `free` for the configured entitlement. Never throws. */
+export const resolvePlanTier = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): PlanTier => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  if (!entitlement) return "free";
+  return isTrial(entitlement) ? "trial" : "paid";
+};
+
+/**
+ * Non-PII props for an offering package: which package, which product, what it costs. Every field
+ * is optional on the wire, so a missing one is OMITTED rather than sent empty or invented.
+ */
+export const describePackage = (
+  pkg: RevenueCatPackageLike | undefined,
+): Record<string, string | number> => {
+  const props: Record<string, string | number> = {};
+  if (!pkg) return props;
+  if (typeof pkg.identifier === "string") props.package_id = pkg.identifier;
+  if (typeof pkg.packageType === "string") props.package_type = pkg.packageType;
+  if (typeof pkg.offeringIdentifier === "string") props.offering_id = pkg.offeringIdentifier;
+  const product = asRecord(pkg.product) as RevenueCatProductFields | undefined;
+  if (product) {
+    if (typeof product.identifier === "string") props.product_id = product.identifier;
+    if (typeof product.price === "number" && Number.isFinite(product.price)) {
+      props.price = product.price;
+    }
+    if (typeof product.currencyCode === "string") props.currency = product.currencyCode;
+  }
+  return props;
+};
+
+/** The product fields `describePackage` reads, narrowed after the defensive record check. */
+type RevenueCatProductFields = {
+  identifier?: unknown;
+  price?: unknown;
+  currencyCode?: unknown;
+};
+
+/**
+ * Non-PII props for the entitlement state after a purchase or a restore. Always carries
+ * `entitlement` + `plan_tier` so a "restore that granted nothing" is still a queryable row; the
+ * rest of the fields only appear when the entitlement is actually active.
+ */
+export const describeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): Record<string, string | number | boolean> => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  const props: Record<string, string | number | boolean> = {
+    entitlement: entitlementId,
+    plan_tier: entitlement ? (isTrial(entitlement) ? "trial" : "paid") : "free",
+  };
+  if (!entitlement) return props;
+  if (typeof entitlement.periodType === "string") props.period_type = entitlement.periodType;
+  props.is_trial = isTrial(entitlement);
+  if (typeof entitlement.willRenew === "boolean") props.will_renew = entitlement.willRenew;
+  if (typeof entitlement.store === "string") props.store = entitlement.store;
+  if (typeof entitlement.productIdentifier === "string") {
+    props.product_id = entitlement.productIdentifier;
+  }
+  if (typeof entitlement.isSandbox === "boolean") props.is_sandbox = entitlement.isSandbox;
+  return props;
+};
+
+/** RevenueCat's `PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR`. A STRING enum, value `"1"`. */
+const PURCHASE_CANCELLED_CODE = "1";
+
+/**
+ * True when the rejection is the user backing out of the store sheet rather than a real failure.
+ * Reads BOTH signals the SDK exposes: the current `code` and the deprecated-but-still-populated
+ * `userCancelled` flag. Anything else (including a plain `Error`) is a genuine failure.
+ */
+export const isUserCancelled = (error: unknown): boolean => {
+  const record = asRecord(error);
+  if (!record) return false;
+  if (record.userCancelled === true) return true;
+  return record.code === PURCHASE_CANCELLED_CODE;
+};
+
+/**
+ * A short, stable, non-PII failure descriptor. The store's `message` is DELIBERATELY dropped: it is
+ * localized, unbounded, and occasionally echoes the account it failed for, so it is not something
+ * the kit forwards to a shared analytics backend. The RevenueCat `code` is the stable handle.
+ */
+export const describeFailure = (error: unknown): { reason: string; code: string } => {
+  const record = asRecord(error);
+  const code = typeof record?.code === "string" ? record.code : "unknown";
+  return { reason: isUserCancelled(error) ? "cancelled" : "error", code };
+};