@wireai/activation 0.13.0 → 0.13.2

package/dist/{currentSession-_GynvhzT.d.mts → currentSession-ClkLjcJ0.d.mts}

@@ -153,15 +153,24 @@ type ClientEvent = {
      */
     user_id?: string;
     /**
-     * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
-     * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
-     * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
-     * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
-     * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
-     * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
-     * an old/strict server that does not model it simply ignores the unknown field.
+     * Client-stamped timestamp of when the event was ENQUEUED on the device. Optional and ADDITIVE.
+     *
+     * TWO REPRESENTATIONS, on purpose:
+     *  - INTERNAL (epoch-ms `number`): what the offline queue stamps at enqueue time (see
+     *    `createEventQueue`), so two otherwise byte-identical events fired seconds apart (a genuine
+     *    repeat, e.g. the user taps "share" twice) are NOT collapsed by the queue's identical-JSON
+     *    de-dup — while two truly simultaneous re-enqueues of the same instant (a redundant
+     *    re-render) still share a `ts` and collapse. The de-dup signature depends on this number.
+     *  - WIRE (ISO8601 UTC `string`): what actually leaves the device. {@link buildEventsRequest}
+     *    converts the number on its way out, because the server declares `ts: str | None` and
+     *    pydantic v2 does NOT coerce a number into it — a numeric `ts` made the server answer HTTP
+     *    200 with `{written: 0, skipped: N, errors: [{field: "ts", reason: "validation_error"}]}`,
+     *    silently discarding EVERY `app_event` through 0.13.0.
+     *
+     * A caller-set ISO string is passed through as-is. Never a wall-clock the server trusts (it
+     * derives its own receive time); an old/strict server that does not model it ignores the field.
      */
-    ts?: number;
+    ts?: number | string;
 };
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
 type ClientEventTarget = {
@@ -206,6 +215,222 @@ declare const reportClientEventsAwait: (target: ClientEventTarget | undefined, e
 /** Convenience single-event wrapper around {@link reportClientEventsAwait}. */
 declare const reportClientEventAwait: (target: ClientEventTarget | undefined, event: ClientEvent) => Promise<boolean>;
 
+/**
+ * permissionCopy - the rationale a priming screen shows, and the kit-quality defaults behind it.
+ *
+ * Same job the `copy` prop does for the loaders: the kit ships English that is good enough to
+ * ship as-is, and a host overrides any single line without having to restate the rest.
+ *
+ * PURE, no React, no React Native - so the resolution is unit-testable and the same function can
+ * later resolve copy a server sent.
+ */
+
+/** Every string a permission screen can render. Both states (the ask and the blocked route). */
+type PermissionScreenCopy = {
+    /** Headline for the ask. */
+    title: string;
+    /** The rationale. The one thing that decides whether the primary gets tapped. */
+    message: string;
+    /** Primary button. Tapping it is the ONLY thing that can open the OS dialog. */
+    primaryLabel: string;
+    /** Secondary button. Advances the flow and does NOT spend the one native prompt. */
+    secondaryLabel: string;
+    /** Headline once the OS says the permission is permanently refused. */
+    blockedTitle: string;
+    /** Rationale for the blocked state, where the only remaining route is the settings app. */
+    blockedMessage: string;
+    /** Primary button on the blocked route. */
+    settingsLabel: string;
+    /** Primary button when there is nothing left to ask for (already granted, or no `request`). */
+    continueLabel: string;
+};
+/**
+ * The notification default. Written to the same bar as the kit's other shipped copy: it names the
+ * benefit in the user's terms and promises a limit, because "we would like to send you
+ * notifications" is exactly the sentence that spends the one iOS prompt on a no.
+ */
+declare const NOTIFICATIONS_PERMISSION_COPY: PermissionScreenCopy;
+/** The fallback for any permission the kit ships no copy for. A host overriding `copy` replaces it. */
+declare const GENERIC_PERMISSION_COPY: PermissionScreenCopy;
+/** The kit's shipped defaults, by permission. Anything not listed falls back to the generic set. */
+declare const DEFAULT_PERMISSION_COPY: Record<string, PermissionScreenCopy>;
+/**
+ * The kit default for `permission`, with the host's overrides applied on top.
+ *
+ * An override key whose value is `undefined` is IGNORED rather than allowed to blank the default:
+ * hosts build this object from their i18n layer, and a missing translation resolving to `undefined`
+ * would otherwise render an empty button.
+ */
+declare const resolvePermissionCopy: (permission: WirePermissionKind, overrides?: Partial<PermissionScreenCopy>) => PermissionScreenCopy;
+
+/**
+ * Public types for the injectable mid-flow permission screens.
+ *
+ * THE ONE RULE THIS WHOLE MODULE EXISTS TO ENFORCE: the OS permission dialog is reached from the
+ * user's explicit primary tap and from nowhere else. iOS grants an app exactly ONE native
+ * notification prompt for its entire lifetime, so firing it on mount (the shape almost every app
+ * ships) spends the single ask on a user who has not been told why. A priming screen spends a
+ * cheap in-app screen first and only forwards the ones who said yes.
+ *
+ * DEPENDENCY-FREE, the RevenueCat-bridge idiom: the kit imports NO native permission module. The
+ * host passes `request` (and optionally `getStatus` / `openSettings`) in, exactly the way it hands
+ * the RevenueCat bridge real `CustomerInfo` objects. Wiring `expo-notifications` is five lines in
+ * the host and zero dependencies here.
+ *
+ * A PERMISSION SCREEN IS NOT A QUESTION. It mints no `key` and no `slot_id`, sends nothing to the
+ * backend, and never enters the thread, so `deriveAnswers` / `readProgress` and every completion
+ * semantic are byte-identical whether or not one is configured. Completion NEVER blocks on a grant.
+ */
+
+/**
+ * Which OS permission a screen primes. `notifications` is the one the kit ships copy for; any other
+ * string is accepted (the host supplies the copy) so a host can prime tracking, health or location
+ * without waiting on a kit release.
+ */
+type WirePermissionKind = "notifications" | (string & {});
+/**
+ * What the host's `request` / `getStatus` answers.
+ *  - `granted`: the user allowed it.
+ *  - `denied`: not allowed right now, but the OS would still show a dialog if asked again
+ *    (Android, or an iOS provisional state).
+ *  - `blocked`: permanently refused. Asking again shows NOTHING, so the only route left is Settings.
+ */
+type WirePermissionStatus = "granted" | "denied" | "blocked";
+/** How a permission screen ENDED. `skipped` is the secondary tap, which never burns the OS prompt. */
+type WirePermissionOutcome = WirePermissionStatus | "skipped";
+/**
+ * The moments a permission screen reports. One stage, one canonical event name (see
+ * `permissionEventName`), so the funnel reads the same across every tenant.
+ *  - `shown`: the primer screen became visible. The denominator.
+ *  - `accepted`: the user tapped the primary, so the OS dialog is ABOUT to open. The gap between
+ *    `shown` and `accepted` is the only number that tells a host whether its rationale copy works.
+ *  - `granted` / `denied`: what the OS answered (a `blocked` answer reports as `denied` and carries
+ *    `status: "blocked"`, so the two are one funnel step and still distinguishable).
+ *  - `skipped`: the secondary tap. The prompt was NOT spent.
+ *  - `settings`: the user was redirected to the OS settings page (the `blocked` route).
+ */
+type PermissionStage = "shown" | "accepted" | "granted" | "denied" | "skipped" | "settings";
+/**
+ * WHERE a screen sits in the server-driven stream. The flow length is decided by the backend and
+ * varies per user, so every position is resolved against the card the flow is ABOUT to render:
+ *  - `"start"`: before the first card.
+ *  - `{ afterCard: n }`: after `n` cards have been shown (`{ afterCard: 2 }` sits between card 2
+ *    and card 3). An `n` past the end of a shorter-than-expected stream degrades to `"beforeEnd"`
+ *    rather than silently never showing.
+ *  - `"beforeEnd"`: immediately before the terminal recap. The default.
+ */
+type PermissionPlacement = "start" | "beforeEnd" | {
+    afterCard: number;
+};
+/**
+ * One injectable permission screen.
+ *
+ * ```tsx
+ * import * as Notifications from "expo-notifications";
+ *
+ * <WireOnboarding
+ *   permissionScreens={[
+ *     {
+ *       permission: "notifications",
+ *       placement: "beforeEnd",
+ *       request: async () => {
+ *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+ *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+ *       },
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+type PermissionScreenConfig = {
+    /** Which permission this screen primes. Drives the default copy and every event's `permission`. */
+    permission: WirePermissionKind;
+    /**
+     * Stable id for the once-only / resume record. Defaults to `<permission>:<index in the array>`,
+     * which is right until you reorder the array; set it explicitly if you configure two screens for
+     * the same permission or intend to reorder them between releases.
+     */
+    id?: string;
+    /** Where the screen sits in the stream. Default `"beforeEnd"`. */
+    placement?: PermissionPlacement;
+    /**
+     * THE ONLY FUNCTION THE KIT CALLS THAT CAN OPEN AN OS DIALOG, and it is called from the primary
+     * press handler alone. Never from mount, never from an effect, never from a status probe.
+     */
+    request: () => Promise<WirePermissionStatus>;
+    /**
+     * Optional NON-PROMPTING status read (`Notifications.getPermissionsAsync()`), used only to pick
+     * which primary action the screen offers: a `blocked` user gets "Open settings" instead of an
+     * "Enable" button that would open nothing, and an already-granted user gets a plain Continue.
+     * Leave it out and the screen simply always offers the ask.
+     */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page (`Linking.openSettings()`). Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Rationale copy overrides. Anything left out keeps the kit default for this permission. */
+    copy?: Partial<PermissionScreenCopy>;
+    /**
+     * Name of a host illustration (the existing `illustrations` registry). Defaults to the
+     * permission name, so registering `illustrations={{ notifications: <MyBell/> }}` is enough. The
+     * kit ships a dependency-free default so the screen is never a blank box.
+     */
+    illustration?: string;
+    /**
+     * Fired once, with the outcome this screen produced. This is the seam for scheduling a local
+     * notification the moment a grant lands; the kit deliberately schedules nothing itself. It can
+     * never break the flow: a throw here is caught and the flow continues.
+     */
+    onResult?: (permission: WirePermissionKind, outcome: WirePermissionOutcome) => void;
+};
+
+/**
+ * permissionEvents - the canonical Wire names for a permission-priming funnel.
+ *
+ * Same job `purchaseEvents.ts` does for the subscription funnel and `analyticsEvent.ts` does for
+ * the onboarding funnel: every app was naming these itself (`push_permission`, `NOTIF_PROMPT`,
+ * `notifications_allowed`), so the same funnel read differently per tenant and no cross-app report
+ * was possible. These are the ONE set of names.
+ *
+ * They are `app_event` `question_key` values on the wire, exactly like `WIRE_PURCHASE_EVENTS`, so
+ * they are ALSO the exact strings a review / questionnaire firing trigger matches on. Never rename
+ * one: a rename silently unfires every trigger configured against the old string.
+ *
+ * PURE + dependency-free: no React, no React Native, no transport, no imports outside the type
+ * declarations - so an analytics-only bundle can carry the names without carrying a screen.
+ */
+
+declare const WIRE_PERMISSION_EVENTS: {
+    /** The priming screen became visible. The denominator for every rate below. */
+    readonly screenShown: "wire_permission_screen_shown";
+    /** The user tapped the primary, so the OS dialog is about to open. The rationale worked. */
+    readonly primerAccepted: "wire_permission_primer_accepted";
+    /** The OS granted it. */
+    readonly granted: "wire_permission_granted";
+    /** The OS refused it (a permanently blocked answer reports here too, with `status: "blocked"`). */
+    readonly denied: "wire_permission_denied";
+    /** The user took the secondary. The one native prompt was NOT spent. */
+    readonly skipped: "wire_permission_skipped";
+    /** A blocked user was redirected to the OS settings page. */
+    readonly settingsOpened: "wire_permission_settings_opened";
+};
+type WirePermissionEventName = (typeof WIRE_PERMISSION_EVENTS)[keyof typeof WIRE_PERMISSION_EVENTS];
+/** The canonical event name for a stage. Exhaustive over the union (a new stage is a compile error). */
+declare const permissionEventName: (stage: PermissionStage) => WirePermissionEventName;
+/**
+ * The small, non-PII props that ride a permission event. `permission` is always present so one
+ * funnel can be sliced per permission; `status` only appears when the OS actually answered, which
+ * is what keeps a `blocked` refusal distinguishable from a plain `denied` without a second event.
+ */
+declare const permissionEventProps: (permission: WirePermissionKind, status?: WirePermissionStatus) => Record<string, string>;
+/**
+ * Normalize whatever the host's `request` / `getStatus` actually returned.
+ *
+ * A native permission bridge is the host's code, and hosts return `"undetermined"`, `true`, or a
+ * whole Expo response object. Anything the kit does not recognise is treated as `denied`: it is the
+ * only reading that cannot invent a grant, and every outcome continues the flow anyway.
+ */
+declare const normalizePermissionStatus: (value: unknown) => WirePermissionStatus;
+
 /** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
 type WireOnboardingConfig = {
     /** Tenant API key (resolves the app server-side). */
@@ -263,6 +488,10 @@ type OnboardingResult = {
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
  *               (or handed off to `onError`). This is the client-side mirror of the
  *               backend's `llm_fallback` reliability event.
+ *  - `permission`: an injected permission screen moved (`shown` / `accepted` / `granted` /
+ *               `denied` / `skipped` / `settings`). Carries NO funnel weight: a permission screen
+ *               is not a question, so it never appears in `answers` and never gates completion.
+ *               `toAnalyticsEvent` maps it to the canonical `wire_permission_*` name.
  */
 type OnboardingEvent = {
     type: "started";
@@ -284,6 +513,12 @@ type OnboardingEvent = {
 } | {
     type: "fallback";
     reason: "backend" | "timeout";
+} | {
+    type: "permission";
+    permission: WirePermissionKind;
+    stage: PermissionStage;
+    /** What the OS actually answered, when it answered. Absent on `shown` / `accepted`. */
+    status?: WirePermissionStatus;
 };
 /**
  * Copy overrides for the kit's built-in (English) strings, so a host can localize
@@ -328,6 +563,48 @@ type WireOnboardingProps = {
     icons?: Record<string, React.ReactNode>;
     /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
     validators?: Record<string, StepValidator>;
+    /**
+     * PERMISSION SCREENS injected into the server-driven flow at a position you choose.
+     *
+     * The screen explains why the app wants the permission and asks the OS **only** on the primary
+     * tap. That priming pattern is not decoration: iOS grants an app exactly ONE native notification
+     * prompt for its whole lifetime, and firing it on mount spends it on a user who was told nothing.
+     * "Maybe later" advances the flow with the prompt still unspent.
+     *
+     * ```tsx
+     * import * as Notifications from "expo-notifications";
+     *
+     * <WireOnboarding
+     *   permissionScreens={[
+     *     {
+     *       permission: "notifications",
+     *       placement: "beforeEnd",
+     *       request: async () => {
+     *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+     *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+     *       },
+     *       getStatus: async () => {
+     *         const { status, canAskAgain } = await Notifications.getPermissionsAsync();
+     *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+     *       },
+     *       onResult: (_p, outcome) => { if (outcome === "granted") scheduleFirstReminder(); },
+     *     },
+     *   ]}
+     * />
+     * ```
+     *
+     * The kit adds NO dependency for this: it imports no `expo-notifications`, no
+     * `react-native-permissions`, nothing native. You inject `request`, exactly the way you hand the
+     * RevenueCat bridge real RevenueCat objects.
+     *
+     * A permission screen is NOT a question. It sends nothing to the backend, never enters the
+     * thread, mints no `key` / `slot_id`, and never appears in `onComplete`'s `answers`. Completion
+     * never blocks on a grant: grant, deny, skip and blocked all continue the flow. Each screen is
+     * shown at most once per session, and with `storage` that survives an app kill (a resumed session
+     * does not re-ask). Analytics ride `onEvent` (`type: "permission"`) and the canonical
+     * `wire_permission_*` events, stamped with the same `device_key` as the rest of the funnel.
+     */
+    permissionScreens?: PermissionScreenConfig[];
     /** Fired once the flow reaches its terminal StatusCard. */
     onComplete: (result: OnboardingResult) => void;
     /**
@@ -490,9 +767,12 @@ type OnboardingProgress = {
      * `answers.interests` silently becomes `answers.what_are_you_into_v2`, with no error anywhere. A
      * slot is the question's identity independent of its wording.
      *
-     * FULLY ADDITIVE AND CURRENTLY INERT: no server emits it yet. Every fallback is PER-CARD, so a
-     * thread that mixes slotted and unslotted cards (the real shape during a rollout) keys each one
-     * correctly, and a backend that never sends it produces byte-identical behaviour to 0.12.2.
+     * FULLY ADDITIVE, AND LIVE SINCE 2026-07-28 (server `47dae92`). The deployed server sends it on
+     * `progress` for every AI-GENERATED question, as `adaptive_<n>` 1-based over adaptive answers, and
+     * for a CONFIGURED question only when the tenant set one. Where the tenant set none the field is
+     * simply absent. Every fallback is PER-CARD, so a thread that mixes slotted and unslotted cards
+     * (the real shape during a rollout) keys each one correctly, and a backend or tenant that never
+     * sends it produces byte-identical behaviour to 0.12.2.
      */
     slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
@@ -530,7 +810,12 @@ declare const WIRE_ONBOARDING_EVENTS: {
 };
 type WireOnboardingEventName = (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
 type AnalyticsEvent = {
-    name: WireOnboardingEventName;
+    /**
+     * A permission screen maps to its own canonical `wire_permission_*` name rather than to an
+     * onboarding one: it is a distinct funnel (see `permissions/permissionEvents.ts`), and folding it
+     * into `wire_onboarding_turn` would make every permission rate unreadable.
+     */
+    name: WireOnboardingEventName | WirePermissionEventName;
     params?: Record<string, unknown>;
 };
 /**
@@ -1100,4 +1385,4 @@ declare const resetCurrentSessionId: () => void;
  */
 declare const ensureCurrentSessionId: () => string;
 
-export { USER_ID_MAX_LENGTH as $, AUTO_DEVICE_ID_PREFIX as A, resetEventQueueKeys as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, resolveAutoDeviceKey as F, setCurrentSessionId as G, toAnalyticsEvent as H, type WireOnboardingProps as I, type WireOnboardingConfig as J, type OnboardingEvent as K, type OnboardingCopy as L, type DeviceContext as M, type DeviceFormFactor as N, type OnboardingResult as O, EXTRA_KEY_PREFIX as P, type IdentifyOnboardingBinding as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, type IdentifyOnboardingOptions as T, type IdentityRecord as U, type IdentitySource as V, type WireUserContext as W, type IdentitySpace as X, type OnboardingProgress as Y, type ResolveUserContextOptions as Z, type ResolvedUserContext as _, type AnalyticsEvent as a, activationJoinContext as a0, collectDeviceContext as a1, hashEmailFnv1a as a2, hostIdentity as a3, hydrateAutoDeviceKey as a4, hydrateDeviceIdentity as a5, identifyOnboarding as a6, isWireScalar as a7, mintDeviceId as a8, namespaceExtra as a9, resetIdentityProvenance as aa, resolveIdentity as ab, resolveUserContext as ac, sanitizeUserId as ad, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };
+export { type IdentifyOnboardingOptions as $, AUTO_DEVICE_ID_PREFIX as A, resetEventQueueKeys as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, resolveAutoDeviceKey as F, setCurrentSessionId as G, toAnalyticsEvent as H, type WireOnboardingProps as I, type WireOnboardingConfig as J, type WirePermissionStatus as K, type WirePermissionOutcome as L, type OnboardingEvent as M, type OnboardingCopy as N, type OnboardingResult as O, type PermissionStage as P, type DeviceContext as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, type PermissionScreenConfig as T, type PermissionPlacement as U, DEFAULT_PERMISSION_COPY as V, type WireUserContext as W, type DeviceFormFactor as X, EXTRA_KEY_PREFIX as Y, GENERIC_PERMISSION_COPY as Z, type IdentifyOnboardingBinding as _, type AnalyticsEvent as a, type IdentityRecord as a0, type IdentitySource as a1, type IdentitySpace as a2, NOTIFICATIONS_PERMISSION_COPY as a3, type OnboardingProgress as a4, type PermissionScreenCopy as a5, type ResolveUserContextOptions as a6, type ResolvedUserContext as a7, USER_ID_MAX_LENGTH as a8, WIRE_PERMISSION_EVENTS as a9, type WirePermissionEventName as aa, type WirePermissionKind as ab, activationJoinContext as ac, collectDeviceContext as ad, hashEmailFnv1a as ae, hostIdentity as af, hydrateAutoDeviceKey as ag, hydrateDeviceIdentity as ah, identifyOnboarding as ai, isWireScalar as aj, mintDeviceId as ak, namespaceExtra as al, normalizePermissionStatus as am, permissionEventName as an, permissionEventProps as ao, resetIdentityProvenance as ap, resolveIdentity as aq, resolvePermissionCopy as ar, resolveUserContext as as, sanitizeUserId as at, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };