@wireai/activation 0.13.3 → 0.13.6-next.0

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:
@@ -1311,6 +1363,137 @@ generation context). For the full
 scaffold-the-screen integration job, the [`wire-rn-integration`](./INTEGRATION_PROMPT.md)
 skill drives it end to end.
 
+## EU AI Act: acceptable use and our position
+
+**Position as of 2026-08-06, against Regulation (EU) 2024/1689 as amended by Regulation (EU) 2026/1744.**
+
+This is our own reading of where this kit sits inside the regulation, written down so an integrator
+can see the reasoning and disagree with it. It is not legal advice. Nobody has audited this kit
+against the regulation, and a review by a qualified lawyer is pending. Where that review says we
+read something wrong, this section gets corrected and re-dated.
+
+### Who is who
+
+The app that ships a Wire-powered surface is the **deployer** of that surface. You choose the flow,
+the audience, the questions, and what the answers are used for.
+
+Wire is the provider of a limited-risk component inside that: a card renderer, plus a backend that
+selects and fills cards from a fixed vocabulary you configure.
+
+### Not for high-risk use
+
+**This system is not intended to be put into service as, or changed into, a high-risk AI system.**
+
+Do not deploy Wire-powered surfaces in an Annex III high-risk area:
+
+1. Biometrics
+2. Critical infrastructure
+3. Education and vocational training
+4. Employment, workers management and access to self-employment
+5. Access to essential private and public services and benefits
+6. Law enforcement
+7. Migration, asylum and border control
+8. Administration of justice and democratic processes
+
+Obligations for Annex III systems apply from 2 December 2027, which is not a countdown to when this
+becomes usable there. It is not what this kit is built for, at any date.
+
+Two prohibitions in Article 5(1) have been live since 2 February 2025 and were left untouched by the
+Omnibus. Do not use these surfaces for subliminal, manipulative or deceptive techniques that
+materially distort behaviour, and do not use them to exploit vulnerabilities due to age, disability,
+or a specific social or economic situation.
+
+That second one deserves saying out loud, because an onboarding flow that adapts per user is an easy
+place to cross it without meaning to. A flow that adapts because it learned what a user responds to
+is one short step from a flow that adapts because it learned what a user cannot resist. Optimise for
+the user finishing something they came to do.
+
+### Article 50(1): telling people they are talking to an AI
+
+Article 50(1) applies since 2 August 2026. There is no legacy grace period for it.
+
+It requires that AI systems intended to interact directly with natural persons are designed so those
+persons are informed they are interacting with an AI system, unless that is obvious from the point of
+view of a reasonably well-informed, observant and circumspect natural person.
+
+Our reading of the generated-UI case: generated onboarding UI is not a conversational agent. Cards,
+buttons, pickers and form fields do not present themselves as a person, and someone tapping through a
+signup flow is not being led to believe there is a human on the other end. A form is obvious.
+
+Where that reading stops: if you build a chat-like or free-text-responding surface, one that answers
+a user in free prose the way a person would, that is the case Article 50(1) was written for. If you
+build that, **your app owns the disclosure**, not the kit.
+
+We cannot place it for you. We do not control your screen, your copy, or your first-run experience.
+Put it where the user meets the surface, not buried in a settings page nobody opens.
+
+The honest edge in between: `TextInputCard` takes free text, and the copy on the next card is
+generated from what the user typed. We read that as a form that adapts rather than a conversation,
+because the system does not answer as an interlocutor and the interaction stays inside the card
+vocabulary you configured. If that reading does not hold for the flow you built, disclose. Nothing in
+the kit stops you.
+
+### Article 50(2): marking generated content
+
+Article 50(2) covers providers of AI systems that generate synthetic audio, image, video or text, and
+requires the outputs to be marked in a machine-readable format as artificially generated or
+manipulated. Its legacy grace period runs to 2 December 2026, and only for providers of those
+generators.
+
+Our reading has two parts.
+
+The first is that Wire does not provide the generative model. The card copy a user reads was produced
+by a third-party model. Provider-level marking of a model's output sits upstream, with the provider
+of that model.
+
+The second is that for the layer we do provide, the carve-out written into the article is the one we
+rely on. It "shall not apply to the extent the AI systems perform an assistive function for standard
+editing or do not substantially alter the input data provided by the deployer or the semantics
+thereof." You supply the app description, the first question, the allowed components and the copy
+constraints. The system selects and fills cards inside that. We read it as assistive rather than as
+generating a work of synthetic content.
+
+Where that reading stops: if you use this kit as the delivery surface for a general content
+generator, handing a model's free-form output to a user as content, our reading does not carry over
+to your app. Look at Article 50(2) for yourself in that case.
+
+### Article 50(3): emotion recognition
+
+We do not read Article 50(3) as engaged by anything this kit does today.
+
+Article 3(39) defines an emotion recognition system as one inferring emotions or intentions **on the
+basis of biometric data**, and recital 18 confines that to biometric signals like face, gesture and
+voice. This kit reads typed and tapped answers, and text is not biometric data. No camera, no
+microphone, no biometric processing anywhere in the flow.
+
+### Article 25: the specification, and why we are not standing behind a licence
+
+Article 25(2) closes with an express carve-out. The provider flip does not apply "in cases where the
+initial provider has clearly specified that its AI system is not to be changed into a high-risk AI
+system."
+
+The sentence in bold under **Not for high-risk use** is that specification. It is written
+deliberately, and it is why this section exists in the README rather than in a lawyer's drawer.
+
+Article 25(4) ends by exempting third parties who make tools, services, processes or components
+(other than general-purpose AI models) publicly available "under a free and open-source licence" from
+the written-agreement duty. `@wireai/activation` is published on npm under the MIT licence, so on the
+face of it that sentence reaches it, though the source repository is private and that is a difference
+worth stating rather than glossing over.
+
+We would rather not stand on that carve-out. Unlike the open-source SDK underneath this kit, we
+usually know who integrates this one and we have a direct channel to them. So if you integrate the
+kit and need information about it to meet your own obligations as a deployer, ask, and you get it in
+writing. That is a commitment about how we behave, not a claim about our legal position.
+
+### What this section is not
+
+Nobody has reviewed or audited this kit against the regulation. This is not a statement that it meets
+a legal standard, and it is not a badge for a landing page.
+
+It is what we think the regulation asks of a component like this one, what we did about it, and which
+parts sit on your side of the line rather than ours. Your app, your users, your assessment.
+
 ## More from Code Meet AI
 
 **Open source:** [wireai-rn](https://github.com/chohra-med/wireai-rn) · [expo_boilerplate](https://github.com/chohra-med/expo_boilerplate) · [colorway-c-brand](https://github.com/chohra-med/colorway-c-brand) · [claude_design_skill](https://github.com/chohra-med/claude_design_skill)

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-Cs3lweFZ.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-Cs3lweFZ.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-DD6dKB0i.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-DD6dKB0i.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 };