@wireai/activation 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/OnboardingFlow.tsx

@@ -36,6 +36,17 @@ import { deriveAnswers } from "./utils/deriveAnswers";
 import { readProgress } from "./utils/readProgress";
 import { reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { sendPreview } from "./analytics/sendPreview";
+import { PermissionCardView, PERMISSION_CARD_NAME } from "./cards/PermissionCard";
+import { permissionEventName, permissionEventProps } from "./permissions/permissionEvents";
+import { selectDuePermissionScreen } from "./permissions/placement";
+import { resolvePermissionCopy } from "./permissions/permissionCopy";
+import type {
+  PermissionScreenConfig,
+  PermissionStage,
+  WirePermissionKind,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "./permissions/types";
 import type { DeviceContext } from "./device/deviceContext";
 import type { OnboardingCopy, OnboardingEvent, OnboardingResult, StepValidator } from "./types";
 
@@ -75,6 +86,25 @@ type OnboardingFlowProps = {
    * `started` so host funnels don't double-count the session.
    */
   resumed?: boolean;
+  /**
+   * Host-declared permission screens injected into this server-driven stream. See
+   * `permissions/types.ts`: the OS dialog is only ever reached from the primary tap.
+   */
+  permissionScreens?: PermissionScreenConfig[];
+  /**
+   * Screen ids already settled in THIS session, restored from `storage` by WireOnboarding so an
+   * app kill mid-flow does not re-ask. Empty (the default) means "nothing settled yet".
+   */
+  settledPermissions?: readonly string[];
+  /**
+   * True while that restore is still in flight. Permission screens are suppressed until it lands,
+   * because showing one before the record is read is exactly the re-ask the record prevents. The
+   * read is short (one storage get, timeout-capped) and cannot outlive the first card's round trip
+   * in practice, so this normally never shows up as a delay.
+   */
+  permissionsPending?: boolean;
+  /** Persist one settled screen id (fire-and-forget; WireOnboarding owns the storage). */
+  onPermissionSettled?: (id: string, outcome: WirePermissionOutcome) => void;
 };
 
 // The kit's per-question Skip sends this sentinel; the backend skips ONE question
@@ -112,6 +142,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   sessionId,
   resumed = false,
   clientContext,
+  permissionScreens,
+  settledPermissions,
+  permissionsPending = false,
+  onPermissionSettled,
 }) => {
   const { messages, error, isLoading, sendMessage, reset } = useWireAIThread();
   const makeActions = useWireAIAction(sendMessage);
@@ -156,6 +190,11 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const [timedOut, setTimedOut] = useState(false);
   const [validationError, setValidationError] = useState<string | undefined>();
   const [validating, setValidating] = useState(false);
+  // Permission screens settled during THIS mount, on top of whatever was restored from storage.
+  // A settled screen never comes back, which is the "shown exactly once" half of the contract.
+  const [locallySettledPermissions, setLocallySettledPermissions] = useState<string[]>([]);
+  const onPermissionSettledRef = useRef(onPermissionSettled);
+  onPermissionSettledRef.current = onPermissionSettled;
 
   const lastCard = useMemo<Message | undefined>(
     () => [...messages].reverse().find((m) => m.role === "assistant" && m.response?.action === "render"),
@@ -324,6 +363,51 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
     sendMessage(SKIP_ONE_SENTINEL);
   }, [isLoading, sendMessage]);
 
+  // ── Permission screens (host-injected, never server-driven in this release) ─────────────────
+  //
+  // Analytics for one moment of a permission screen. It rides the SAME plumbing as the rest of the
+  // funnel: an `app_event` on `/v1/events` whose `question_key` is the canonical `wire_permission_*`
+  // name (exactly how `WIRE_PURCHASE_EVENTS` reach the wire), carrying the same device snapshot and
+  // `user_context`, so the `device_key` join that makes every other number real covers these too.
+  // It is ALSO surfaced on `onEvent`, so a host keeps its own analytics without a second wiring.
+  //
+  // `screen_index` is the last card index shown, NOT a new one: a permission screen is not a
+  // question, so it must never introduce a screen index the server never emitted a `screen_shown`
+  // for. Nothing here can throw into the UI (reportClientEvent is fire-and-forget by contract).
+  const emitPermissionStage = useCallback(
+    (permission: WirePermissionKind, stage: PermissionStage, status?: WirePermissionStatus) => {
+      onEventRef.current?.({ type: "permission", permission, stage, status });
+      reportClientEvent(reportTargetRef.current, {
+        event_type: "app_event",
+        session_id: sessionIdRef.current,
+        question_key: permissionEventName(stage),
+        component: PERMISSION_CARD_NAME,
+        screen_index: lastScreenIndexRef.current >= 0 ? lastScreenIndexRef.current : undefined,
+        meta: JSON.stringify(permissionEventProps(permission, status)),
+        device: clientContextRef.current?.device,
+        user_context: clientContextRef.current?.userContext,
+        user_id: clientContextRef.current?.userId,
+      });
+    },
+    [],
+  );
+
+  // A screen is DONE: remember it (so it never returns), let the host persist that across a kill,
+  // and hand the outcome to `onResult`, the seam a host schedules its first local notification
+  // from. A throwing host callback is swallowed: the flow continues on every path, always.
+  const settlePermission = useCallback(
+    (id: string, screen: PermissionScreenConfig, outcome: WirePermissionOutcome) => {
+      setLocallySettledPermissions((prev) => (prev.includes(id) ? prev : [...prev, id]));
+      onPermissionSettledRef.current?.(id, outcome);
+      try {
+        screen.onResult?.(screen.permission, outcome);
+      } catch {
+        // A host's post-grant work (scheduling a reminder) must never break onboarding.
+      }
+    },
+    [],
+  );
+
   // Prefetch on SELECT — the fix for "the first AI question is always the slowest". Q1 is a
   // deterministic base card (instant); Q2 is the first LLM turn, and neither cache protects it
   // (flow-cache misses a novel answer combo, the provider prompt-cache is cold on the first
@@ -438,6 +522,53 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const total = progress.total ?? approxScreens;
   const isTerminal = response.action === "render" && response.component === "StatusCard";
 
+  // A permission screen sits IN FRONT of the card the flow was about to render (including the
+  // terminal recap, which is what `"beforeEnd"` means), and hands that card straight back once it
+  // settles. Nothing is sent to the backend, nothing is appended to the thread, and `step` is
+  // untouched, so the progress bar, the funnel, and `deriveAnswers` cannot tell it happened.
+  // Placement is resolved against the card ABOUT to render, because the stream length is
+  // server-driven; an `afterCard` the stream never reaches clamps to the terminal position.
+  const duePermission = permissionsPending
+    ? undefined
+    : selectDuePermissionScreen(
+        permissionScreens,
+        settledPermissions
+          ? [...settledPermissions, ...locallySettledPermissions]
+          : locallySettledPermissions,
+        { cardIndex: renderedCount - 1, isTerminal },
+      );
+
+  if (duePermission) {
+    const { screen, id } = duePermission;
+    const copy = resolvePermissionCopy(screen.permission, screen.copy);
+    return (
+      <OnboardingScaffold step={step} approxScreens={total}>
+        {/* The same shell + handoff every card uses; "spring" is the value-beat register the
+            InterstitialCard already wears, which is what this screen is. */}
+        <CardHandoff transitionKey={`permission:${id}`} variant="spring">
+          <PermissionCardView
+            key={id}
+            permission={screen.permission}
+            title={copy.title}
+            message={copy.message}
+            primaryLabel={copy.primaryLabel}
+            secondaryLabel={copy.secondaryLabel}
+            blockedTitle={copy.blockedTitle}
+            blockedMessage={copy.blockedMessage}
+            settingsLabel={copy.settingsLabel}
+            continueLabel={copy.continueLabel}
+            illustration={screen.illustration}
+            request={screen.request}
+            getStatus={screen.getStatus}
+            openSettings={screen.openSettings}
+            onStage={(stage, status) => emitPermissionStage(screen.permission, stage, status)}
+            onSettled={(outcome) => settlePermission(id, screen, outcome)}
+          />
+        </CardHandoff>
+      </OnboardingScaffold>
+    );
+  }
+
   // Terminal recap: show what the app will now do for the user (backend-authored),
   // and finish only when they tap the CTA.
   if (isTerminal) {

package/src/WireOnboarding.tsx

@@ -34,6 +34,12 @@ import {
   DEFAULT_SESSION_TTL_MS,
   type LoadedSession,
 } from "./session/persistedSession";
+import {
+  clearSettledPermissions,
+  loadSettledPermissions,
+  permissionStorageKey,
+  saveSettledPermissions,
+} from "./permissions/permissionMemory";
 import type { OnboardingResult, WireOnboardingProps } from "./types";
 import { warnInDev } from "./utils/warnInDev";
 
@@ -70,6 +76,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   userContext,
   userId,
   autoJoinKey = true,
+  permissionScreens,
 }) => {
   // The host's own opaque user id (trimmed + capped, NO PII) so onboarding sessions can be
   // reconciled to real users later. `sanitizeUserId` is a pure string transform → the memoized
@@ -321,6 +328,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     storage ? null : { id: makeSessionId(), resumed: false },
   );
   const storageKey = persistKey ?? sessionStorageKey(config.appId);
+  const permissionsKey = permissionStorageKey(config.appId);
 
   useEffect(() => {
     if (!storage || session) return;
@@ -351,14 +359,63 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // host that does not opt in lands on the byte-for-byte legacy clear-on-complete path.
   const handleComplete = useCallback(
     (result: OnboardingResult) => {
-      if (storage && shouldClearOnComplete(retainSessionOnComplete)) clearPersistedSession(storage, storageKey);
+      if (storage && shouldClearOnComplete(retainSessionOnComplete)) {
+        clearPersistedSession(storage, storageKey);
+        // The permission record is keyed by session id, so a stale one already reads as empty,
+        // this only keeps the adapter from carrying a dead entry forever.
+        clearSettledPermissions(storage, permissionsKey);
+      }
       onComplete(result);
     },
-    [storage, storageKey, retainSessionOnComplete, onComplete],
+    [storage, storageKey, permissionsKey, retainSessionOnComplete, onComplete],
   );
 
   const sessionId = session?.id ?? "";
 
+  // ── Permission-screen memory: "shown once per session", kept true across an app KILL ─────────
+  //
+  // The in-memory guard covers one mount. A resumed session (the whole point of `storage`) is a
+  // NEW mount of the SAME session, so without a persisted record it would re-show a screen the user
+  // already answered, and on the ask path that is a second attempt at a prompt iOS grants once.
+  //
+  // Unlike the auto-join key, this does NOT hold the loader gate: it feeds no `llm` dependency, so
+  // a late arrival cannot recreate the A2A adapter. The flow simply suppresses permission screens
+  // while `permissionsPending` is true, and that window closes long before the first card arrives
+  // (one timeout-capped storage read against a backend round trip).
+  const wantsPermissionMemory = Boolean(storage) && (permissionScreens?.length ?? 0) > 0;
+  const [settledPermissions, setSettledPermissions] = useState<string[] | undefined>(undefined);
+  useEffect(() => {
+    if (!wantsPermissionMemory || !storage || !sessionId || settledPermissions !== undefined) return;
+    let cancelled = false;
+    void loadSettledPermissions(storage, permissionsKey, sessionId).then((ids) => {
+      if (!cancelled) setSettledPermissions(ids);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [wantsPermissionMemory, storage, permissionsKey, sessionId, settledPermissions]);
+
+  // Persist the settled set as it grows. Fire-and-forget: a failed write only costs a re-ask on a
+  // resume, never a broken flow. Without `storage` there is nothing to write to and the
+  // in-memory guard alone carries the once-only contract for this mount.
+  // Mirrored in a ref so the handler can compute the next set WITHOUT doing the storage write
+  // inside a state updater (React invokes updaters twice under StrictMode; a write belongs outside).
+  const settledPermissionsRef = useRef<string[] | undefined>(undefined);
+  settledPermissionsRef.current = settledPermissions;
+  const handlePermissionSettled = useCallback(
+    (id: string) => {
+      const current = settledPermissionsRef.current ?? [];
+      if (current.includes(id)) return;
+      const next = [...current, id];
+      settledPermissionsRef.current = next;
+      setSettledPermissions(next);
+      if (storage && wantsPermissionMemory && sessionId) {
+        saveSettledPermissions(storage, permissionsKey, sessionId, next);
+      }
+    },
+    [storage, wantsPermissionMemory, permissionsKey, sessionId],
+  );
+
   // Session-start snapshot of the bound user id. It seeds the A2A `metadata.userId` so the
   // adapter is built ONCE with whatever id was known at session start. A mid-session userId
   // change must NOT flow through this memo — recreating `llm` recreates the A2A adapter,
@@ -478,6 +535,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
             sessionId={sessionId}
             resumed={session.resumed}
             clientContext={clientContext}
+            permissionScreens={permissionScreens}
+            settledPermissions={settledPermissions}
+            permissionsPending={wantsPermissionMemory && settledPermissions === undefined}
+            onPermissionSettled={handlePermissionSettled}
           />
         </WireAIProvider>
         </IconRegistryProvider>

package/src/analytics/analyticsEvent.ts

@@ -15,6 +15,11 @@
  * `onEvent`) — the app logs it explicitly on `onComplete` using the constant below, so the
  * funnel name stays canonical.
  */
+import {
+  permissionEventName,
+  permissionEventProps,
+  type WirePermissionEventName,
+} from "../permissions/permissionEvents";
 import type { OnboardingEvent } from "../types";
 
 export const WIRE_ONBOARDING_EVENTS = {
@@ -33,7 +38,12 @@ export type WireOnboardingEventName =
   (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
 
 export 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>;
 };
 
@@ -61,6 +71,11 @@ export const toAnalyticsEvent = (event: OnboardingEvent): AnalyticsEvent => {
       };
     case "fallback":
       return { name: WIRE_ONBOARDING_EVENTS.fallback, params: { reason: event.reason } };
+    case "permission":
+      return {
+        name: permissionEventName(event.stage),
+        params: permissionEventProps(event.permission, event.status),
+      };
     default: {
       const _exhaustive: never = event;
       return _exhaustive;

package/src/analytics/eventQueue.ts

@@ -238,6 +238,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     // from a REDUNDANT re-enqueue of the same instant. The de-dup signature below includes it, so
     // two identical events enqueued in the same millisecond still collapse (a re-render), while the
     // same action repeated later carries a fresh `ts` and survives. A caller-set `ts` is preserved.
+    // This stays a NUMBER in the queue (the de-dup signature depends on it); `buildEventsRequest`
+    // serializes it to the ISO8601 string the server requires at send time.
     if (stamped.ts === undefined) stamped.ts = Date.now();
     if (!env) return stamped;
     if (!stamped.device && env.device) stamped.device = env.device;

package/src/analytics/reportClientEvent.ts

@@ -77,15 +77,24 @@ export 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`). */
@@ -105,12 +114,46 @@ export type ClientEventTarget = {
 export const makeSessionId = (): string =>
   `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 
+/**
+ * Serialize the internal epoch-ms `ts` to the ISO8601 UTC string the WIRE requires.
+ *
+ * The server's event model declares `ts: str | None` and pydantic v2 does NOT coerce int → str, so
+ * a numeric `ts` fails per-event validation: the endpoint still answers HTTP 200, but with
+ * `{written: 0, skipped: N, errors: [{index, reason: "validation_error", field: "ts"}]}` — every
+ * `app_event` from `track()`/`screen()` silently discarded behind a green response.
+ *
+ * WHY HERE and not at the queue's `stamp()`: this is the single choke point all FOUR send paths go
+ * through (offline queue, fire-and-forget, awaitable, session-start). Converting here leaves the
+ * queue's numeric `ts` — and therefore its identical-JSON de-dup signature — exactly as it was, and
+ * it also converts the persisted 0.13.0 backlogs (which hold a numeric `ts`) on their way out.
+ *
+ * NEVER mutates the caller's event: an event that needs a change is copied. A string `ts` (a
+ * caller-set ISO stamp) and an absent `ts` pass through untouched. A non-finite (`NaN`/`Infinity`)
+ * or out-of-range number — the latter makes `toISOString` throw — drops the `ts` field from the
+ * copy rather than killing the whole batch.
+ */
+const toWireEvents = (events: ClientEvent[]): ClientEvent[] =>
+  events.map((event) => {
+    if (typeof event.ts !== "number") return event;
+    const { ts, ...rest } = event;
+    if (!Number.isFinite(ts)) return rest;
+    try {
+      return { ...rest, ts: new Date(ts).toISOString() };
+    } catch {
+      // Out-of-range epoch-ms — send the event WITHOUT a ts rather than lose the batch.
+      return rest;
+    }
+  });
+
 /**
  * The ONE place the `/v1/events` POST is described (url + method + headers + body). Both the
  * fire-and-forget {@link reportClientEvents} and the awaitable {@link reportClientEventsAwait}
  * build their request here so there is a SINGLE definition of the events transport — no second
  * copy of the endpoint path, headers, or envelope shape to drift. Returns `null` when there is
  * nothing to send (no target / no events) or serialization throws, so callers just bail.
+ *
+ * It is also where the internal epoch-ms `ts` becomes the wire's ISO8601 string — see
+ * {@link toWireEvents} for why the conversion belongs at this choke point.
  */
 export const buildEventsRequest = (
   target: { serverUrl: string; apiKey?: string } | undefined,
@@ -121,15 +164,18 @@ export const buildEventsRequest = (
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
+    const body = JSON.stringify({ events: toWireEvents(events) });
+    return { url, init: { method: "POST", headers, body } };
   } catch {
     // URL construction or JSON serialization failed — nothing to send.
     return null;
   }
 };
 
-/** What the `/v1/events` endpoint says in its 200 body. `errors` is the server's planned per-event
- *  reason list; it is read defensively because no deployed server sends it yet. */
+/** What the `/v1/events` endpoint says in its 200 body. The deployed server DOES send `errors[]`,
+ *  each entry carrying `{index, reason, field}` — `field` names the property that failed validation
+ *  (it is what identified the `ts` rejection), so it is folded into the reason string here. Still
+ *  read defensively: an older server sends no `errors` at all. */
 type EventsAck = { written?: number; skipped: number; reasons: string[] };
 
 /**
@@ -153,7 +199,17 @@ const readEventsAck = async (res: unknown): Promise<EventsAck | undefined> => {
     if (typeof skipped !== "number" || !Number.isFinite(skipped)) return undefined;
     const reasons = Array.isArray(body?.errors)
       ? body.errors
-          .map((e) => (e as { reason?: unknown } | null)?.reason)
+          .map((e) => {
+            const entry = e as { reason?: unknown; field?: unknown } | null;
+            const reason = entry?.reason;
+            if (typeof reason !== "string") return undefined;
+            // `field` is the whole point of a validation error — a bare "validation_error" sends the
+            // reader hunting; "validation_error (field: ts)" names the property the server refused.
+            const field = entry?.field;
+            return typeof field === "string" && field.length > 0
+              ? `${reason} (field: ${field})`
+              : reason;
+          })
           .filter((r): r is string => typeof r === "string")
       : [];
     return { written: typeof body?.written === "number" ? body.written : undefined, skipped, reasons };