@tribe-nest/forge 3.67.0 → 3.74.0

package/src/data/queries/useWebsiteAgent.ts

@@ -16,6 +16,29 @@ export interface WebsiteAgentConfig {
   excludedPaths?: string[];
   /** The agent also takes calls from the browser: show "Call us". */
   voiceEnabled?: boolean;
+  /** Through an embed only: the business the key belongs to. */
+  profileId?: string;
+  /** Through an embed only: the business theme with the key's overrides. */
+  theme?: EmbedAgentTheme;
+}
+
+/** The look an embed key gives the widget (see packages/embed). */
+export interface EmbedAgentTheme {
+  primary: string;
+  background: string;
+  text: string;
+  radius: number;
+  position: "bottom-right" | "bottom-left";
+  colorScheme: "business" | "light" | "dark";
+}
+
+/**
+ * Where the website agent's public routes live. A TribeNest site uses
+ * `/public/agent`; an embed on another site goes through its key, whose
+ * gate answers CORS for the key's allowed origins only.
+ */
+export function agentApiPath(embedKey?: string | null): string {
+  return embedKey ? `/public/embed/${encodeURIComponent(embedKey)}/agent` : "/public/agent";
 }
 
 /** Widget bootstrap config for the website. When `enabled` is false the widget
@@ -23,11 +46,11 @@ export interface WebsiteAgentConfig {
  * profile with several sites can give each its own; without it the backend
  * answers with the profile's default agent. */
 export function useWebsiteAgentConfig() {
-  const { client, profileId, websiteId } = useForge();
+  const { client, profileId, websiteId, embedKey } = useForge();
   return useQuery<WebsiteAgentConfig>({
-    queryKey: ["website-agent-config", profileId, websiteId ?? null],
+    queryKey: ["website-agent-config", profileId, websiteId ?? null, embedKey ?? null],
     queryFn: async () => {
-      const res = await client.get(`/public/agent/config`, {
+      const res = await client.get(`${agentApiPath(embedKey)}/config`, {
         params: { profileId, ...(websiteId ? { websiteId } : {}) },
       });
       return res.data;
@@ -37,12 +60,93 @@ export function useWebsiteAgentConfig() {
   });
 }
 
+/** One option of a playbook choice. Live items (services) carry their details, and render as cards. */
+export interface AgentChoiceOption {
+  value: string;
+  label: string;
+  description?: string;
+  priceText?: string;
+  durationText?: string;
+  imageUrl?: string;
+}
+
+/**
+ * A playbook Choose step, sent as its own event. `text` is the same choice
+ * rendered as plain text, for a widget that cannot draw buttons.
+ */
+export interface AgentChoiceEvent {
+  type: "choice";
+  stepId: string;
+  question: string;
+  multiple: false;
+  options: AgentChoiceOption[];
+  text: string;
+}
+
+/** A tapped option, sent back in place of a typed message. */
+export interface AgentChoiceReply {
+  stepId: string;
+  value: string;
+}
+
 export type AgentStreamEvent =
   | { type: "text_delta"; delta: string }
   | { type: "tool_use_start"; name: string }
   | { type: "tool_use_result"; name: string }
   | { type: "turn_complete" }
-  | { type: "error"; message: string };
+  | { type: "error"; message: string }
+  | AgentChoiceEvent;
+
+/**
+ * The words of an assistant message without the choice's plain text. The
+ * server streams `choice.text` as the turn's last `text_delta` ("\n\n" + text,
+ * or the text alone when nothing came before it) so a widget without buttons
+ * still shows the options. A widget that draws the buttons hides that tail so
+ * the options are not shown twice. Only an exact suffix is removed.
+ */
+export function textWithoutChoice(text: string, choice: Pick<AgentChoiceEvent, "text"> | null | undefined): string {
+  const tail = choice?.text;
+  if (!tail) return text;
+  if (text === tail) return "";
+  if (text.endsWith(`\n\n${tail}`)) return text.slice(0, text.length - tail.length - 2);
+  return text;
+}
+
+/**
+ * A choice event in a shape the widget can draw. Anything else, including a
+ * choice with no usable options, is dropped rather than crashing the chat.
+ */
+export function parseChoiceEvent(raw: unknown): AgentChoiceEvent | null {
+  if (!raw || typeof raw !== "object") return null;
+  const ev = raw as Record<string, unknown>;
+  if (ev.type !== "choice" || typeof ev.stepId !== "string" || !Array.isArray(ev.options)) return null;
+  const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
+  const options: AgentChoiceOption[] = [];
+  for (const o of ev.options) {
+    if (!o || typeof o !== "object") continue;
+    const opt = o as Record<string, unknown>;
+    const value = typeof opt.value === "string" ? opt.value : typeof opt.value === "number" ? String(opt.value) : null;
+    const label = str(opt.label) ?? value;
+    if (!value || !label) continue;
+    options.push({
+      value,
+      label,
+      description: str(opt.description),
+      priceText: str(opt.priceText),
+      durationText: str(opt.durationText),
+      imageUrl: str(opt.imageUrl),
+    });
+  }
+  if (!options.length) return null;
+  return {
+    type: "choice",
+    stepId: ev.stepId,
+    question: str(ev.question) ?? "",
+    multiple: false,
+    options,
+    text: str(ev.text) ?? "",
+  };
+}
 
 /**
  * Streams a chat turn over SSE using fetch (axios can't stream). Calls
@@ -54,17 +158,26 @@ export async function streamAgentMessage(params: {
   profileId: string;
   visitorId: string;
   conversationId: string;
-  message: string;
+  /** What the visitor typed. */
+  message?: string;
+  /** A tapped choice, sent instead of `message`. */
+  choice?: AgentChoiceReply;
   onEvent: (ev: AgentStreamEvent) => void;
   signal?: AbortSignal;
+  /** Through an embed: the key the request goes through. */
+  embedKey?: string | null;
 }): Promise<void> {
-  const res = await fetch(`${params.apiUrl}/public/agent/conversations/${params.conversationId}/messages`, {
+  const res = await fetch(`${params.apiUrl}${agentApiPath(params.embedKey)}/conversations/${params.conversationId}/messages`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       ...(params.token ? { authorization: `Bearer ${params.token}` } : {}),
     },
-    body: JSON.stringify({ profileId: params.profileId, visitorId: params.visitorId, message: params.message }),
+    body: JSON.stringify({
+      profileId: params.profileId,
+      visitorId: params.visitorId,
+      ...(params.choice ? { choice: params.choice } : { message: params.message }),
+    }),
     signal: params.signal,
   });
 
@@ -84,15 +197,96 @@ export async function streamAgentMessage(params: {
       if (!line) continue;
       const payload = line.slice(5).trim();
       if (!payload) continue;
+      let parsed: unknown;
       try {
-        params.onEvent(JSON.parse(payload) as AgentStreamEvent);
+        parsed = JSON.parse(payload);
       } catch {
-        /* ignore heartbeats / malformed frames */
+        continue; // a heartbeat or a malformed frame
+      }
+      if (!parsed || typeof parsed !== "object") continue;
+      // A choice is validated, so a widget never draws half an option list.
+      // Unknown types pass through; every consumer switches on `type` and
+      // ignores the rest.
+      const ev = (parsed as { type?: unknown }).type === "choice" ? parseChoiceEvent(parsed) : (parsed as AgentStreamEvent);
+      if (!ev) continue;
+      try {
+        params.onEvent(ev);
+      } catch {
+        /* a consumer's error must not end the stream */
       }
     }
   }
 }
 
+/** One message of a saved conversation, as `GET /public/agent/conversations/:id` returns it. */
+export interface AgentTranscriptMessage {
+  role: "user" | "assistant";
+  text: string;
+  /** The playbook choice this assistant message offered. */
+  choice?: AgentChoiceEvent;
+  /** The value the visitor picked, when the next message is one of the options' labels. */
+  picked?: string;
+  /** A choice that can no longer be answered: the conversation moved on past it. */
+  closed?: boolean;
+}
+
+/**
+ * A saved transcript in the shape the widget draws. Only user and assistant
+ * text survives; a saved choice is validated like a streamed one. A choice is
+ * answerable only while it is the last message: one the visitor answered is
+ * marked with the picked option (its label is the next user message), and one
+ * the conversation moved past is closed.
+ */
+export function restoreTranscriptMessages(raw: unknown): AgentTranscriptMessage[] {
+  const list = raw && typeof raw === "object" ? (raw as { messages?: unknown }).messages : undefined;
+  if (!Array.isArray(list)) return [];
+  const out: AgentTranscriptMessage[] = [];
+  for (const item of list) {
+    if (!item || typeof item !== "object") continue;
+    const m = item as Record<string, unknown>;
+    if (m.role !== "user" && m.role !== "assistant") continue;
+    const text = typeof m.text === "string" ? m.text : "";
+    const choice = m.role === "assistant" ? parseChoiceEvent(m.choice) : null;
+    if (!text && !choice) continue;
+    out.push({ role: m.role, text, ...(choice ? { choice } : {}) });
+  }
+  out.forEach((m, i) => {
+    if (!m.choice || i === out.length - 1) return;
+    const next = out[i + 1];
+    const picked = next?.role === "user" ? m.choice.options.find((o) => o.label === next.text.trim()) : undefined;
+    if (picked) m.picked = picked.value;
+    m.closed = true;
+  });
+  return out;
+}
+
+/**
+ * Loads a saved conversation. Null when it is not this visitor's (any more),
+ * so the caller can forget the stored id and start afresh.
+ */
+export async function fetchAgentTranscript(params: {
+  apiUrl: string;
+  token?: string | null;
+  profileId: string;
+  visitorId: string;
+  conversationId: string;
+  signal?: AbortSignal;
+  embedKey?: string | null;
+}): Promise<{ id: string; messages: AgentTranscriptMessage[] } | null> {
+  const qs = new URLSearchParams({ profileId: params.profileId, visitorId: params.visitorId });
+  const res = await fetch(
+    `${params.apiUrl}${agentApiPath(params.embedKey)}/conversations/${encodeURIComponent(params.conversationId)}?${qs.toString()}`,
+    {
+      headers: params.token ? { authorization: `Bearer ${params.token}` } : {},
+      signal: params.signal,
+    },
+  );
+  if (!res.ok) return null;
+  const body = (await res.json()) as { id?: unknown } | null;
+  if (!body || typeof body.id !== "string") return null;
+  return { id: body.id, messages: restoreTranscriptMessages(body) };
+}
+
 /** Creates a visitor conversation, returning its id (or null when disabled). */
 export async function createAgentConversation(params: {
   apiUrl: string;
@@ -100,8 +294,9 @@ export async function createAgentConversation(params: {
   profileId: string;
   websiteId?: string;
   visitorId: string;
+  embedKey?: string | null;
 }): Promise<{ id: string | null; requiresLogin?: boolean }> {
-  const res = await fetch(`${params.apiUrl}/public/agent/conversations`, {
+  const res = await fetch(`${params.apiUrl}${agentApiPath(params.embedKey)}/conversations`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",

package/src/i18n/de.json

@@ -191,6 +191,7 @@
   "forge.ai_agent_call_room.speaking": "{name} spricht",
   "forge.ai_agent_widget.aria_call": "Ruf uns an",
   "forge.ai_agent_widget.aria_close": "Schließen",
+  "forge.ai_agent_widget.aria_message": "Nachricht",
   "forge.ai_agent_widget.aria_open": "Chat-Assistent öffnen",
   "forge.ai_agent_widget.aria_show_call": "Anruf anzeigen",
   "forge.ai_agent_widget.call_again": "Erneut anrufen",
@@ -204,6 +205,7 @@
   "forge.ai_agent_widget.call_error_unavailable": "Anrufe sind gerade nicht möglich.",
   "forge.ai_agent_widget.call_hang_up": "Auflegen",
   "forge.ai_agent_widget.call_try_again": "Erneut versuchen",
+  "forge.ai_agent_widget.choice_label": "Eine Option wählen",
   "forge.ai_agent_widget.default_greeting": "Hi! Frag mich, was du willst.",
   "forge.ai_agent_widget.default_title": "Assistent",
   "forge.ai_agent_widget.input_placeholder": "Nachricht schreiben…",
@@ -713,6 +715,37 @@
   "forge.checkout_confirmation.total": "Gesamt",
   "forge.checkout_confirmation.total_paid": "Bezahlt gesamt",
   "forge.checkout_confirmation.view_orders": "Bestellungen ansehen",
+  "forge.checkout_link_payment.browse_store": "Zum Shop",
+  "forge.checkout_link_payment.cancelled_body": "Das Unternehmen hat diesen Link zurückgezogen. Es wurde nichts berechnet.",
+  "forge.checkout_link_payment.cancelled_title": "Dieser Link ist nicht mehr verfügbar",
+  "forge.checkout_link_payment.each": "je {price}",
+  "forge.checkout_link_payment.ended_body": "Wir konnten dies nicht länger für Sie reservieren, deshalb ist es wieder im Verkauf. Es wurde nichts berechnet.",
+  "forge.checkout_link_payment.ended_title": "Diese Reservierung ist abgelaufen",
+  "forge.checkout_link_payment.held_until": "Für Sie reserviert bis {time}",
+  "forge.checkout_link_payment.hold_noun": "Artikel",
+  "forge.checkout_link_payment.hold_noun_booking": "diesen Termin",
+  "forge.checkout_link_payment.not_found_body": "Dieser Link ist ungültig. Prüfen Sie die Adresse in Ihrer E-Mail.",
+  "forge.checkout_link_payment.not_found_title": "Link nicht gefunden",
+  "forge.checkout_link_payment.other_times": "Anderen Termin wählen",
+  "forge.checkout_link_payment.paid_body": "Vielen Dank. Die Details sind unterwegs an Ihre E-Mail-Adresse.",
+  "forge.checkout_link_payment.paid_title": "Zahlung erhalten",
+  "forge.checkout_link_payment.pay_amount": "{amount} bezahlen",
+  "forge.checkout_link_payment.payment_unavailable": "Die Zahlung ist gerade nicht möglich. Bitte versuchen Sie es gleich noch einmal.",
+  "forge.checkout_link_payment.preparing_payment": "Zahlung wird vorbereitet…",
+  "forge.checkout_link_payment.quantity": "Anzahl: {quantity}",
+  "forge.checkout_link_payment.title": "Für Sie reserviert",
+  "forge.checkout_link_payment.too_late_body": "Ihre Zahlung ist nach dem Ende dieser Reservierung eingegangen, deshalb wurde nichts gebucht. Ihre Zahlung wird erstattet.",
+  "forge.checkout_link_payment.too_late_title": "Ihre Zahlung wird erstattet",
+  "forge.checkout_link_payment.total": "Gesamt",
+  "forge.checkout_link_payment.try_again": "Erneut versuchen",
+  "forge.checkout_link_payment.unpaid_body": "Ihre Zahlung ist nicht durchgegangen, und es wurde nichts berechnet. Ihre Reservierung besteht weiter, Sie können es erneut versuchen.",
+  "forge.checkout_link_payment.unpaid_title": "Zahlung nicht abgeschlossen",
+  "forge.checkout_link_payment.shipping_title": "Lieferadresse",
+  "forge.checkout_link_payment.ship_to": "Lieferung an",
+  "forge.checkout_link_payment.change_address": "Ändern",
+  "forge.checkout_link_payment.use_shipping": "Diesen Versand nutzen",
+  "forge.checkout_link_payment.shipping": "Versand",
+  "forge.checkout_link_payment.shipping_unavailable": "Für diese Adresse konnten wir keinen Versand finden. Prüfe sie und versuche es erneut.",
   "forge.coaching_booking.aria_close": "Schließen",
   "forge.coaching_booking.aria_next_month": "Nächster Monat",
   "forge.coaching_booking.aria_next_week": "Nächste Woche",
@@ -2438,5 +2471,6 @@
   "forge.work_task_detail.fallback_title": "Aufgabe",
   "forge.work_task_detail.status_done": "Erledigt",
   "forge.work_task_detail.status_open": "Offen",
-  "forge.work_token_report.invalid_link": "Dieser Berichtslink ist ungültig oder abgelaufen."
+  "forge.work_token_report.invalid_link": "Dieser Berichtslink ist ungültig oder abgelaufen.",
+  "forge.form_renderer.consent_phone_required": "Geben Sie Ihre Telefonnummer ein, um Anrufen oder Nachrichten zuzustimmen."
 }

package/src/i18n/en.json

@@ -191,6 +191,7 @@
   "forge.ai_agent_call_room.speaking": "{name} is speaking",
   "forge.ai_agent_widget.aria_call": "Call us",
   "forge.ai_agent_widget.aria_close": "Close",
+  "forge.ai_agent_widget.aria_message": "Message",
   "forge.ai_agent_widget.aria_open": "Open chat assistant",
   "forge.ai_agent_widget.aria_show_call": "Show the call",
   "forge.ai_agent_widget.call_again": "Call again",
@@ -204,6 +205,7 @@
   "forge.ai_agent_widget.call_error_unavailable": "Calls are not available right now.",
   "forge.ai_agent_widget.call_hang_up": "Hang up",
   "forge.ai_agent_widget.call_try_again": "Try again",
+  "forge.ai_agent_widget.choice_label": "Choose an option",
   "forge.ai_agent_widget.default_greeting": "Hi! Ask me anything.",
   "forge.ai_agent_widget.default_title": "Assistant",
   "forge.ai_agent_widget.input_placeholder": "Type a message…",
@@ -713,6 +715,37 @@
   "forge.checkout_confirmation.total": "Total",
   "forge.checkout_confirmation.total_paid": "Total paid",
   "forge.checkout_confirmation.view_orders": "View your orders",
+  "forge.checkout_link_payment.browse_store": "Browse the store",
+  "forge.checkout_link_payment.cancelled_body": "The business withdrew this link. Nothing was charged.",
+  "forge.checkout_link_payment.cancelled_title": "This link is no longer available",
+  "forge.checkout_link_payment.each": "{price} each",
+  "forge.checkout_link_payment.ended_body": "We could not hold this for you any longer, so it went back on sale. Nothing was charged.",
+  "forge.checkout_link_payment.ended_title": "This reservation has ended",
+  "forge.checkout_link_payment.held_until": "Held for you until {time}",
+  "forge.checkout_link_payment.hold_noun": "items",
+  "forge.checkout_link_payment.hold_noun_booking": "this time",
+  "forge.checkout_link_payment.not_found_body": "This link is not valid. Check the address in your email.",
+  "forge.checkout_link_payment.not_found_title": "Link not found",
+  "forge.checkout_link_payment.other_times": "Pick another time",
+  "forge.checkout_link_payment.paid_body": "Thank you. The details are on their way to your email.",
+  "forge.checkout_link_payment.paid_title": "Payment received",
+  "forge.checkout_link_payment.pay_amount": "Pay {amount}",
+  "forge.checkout_link_payment.payment_unavailable": "Payment is not available right now. Please try again in a moment.",
+  "forge.checkout_link_payment.preparing_payment": "Preparing payment…",
+  "forge.checkout_link_payment.quantity": "Quantity: {quantity}",
+  "forge.checkout_link_payment.title": "Held for you",
+  "forge.checkout_link_payment.too_late_body": "Your payment arrived after this reservation had ended, so nothing was booked. Your payment will be refunded.",
+  "forge.checkout_link_payment.too_late_title": "Your payment will be refunded",
+  "forge.checkout_link_payment.total": "Total",
+  "forge.checkout_link_payment.try_again": "Try again",
+  "forge.checkout_link_payment.unpaid_body": "Your payment did not go through, and nothing was charged. Your reservation is still held, so you can try again.",
+  "forge.checkout_link_payment.unpaid_title": "Payment not completed",
+  "forge.checkout_link_payment.shipping_title": "Delivery address",
+  "forge.checkout_link_payment.ship_to": "Delivering to",
+  "forge.checkout_link_payment.change_address": "Change",
+  "forge.checkout_link_payment.use_shipping": "Use this shipping",
+  "forge.checkout_link_payment.shipping": "Shipping",
+  "forge.checkout_link_payment.shipping_unavailable": "We could not get shipping for this address. Check it and try again.",
   "forge.coaching_booking.aria_close": "Close",
   "forge.coaching_booking.aria_next_month": "Next month",
   "forge.coaching_booking.aria_next_week": "Next week",
@@ -2438,5 +2471,6 @@
   "forge.work_task_detail.fallback_title": "Task",
   "forge.work_task_detail.status_done": "Done",
   "forge.work_task_detail.status_open": "To do",
-  "forge.work_token_report.invalid_link": "This report link is invalid or has expired."
+  "forge.work_token_report.invalid_link": "This report link is invalid or has expired.",
+  "forge.form_renderer.consent_phone_required": "Enter your phone number to agree to calls or messages."
 }

package/src/index.ts

@@ -104,6 +104,7 @@ export * from "./data/queries/useMusicLink";
 export * from "./data/queries/useEventSeries";
 export * from "./data/queries/useInvoice";
 export * from "./data/queries/usePaymentLink";
+export * from "./data/queries/useCheckoutLink";
 export * from "./data/queries/useLeadMagnet";
 export * from "./data/queries/useBlogComments";
 export * from "./data/queries/usePageActions";

package/src/provider/ForgeProvider.tsx

@@ -31,6 +31,13 @@ export interface ForgeContextValue {
   subdomain?: string;
   /** Per-tenant publishable key (`pk_site_…`), sent as `x-forge-key`. */
   publishableKey?: string;
+  /**
+   * An agent embed key (`pk_embed_...`), set only by the embed loader
+   * (packages/embed) on a site TribeNest does not host. The website agent then
+   * talks to `/public/embed/<key>/agent/*`, where the key, not `profileId`,
+   * decides the business and the agent, and nobody is signed in.
+   */
+  embedKey?: string;
   /** The configured Axios client, scoped to this tenant. */
   client: AxiosInstance;
   /** Current member bearer token, or null when anonymous. */
@@ -49,6 +56,8 @@ export interface ForgeClientProviderProps {
   appId?: string;
   subdomain?: string;
   publishableKey?: string;
+  /** See `ForgeContextValue.embedKey`. */
+  embedKey?: string;
   /** Optional initial token (e.g. restored from storage on mount). */
   initialToken?: string | null;
   children: React.ReactNode;
@@ -71,6 +80,7 @@ export const ForgeClientProvider = ({
   appId,
   subdomain,
   publishableKey,
+  embedKey,
   initialToken = null,
   children,
 }: ForgeClientProviderProps) => {
@@ -119,8 +129,8 @@ export const ForgeClientProvider = ({
   );
 
   const value = useMemo<ForgeContextValue>(
-    () => ({ apiUrl, rootDomain, profileId, websiteId, appId, subdomain, publishableKey, client, token, setToken }),
-    [apiUrl, rootDomain, profileId, websiteId, appId, subdomain, publishableKey, client, token, setToken],
+    () => ({ apiUrl, rootDomain, profileId, websiteId, appId, subdomain, publishableKey, embedKey, client, token, setToken }),
+    [apiUrl, rootDomain, profileId, websiteId, appId, subdomain, publishableKey, embedKey, client, token, setToken],
   );
 
   return <ForgeContext.Provider value={value}>{children}</ForgeContext.Provider>;

package/src/runtime/pages.ts

@@ -59,6 +59,7 @@ export const INTERNAL_PAGES = [
   "blog/$slug",
   "checkout",
   "checkout/finalise",
+  "checkout/pay/$token",
   "checkout/resume",
   "coaching",
   "coaching/$slug",

package/src/types/models.ts

@@ -2076,6 +2076,30 @@ export type FormField = {
   order: number;
   /** Which section this field belongs to (null on legacy flat forms). */
   sectionId?: string | null;
+  /**
+   * Type-specific settings. A consent box (`call_consent`) keeps its channel and
+   * the phone field it is bound to here.
+   */
+  config?: { channel?: ConsentChannel; phoneFieldId?: string | null } | null;
+  /**
+   * On a consent box only: the exact text to show beside it, in the visitor's
+   * language, as the server built it. Show `text` as it is (never rewrite it)
+   * and send `textHash` back with the tick: that is what makes the tick evidence.
+   */
+  consent?: FormFieldConsent | null;
+};
+
+/** A channel a person can agree to be contacted on. */
+export type ConsentChannel = "ai_call" | "sms" | "whatsapp";
+
+/** The locked consent wording the server serves with a consent box. */
+export type FormFieldConsent = {
+  channel: ConsentChannel;
+  phoneFieldId: string | null;
+  locale: string;
+  version: string;
+  text: string;
+  textHash: string;
 };
 
 /** Edge scope: field→field jump, section→section page flow, or in-page show/hide. */