@wireai/activation 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ Historical entries below the rename keep the old package name on purpose.
 
 ## [Unreleased]
 
+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.
+
+### 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)
 
 A kit-owned event-trigger surface so a consumer stops hand-rolling the session-id + await-POST +

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,34 @@ 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.
 
 ## Session mapping (know when a user opens the app again)
 

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-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';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
@@ -131,6 +131,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 +160,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-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';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
@@ -131,6 +131,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 +160,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.js

@@ -400,13 +400,45 @@ var init_Constants = __esm({
   }
 });
 
-// src/reviews/transport.ts
-var reportAppEvent = (target, name2, options = {}) => {
-  if (!(target == null ? void 0 : target.serverUrl) || !name2) return;
+// src/analytics/reportClientEvent.ts
+var makeSessionId = () => `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+var buildEventsRequest = (target, events) => {
+  if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return null;
   try {
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
     const headers = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
+  } catch {
+    return null;
+  }
+};
+var reportClientEvents = (target, events) => {
+  try {
+    const req = buildEventsRequest(target, events);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
+    });
+  } catch {
+  }
+};
+var reportClientEvent = (target, event) => reportClientEvents(target, [event]);
+var reportClientEventsAwait = async (target, events) => {
+  try {
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
+    const res = await fetch(req.url, req.init);
+    return Boolean(res && res.ok);
+  } catch {
+    return false;
+  }
+};
+var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
+
+// src/reviews/transport.ts
+var reportAppEvent = (target, name2, options = {}) => {
+  if (!(target == null ? void 0 : target.serverUrl) || !name2) return;
+  try {
     const event = {
       event_type: "app_event",
       question_key: name2
@@ -416,11 +448,9 @@ var reportAppEvent = (target, name2, options = {}) => {
     if (options.meta && Object.keys(options.meta).length > 0) {
       event.meta = JSON.stringify(options.meta);
     }
-    void fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ events: [event] })
-    }).catch(() => {
+    const req = buildEventsRequest(target, [event]);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
     });
   } catch {
   }
@@ -497,41 +527,6 @@ var useScreenTracking = (navigationRef, options = {}) => {
   }, [navigationRef]);
 };
 
-// src/analytics/reportClientEvent.ts
-var makeSessionId = () => `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-var buildEventsRequest = (target, events) => {
-  if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return null;
-  try {
-    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-    const headers = { "Content-Type": "application/json" };
-    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
-  } catch {
-    return null;
-  }
-};
-var reportClientEvents = (target, events) => {
-  try {
-    const req = buildEventsRequest(target, events);
-    if (!req) return;
-    void fetch(req.url, req.init).catch(() => {
-    });
-  } catch {
-  }
-};
-var reportClientEvent = (target, event) => reportClientEvents(target, [event]);
-var reportClientEventsAwait = async (target, events) => {
-  try {
-    const req = buildEventsRequest(target, events);
-    if (!req) return false;
-    const res = await fetch(req.url, req.init);
-    return Boolean(res && res.ok);
-  } catch {
-    return false;
-  }
-};
-var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
-
 // src/analytics/analyticsEvent.ts
 var WIRE_ONBOARDING_EVENTS = {
   started: "wire_onboarding_started",
@@ -822,6 +817,7 @@ var createEventQueue = (options) => {
     var _a3;
     const env = resolveEnvelope();
     const stamped = { ...event };
+    if (stamped.ts === void 0) stamped.ts = Date.now();
     if (!env) return stamped;
     if (!stamped.device && env.device) stamped.device = env.device;
     if (!stamped.session_id && env.sessionId) stamped.session_id = env.sessionId;
@@ -877,19 +873,12 @@ var createEventQueue = (options) => {
     }
   })();
   const postBatch = async (events) => {
-    if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return false;
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
     const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
     const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), 15e3);
     try {
-      const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-      const headers = { "Content-Type": "application/json" };
-      if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-      const res = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ events }),
-        signal: controller == null ? void 0 : controller.signal
-      });
+      const res = await fetch(req.url, { ...req.init, signal: controller == null ? void 0 : controller.signal });
       return !!(res && res.ok);
     } catch {
       return false;
@@ -991,6 +980,7 @@ var sanitizeUserId = (raw) => {
   if (!trimmed) return void 0;
   return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
 };
+var looksLikeEmail = (value) => typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
 
 // src/context/userContext.ts
 var EXTRA_KEY_PREFIX = "custom.";
@@ -1025,6 +1015,21 @@ var namespaceExtra = (extra) => {
   }
   return out;
 };
+var analyticsUserIdStorageKey = (appId) => `wireai:analytics:userId:${appId != null ? appId : "default"}`;
+var clearPiiFromContext = (ctx = {}) => {
+  const rest = {};
+  if (typeof ctx.appVersion === "string") rest.appVersion = ctx.appVersion;
+  if (typeof ctx.deviceKey === "string") rest.deviceKey = ctx.deviceKey;
+  return rest;
+};
+var clearUserContext = async (opts = {}) => {
+  const storage = opts.storage;
+  if (!storage) return;
+  try {
+    await storage.removeItem(analyticsUserIdStorageKey(opts.appId));
+  } catch {
+  }
+};
 var resolveUserContext = (ctx = {}, opts = {}) => {
   var _a2;
   const result = {};
@@ -1065,8 +1070,13 @@ var mintDeviceId = () => {
 };
 
 // src/analytics/analyticsFacade.ts
+var warnInDev = (message) => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+  }
+};
 var createAnalytics = (config, options = {}) => {
-  var _a2, _b, _c, _d, _e;
+  var _a2, _b, _c, _d;
   const instanceSessionId = (_a2 = config.sessionId) != null ? _a2 : makeSessionId();
   const resolveSessionId = () => {
     var _a3, _b2;
@@ -1103,7 +1113,7 @@ var createAnalytics = (config, options = {}) => {
     ...options
   });
   let boundUserId = sanitizeUserId((_d = config.userContext) == null ? void 0 : _d.userId);
-  const storageKey = `wireai:analytics:userId:${(_e = config.appId) != null ? _e : "default"}`;
+  const storageKey = analyticsUserIdStorageKey(config.appId);
   if (config.storage) {
     void config.storage.getItem(storageKey).then((saved) => {
       if (saved && !boundUserId) boundUserId = saved;
@@ -1122,6 +1132,13 @@ var createAnalytics = (config, options = {}) => {
     }
     if (boundUserId && !event.user_id) event.user_id = boundUserId;
   };
+  const guardUserId = (clean) => {
+    if (config.allowEmailAsUserId || !looksLikeEmail(clean)) return clean;
+    warnInDev(
+      "[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;
+  };
   const setUserContext = (partial) => {
     var _a3, _b2;
     if (!partial || typeof partial !== "object") return;
@@ -1130,11 +1147,20 @@ var createAnalytics = (config, options = {}) => {
     if (mergedExtra) userContext.extra = mergedExtra;
     const uid = sanitizeUserId(partial.userId);
     if (uid) {
-      boundUserId = uid;
-      if (config.storage) void config.storage.setItem(storageKey, uid).catch(() => {
-      });
+      const bindable = guardUserId(uid);
+      if (bindable) {
+        boundUserId = bindable;
+        if (config.storage) void config.storage.setItem(storageKey, bindable).catch(() => {
+        });
+      }
     }
   };
+  const reset = () => {
+    boundUserId = void 0;
+    userContext = clearPiiFromContext(userContext);
+    if (config.storage) void config.storage.removeItem(storageKey).catch(() => {
+    });
+  };
   const track = (event, props) => {
     if (!event) return;
     const clientEvent = {
@@ -1161,9 +1187,11 @@ var createAnalytics = (config, options = {}) => {
   const identify = (userId, traits) => {
     const clean = sanitizeUserId(userId);
     if (!clean) return;
-    boundUserId = clean;
+    const bindable = guardUserId(clean);
+    if (!bindable) return;
+    boundUserId = bindable;
     if (config.storage) {
-      void config.storage.setItem(storageKey, clean).catch(() => {
+      void config.storage.setItem(storageKey, bindable).catch(() => {
       });
     }
     const clientEvent = {
@@ -1171,7 +1199,7 @@ var createAnalytics = (config, options = {}) => {
       // Reuse the LIVE per-open session id (see `resolveSessionId`) so the server binds identity to
       // the session it already saw instead of back-filling a phantom `session_started`.
       session_id: resolveSessionId(),
-      user_id: clean
+      user_id: bindable
     };
     if (traits && Object.keys(traits).length > 0) clientEvent.meta = JSON.stringify(traits);
     applyContext(clientEvent);
@@ -1182,6 +1210,7 @@ var createAnalytics = (config, options = {}) => {
     screen,
     identify,
     setUserContext,
+    reset,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size
@@ -1199,12 +1228,16 @@ var useAnalytics = (config, options = {}) => {
 };
 
 exports.WIRE_ONBOARDING_EVENTS = WIRE_ONBOARDING_EVENTS;
+exports.analyticsUserIdStorageKey = analyticsUserIdStorageKey;
 exports.buildContextEnvelope = buildContextEnvelope;
+exports.clearPiiFromContext = clearPiiFromContext;
+exports.clearUserContext = clearUserContext;
 exports.createAnalytics = createAnalytics;
 exports.createEventQueue = createEventQueue;
 exports.createScreenTracker = createScreenTracker;
 exports.getActiveRouteName = getActiveRouteName;
 exports.getCurrentSessionId = getCurrentSessionId;
+exports.looksLikeEmail = looksLikeEmail;
 exports.makeSessionId = makeSessionId;
 exports.reportAppEvent = reportAppEvent;
 exports.reportClientEvent = reportClientEvent;