@wireai/activation 0.13.3 → 0.13.5

package/AGENTS.md

@@ -32,7 +32,7 @@ Everything an integration needs lives on the ROOT import (`@wireai/activation`).
 subpaths are optional secondary feature modules; import one only if you use it.
 
 - `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the device-only event reporters (`reportClientEvent`, `makeSessionId`, `WIRE_ONBOARDING_EVENTS`, see "App events" below).
-- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`. Except for `clearUserContext`, these are NOT root exports; importing them from the root does not compile. `clearUserContext` IS also a root export (`import { clearUserContext } from "@wireai/activation"`), which is the form the README teaches for the sign-out purge.
+- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`, `wireDoctor`. Except for `clearUserContext`, these are NOT root exports; importing them from the root does not compile. `clearUserContext` IS also a root export (`import { clearUserContext } from "@wireai/activation"`), which is the form the README teaches for the sign-out purge. `wireDoctor({ target, storage })` is the DEV-ONLY integration self-check: it resolves `{ok, checks:[{name, ok, detail}]}`, never throws, and posts one `dry_run` probe event so a broken integration is caught on the first run instead of in a funnel report. It is dev-gated on `__DEV__` (a release build makes no network call), it reports the apiKey's SHAPE and never its value, and its verdict is read from the ack body, never from the status code. See the README "Verify your integration" section.
 - `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
 - `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
 - `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`, `useReviewGate`, `fetchReviewDecision`).
@@ -79,7 +79,9 @@ subpaths are optional secondary feature modules; import one only if you use it.
 | `storage` | `WireOnboardingStorage` | no | Host-injected AsyncStorage-compatible storage. When set, the kit caches its session id so an app kill mid-onboarding resumes the SAME backend session (keeps the `started` count honest). Persists the correlation seed only, never answers. |
 | `sessionTtlMs` | `number` | no | How long a persisted session id stays resumable, ms. Default `3600000` (1h). Only meaningful with `storage`. |
 | `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`. |
 | `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,69 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.13.5] - 2026-08-03
+
+Two halves of one idea: stop finding out about a broken events integration from a funnel report.
+
+`POST /v1/events` answers HTTP 200 for a batch it discards and reports the refusal only in the
+response body, so a client/server contract drift breaks nothing anyone can see. It quietly flattens
+a graph. That is exactly how a numeric `ts` threw away every `app_event` through 0.13.0. This
+release adds a check on each side of that gap: one in CI, one on the developer's first run.
+
+(0.13.4 is deliberately skipped.)
+
+### Added
+
+- **`wireDoctor`, a dev-only integration self-check**, exported from `@wireai/activation/analytics`.
+  It resolves a structured report and never throws, whatever the target, the storage adapter or the
+  network does. Four independent checks, each a `{name, ok, detail}` unit:
+
+  1. `target`: the `serverUrl` parses and an `apiKey` is present. It reports the key's SHAPE only,
+     its length and whether the prefix matches, and never any character of the key itself.
+  2. `reachability`: `GET /v1/events/contract` answers, so the URL really is a Wire server.
+  3. `storage`: a write / read / delete probe proves the offline queue can persist. The probe uses
+     its own key, outside the queue's namespace, and deletes it in a `finally` even when the read or
+     the write throws. A diagnostic that eats a pending backlog would be worse than no diagnostic.
+  4. `round_trip`: one synthetic event goes through the REAL transport with `dry_run: true`, so the
+     server validates it exactly as it would a production event and writes nothing. The verdict is
+     read from the ack body (`written === 1 && skipped === 0`), never from the status code. A
+     `ts`-shaped drift surfaces as `skipped: 1` carrying the server's own `field: "ts"`.
+
+  Dev-only by contract: the `__DEV__` guard is the first statement, so a release build makes no
+  network call and writes no storage key. The report says it was skipped rather than reporting a
+  pass it never earned. No new export subpath, no new `globalThis` slot, and a host that never calls
+  it does not bundle it.
+
+- **An `events-contract` CI job** that validates the payloads `buildEventsRequest` actually produces
+  against the JSON Schema the production server publishes, one fixture per send-path family
+  (analytics façade, session-start lifecycle, review transport, `client_fallback`, the unmount
+  `dropped`, and an offline queue flush carrying a persisted numeric-`ts` backlog). It uses the real
+  transport rather than a copied envelope, and reads the schema live rather than from a vendored
+  snapshot, so it cannot pass by validating a replica of something that has already drifted.
+
+  The fixtures are defined once, in `test/fixtures/sendPathFamilies.ts`, and read by both this check
+  and the transport-parity test. Each one names the emitter (`file:line`) whose shape it was built
+  from, and the check prints that line beside its result, so "this is what that path really sends"
+  is a claim you can check rather than one you have to trust. The module is under `test/` and is
+  absent from `files`, so it never reaches the tarball.
+
+  It fails, it never skips. A network error, a non-200, an unparseable contract, a missing
+  `client_event_types`, an unknown `event_type` or any invalid event exits non-zero. Run it locally
+  with `npm run check:contract`. `ajv` is a devDependency and does not ship in the tarball.
+
+### Changed
+
+- **`buildEventsRequest` takes an optional third argument, `options?: { dryRun?: boolean }`.** The
+  `dry_run` key is added to the envelope ONLY on an explicit `true`, so every production send path
+  (which passes nothing) still serializes byte-identical bytes. That parity is asserted per
+  send-path family against golden strings captured from 0.13.3, because FIVE shipped call sites ride
+  this one envelope (the offline queue's `postBatch`, the fire-and-forget POST, the awaitable POST,
+  the review transport, and the session-start lifecycle) and a diagnostic has no business changing it
+  for them.
+- **`readEventsAck` is exported from its module** so `wireDoctor` reuses the same ack reader the send
+  paths use. It is deliberately NOT added to the `./analytics` barrel: the module's surface widens,
+  the package's public API does not. The exports map still has exactly 8 keys.
+
 ## [0.13.3] — 2026-08-02
 
 The headline is a fix nobody could see from inside the kit: **on the DEFAULT configuration, a

package/INTEGRATION_PROMPT.md

@@ -76,7 +76,13 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    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.
-11. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+11. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths. Then
+   prove the events wiring actually works, because `/v1/events` answers 200 for a batch it discards:
+   behind an `if (__DEV__)` guard, call
+   `wireDoctor({ target: { serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY }, storage })` from
+   `@wireai/activation/analytics` once at app root and log the report. Every check must come back
+   `ok`. A failing `round_trip` names the field the server refused. Remove the call, or leave it
+   dev-gated, once the report is green.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -234,6 +234,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `onComplete` | `(result: { answers, raw }) => void` | Fires when the user taps the terminal recap's CTA. **Required.** |
 | `theme` | `Partial<OnboardingTheme>` | Brand colors/fonts/radius/spacing, deep-merged over a neutral default. |
 | `illustrations` | `Record<string, ReactNode>` | App artwork for `InterstitialCard`, keyed by name. |
+| `icons` | `Record<string, ReactNode>` | Your own icon nodes, keyed by the semantic name the AI emits (`{ instagram: <BrandIg/> }`). Checked first, so use it to put your brand mark on a choice card, to add names the vocabulary does not carry, or to get icons at all without installing `@expo/vector-icons`. Anything you leave out falls back to that optional peer, then to no icon. Never a crash. See [Icons](#icons). |
 | `validators` | `Record<string, StepValidator>` | Per-step, keyed by base-question key (e.g. `username`). Blocks advance + shows an inline error. When the backend sends a `progress.slot_id` for a screen, the kit looks up that slot FIRST and falls back to the question key, so a validator map written against today's keys keeps working. |
 | `permissionScreens` | `PermissionScreenConfig[]` | Priming screens injected mid-flow, starting with notifications. The screen explains why, and the OS dialog opens **only** on the primary tap, never on mount. Zero new dependencies: you inject `request`. See [Permission screens](#permission-screens-the-priming-pattern). |
 | `onSkip` | `() => void` | User skipped. |
@@ -249,6 +250,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. |
+| `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)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). 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)). |
 | `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). |
@@ -714,6 +716,56 @@ check, because a component name a device cannot render does **not** degrade grac
 `COMPONENT_NOT_FOUND` inside `wireai-rn` before the renderer ever sees it, and the user loses the
 turn to the retry/fallback path.
 
+## Verify your integration (`wireDoctor`)
+
+`POST /v1/events` answers **HTTP 200 for a batch it throws away**. It reports the refusal in the
+response body (`{written, skipped, errors: [{reason, field}]}`), never in the status code. So a
+mis-wired integration looks healthy from the outside while every event disappears. That is how a
+numeric `ts` discarded every `app_event` through 0.13.0.
+
+`wireDoctor` catches that on the first run instead of in a funnel report three weeks later.
+
+```tsx
+import { useEffect } from "react";
+import { wireDoctor } from "@wireai/activation/analytics";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+useEffect(() => {
+  if (!__DEV__) return;
+  wireDoctor({
+    target: { serverUrl: DRIVELINE_SERVER_URL, apiKey: DRIVELINE_API_KEY },
+    storage: AsyncStorage,
+  }).then((report) => console.log(report.ok, report.checks));
+}, []);
+```
+
+It resolves `{ ok, checks: [{ name, ok, detail }] }` and **never throws**, whatever the target, the
+storage adapter or the network does. Four independent checks:
+
+| `name` | What it proves |
+|---|---|
+| `target` | `serverUrl` is a valid http(s) URL and an `apiKey` is present. Reports the key's SHAPE only (its length, and whether the prefix matches), never its value. |
+| `reachability` | `GET /v1/events/contract` answers, so the URL really points at a Wire server. |
+| `storage` | The offline queue can persist, via a write / read / delete probe on its own key. Your pending backlog is never read, overwritten or deleted. |
+| `round_trip` | One synthetic event survives real server validation. It goes out with `dry_run`, so nothing is written and no metric moves. The verdict is `written === 1 && skipped === 0`, read from the ack body, because the status code cannot tell you. |
+
+A `ts`-shaped drift shows up as `skipped=1` carrying the server's own `field: ts`.
+
+**Dev-only by contract.** The `__DEV__` guard is the first statement in the function, so a release
+build does nothing at all: no network call, no storage write. In that case the report says it was
+skipped rather than reporting a pass it never earned. A host that never imports `wireDoctor` does not
+bundle it.
+
+### The contract check
+
+The kit's `events-contract` CI job validates the payloads `buildEventsRequest` actually produces
+against the JSON Schema the production server publishes at
+`https://wire-rn-dynamic-onboarding.fly.dev/v1/events/contract`, one fixture per send path. Run it
+yourself with `npm run check:contract`.
+
+It fails, it never skips. An unreachable endpoint, a non-200 or an unparseable contract is a red
+job, because a check that has learned nothing must not report green.
+
 ## Consuming from source (Metro + tsconfig)
 
 The monorepo apps resolve the kit from source. In each app:

package/dist/analytics/index.d.mts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CefdERPs.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BoWtr3Jp.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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-BoWtr3Jp.mjs';
-import '../types-l2tfg23P.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-j5gFfJhK.mjs';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-DgJf0fRz.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-DgJf0fRz.mjs';
+import { W as WireOnboardingStorage } from '../types-BpwiRpA8.mjs';
+import '../types-Cju-1_jT.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
-import '../types-CKFhyrMu.mjs';
 import 'react';
 import 'wireai-rn';
 import 'react-native';
@@ -95,6 +95,86 @@ interface NavigationRefLike {
  */
 declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined, options?: ScreenTrackerOptions) => void;
 
+/**
+ * wireDoctor: a DEV-ONLY, opt-in self-check that proves a fresh integration end to end before the
+ * first real user ever runs it.
+ *
+ * WHY IT EXISTS: the `/v1/events` endpoint answers HTTP **200** for a batch it throws away. It
+ * reports the refusal in the response body (`{written, skipped, errors:[{reason, field}]}`), so a
+ * mis-wired integration looks perfectly healthy from the outside while every event evaporates. A
+ * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
+ * discover in a funnel report weeks later into something the first run tells you.
+ *
+ * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * without the others. The report is data, never a thrown error and never a side effect on the host:
+ *
+ *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
+ *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
+ *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
+ *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *
+ * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
+ * that can crash the screen it is diagnosing is worse than no doctor.
+ *
+ * ⛔ NEVER PRINTS A SECRET. The `target` check reports the key's SHAPE (present / absent, length,
+ * whether the prefix is the expected one) and never any character of the key itself, in any
+ * `detail`, any log line, or any error. `wireDoctor.test.ts` asserts that with a sentinel key.
+ *
+ * COSTS A NON-CALLER NOTHING: it is a plain function behind the `./analytics` subpath, the package
+ * is `sideEffects: false`, and this module has no top-level side effects, so a host that never
+ * imports it never bundles it. It also mints no `globalThis` slot and retains no timer or listener.
+ *
+ * USAGE (dev builds only):
+ *
+ *   import { wireDoctor } from "@wireai/activation/analytics";
+ *
+ *   const report = await wireDoctor({
+ *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
+ *     storage: AsyncStorage,
+ *   });
+ *   console.log(report.ok, report.checks);
+ */
+
+/** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
+type WireDoctorCheck = {
+    /**
+     * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+     *
+     * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
+     * `internal_error` is the separate catch-all for a failure that got past every check's own
+     * swallow. They are distinct names because a consumer branching on `dev_only` would otherwise
+     * read an internal fault as "this is a release build" and report a healthy skip.
+     */
+    name: string;
+    ok: boolean;
+    /** Human-readable result. ⛔ Never contains any part of an API key. */
+    detail: string;
+};
+/** What {@link wireDoctor} resolves to. `ok` is true only when EVERY check passed. */
+type WireDoctorReport = {
+    ok: boolean;
+    checks: WireDoctorCheck[];
+};
+/** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
+type WireDoctorOptions = {
+    /** The same `{serverUrl, apiKey}` the kit is configured with. */
+    target: ClientEventTarget | undefined;
+    /**
+     * The host storage the offline queue would use (AsyncStorage-compatible). Omit it and the storage
+     * check reports the DEGRADED in-memory mode rather than failing.
+     */
+    storage?: WireOnboardingStorage;
+};
+/**
+ * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
+ *
+ * DEV-ONLY BY CONTRACT: the `__DEV__` guard is the FIRST statement, so a release build performs no
+ * network call, no storage write, and no work at all. The report says it was skipped rather than
+ * pretending everything passed, because a green report that never ran is the exact failure mode
+ * this whole feature exists to remove.
+ */
+declare const wireDoctor: (options: WireDoctorOptions) => Promise<WireDoctorReport>;
+
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 type AnalyticsProps = Record<string, unknown>;
 /**
@@ -203,4 +283,4 @@ declare const createAnalytics: (config: CreateAnalyticsConfig, options?: Analyti
  */
 declare const useAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
 
-export { type Analytics, type AnalyticsOptions, type AnalyticsProps, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking };
+export { type Analytics, type AnalyticsOptions, type AnalyticsProps, ClientEventTarget, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, type WireDoctorCheck, type WireDoctorOptions, type WireDoctorReport, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking, wireDoctor };

package/dist/analytics/index.d.ts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DFuPyCoJ.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-CCOMlaQ2.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 resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CCOMlaQ2.js';
-import '../types-UVYt9BJe.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-B_0SgCBe.js';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-EOHU64QD.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-EOHU64QD.js';
+import { W as WireOnboardingStorage } from '../types-BpwiRpA8.js';
+import '../types-h2BZvl1t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
-import '../types-CKFhyrMu.js';
 import 'react';
 import 'wireai-rn';
 import 'react-native';
@@ -95,6 +95,86 @@ interface NavigationRefLike {
  */
 declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined, options?: ScreenTrackerOptions) => void;
 
+/**
+ * wireDoctor: a DEV-ONLY, opt-in self-check that proves a fresh integration end to end before the
+ * first real user ever runs it.
+ *
+ * WHY IT EXISTS: the `/v1/events` endpoint answers HTTP **200** for a batch it throws away. It
+ * reports the refusal in the response body (`{written, skipped, errors:[{reason, field}]}`), so a
+ * mis-wired integration looks perfectly healthy from the outside while every event evaporates. A
+ * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
+ * discover in a funnel report weeks later into something the first run tells you.
+ *
+ * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * without the others. The report is data, never a thrown error and never a side effect on the host:
+ *
+ *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
+ *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
+ *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
+ *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *
+ * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
+ * that can crash the screen it is diagnosing is worse than no doctor.
+ *
+ * ⛔ NEVER PRINTS A SECRET. The `target` check reports the key's SHAPE (present / absent, length,
+ * whether the prefix is the expected one) and never any character of the key itself, in any
+ * `detail`, any log line, or any error. `wireDoctor.test.ts` asserts that with a sentinel key.
+ *
+ * COSTS A NON-CALLER NOTHING: it is a plain function behind the `./analytics` subpath, the package
+ * is `sideEffects: false`, and this module has no top-level side effects, so a host that never
+ * imports it never bundles it. It also mints no `globalThis` slot and retains no timer or listener.
+ *
+ * USAGE (dev builds only):
+ *
+ *   import { wireDoctor } from "@wireai/activation/analytics";
+ *
+ *   const report = await wireDoctor({
+ *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
+ *     storage: AsyncStorage,
+ *   });
+ *   console.log(report.ok, report.checks);
+ */
+
+/** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
+type WireDoctorCheck = {
+    /**
+     * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+     *
+     * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
+     * `internal_error` is the separate catch-all for a failure that got past every check's own
+     * swallow. They are distinct names because a consumer branching on `dev_only` would otherwise
+     * read an internal fault as "this is a release build" and report a healthy skip.
+     */
+    name: string;
+    ok: boolean;
+    /** Human-readable result. ⛔ Never contains any part of an API key. */
+    detail: string;
+};
+/** What {@link wireDoctor} resolves to. `ok` is true only when EVERY check passed. */
+type WireDoctorReport = {
+    ok: boolean;
+    checks: WireDoctorCheck[];
+};
+/** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
+type WireDoctorOptions = {
+    /** The same `{serverUrl, apiKey}` the kit is configured with. */
+    target: ClientEventTarget | undefined;
+    /**
+     * The host storage the offline queue would use (AsyncStorage-compatible). Omit it and the storage
+     * check reports the DEGRADED in-memory mode rather than failing.
+     */
+    storage?: WireOnboardingStorage;
+};
+/**
+ * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
+ *
+ * DEV-ONLY BY CONTRACT: the `__DEV__` guard is the FIRST statement, so a release build performs no
+ * network call, no storage write, and no work at all. The report says it was skipped rather than
+ * pretending everything passed, because a green report that never ran is the exact failure mode
+ * this whole feature exists to remove.
+ */
+declare const wireDoctor: (options: WireDoctorOptions) => Promise<WireDoctorReport>;
+
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 type AnalyticsProps = Record<string, unknown>;
 /**
@@ -203,4 +283,4 @@ declare const createAnalytics: (config: CreateAnalyticsConfig, options?: Analyti
  */
 declare const useAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
 
-export { type Analytics, type AnalyticsOptions, type AnalyticsProps, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking };
+export { type Analytics, type AnalyticsOptions, type AnalyticsProps, ClientEventTarget, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, type WireDoctorCheck, type WireDoctorOptions, type WireDoctorReport, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking, wireDoctor };

package/dist/analytics/index.js

@@ -22,13 +22,15 @@ var toWireEvents = (events) => events.map((event) => {
     return rest;
   }
 });
-var buildEventsRequest = (target, events) => {
+var buildEventsRequest = (target, events, options) => {
   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}`;
-    const body = JSON.stringify({ events: toWireEvents(events) });
+    const envelope = { events: toWireEvents(events) };
+    if ((options == null ? void 0 : options.dryRun) === true) envelope.dry_run = true;
+    const body = JSON.stringify(envelope);
     return { url, init: { method: "POST", headers, body } };
   } catch {
     return null;
@@ -225,6 +227,168 @@ var useScreenTracking = (navigationRef, options = {}) => {
   }, [navigationRef]);
 };
 
+// src/analytics/wireDoctor.ts
+var PROBE_STORAGE_KEY = "wireai:doctor:probe";
+var PROBE_QUESTION_KEY = "wire_doctor_probe";
+var EXPECTED_KEY_PREFIX = "wai_";
+var NETWORK_TIMEOUT_MS = 1e4;
+var check = (name, ok, detail) => ({ name, ok, detail });
+var fetchWithTimeout = async (url, init) => {
+  if (typeof fetch === "undefined") return void 0;
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+  const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    return await fetch(url, controller ? { ...init, signal: controller.signal } : init);
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+var checkTarget = (target) => {
+  const serverUrl = target == null ? void 0 : target.serverUrl;
+  if (typeof serverUrl !== "string" || serverUrl.trim().length === 0) {
+    return check("target", false, "no serverUrl configured: set `serverUrl` on the kit config.");
+  }
+  let parsedHost = false;
+  try {
+    const parsed = new URL(serverUrl);
+    parsedHost = parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    parsedHost = false;
+  }
+  if (!parsedHost) {
+    return check("target", false, "serverUrl is not a valid http(s) URL.");
+  }
+  const apiKey = target == null ? void 0 : target.apiKey;
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    return check("target", false, "serverUrl looks valid, but no apiKey is configured.");
+  }
+  const prefixOk = apiKey.startsWith(EXPECTED_KEY_PREFIX);
+  return check(
+    "target",
+    true,
+    `serverUrl is a valid http(s) URL; apiKey present (${apiKey.length} chars, expected prefix: ${prefixOk ? "yes" : "no"}).`
+  );
+};
+var checkReachability = async (serverUrl) => {
+  const url = `${serverUrl.replace(/\/$/, "")}/v1/events/contract`;
+  const res = await fetchWithTimeout(url, { method: "GET" });
+  if (!res) {
+    return check("reachability", false, "could not reach the server (network error or timeout).");
+  }
+  const status = res.status;
+  const ok = !!res.ok;
+  if (!ok) {
+    return check(
+      "reachability",
+      false,
+      `the server answered ${typeof status === "number" ? status : "an error"} for the events contract; check the serverUrl points at a Wire server.`
+    );
+  }
+  return check("reachability", true, "the server answered the events contract.");
+};
+var checkStorage = async (storage) => {
+  if (!storage) {
+    return check(
+      "storage",
+      true,
+      "no storage injected: the queue runs in DEGRADED in-memory mode and loses pending events on an app kill. Pass AsyncStorage (or an MMKV wrapper) to make it durable."
+    );
+  }
+  const token = `probe_${Date.now().toString(36)}`;
+  try {
+    await storage.setItem(PROBE_STORAGE_KEY, token);
+    const read = await storage.getItem(PROBE_STORAGE_KEY);
+    if (read !== token) {
+      return check(
+        "storage",
+        false,
+        "the storage adapter accepted a write but did not read the same value back, so the queue cannot persist."
+      );
+    }
+    return check("storage", true, "storage write / read round trip succeeded.");
+  } catch {
+    return check("storage", false, "the storage adapter threw, so the queue cannot persist events.");
+  } finally {
+    try {
+      await storage.removeItem(PROBE_STORAGE_KEY);
+    } catch {
+    }
+  }
+};
+var checkRoundTrip = async (target) => {
+  var _a;
+  const event = {
+    event_type: "app_event",
+    session_id: makeSessionId(),
+    question_key: PROBE_QUESTION_KEY
+  };
+  const req = buildEventsRequest(target, [event], { dryRun: true });
+  if (!req) {
+    return check("round_trip", false, "could not build the events request from this target.");
+  }
+  const res = await fetchWithTimeout(req.url, req.init);
+  if (!res) {
+    return check("round_trip", false, "the events POST failed (network error or timeout).");
+  }
+  if (!res.ok) {
+    const status = res.status;
+    return check(
+      "round_trip",
+      false,
+      `the events endpoint answered ${typeof status === "number" ? status : "an error"}; a 401 here means the apiKey is not accepted.`
+    );
+  }
+  const ack = await readEventsAck(res);
+  if (!ack) {
+    return check(
+      "round_trip",
+      false,
+      "the server answered 2xx but sent no readable ack body, so it is unknown whether the event validated."
+    );
+  }
+  if (ack.written === 1 && ack.skipped === 0) {
+    return check("round_trip", true, "the server validated the probe event: written=1, skipped=0.");
+  }
+  return check(
+    "round_trip",
+    false,
+    `the server DISCARDED the probe event: written=${(_a = ack.written) != null ? _a : "unknown"}, skipped=${ack.skipped}` + (ack.reasons.length > 0 ? `, reasons: ${ack.reasons.join(", ")}.` : ". It gave no reason; check the server's ingest log for this request.")
+  );
+};
+var wireDoctor = async (options) => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) {
+    return {
+      ok: false,
+      checks: [
+        check(
+          "dev_only",
+          false,
+          "wireDoctor is dev-only and did NOT run: __DEV__ is unset or false. Nothing was checked."
+        )
+      ]
+    };
+  }
+  try {
+    const target = options == null ? void 0 : options.target;
+    const checks = [checkTarget(target)];
+    if (checks[0].ok && target) {
+      checks.push(await checkReachability(target.serverUrl));
+      checks.push(await checkStorage(options == null ? void 0 : options.storage));
+      checks.push(await checkRoundTrip(target));
+    } else {
+      checks.push(await checkStorage(options == null ? void 0 : options.storage));
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+  } catch {
+    return {
+      ok: false,
+      checks: [check("internal_error", false, "wireDoctor could not complete: an unexpected error was swallowed.")]
+    };
+  }
+};
+
 // src/permissions/permissionEvents.ts
 var WIRE_PERMISSION_EVENTS = {
   /** The priming screen became visible. The denominator for every rate below. */
@@ -1132,5 +1296,6 @@ exports.setCurrentSessionId = setCurrentSessionId;
 exports.toAnalyticsEvent = toAnalyticsEvent;
 exports.useAnalytics = useAnalytics;
 exports.useScreenTracking = useScreenTracking;
+exports.wireDoctor = wireDoctor;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map