@tribe-nest/forge 3.69.0 → 3.74.0

package/src/ui/headless/agent/useAiAgent.ts

@@ -1,85 +1,233 @@
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useForge } from "../../../provider/ForgeProvider";
 import {
   createAgentConversation,
+  fetchAgentTranscript,
   streamAgentMessage,
   useWebsiteAgentConfig,
+  type AgentChoiceEvent,
+  type AgentChoiceReply,
 } from "../../../data/queries/useWebsiteAgent";
 import { isPathExcluded } from "./pathExclusion";
 import { useCurrentPath } from "./useCurrentPath";
-import { getAgentVisitorId } from "./visitorId";
+import { getAgentVisitorId, getStoredConversationId, setStoredConversationId } from "./visitorId";
+
+/**
+ * What happened in the chat, for a host page's analytics. Never carries what
+ * anyone typed or was told: only that something happened, and how much.
+ */
+export type AiAgentEvent =
+  | { type: "chat_started" }
+  | { type: "message_sent"; choice: boolean }
+  | { type: "reply_received" }
+  | { type: "link_sent"; count: number }
+  | { type: "error" };
+
+export interface UseAiAgentOptions {
+  /** Called for every `AiAgentEvent`. */
+  onEvent?: (event: AiAgentEvent) => void;
+}
+
+/** Links in a reply: Markdown links and bare http(s) URLs, each counted once. */
+export function countLinks(text: string): number {
+  return new Set(text.match(/https?:\/\/[^\s)\]>"']+/g) ?? []).size;
+}
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
   text: string;
+  /** A playbook choice the assistant offered with this message. */
+  choice?: AgentChoiceEvent;
+  /** The value picked from `choice`, once one is. A picked choice cannot be picked again. */
+  picked?: string;
+  /** A restored choice the conversation already moved past; it shows, but cannot be answered. */
+  closed?: boolean;
 }
 
 /**
  * Headless controller for the website AI agent widget. Owns visitor identity,
  * the conversation (created lazily on first send), the message list, and the
  * streaming turn. A site can build any UI on top of this.
+ *
+ * A playbook step can offer a choice: it arrives on the assistant's message as
+ * `choice`, and `choose(stepId, value)` answers it. The pick is sent as a
+ * structured reply, not as text the model has to re-read, and shows in the
+ * conversation as the visitor's message.
+ *
+ * Inside an embed (`embedKey` on the provider) every call goes through the
+ * key's routes and no member token is ever sent: embeds have no sign-in.
  */
-export function useAiAgent() {
-  const { apiUrl, profileId, websiteId, token } = useForge();
+export function useAiAgent(options: UseAiAgentOptions = {}) {
+  const { apiUrl, profileId, websiteId, token: memberToken, embedKey } = useForge();
+  const token = embedKey ? null : memberToken;
   const config = useWebsiteAgentConfig();
   const path = useCurrentPath();
 
+  const onEventRef = useRef(options.onEvent);
+  onEventRef.current = options.onEvent;
+  const emit = useCallback((event: AiAgentEvent) => {
+    try {
+      onEventRef.current?.(event);
+    } catch {
+      /* a listener's error must not break the chat */
+    }
+  }, []);
+
   const [messages, setMessages] = useState<AiAgentMessage[]>([]);
   const [sending, setSending] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [restoring, setRestoring] = useState(false);
   const conversationIdRef = useRef<string | null>(null);
+  /** The saved conversation being loaded; a send waits for it so it lands in the same conversation. */
+  const restoreRef = useRef<Promise<void> | null>(null);
   const visitorId = useMemo(getAgentVisitorId, []);
 
+  // A returning visitor sees the conversation so far. The id is remembered per
+  // profile; one that is no longer theirs (or no longer exists) is forgotten.
+  useEffect(() => {
+    if (!apiUrl || !profileId || visitorId === "ssr") return;
+    const storedId = getStoredConversationId(profileId);
+    if (!storedId) return;
+    const controller = new AbortController();
+    setRestoring(true);
+    const run = fetchAgentTranscript({
+      apiUrl,
+      token,
+      profileId,
+      visitorId,
+      conversationId: storedId,
+      signal: controller.signal,
+      embedKey,
+    })
+      .then((saved) => {
+        if (controller.signal.aborted) return;
+        if (!saved) {
+          setStoredConversationId(profileId, null);
+          return;
+        }
+        conversationIdRef.current = saved.id;
+        // Never replace a turn the visitor started while this was loading.
+        setMessages((prev) => (prev.length ? prev : saved.messages));
+      })
+      .catch(() => {
+        /* offline or aborted: the chat starts empty and a send makes a new conversation */
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setRestoring(false);
+      });
+    restoreRef.current = run;
+    return () => {
+      controller.abort();
+      restoreRef.current = null;
+    };
+  }, [apiUrl, profileId, token, visitorId, embedKey]);
+
   const ensureConversation = useCallback(async (): Promise<string | null> => {
+    if (restoreRef.current) await restoreRef.current;
     if (conversationIdRef.current) return conversationIdRef.current;
     if (!apiUrl || !profileId) return null;
-    const res = await createAgentConversation({ apiUrl, token, profileId, websiteId, visitorId });
+    const res = await createAgentConversation({ apiUrl, token, profileId, websiteId, visitorId, embedKey });
     conversationIdRef.current = res.id;
+    setStoredConversationId(profileId, res.id);
+    if (res.id) emit({ type: "chat_started" });
     return res.id;
-  }, [apiUrl, profileId, websiteId, token, visitorId]);
+  }, [apiUrl, profileId, websiteId, token, visitorId, embedKey, emit]);
 
-  const send = useCallback(
-    async (text: string) => {
-      const trimmed = text.trim();
-      if (!trimmed || sending || !apiUrl || !profileId) return;
+  /** One turn: the visitor's bubble, an empty assistant bubble, then the stream into it. */
+  const runTurn = useCallback(
+    async (userText: string, input: { message: string } | { choice: AgentChoiceReply }) => {
+      if (!apiUrl || !profileId) return;
       setError(null);
       setSending(true);
-      setMessages((prev) => [...prev, { role: "user", text: trimmed }, { role: "assistant", text: "" }]);
+      setMessages((prev) => [...prev, { role: "user", text: userText }, { role: "assistant", text: "" }]);
+
+      const updateLast = (fn: (m: AiAgentMessage) => AiAgentMessage) =>
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last && last.role === "assistant") next[next.length - 1] = fn(last);
+          return next;
+        });
 
       try {
         const conversationId = await ensureConversation();
         if (!conversationId) {
           setError("The assistant is unavailable.");
-          setSending(false);
+          emit({ type: "error" });
           return;
         }
+        emit({ type: "message_sent", choice: "choice" in input });
+        let reply = "";
+        let failed = false;
         await streamAgentMessage({
           apiUrl,
           token,
           profileId,
           visitorId,
           conversationId,
-          message: trimmed,
+          embedKey,
+          ...input,
           onEvent: (ev) => {
             if (ev.type === "text_delta") {
-              setMessages((prev) => {
-                const next = [...prev];
-                const last = next[next.length - 1];
-                if (last && last.role === "assistant") next[next.length - 1] = { ...last, text: last.text + ev.delta };
-                return next;
-              });
+              reply += ev.delta;
+              updateLast((m) => ({ ...m, text: m.text + ev.delta }));
+            } else if (ev.type === "choice") {
+              // One choice per assistant message; a later one in the same turn replaces it.
+              updateLast((m) => ({ ...m, choice: ev, picked: undefined }));
             } else if (ev.type === "error") {
+              failed = true;
               setError(ev.message);
             }
           },
         });
+        if (failed) {
+          emit({ type: "error" });
+        } else {
+          emit({ type: "reply_received" });
+          const links = countLinks(reply);
+          if (links > 0) emit({ type: "link_sent", count: links });
+        }
       } catch {
         setError("Sorry, something went wrong. Please try again.");
+        emit({ type: "error" });
       } finally {
         setSending(false);
       }
     },
-    [apiUrl, profileId, token, visitorId, sending, ensureConversation],
+    [apiUrl, profileId, token, visitorId, embedKey, ensureConversation, emit],
+  );
+
+  const send = useCallback(
+    async (text: string) => {
+      const trimmed = text.trim();
+      if (!trimmed || sending) return;
+      await runTurn(trimmed, { message: trimmed });
+    },
+    [sending, runTurn],
+  );
+
+  /**
+   * Answers a choice. Only the newest offered choice can be answered, once;
+   * the picked option's label becomes the visitor's message.
+   */
+  const choose = useCallback(
+    async (stepId: string, value: string) => {
+      if (sending) return;
+      let index = -1;
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].choice) {
+          index = i;
+          break;
+        }
+      }
+      const target = index >= 0 ? messages[index] : undefined;
+      if (!target?.choice || target.choice.stepId !== stepId || target.picked !== undefined || target.closed) return;
+      const option = target.choice.options.find((o) => o.value === value);
+      if (!option) return;
+      setMessages((prev) => prev.map((m, i) => (i === index ? { ...m, picked: value } : m)));
+      await runTurn(option.label, { choice: { stepId, value } });
+    },
+    [sending, messages, runTurn],
   );
 
   // The artist can keep the assistant off named pages. Checked here rather than
@@ -96,8 +244,11 @@ export function useAiAgent() {
     canCall: !!config.data?.enabled && !!config.data?.voiceEnabled && !excluded,
     visitorId,
     messages,
+    /** True while a returning visitor's saved conversation loads. */
+    restoring,
     sending,
     error,
     send,
+    choose,
   };
 }

package/src/ui/headless/agent/visitorId.ts

@@ -18,3 +18,30 @@ export function getAgentVisitorId(): string {
     return `v_${Date.now()}`;
   }
 }
+
+const conversationKey = (profileId: string) => `forge_agent_conversation:${profileId}`;
+
+/**
+ * The visitor's open conversation with this profile's agent, so a reload or
+ * the next page shows the chat so far. Kept per profile: one browser can
+ * visit several sites on the same origin (previews, the platform domain).
+ */
+export function getStoredConversationId(profileId: string): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage.getItem(conversationKey(profileId));
+  } catch {
+    return null;
+  }
+}
+
+/** Remembers (or, with null, forgets) the visitor's conversation with this profile. */
+export function setStoredConversationId(profileId: string, conversationId: string | null): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (conversationId) window.localStorage.setItem(conversationKey(profileId), conversationId);
+    else window.localStorage.removeItem(conversationKey(profileId));
+  } catch {
+    /* storage blocked: the chat simply starts afresh next time */
+  }
+}

package/src/ui/headless/checkoutLink/useCheckoutLinkPayment.ts

@@ -1,6 +1,13 @@
 import { useCallback, useState } from "react";
 import { useQueryClient } from "@tanstack/react-query";
-import { useCheckoutLink, useCheckoutLinkFinalize } from "../../../data/queries/useCheckoutLink";
+import {
+  useCheckoutLink,
+  useCheckoutLinkFinalize,
+  useSetCheckoutLinkShipping,
+  type CheckoutLinkAddress,
+} from "../../../data/queries/useCheckoutLink";
+import type { CreateOrderShippingRate } from "../../../data/queries/useOrders";
+import { useForge } from "../../../provider/ForgeProvider";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 
 export interface UseCheckoutLinkPaymentOptions {
@@ -42,6 +49,30 @@ export function useCheckoutLinkPayment(token?: string | null, opts: UseCheckoutL
   });
 
   const [refusal, setRefusal] = useState<{ message: string; code: string | null; status: string | null } | null>(null);
+  const [shippingError, setShippingError] = useState<string | null>(null);
+  const { profileId } = useForge();
+  const shippingMutation = useSetCheckoutLinkShipping(token);
+
+  /**
+   * The delivery address and the rate picked for it (phase 2). The answer is
+   * the link as the page reads it, with the shipping priced by the server, so
+   * the page shows that rather than the client's own sum.
+   */
+  const saveShipping = useCallback(
+    async (input: { shippingAddress: CheckoutLinkAddress & { phone?: string }; selectedShippingRates: CreateOrderShippingRate[] }) => {
+      setShippingError(null);
+      try {
+        const view = await shippingMutation.mutateAsync(input);
+        queryClient.setQueryData(["checkout-link", token, profileId], view);
+        return true;
+      } catch (error) {
+        setShippingError((error as ApiError)?.response?.data?.message ?? "");
+        await queryClient.invalidateQueries({ queryKey: ["checkout-link", token] });
+        return false;
+      }
+    },
+    [shippingMutation, queryClient, token, profileId],
+  );
 
   const pay = useCallback(async () => {
     setRefusal(null);
@@ -71,6 +102,13 @@ export function useCheckoutLinkPayment(token?: string | null, opts: UseCheckoutL
     openPaystackCheckout: flow.openPaystackCheckout,
     /** The server's refusal of the last Pay, in its own words, with its code. */
     refusal,
+    /** Phase 2: give the delivery address and picked rate for what the link ships. */
+    saveShipping,
+    isSavingShipping: shippingMutation.isPending,
+    /** The server's refusal of the last address, in its own words ("" when it gave none). */
+    shippingError,
+    /** A payment exists on the page: the address can no longer be changed here. */
+    paymentStarted: !!flow.clientSecret || flow.canOpenPaystack,
     /** When the hold ends: the link's own deadline, as Pay last extended it. */
     holdExpiresAt:
       (flow.result as { link?: { expiresAt?: string } } | null)?.link?.expiresAt ?? link.data?.expiresAt ?? null,

package/src/ui/headless/forms/useEmailListForm.ts

@@ -1,6 +1,8 @@
 import { useState } from "react";
 import type { CountryCode } from "libphonenumber-js";
 import { useJoinEmailList } from "../../../data/queries/useLeadMagnet";
+import { useConsentWording } from "../../../data/queries/useForms";
+import type { ConsentChannel } from "../../../types/models";
 import { usePhoneInput } from "./usePhoneInput";
 
 export type FormStatus = "idle" | "submitting" | "success" | "error";
@@ -17,6 +19,13 @@ export interface UseEmailListFormOptions {
    * a number ends up stored under the wrong country.
    */
   defaultCountry?: CountryCode;
+  /**
+   * Offer consent boxes for these channels: `ai_call` (calls, including by an
+   * AI voice agent), `sms`, `whatsapp`. One box per channel, unticked, never
+   * required, with the business's locked wording. Turns the phone field on,
+   * because the consent is for a number.
+   */
+  consentChannels?: ConsentChannel[];
 }
 
 const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -38,8 +47,16 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
    * asked us not to. `usePhoneInput` asks for the country instead of guessing
    * it, which is the only point in the flow where it can be known.
    */
+  const channels = opts.consentChannels ?? [];
+  const wantsPhone = !!opts.includePhoneNumber || channels.length > 0;
+  // One query per channel, always called (hooks cannot be conditional).
+  const aiCall = useConsentWording(channels.includes("ai_call") ? "ai_call" : undefined);
+  const sms = useConsentWording(channels.includes("sms") ? "sms" : undefined);
+  const whatsapp = useConsentWording(channels.includes("whatsapp") ? "whatsapp" : undefined);
+  const wordings = { ai_call: aiCall.data, sms: sms.data, whatsapp: whatsapp.data };
+  const [consentTicks, setConsentTicks] = useState<Record<string, boolean>>({});
   const phone = usePhoneInput({
-    enabled: !!opts.includePhoneNumber,
+    enabled: wantsPhone,
     defaultCountry: opts.defaultCountry,
     mode: "messaging",
   });
@@ -57,11 +74,21 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
       setError("Please enter your name");
       return;
     }
-    if (opts.includePhoneNumber && !phone.e164) {
+    const anyTicked = channels.some((c) => consentTicks[c]);
+    if ((opts.includePhoneNumber || anyTicked) && !phone.e164) {
       phone.markTouched();
       setError("Please enter a valid phone number");
       return;
     }
+    // A box is only sent once its wording is on screen: the hash is the evidence.
+    const consents = channels
+      .filter((c) => !!wordings[c])
+      .map((c) => ({
+        channel: c,
+        checked: !!consentTicks[c],
+        textHash: wordings[c]!.textHash,
+        locale: wordings[c]!.locale,
+      }));
     setStatus("submitting");
     try {
       const data = await join.mutateAsync({
@@ -69,7 +96,10 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
         emailListId: opts.emailListId,
         leadMagnetId: opts.leadMagnetId,
         firstName: opts.includeName ? name.trim() : undefined,
-        phoneNumber: opts.includePhoneNumber ? (phone.e164 ?? undefined) : undefined,
+        phoneNumber: wantsPhone ? (phone.e164 ?? undefined) : undefined,
+        ...(consents.length > 0
+          ? { consents, pageUrl: typeof window !== "undefined" ? window.location.href : undefined }
+          : {}),
       });
       setRequiresConfirmation(!!data?.requiresConfirmation);
       setStatus("success");
@@ -87,6 +117,18 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
     setName,
     /** The phone field's controller. Hand it to <PhoneInput controller={...} />. */
     phone,
+    /** Whether a phone field should show (asked for, or needed by a consent box). */
+    showPhone: wantsPhone,
+    /**
+     * The consent boxes to show, in order: the channel, the exact text (show it
+     * as it is) and whether it is ticked. A box whose wording has not loaded is
+     * left out rather than shown with different words.
+     */
+    consentBoxes: channels
+      .filter((c) => !!wordings[c])
+      .map((c) => ({ channel: c, text: wordings[c]!.text, checked: !!consentTicks[c] })),
+    setConsent: (channel: ConsentChannel, checked: boolean) =>
+      setConsentTicks((prev) => ({ ...prev, [channel]: checked })),
     /** E.164 or empty. Kept for callers that only want the value. */
     phoneNumber: phone.e164 ?? "",
     /**

package/src/ui/headless/forms/useSectionedForm.ts

@@ -1,5 +1,11 @@
 import { useEffect, useMemo, useRef, useState } from "react";
-import { usePublicForm, useSubmitPublicForm } from "../../../data/queries/useForms";
+import {
+  usePublicForm,
+  useSubmitPublicForm,
+  formConsentPayload,
+  consentWithoutPhone,
+} from "../../../data/queries/useForms";
+import { translateForge, useForgeLocale } from "../../../i18n";
 import type { FormData, FormField, FormFieldEdge } from "../../../types/models";
 
 const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -98,7 +104,7 @@ function buildModel(form?: FormData) {
       sectionEdges.set(e.sourceSectionId, a);
     } else if (e.sourceFieldId && e.targetFieldId && e.condition) {
       // A field→field edge with a CONDITION is an in-page visibility rule ("show
-      // target when source matches") — treat scope "field"/"visibility" alike
+      // target when source matches"): treat scope "field"/"visibility" alike
       // since jumps don't apply to paged forms. A field→field edge WITHOUT a
       // condition is not a visibility rule and must NOT hide its target.
       const a = visByTarget.get(e.targetFieldId) ?? [];
@@ -116,11 +122,13 @@ function buildModel(form?: FormData) {
  * section→section branching (incl. submit), Back navigation, and submit. Bring
  * your own markup (or use the styled `<SectionedFormRenderer>`).
  *
- * For forms with no sections, prefer the flat `<FormRenderer>` — this hook has
+ * For forms with no sections, prefer the flat `<FormRenderer>`: this hook has
  * nothing to page through.
  */
 export function useSectionedForm(formId?: string) {
   const { data: rawForm, isLoading } = usePublicForm(formId);
+  const locale = useForgeLocale();
+  const t = (key: string) => translateForge(locale, key);
   const submitMutation = useSubmitPublicForm(formId);
 
   // Seeded per-mount option shuffle for quiz-mode forms (no-op otherwise).
@@ -135,7 +143,7 @@ export function useSectionedForm(formId?: string) {
   const [error, setError] = useState("");
   const [isCompleted, setIsCompleted] = useState(false);
   // Graded quiz result (null until submit + only for quiz-mode forms). Shaped by
-  // the server's reveal policy — see docs/archive/shipped/quizzes-certification-initiative.md.
+  // the server's reveal policy: see docs/archive/shipped/quizzes-certification-initiative.md.
   const [quizResult, setQuizResult] = useState<Record<string, unknown> | null>(null);
 
   // Start at the first section once the form loads.
@@ -194,13 +202,25 @@ export function useSectionedForm(formId?: string) {
     // Send answers only for active fields in the sections actually visited.
     const visited = stack.length ? stack : sections[0] ? [sections[0].id] : [];
     const entries: { fieldId: string; value: string | null }[] = [];
+    const shown: FormField[] = [];
     for (const sid of visited) {
       for (const f of fieldsBySection.get(sid) ?? []) {
-        if (isActive(f)) entries.push({ fieldId: f.id, value: answers[f.id] || null });
+        if (isActive(f)) {
+          entries.push({ fieldId: f.id, value: answers[f.id] || null });
+          shown.push(f);
+        }
       }
     }
+    if (consentWithoutPhone(shown, answers)) {
+      setError(t("forge.form_renderer.consent_phone_required"));
+      return;
+    }
     try {
-      const res = (await submitMutation.mutateAsync(entries)) as { result?: Record<string, unknown> | null };
+      const res = (await submitMutation.mutateAsync({
+        answers: entries,
+        // The consent boxes the visitor was actually shown, with their text hashes.
+        consent: formConsentPayload(shown, locale),
+      })) as { result?: Record<string, unknown> | null };
       if (res?.result) setQuizResult(res.result);
       setIsCompleted(true);
     } catch {

package/src/ui/index.ts

@@ -205,9 +205,9 @@ export { ChatComposer, type ChatComposerProps } from "./styled/chat/ChatComposer
 export { ChatThreadPanel, type ChatThreadPanelProps } from "./styled/chat/ChatThreadPanel";
 export { MessageBubble, type MessageBubbleProps } from "./styled/chat/MessageBubble";
 export { NewDmDialog, type NewDmDialogProps } from "./styled/chat/NewDmDialog";
-export { AiAgentWidget, type AiAgentWidgetProps } from "./styled/AiAgentWidget";
+export { AiAgentWidget, type AiAgentWidgetProps, type AiAgentWidgetEvent } from "./styled/AiAgentWidget";
 export { Markdown } from "./styled/Markdown";
-export { useAiAgent, type AiAgentMessage } from "./headless/agent/useAiAgent";
+export { useAiAgent, countLinks, type AiAgentMessage, type AiAgentEvent, type UseAiAgentOptions } from "./headless/agent/useAiAgent";
 // "Call us". The room hook (`useAgentCallRoom`) is deliberately not exported
 // here: it imports the media SDK, and this entry is on every page. A custom
 // call UI imports the media hooks from `@tribe-nest/forge/media` itself.