@tribe-nest/forge 3.67.0 → 3.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.67.0",
+  "version": "3.74.0",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/_tests/formConsent.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { consentWithoutPhone, formConsentPayload } from "../useForms";
+import type { FormField } from "../../../types/models";
+
+const base = {
+  description: null,
+  placeholder: null,
+  isRequired: false,
+  options: null,
+  validation: null,
+  order: 0,
+};
+
+const phone: FormField = { ...base, id: "p1", type: "phone", label: "Phone" };
+const consent: FormField = {
+  ...base,
+  id: "c1",
+  type: "call_consent",
+  label: "Call me back",
+  config: { channel: "ai_call", phoneFieldId: "p1" },
+  consent: {
+    channel: "ai_call",
+    phoneFieldId: "p1",
+    locale: "de",
+    version: "2026-10-07.1",
+    text: "Ich bin damit einverstanden, ...",
+    textHash: "a".repeat(64),
+  },
+};
+const email: FormField = { ...base, id: "e1", type: "email", label: "Email" };
+
+describe("formConsentPayload", () => {
+  it("sends the hash of every consent box shown, in the language it was worded in", () => {
+    const payload = formConsentPayload([email, phone, consent], "en");
+    expect(payload?.locale).toBe("de");
+    expect(payload?.fields).toEqual([{ fieldId: "c1", textHash: "a".repeat(64) }]);
+  });
+
+  it("is undefined for a form without consent boxes", () => {
+    expect(formConsentPayload([email, phone], "en")).toBeUndefined();
+  });
+
+  it("leaves out a box the server sent no wording for (an old renderer cannot evidence it)", () => {
+    expect(formConsentPayload([{ ...consent, consent: null }], "en")).toBeUndefined();
+  });
+});
+
+describe("consentWithoutPhone", () => {
+  it("flags a ticked box whose phone field is empty", () => {
+    expect(consentWithoutPhone([phone, consent], { c1: "true" })).toBe("c1");
+  });
+
+  it("passes a ticked box with a number, and an unticked box without one", () => {
+    expect(consentWithoutPhone([phone, consent], { c1: "true", p1: "+4915112345678" })).toBeNull();
+    expect(consentWithoutPhone([phone, consent], { c1: "" })).toBeNull();
+  });
+});

package/src/data/queries/_tests/websiteAgentChoice.spec.ts

@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { parseChoiceEvent, streamAgentMessage, textWithoutChoice, type AgentStreamEvent } from "../useWebsiteAgent";
+
+/**
+ * Playbook choices in the website chat stream: a `choice` event is validated
+ * before a widget draws it, unknown events are ignored by the consumer, and a
+ * tapped option goes back as `{ choice: { stepId, value } }` instead of text.
+ */
+
+const sseResponse = (frames: string[]) => {
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const enc = new TextEncoder();
+      for (const f of frames) controller.enqueue(enc.encode(f));
+      controller.close();
+    },
+  });
+  return new Response(body, { status: 200, headers: { "Content-Type": "text/event-stream" } });
+};
+
+const frame = (data: unknown) => `data: ${typeof data === "string" ? data : JSON.stringify(data)}\n\n`;
+
+const choice = {
+  type: "choice",
+  stepId: "step-1",
+  question: "Which service?",
+  multiple: false,
+  options: [
+    { value: "svc-a", label: "Haircut", durationText: "45 min", priceText: "$40" },
+    { value: "svc-b", label: "Colour" },
+  ],
+  text: "1. Haircut, 45 min, $40\n2. Colour",
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("parseChoiceEvent", () => {
+  it("keeps a well formed choice with its card fields", () => {
+    expect(parseChoiceEvent(choice)).toEqual({
+      type: "choice",
+      stepId: "step-1",
+      question: "Which service?",
+      multiple: false,
+      options: [
+        { value: "svc-a", label: "Haircut", durationText: "45 min", priceText: "$40", description: undefined, imageUrl: undefined },
+        { value: "svc-b", label: "Colour", description: undefined, priceText: undefined, durationText: undefined, imageUrl: undefined },
+      ],
+      text: "1. Haircut, 45 min, $40\n2. Colour",
+    });
+  });
+
+  it("drops options without a value and falls back to the value as the label", () => {
+    const parsed = parseChoiceEvent({ ...choice, options: [{ label: "no value" }, { value: "x" }, null, 7] });
+    expect(parsed?.options).toEqual([
+      { value: "x", label: "x", description: undefined, priceText: undefined, durationText: undefined, imageUrl: undefined },
+    ]);
+  });
+
+  it("refuses a choice with no usable option, no step or the wrong type", () => {
+    expect(parseChoiceEvent({ ...choice, options: [] })).toBeNull();
+    expect(parseChoiceEvent({ ...choice, stepId: undefined })).toBeNull();
+    expect(parseChoiceEvent({ ...choice, type: "text_delta" })).toBeNull();
+    expect(parseChoiceEvent(null)).toBeNull();
+  });
+});
+
+describe("streamAgentMessage", () => {
+  const base = { apiUrl: "https://api.test", profileId: "p1", visitorId: "v1", conversationId: "c1" };
+
+  it("delivers a choice event between text deltas, and skips malformed and invalid frames", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        sseResponse([
+          frame({ type: "text_delta", delta: "Sure. " }),
+          frame("{not json"),
+          frame({ ...choice, options: [] }),
+          frame(choice),
+          frame({ type: "something_new", x: 1 }),
+          frame({ type: "turn_complete" }),
+        ]),
+      ),
+    );
+    const events: AgentStreamEvent[] = [];
+    await streamAgentMessage({ ...base, message: "book me in", onEvent: (ev) => events.push(ev) });
+
+    expect(events.map((e) => e.type)).toEqual(["text_delta", "choice", "something_new", "turn_complete"]);
+    const got = events[1];
+    expect(got.type === "choice" && got.options.map((o) => o.value)).toEqual(["svc-a", "svc-b"]);
+  });
+
+  it("sends a typed message as `message`", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(sseResponse([]));
+    vi.stubGlobal("fetch", fetchMock);
+    await streamAgentMessage({ ...base, message: "hello", onEvent: () => {} });
+
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.test/public/agent/conversations/c1/messages");
+    expect(JSON.parse(init.body)).toEqual({ profileId: "p1", visitorId: "v1", message: "hello" });
+  });
+
+  it("sends a tapped option as `choice`, with no message text", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(sseResponse([]));
+    vi.stubGlobal("fetch", fetchMock);
+    await streamAgentMessage({ ...base, choice: { stepId: "step-1", value: "svc-a" }, onEvent: () => {} });
+
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({
+      profileId: "p1",
+      visitorId: "v1",
+      choice: { stepId: "step-1", value: "svc-a" },
+    });
+  });
+
+  it("keeps reading when a consumer throws", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(sseResponse([frame(choice), frame({ type: "turn_complete" })])),
+    );
+    const seen: string[] = [];
+    await streamAgentMessage({
+      ...base,
+      message: "hi",
+      onEvent: (ev) => {
+        seen.push(ev.type);
+        if (ev.type === "choice") throw new Error("render failed");
+      },
+    });
+    expect(seen).toEqual(["choice", "turn_complete"]);
+  });
+});
+
+describe("textWithoutChoice", () => {
+  const plain = "Which service?\n1. Haircut, 45 min, $40\n2. Colour";
+
+  it("removes the choice text streamed after the agent's words", () => {
+    expect(textWithoutChoice(`Sure, here are the options.\n\n${plain}`, { text: plain })).toBe("Sure, here are the options.");
+  });
+
+  it("leaves nothing when the choice text is all that was streamed", () => {
+    expect(textWithoutChoice(plain, { text: plain })).toBe("");
+  });
+
+  it("keeps the words when they do not end with the exact choice text", () => {
+    const words = "Here they are: 1. Haircut";
+    expect(textWithoutChoice(words, { text: plain })).toBe(words);
+    expect(textWithoutChoice(`${plain} and more`, { text: plain })).toBe(`${plain} and more`);
+  });
+
+  it("keeps the words when there is no choice", () => {
+    expect(textWithoutChoice("Hello", undefined)).toBe("Hello");
+    expect(textWithoutChoice("Hello", { text: "" })).toBe("Hello");
+  });
+});

package/src/data/queries/_tests/websiteAgentEmbed.spec.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { agentApiPath, createAgentConversation, fetchAgentTranscript, streamAgentMessage } from "../useWebsiteAgent";
+import { countLinks } from "../../../ui/headless/agent/useAiAgent";
+
+/**
+ * The website agent through an embed key: every call goes to the key's
+ * routes, where the key (not the profileId in the body) decides the business.
+ */
+describe("the agent's routes through an embed key", () => {
+  const fetchSpy = vi.fn();
+  afterEach(() => {
+    fetchSpy.mockReset();
+    vi.unstubAllGlobals();
+  });
+
+  it("names the key's path, and the plain path without one", () => {
+    expect(agentApiPath(undefined)).toBe("/public/agent");
+    expect(agentApiPath(null)).toBe("/public/agent");
+    expect(agentApiPath("pk_embed_abc")).toBe("/public/embed/pk_embed_abc/agent");
+  });
+
+  it("creates the conversation, loads the transcript and streams through the key", async () => {
+    vi.stubGlobal("fetch", fetchSpy);
+    fetchSpy.mockResolvedValueOnce({ json: async () => ({ id: "c1" }) });
+    await createAgentConversation({ apiUrl: "https://api.test", profileId: "p1", visitorId: "v1", embedKey: "pk_embed_k" });
+    expect(fetchSpy.mock.calls[0][0]).toBe("https://api.test/public/embed/pk_embed_k/agent/conversations");
+
+    fetchSpy.mockResolvedValueOnce({ ok: false });
+    await fetchAgentTranscript({ apiUrl: "https://api.test", profileId: "p1", visitorId: "v1", conversationId: "c1", embedKey: "pk_embed_k" });
+    expect(fetchSpy.mock.calls[1][0]).toBe("https://api.test/public/embed/pk_embed_k/agent/conversations/c1?profileId=p1&visitorId=v1");
+
+    fetchSpy.mockResolvedValueOnce({ body: new Response("").body });
+    await streamAgentMessage({
+      apiUrl: "https://api.test",
+      profileId: "p1",
+      visitorId: "v1",
+      conversationId: "c1",
+      message: "hi",
+      onEvent: () => {},
+      embedKey: "pk_embed_k",
+    });
+    expect(fetchSpy.mock.calls[2][0]).toBe("https://api.test/public/embed/pk_embed_k/agent/conversations/c1/messages");
+  });
+});
+
+describe("countLinks", () => {
+  it("counts each distinct link once, Markdown or bare, and nothing else", () => {
+    expect(countLinks("No links here.")).toBe(0);
+    expect(countLinks("Pay here: [checkout](https://pay.example.com/l/abc) or https://pay.example.com/l/abc")).toBe(1);
+    expect(countLinks("Book https://a.example.com/x and read http://b.example.com.")).toBe(2);
+  });
+});

package/src/data/queries/_tests/websiteAgentTranscript.spec.ts

@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchAgentTranscript, restoreTranscriptMessages } from "../useWebsiteAgent";
+
+/**
+ * A returning visitor's chat: the saved conversation is loaded and drawn, and
+ * a saved playbook choice comes back as buttons that can be answered only
+ * while it is still the last message.
+ */
+
+const choice = {
+  type: "choice",
+  stepId: "step-1",
+  question: "Which service?",
+  multiple: false,
+  options: [
+    { value: "svc-a", label: "Haircut" },
+    { value: "svc-b", label: "Colour" },
+  ],
+  text: "Which service?\n1. Haircut\n2. Colour",
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("restoreTranscriptMessages", () => {
+  it("keeps user and assistant text in order and drops anything else", () => {
+    const out = restoreTranscriptMessages({
+      messages: [
+        { role: "user", text: "Hi" },
+        { role: "tool", text: "internal" },
+        { role: "assistant", text: "Hello, how can I help?" },
+        { role: "assistant", text: "" },
+        null,
+      ],
+    });
+    expect(out).toEqual([
+      { role: "user", text: "Hi" },
+      { role: "assistant", text: "Hello, how can I help?" },
+    ]);
+  });
+
+  it("leaves the last message's choice answerable", () => {
+    const out = restoreTranscriptMessages({
+      messages: [
+        { role: "user", text: "Book me in" },
+        { role: "assistant", text: `Sure.\n\n${choice.text}`, choice },
+      ],
+    });
+    expect(out[1].choice?.stepId).toBe("step-1");
+    expect(out[1].choice?.options.map((o) => o.value)).toEqual(["svc-a", "svc-b"]);
+    expect(out[1].closed).toBeUndefined();
+    expect(out[1].picked).toBeUndefined();
+  });
+
+  it("marks an answered choice with the option whose label the visitor sent, and closes it", () => {
+    const out = restoreTranscriptMessages({
+      messages: [
+        { role: "assistant", text: choice.text, choice },
+        { role: "user", text: "Colour" },
+        { role: "assistant", text: "Colour it is." },
+      ],
+    });
+    expect(out[0]).toMatchObject({ picked: "svc-b", closed: true });
+  });
+
+  it("closes a choice the visitor answered by typing, with nothing picked", () => {
+    const out = restoreTranscriptMessages({
+      messages: [
+        { role: "assistant", text: choice.text, choice },
+        { role: "user", text: "Actually, what are your hours?" },
+      ],
+    });
+    expect(out[0].closed).toBe(true);
+    expect(out[0].picked).toBeUndefined();
+  });
+
+  it("ignores a malformed saved choice and a body with no messages", () => {
+    expect(restoreTranscriptMessages({ messages: [{ role: "assistant", text: "x", choice: { type: "choice" } }] })).toEqual([
+      { role: "assistant", text: "x" },
+    ]);
+    expect(restoreTranscriptMessages(null)).toEqual([]);
+    expect(restoreTranscriptMessages({ id: null })).toEqual([]);
+  });
+});
+
+describe("fetchAgentTranscript", () => {
+  it("asks for the conversation as this visitor of this profile", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ id: "c-1", messages: [{ role: "user", text: "Hi" }] }), { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const saved = await fetchAgentTranscript({
+      apiUrl: "https://api.test",
+      token: "tok",
+      profileId: "p-1",
+      visitorId: "v-1",
+      conversationId: "c-1",
+    });
+    expect(saved).toEqual({ id: "c-1", messages: [{ role: "user", text: "Hi" }] });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.test/public/agent/conversations/c-1?profileId=p-1&visitorId=v-1");
+    expect(init.headers).toEqual({ authorization: "Bearer tok" });
+  });
+
+  it("is null when the conversation is not this visitor's any more", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: null, messages: [] }), { status: 200 })));
+    expect(
+      await fetchAgentTranscript({ apiUrl: "https://api.test", profileId: "p", visitorId: "v", conversationId: "c" }),
+    ).toBeNull();
+  });
+
+  it("is null on an error response", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("nope", { status: 400 })));
+    expect(
+      await fetchAgentTranscript({ apiUrl: "https://api.test", profileId: "p", visitorId: "v", conversationId: "c" }),
+    ).toBeNull();
+  });
+});

package/src/data/queries/useCheckoutLink.ts

@@ -0,0 +1,127 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import type { CreateOrderShippingRate } from "./useOrders";
+import { useForge } from "../../provider/ForgeProvider";
+
+/** What the pay page may show about a checkout link. Nothing about the buyer. */
+export type CheckoutLinkView = {
+  status: "open" | "paid" | "expired" | "cancelled";
+  /** The buyer paid after the link closed: nothing was confirmed and the money goes back. */
+  needsRefund: boolean;
+  item: { type: "event_ticket" | "product" | "booking"; title: string } | null;
+  /**
+   * A booking link only: every session it holds (ISO), the business's own time
+   * zone, and the service's booking page for picking another time.
+   */
+  booking?: {
+    sessions: { startsAt: string; endsAt: string }[];
+    timezone: string | null;
+    servicePath: string | null;
+  };
+  /**
+   * Every line the link holds (phase 2: a link can hold several). Absent on a
+   * server older than phase 2, where `item` and `quantity` are the one line.
+   */
+  items?: CheckoutLinkLine[];
+  quantity: number;
+  /** Minor units, in `currency`. Null when the link holds several lines. */
+  unitPriceCents: number | null;
+  /** The items, in minor units. Shipping is `shipping.costCents`, on top. */
+  totalCents: number;
+  currency: string;
+  /** Something on the link ships: the address and its shipping (phase 2). */
+  shipping?: CheckoutLinkShipping | null;
+  /** ISO. When the hold ends if nobody pays. */
+  expiresAt: string;
+};
+
+export type CheckoutLinkLine = {
+  type: "event_ticket" | "product" | "booking";
+  title: string;
+  quantity: number;
+  unitPriceCents: number;
+  /** A product that ships. */
+  physical: boolean;
+  /** Products only: what the store's shipping rates are asked for. */
+  productId?: string;
+  productVariantId?: string;
+};
+
+export type CheckoutLinkAddress = {
+  address1: string;
+  city: string;
+  stateCode: string;
+  countryCode: string;
+  zip: string;
+};
+
+export type CheckoutLinkShipping = {
+  required: true;
+  /** The address is in and the shipping priced: Pay may go ahead. */
+  set: boolean;
+  address: CheckoutLinkAddress | null;
+  /** The shipping in the link's currency, minor units; null until set. */
+  costCents: number | null;
+};
+
+export type CheckoutLinkFinalizeResult = {
+  /** `fulfilled`, `paid` (settling), `unpaid`, or `needs_refund`. */
+  outcome: string;
+  link: CheckoutLinkView;
+};
+
+/**
+ * Open a checkout link by its token (`POST /public/checkout-links/open`).
+ *
+ * A POST, and not refetched on focus: opening extends the link's hold to the
+ * payment window, which is a write the page should make once per visit.
+ */
+export function useCheckoutLink(token?: string | null) {
+  const { client, profileId } = useForge();
+  return useQuery<CheckoutLinkView>({
+    queryKey: ["checkout-link", token, profileId],
+    queryFn: async () => {
+      const res = await client.post("/public/checkout-links/open", { profileId, token });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!token,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+/**
+ * Give the delivery address and the picked rate for what a link ships
+ * (`POST /public/checkout-links/shipping`). The server prices the shipping
+ * again from the store's own rates and answers the link as `open` does.
+ */
+export function useSetCheckoutLinkShipping(token?: string | null) {
+  const { client, profileId } = useForge();
+  return useMutation<
+    CheckoutLinkView,
+    unknown,
+    { shippingAddress: CheckoutLinkAddress & { phone?: string }; selectedShippingRates: CreateOrderShippingRate[] }
+  >({
+    mutationFn: async (input) => {
+      const res = await client.post("/public/checkout-links/shipping", { profileId, token, ...input });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Settle a checkout link on the return page (`POST /public/checkout-links/finalize`).
+ * Idempotent on the server: a reload settles nothing twice.
+ */
+export function useCheckoutLinkFinalize(token?: string | null, enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<CheckoutLinkFinalizeResult>({
+    queryKey: ["checkout-link-finalize", token, profileId],
+    queryFn: async () => {
+      const res = await client.post("/public/checkout-links/finalize", { profileId, token });
+      return res.data;
+    },
+    enabled: enabled && !!profileId && !!client && !!token,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}

package/src/data/queries/useForms.ts

@@ -1,18 +1,23 @@
 import { useRef } from "react";
 import { fireServerMetaEvent, readMetaSignals } from "../../utils/metaEvents";
-import type { FormData, FormAnswerEntry } from "../../types/models";
+import type { FormData, FormAnswerEntry, FormField, ConsentChannel } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
+import { useForgeLocale } from "../../i18n";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
-/** A single public form (fields + conditional edges) by id. */
+/**
+ * A single public form (fields + conditional edges) by id. Consent boxes come
+ * back worded in the site's language.
+ */
 export function usePublicForm(formId?: string) {
   const { client, profileId } = useForge();
+  const locale = useForgeLocale();
 
   return useQuery<FormData>({
-    queryKey: ["publicForm", formId],
+    queryKey: ["publicForm", formId, locale],
     queryFn: async () => {
       const res = await client.get(`/public/forms/${formId}`, {
-        params: { profileId },
+        params: { profileId, locale },
       });
       return res.data;
     },
@@ -20,6 +25,68 @@ export function usePublicForm(formId?: string) {
   });
 }
 
+/** What a submit sends about the consent boxes it showed. */
+export type SubmitConsentPayload = {
+  locale: string;
+  pageUrl?: string;
+  fields: Array<{ fieldId: string; textHash: string }>;
+};
+
+/**
+ * The consent evidence for a submit: for every consent box the visitor was
+ * shown, the hash of the exact text beside it, plus the page. Undefined when
+ * the form has no consent boxes. Pass the fields that were actually shown.
+ */
+export function formConsentPayload(fields: FormField[], locale: string): SubmitConsentPayload | undefined {
+  const shown = fields.filter((f) => f.type === "call_consent" && f.consent?.textHash);
+  if (shown.length === 0) return undefined;
+  return {
+    locale: shown[0].consent?.locale ?? locale,
+    pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+    fields: shown.map((f) => ({ fieldId: f.id, textHash: f.consent!.textHash })),
+  };
+}
+
+/**
+ * A ticked consent box whose phone field holds no number cannot be evidenced:
+ * the consent is for a number. Returns the box's id, or null when all is well.
+ */
+export function consentWithoutPhone(fields: FormField[], answers: Record<string, string>): string | null {
+  for (const f of fields) {
+    if (f.type !== "call_consent" || answers[f.id] !== "true") continue;
+    const phoneFieldId = f.consent?.phoneFieldId ?? f.config?.phoneFieldId ?? null;
+    if (!phoneFieldId || !answers[phoneFieldId]) return f.id;
+  }
+  return null;
+}
+
+/** The locked consent text a business shows for a channel (newsletter signups). */
+export type ConsentWording = {
+  channel: ConsentChannel;
+  locale: string;
+  version: string;
+  text: string;
+  textHash: string;
+};
+
+/**
+ * The exact consent text for a channel, worded with the business's name in the
+ * site's language. Show `text` as it is and send `textHash` back with the tick.
+ */
+export function useConsentWording(channel: ConsentChannel | undefined) {
+  const { client, profileId } = useForge();
+  const locale = useForgeLocale();
+  return useQuery<ConsentWording>({
+    queryKey: ["consentWording", profileId, channel, locale],
+    queryFn: async () => {
+      const res = await client.get(`/public/consent/wording`, { params: { profileId, channel, locale } });
+      return res.data;
+    },
+    enabled: !!client && !!profileId && !!channel,
+    staleTime: 5 * 60 * 1000,
+  });
+}
+
 export interface SubmitPublicFormInput {
   answers: FormAnswerEntry[];
   /**
@@ -33,6 +100,8 @@ export interface SubmitPublicFormInput {
   respondentEmail?: string;
   respondentName?: string;
   metadata?: Record<string, unknown>;
+  /** The consent boxes shown, from `formConsentPayload`. */
+  consent?: SubmitConsentPayload;
 }
 
 function newIdempotencyKey(): string {

package/src/data/queries/useLeadMagnet.ts

@@ -22,7 +22,7 @@ export type LeadMagnetConfirmation = {
 
 /**
  * Confirms a lead-magnet subscription link and returns the lead magnet + profile.
- * The double opt-in confirm is a read (idempotent GET) — the download tracking
+ * The double opt-in confirm is a read (idempotent GET): the download tracking
  * POST stays a separate flow.
  */
 export function useLeadMagnetConfirm(leadMagnetId?: string, subscriberId?: string) {
@@ -63,9 +63,16 @@ export type JoinEmailListInput = {
   emailListId?: string;
   leadMagnetId?: string;
   firstName?: string;
-  /** @deprecated send `firstName` — kept only for backward compatibility. */
+  /** @deprecated send `firstName`: kept only for backward compatibility. */
   name?: string;
   phoneNumber?: string;
+  /**
+   * The consent boxes the signup showed, ticked or not, each with the hash of
+   * the exact text beside it (from `useConsentWording`).
+   */
+  consents?: Array<{ channel: "ai_call" | "sms" | "whatsapp"; checked: boolean; textHash?: string; locale?: string }>;
+  /** The page the signup was on, for the consent evidence. */
+  pageUrl?: string;
 };
 
 /** Join an email list / subscribe (may require double opt-in confirmation). */