@wireai/activation 0.13.2 → 0.13.5

package/dist/analytics/index.d.ts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DOVZEWJl.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-DOVZEWJl.js';
-import '../types-Buj9Lw9t.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 };