@wireai/activation 0.13.5 → 0.13.6-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.5",
+  "version": "0.13.6-next.0",
   "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

@@ -33,6 +33,7 @@ import { ErrorBlock } from "./components/ErrorBlock";
 import { CompletionView } from "./components/CompletionView";
 import { CardHandoff } from "./components/CardHandoff";
 import { deriveAnswers } from "./utils/deriveAnswers";
+import { readPlan } from "./utils/readPlan";
 import { readProgress } from "./utils/readProgress";
 import { reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { sendPreview } from "./analytics/sendPreview";
@@ -366,7 +367,13 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const handleFinish = useCallback(() => {
     if (finished.current) return;
     finished.current = true;
-    onCompleteRef.current({ answers: deriveAnswers(messages), raw: messages });
+    const result: OnboardingResult = { answers: deriveAnswers(messages), raw: messages };
+    // The plan rides a second DataPart on the AI path only; the static flow carries none. Setting
+    // the key ONLY when there is one keeps the no-plan result byte-identical to the pre-plan
+    // object — a host that inspects `Object.keys(result)` or `"plan" in result` sees no change.
+    const plan = readPlan(messages);
+    if (plan !== undefined) result.plan = plan;
+    onCompleteRef.current(result);
   }, [messages]);
 
   // Manual retry (the no-fallback ErrorBlock button): clear the degrade + counter so

package/src/types.ts

@@ -53,6 +53,19 @@ export type OnboardingResult = {
   answers: Record<string, unknown>;
   /** The raw message thread, for custom downstream parsing. */
   raw: Message[];
+  /**
+   * The backend's onboarding plan, when it sent one. Present ONLY on the AI path: a tenant running
+   * the static flow, or any run the server finished without a plan, leaves this `undefined` AND
+   * leaves the key off the result object entirely — so a host written before plans existed sees
+   * byte-identically what it always saw.
+   *
+   * ⚠️ The kit does NOT interpret this and does NOT validate it. It checks one structural fact (a
+   * plan is an object) and hands the payload straight through, unread, unlogged, and never attached
+   * to an analytics event. THE HOST MUST VALIDATE IT before applying it: the fields are
+   * backend-authored, they may gain new ones without a kit release, and what any of them mean is
+   * the host's decision, not the kit's.
+   */
+  plan?: unknown;
 };
 
 /**

package/src/utils/readPlan.ts

@@ -0,0 +1,74 @@
+/**
+ * readPlan — lift the backend's onboarding plan off the message thread.
+ *
+ * WHY IT EXISTS. On the AI path the server appends a SECOND A2A DataPart to the turn it finishes
+ * on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer
+ * already consumes. The kit carries that payload out through `OnboardingResult.plan` and stops
+ * there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
+ * attach it to any event — the plan is user-derived content, and deciding what it MEANS is the
+ * host's job (the kit/host boundary in `ai_rules/context_map.md`: the kit ends at the completion
+ * CTA).
+ *
+ * THE ONE THING IT IS ALLOWED TO REJECT is a structural fact: a plan is an object. A scalar, an
+ * array, or a missing payload is not a plan, and yields `undefined` so the host falls back to
+ * exactly its pre-plan behavior. Nothing below that line is checked: no field is required and no
+ * unknown field is stripped (the server's lenient path adds its own markers), because a kit-side
+ * schema would make the kit the thing that rejects a plan the host could have used.
+ *
+ * MALFORMED INPUT NEVER THROWS. This runs inside `handleFinish`, the single path to `onComplete`,
+ * so a throw here would cost the user the completion of an onboarding they already finished. Every
+ * step below is a runtime-guarded read.
+ *
+ * The static (non-AI) flow carries no plan at all. That path is unchanged and fully supported.
+ */
+import type { Message } from "wireai-rn";
+
+/**
+ * The read-back member the SDK surfaces for every A2A DataPart past the first, in wire order and
+ * uninterpreted. Declared HERE, structurally, because the installed `wireai-rn` peer (0.2.4) does
+ * not declare it on `Message` yet.
+ *
+ * TODO(re-pin): delete this local type and read the member straight off `Message` once a
+ * `wireai-rn` that declares it is published and the peer range is re-pinned. Until then the two
+ * shapes are equal by CONVENTION, not by the compiler, and `hasDataParts` below is what makes that
+ * safe at runtime. Deliberately NOT an `as` cast: a cast silences the compiler in BOTH directions,
+ * including the day the published type disagrees with this one.
+ */
+type WithDataParts = { dataParts: readonly unknown[] };
+
+/** The marker the server stamps on the plan DataPart. */
+const PLAN_PART_KIND = "onboarding_plan";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** RUNTIME proof that a value carries a `dataParts` ARRAY, before anything indexes into one. */
+const hasDataParts = (value: unknown): value is WithDataParts =>
+  isRecord(value) && Array.isArray(value.dataParts);
+
+/** The plan a single DataPart carries, or `undefined` when that part is not a well-formed plan. */
+const planFromPart = (part: unknown): unknown => {
+  if (!isRecord(part) || part.kind !== PLAN_PART_KIND) return undefined;
+  return isRecord(part.plan) ? part.plan : undefined;
+};
+
+/**
+ * The plan the backend sent, or `undefined` when it sent none (or sent something that is not a
+ * plan). Never throws.
+ *
+ * ORDERING, stated so it is not undefined behavior: the thread is scanned NEWEST TURN FIRST, so a
+ * thread carrying two plans resolves to the LAST one — the same turn `handleFinish` completes on.
+ * Within a single turn, wire order decides: the first well-formed plan part wins. A malformed part
+ * is skipped rather than treated as a terminator, so a broken payload can never shadow a good one.
+ */
+export const readPlan = (messages: readonly Message[]): unknown => {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!hasDataParts(message)) continue;
+    for (const part of message.dataParts) {
+      const plan = planFromPart(part);
+      if (plan !== undefined) return plan;
+    }
+  }
+  return undefined;
+};