@wireai/activation 0.1.0

package/src/WireOnboarding.tsx

@@ -0,0 +1,248 @@
+/**
+ * WireOnboarding — the public host component. Drop it into a screen and it runs
+ * the whole AI onboarding: builds the A2A transport from `config`, wires the SDK
+ * provider with the themed cards, applies the theme, and renders the flow.
+ *
+ *   <WireOnboarding
+ *     config={{ apiKey, serverUrl, appId }}
+ *     theme={myBrandTheme}
+ *     validators={{ username: checkUsernameAvailable }}
+ *     onComplete={persist}
+ *     onSkip={skip}
+ *   />
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { WireAIProvider, type LocalLLMConfig } from "wireai-rn";
+import { OnboardingThemeProvider } from "./theme/ThemeContext";
+import { IllustrationProvider } from "./components/Illustration";
+import { defaultIllustrations } from "./illustrations/defaultIllustrations";
+import { LoadingScreen } from "./components/LoadingScreen";
+import { OnboardingFlow, DEFAULT_COPY } from "./OnboardingFlow";
+import { onboardingComponents } from "./cards";
+import { makeSessionId, reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
+import { collectDeviceContext, type DeviceContext } from "./device/deviceContext";
+import { sanitizeUserId } from "./identity/userIdentity";
+import {
+  clearPersistedSession,
+  loadPersistedSession,
+  sessionStorageKey,
+  DEFAULT_SESSION_TTL_MS,
+  type LoadedSession,
+} from "./session/persistedSession";
+import type { OnboardingResult, WireOnboardingProps } from "./types";
+
+export const WireOnboarding: React.FC<WireOnboardingProps> = ({
+  config,
+  theme,
+  components,
+  illustrations,
+  validators,
+  onComplete,
+  onSkip,
+  onError,
+  onEvent,
+  copy,
+  approxScreens,
+  startMessage = "start",
+  startTimeoutMs = 15_000,
+  fallbackFlow,
+  maxRetries = 1,
+  storage,
+  sessionTtlMs = DEFAULT_SESSION_TTL_MS,
+  persistKey,
+  userContext,
+  userId,
+}) => {
+  // 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
+  // result is a stable primitive, safe to feed the `llm` / `clientContext` memos directly (unlike
+  // the raw object props). Bound at three moments: session-start metadata (mount), an `identify`
+  // event on a mid-session change (late binding), and the `identifyOnboarding` helper post-flow.
+  const boundUserId = useMemo(() => sanitizeUserId(userId), [userId]);
+
+  // Privacy-label-neutral device snapshot, collected once per mount (no advertising IDs, no
+  // fingerprinting — see device/deviceContext.ts). `config.appVersion` is host-injected and
+  // merged in here (collectDeviceContext never sets it). Attached to BOTH the A2A session
+  // metadata and every client event so the backend can segment the funnel by device.
+  const device = useMemo<DeviceContext>(() => {
+    const collected = collectDeviceContext();
+    return config.appVersion ? { ...collected, appVersion: config.appVersion } : collected;
+  }, [config.appVersion]);
+
+  // Stable serialization of `userContext`. Hosts pass it INLINE (`userContext={{ … }}`, the
+  // documented usage), so the raw object identity changes every render. Feeding that raw object
+  // into the `llm` / `clientContext` memos below would make them unstable, and wireai-rn recreates
+  // its A2A adapter whenever the llmConfig identity changes — the adapter ctor resets `contextId`
+  // (node_modules/wireai-rn: `this.contextId = void 0`), so the server-learned session id is
+  // dropped and correlation breaks. We key both memos on the JSON string (compared by value) and
+  // reuse ONE normalized reference in the metadata + client-event paths.
+  const userContextKey = userContext ? JSON.stringify(userContext) : "";
+  const userContextStable = useMemo<Record<string, string | number | boolean> | undefined>(
+    () => (userContextKey ? (JSON.parse(userContextKey) as Record<string, string | number | boolean>) : undefined),
+    [userContextKey],
+  );
+
+  // The context payload shared by the A2A metadata + client-event paths. `userContext` +
+  // `userId` are host-injected and forwarded verbatim (the server sanitizes them). Omitted keys
+  // stay absent, so `dropped`/`client_fallback` events carry the user id when it's known.
+  const clientContext = useMemo(
+    () => ({ device, userContext: userContextStable, userId: boundUserId }),
+    [device, userContextStable, boundUserId],
+  );
+  // One stable session id per onboarding SESSION (not per mount). It's used as the
+  // client event `session_id` AND forwarded to the backend as `metadata.sessionId` so
+  // the server can adopt it as the A2A `contextId` — making client-reported events
+  // (`dropped`) correlate to the same session the server keys its own events by. See
+  // the SDK-correlation note in analytics/reportClientEvent.ts.
+  //
+  // Without `storage`: minted synchronously per mount (the original behavior).
+  // With `storage`: hydrated from the host-injected storage BEFORE the provider mounts
+  // (loader-gate below), so an app KILL mid-onboarding resumes the SAME backend session
+  // instead of minting a new one — which would count a phantom second `started` + a
+  // false "drop" in the analytics funnel. See session/persistedSession.ts.
+  const [session, setSession] = useState<LoadedSession | null>(() =>
+    storage ? null : { id: makeSessionId(), resumed: false },
+  );
+  const storageKey = persistKey ?? sessionStorageKey(config.appId);
+
+  useEffect(() => {
+    if (!storage || session) return;
+    // StrictMode/dev double-effect safe: the cancel flag drops the stale resolution.
+    // Dev-only caveat: on a brand-new first mint, StrictMode's double-invoke can persist
+    // then read the id back, surfacing a spurious `resumed: true`. Production is unaffected
+    // (double-invoke is dev-only) and it self-heals on the next mount.
+    let cancelled = false;
+    void loadPersistedSession(storage, storageKey, sessionTtlMs).then((loaded) => {
+      if (!cancelled) setSession(loaded);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, storageKey, sessionTtlMs, session]);
+
+  // Clear the cached id the moment the flow completes, so the next onboarding on this
+  // device starts a fresh session. Dropped/degraded paths deliberately do NOT clear —
+  // a dropped session must stay resumable within the TTL.
+  const handleComplete = useCallback(
+    (result: OnboardingResult) => {
+      if (storage) clearPersistedSession(storage, storageKey);
+      onComplete(result);
+    },
+    [storage, storageKey, onComplete],
+  );
+
+  const sessionId = session?.id ?? "";
+
+  // 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,
+  // whose ctor resets `contextId` (see the userContext note above) and drops the server-
+  // learned session id. Later changes ride EXCLUSIVELY on the `identify` effect below, which
+  // mutates the live session in place. `useRef` captures the first-render value once.
+  const startupUserIdRef = useRef<string | undefined>(boundUserId);
+
+  // Build the A2A LocalLLMConfig from the friendlier kit config. The backend
+  // resolves the app from the API key, so `model` (appId) is informational.
+  const llm = useMemo<LocalLLMConfig>(() => {
+    const baseUrl = config.serverUrl.replace(/\/$/, "");
+    return {
+      provider: "a2a",
+      baseUrl: `${baseUrl}/a2a`,
+      model: config.appId,
+      apiKey: config.apiKey,
+      // Carry the kit session id alongside any host attribution so it reaches the A2A
+      // request's `params.metadata` (the correlation seed; see note above), plus the
+      // names of the components this device can actually render — so the backend only
+      // emits cards the kit knows how to draw.
+      metadata: {
+        ...config.metadata,
+        sessionId,
+        supportedComponents: (components ?? onboardingComponents).map((c) => c.name),
+        // Device snapshot + host-injected user context ride the session-start metadata so the
+        // backend can segment the funnel. Old servers ignore these unknown keys (backward compat).
+        device,
+        ...(userContextStable ? { userContext: userContextStable } : {}),
+        // The session-start user id (from the ref) rides the session-start metadata so the
+        // server binds the session to a real user at creation. Reading the ref — not
+        // `boundUserId` — keeps this memo off the userId dependency, so a mid-session change
+        // does NOT recreate the adapter; it's bound by the `identify` effect below instead.
+        ...(startupUserIdRef.current ? { userId: startupUserIdRef.current } : {}),
+      },
+      timeoutMs: 60_000,
+    };
+  }, [config.serverUrl, config.appId, config.apiKey, config.metadata, sessionId, components, device, userContextStable]);
+
+  // Where client-reported events are POSTed (`/v1/events`). Same tenant creds as the flow.
+  const reportTarget = useMemo<ClientEventTarget>(
+    () => ({ serverUrl: config.serverUrl, apiKey: config.apiKey }),
+    [config.serverUrl, config.apiKey],
+  );
+
+  // LATE BINDING (mid-session): the user often registers DURING onboarding. When `userId`
+  // becomes known (or changes) after the session already started, emit an `identify` client
+  // event that attaches the id to the LIVE session, so the backend can map this in-flight
+  // session to the real user. On a FRESH mount the initial id already rode the session-start
+  // metadata, so we seed the "already bound" ref with it and only react to later CHANGES. On a
+  // RESUMED session the server-side record predates this mount and won't re-read start metadata,
+  // so we leave the seed empty to force an identify when a userId is present. Fire-and-forget.
+  const identifiedRef = useRef<string | undefined>(undefined);
+  const identifySeededRef = useRef(false);
+  useEffect(() => {
+    if (!session || !sessionId) return;
+    if (!identifySeededRef.current) {
+      identifySeededRef.current = true;
+      identifiedRef.current = session.resumed ? undefined : boundUserId;
+    }
+    if (!boundUserId || boundUserId === identifiedRef.current) return;
+    identifiedRef.current = boundUserId;
+    reportClientEvent(reportTarget, {
+      event_type: "identify",
+      session_id: sessionId,
+      user_id: boundUserId,
+    });
+  }, [session, sessionId, boundUserId, reportTarget]);
+
+  const cards = components ?? onboardingComponents;
+
+  // Loader-gate (hydration approach A): hold the entire provider subtree until the
+  // stored id resolves. `sessionId` is a dependency of the `llm` memo above, so mounting
+  // the provider with a throwaway id and swapping later would re-init it mid-flight.
+  // The read is timeout-capped in loadPersistedSession, so this gate is one storage
+  // read (~a frame), never an indefinite hold.
+  if (!session) {
+    return (
+      <OnboardingThemeProvider theme={theme}>
+        <LoadingScreen
+          title={copy?.restoringTitle ?? DEFAULT_COPY.restoringTitle}
+          hint={copy?.restoringHint ?? DEFAULT_COPY.restoringHint}
+        />
+      </OnboardingThemeProvider>
+    );
+  }
+
+  return (
+    <OnboardingThemeProvider theme={theme}>
+      <IllustrationProvider registry={{ ...defaultIllustrations, ...illustrations }}>
+        <WireAIProvider llm={llm} components={cards}>
+          <OnboardingFlow
+            validators={validators}
+            onComplete={handleComplete}
+            onSkip={onSkip}
+            onError={onError}
+            onEvent={onEvent}
+            copy={copy}
+            approxScreens={approxScreens}
+            startMessage={startMessage}
+            startTimeoutMs={startTimeoutMs}
+            fallbackFlow={fallbackFlow}
+            maxRetries={maxRetries}
+            reportTarget={reportTarget}
+            sessionId={sessionId}
+            resumed={session.resumed}
+            clientContext={clientContext}
+          />
+        </WireAIProvider>
+      </IllustrationProvider>
+    </OnboardingThemeProvider>
+  );
+};

package/src/analytics/analyticsEvent.ts

@@ -0,0 +1,69 @@
+/**
+ * Canonical analytics names for the onboarding funnel. The kit already emits a typed
+ * `OnboardingEvent` (`started | turn | error | retry | fallback`) — but one app logged them as
+ * `onboarding_*` and another as `AI_ONBOARDING_*`, so the same funnel reads differently per app.
+ * This maps the kit event to ONE canonical `wire_onboarding_*` name + params, and the app logs
+ * it through whatever transport it already has (Firebase, Amplitude, console). The app still
+ * owns the logger; only the NAMES are standardized.
+ *
+ *   <WireOnboarding
+ *     onEvent={(e) => { const a = toAnalyticsEvent(e); logEvent(a.name, a.params); }}
+ *     onComplete={(r) => { logEvent(WIRE_ONBOARDING_EVENTS.completed, { answers: Object.keys(r.answers).length }); persist(r); }}
+ *   />
+ *
+ * `completed` has no kit `OnboardingEvent` (the kit signals completion via `onComplete`, not
+ * `onEvent`) — the app logs it explicitly on `onComplete` using the constant below, so the
+ * funnel name stays canonical.
+ */
+import type { OnboardingEvent } from "../types";
+
+export const WIRE_ONBOARDING_EVENTS = {
+  started: "wire_onboarding_started",
+  /** A persisted session was restored after an app kill (fires instead of `started`). */
+  resumed: "wire_onboarding_resumed",
+  turn: "wire_onboarding_turn",
+  error: "wire_onboarding_error",
+  retry: "wire_onboarding_retry",
+  fallback: "wire_onboarding_fallback",
+  /** Logged by the host on `onComplete` (no matching kit `OnboardingEvent`). */
+  completed: "wire_onboarding_completed",
+} as const;
+
+export type WireOnboardingEventName =
+  (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
+
+export type AnalyticsEvent = {
+  name: WireOnboardingEventName;
+  params?: Record<string, unknown>;
+};
+
+/**
+ * Map a kit `OnboardingEvent` to its canonical `{ name, params }`. Exhaustive over the union
+ * (the `never` default makes a new event type a compile error here — intentional).
+ */
+export const toAnalyticsEvent = (event: OnboardingEvent): AnalyticsEvent => {
+  switch (event.type) {
+    case "started":
+      return { name: WIRE_ONBOARDING_EVENTS.started };
+    case "resumed":
+      return { name: WIRE_ONBOARDING_EVENTS.resumed };
+    case "turn":
+      return {
+        name: WIRE_ONBOARDING_EVENTS.turn,
+        params: { step: event.step, component: event.component },
+      };
+    case "error":
+      return { name: WIRE_ONBOARDING_EVENTS.error, params: { reason: event.reason } };
+    case "retry":
+      return {
+        name: WIRE_ONBOARDING_EVENTS.retry,
+        params: { reason: event.reason, attempt: event.attempt },
+      };
+    case "fallback":
+      return { name: WIRE_ONBOARDING_EVENTS.fallback, params: { reason: event.reason } };
+    default: {
+      const _exhaustive: never = event;
+      return _exhaustive;
+    }
+  }
+};

package/src/analytics/reportClientEvent.ts

@@ -0,0 +1,119 @@
+/**
+ * reportClientEvent — forward DEVICE-ONLY onboarding events to the Wire AI analytics
+ * backend (`POST {serverUrl}/v1/events`), completing the funnel for events the server
+ * can't observe on its own.
+ *
+ * The backend already records the server-observable funnel during the A2A flow
+ * (`session_started`, `screen_shown`, `answer_submitted`, `completed`, `llm_fallback`,
+ * and even `screen_skipped` — it derives that from the kit's skip sentinel). The one
+ * event no server request can capture is `dropped`: the user closing the app / unmounting
+ * the flow without finishing. That's what this reporter is for.
+ *
+ * Contract (server: routers/onboarding.py → analytics/events.py):
+ *   POST {serverUrl}/v1/events
+ *   Authorization: Bearer {apiKey}
+ *   { "events": [ { event_type, session_id, screen_index?, component?, question_key?,
+ *                   latency_ms?, meta?, device?, user_context? } ] }
+ * The server fills `app_id` + `environment` from the resolving key (never send app_id),
+ * and silently skips malformed events — one bad payload never fails the batch.
+ *
+ * ⚠️ Correlation: `session_id` MUST equal the A2A `contextId` the server uses to key the
+ * server-side events, or the funnel report (which groups by `session_id`) treats this as a
+ * phantom session. See `makeSessionId` + WireOnboarding for how the kit seeds it.
+ *
+ * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
+ * be able to break onboarding.
+ */
+import type { DeviceContext } from "../device/deviceContext";
+
+/** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
+ *  here would double-count. `screen_skipped` is included for completeness, but the kit does
+ *  NOT emit it — the backend already derives it from the skip sentinel (see OnboardingFlow).
+ *  `client_fallback` is emitted by the kit when the AI flow degrades to the static fallback,
+ *  so the dashboard's fallback-rate counts the whole-flow case (distinct from the server's
+ *  per-turn `llm_fallback`). The server back-fills a `session_started` for it if unseen.
+ *  This is the SINGLE fallback signal — hosts must NOT also report their own.
+ *  `identify` binds the host's opaque `user_id` to this `session_id` (late binding — the user
+ *  registered during/after onboarding). It carries no funnel weight; the server maps the
+ *  session to the user and back-fills a `session_started` if it never saw the session. */
+export type ClientEventType = "screen_skipped" | "dropped" | "client_fallback" | "identify";
+
+/** One client-reported event. Mirrors the server's `OnboardingEvent` (client-settable fields). */
+export type ClientEvent = {
+  event_type: ClientEventType;
+  /** Must match the server-side A2A contextId for this onboarding (see makeSessionId). */
+  session_id: string;
+  /** 0-based index of the screen the event refers to (matches server `screen_shown`). */
+  screen_index?: number;
+  component?: string;
+  question_key?: string;
+  latency_ms?: number;
+  /** JSON-stringified extras; the server stores it verbatim. */
+  meta?: string;
+  /**
+   * Privacy-label-neutral device snapshot (platform / form factor / locale / host appVersion).
+   * Sent as an object; the server sanitizes + persists it and derives a coarse country. Old
+   * servers ignore this unknown field — fully backward compatible. See device/deviceContext.ts.
+   */
+  device?: DeviceContext;
+  /**
+   * Host-injected, non-PII context (signup method, referral, plan, hashed user id). Old servers
+   * ignore it. MUST NOT contain PII like raw emails — see the README `userContext` section.
+   */
+  user_context?: Record<string, string | number | boolean>;
+  /**
+   * The host's OPAQUE PSEUDONYMOUS user id (their internal id, NOT an email/name). Required on
+   * `identify`, optional (rides along) on other events. Trimmed + capped at 128 chars host-side.
+   * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
+   */
+  user_id?: string;
+};
+
+/** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
+export type ClientEventTarget = {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+  serverUrl: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey: string;
+};
+
+/**
+ * A unique-per-onboarding session id. Used both as the client event `session_id` AND as the
+ * seed the kit forwards to the backend so the SERVER adopts it as the A2A `contextId` — making
+ * client and server agree (see WireOnboarding + the SDK-correlation note in the kit docs).
+ * No crypto dependency: timestamp + random is collision-safe for a single device's onboarding.
+ */
+export const makeSessionId = (): string =>
+  `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+
+/**
+ * POST one or more client events, fire-and-forget. A missing/invalid target, a build error,
+ * a missing `fetch`, or a network failure is swallowed — the call returns immediately and the
+ * request (if any) runs in the background.
+ */
+export const reportClientEvents = (
+  target: ClientEventTarget | undefined,
+  events: ClientEvent[],
+): void => {
+  if (!target?.serverUrl || events.length === 0) return;
+  try {
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ events }),
+    }).catch(() => {
+      // Network/transport error — analytics is best-effort, swallow.
+    });
+  } catch {
+    // URL construction, JSON serialization, or a missing fetch — swallow.
+  }
+};
+
+/** Convenience single-event wrapper around {@link reportClientEvents}. */
+export const reportClientEvent = (
+  target: ClientEventTarget | undefined,
+  event: ClientEvent,
+): void => reportClientEvents(target, [event]);

package/src/analytics/sendPreview.ts

@@ -0,0 +1,73 @@
+/**
+ * sendPreview — fire-and-forget PREFETCH of the next A2A turn, so the backend can warm
+ * its generation cache during a moment the user isn't waiting.
+ *
+ * Two callers, both firing the SAME text the real commit will send (the backend keys the
+ * preview cache on the raw message string, so a mismatch just misses harmlessly):
+ *   1. InterstitialCard — its answer is always "continue" (SDK-wrapped `My answer is: "continue"`),
+ *      warmed while the user reads the momentum screen.
+ *   2. Choice cards (Selection/ChipSelect) — warmed on selection-change with the exact
+ *      `I selected: ${JSON.stringify(value)}` the Continue tap will send, so the perceptibly-slow
+ *      first LLM question returns from cache. See OnboardingFlow.previewOnSelect.
+ *
+ * Contract (mirrors the A2A `message/send` shape, but a distinct `method`):
+ *   POST {serverUrl}/a2a
+ *   Authorization: Bearer {apiKey}
+ *   { jsonrpc:"2.0", id:<rand>, method:"message/preview",
+ *     params:{ message:{ role:"user", parts:[{ text }] }, contextId:<sessionId>,
+ *              metadata:{ sessionId } } }
+ *
+ * Fire-and-forget, exactly like reportClientEvent: never awaits, never throws into the UI —
+ * a prefetch that fails just means the real turn generates normally.
+ */
+
+/** Where to POST the preview. Same tenant creds as the flow (`serverUrl` + `apiKey`). */
+export type PreviewTarget = {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/a2a` is appended. */
+  serverUrl: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey: string;
+};
+
+/** What to preview: the session to warm and the message the user is about to send. */
+export type PreviewArgs = {
+  /** A2A contextId for this onboarding (the kit session id). */
+  sessionId: string;
+  /** The message that will be committed next (for interstitials, always "continue"). */
+  userMessage: string;
+};
+
+/**
+ * Warm the next turn's cache, fire-and-forget. A missing/invalid target, a build error,
+ * a missing `fetch`, or a network failure is swallowed — the call returns immediately and
+ * the request (if any) runs in the background.
+ */
+export const sendPreview = (
+  target: PreviewTarget | undefined,
+  { sessionId, userMessage }: PreviewArgs,
+): void => {
+  if (!target?.serverUrl) return;
+  try {
+    const url = `${target.serverUrl.replace(/\/$/, "")}/a2a`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: Math.floor(Math.random() * 1e9),
+        method: "message/preview",
+        params: {
+          message: { role: "user", parts: [{ text: userMessage }] },
+          contextId: sessionId,
+          metadata: { sessionId },
+        },
+      }),
+    }).catch(() => {
+      // Network/transport error — prefetch is best-effort, swallow.
+    });
+  } catch {
+    // URL construction, JSON serialization, or a missing fetch — swallow.
+  }
+};

package/src/attribution/attribution.ts

@@ -0,0 +1,46 @@
+/**
+ * attribution — forward install/ad attribution to the onboarding agent so it can tailor the
+ * first question by acquisition source (e.g. a paid-campaign install vs an organic one). The
+ * channel already exists: `WireOnboardingConfig.metadata` is merged into every A2A request by
+ * `WireOnboarding`. No production app populated it before; this gives every app a standard shape.
+ *
+ * The app reads its raw attribution (AppsFlyer / Branch / deferred deep link — an app concern,
+ * not the kit's) and passes the normalized result as `metadata`:
+ *
+ *   const config = wireConfigFromEnv({
+ *     appId: "morrow-self",
+ *     metadata: attributionMetadata({ source: conv.mediaSource, campaign: conv.campaign, isOrganic: conv.isOrganic }),
+ *   });
+ *
+ * The backend sees `metadata.attribution = { source, campaign, ... }`.
+ */
+
+/** Normalized acquisition attribution. All fields optional — pass what the SDK gives you. */
+export type OnboardingAttribution = {
+  /** Media source / network, e.g. "appsflyer", "branch", "organic". */
+  source?: string;
+  campaign?: string;
+  adset?: string;
+  ad?: string;
+  /** Deferred deep-link slug / path that routed the install. */
+  deepLink?: string;
+  isFirstLaunch?: boolean;
+  isOrganic?: boolean;
+  /** Escape hatch for SDK-specific fields not covered above. */
+  raw?: Record<string, unknown>;
+};
+
+/**
+ * Wrap attribution into the `{ attribution: {...} }` metadata the agent reads. Drops `undefined`
+ * fields so the request payload stays compact. Returns `{ attribution: {} }` for empty input
+ * (still a valid, harmless metadata object).
+ */
+export const attributionMetadata = (
+  a: OnboardingAttribution,
+): { attribution: Record<string, unknown> } => {
+  const attribution: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(a)) {
+    if (value !== undefined) attribution[key] = value;
+  }
+  return { attribution };
+};