@tribe-nest/forge 3.65.0 → 3.69.0

package/package.json

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

package/src/data/queries/useCheckoutLink.ts

@@ -0,0 +1,70 @@
+import { useQuery } from "@tanstack/react-query";
+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;
+  };
+  quantity: number;
+  /** Minor units, in `currency`. */
+  unitPriceCents: number | null;
+  totalCents: number;
+  currency: string;
+  /** ISO. When the hold ends if nobody pays. */
+  expiresAt: string;
+};
+
+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,
+  });
+}
+
+/**
+ * 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/useWebsite.ts

@@ -1,10 +1,11 @@
 import type { WebPage } from "../../types";
-import { useForge } from "../../provider/ForgeProvider";
+import { useContext } from "react";
+import { useForge, useOptionalForge } from "../../provider/ForgeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
-import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";
+import { keepPreviousData, QueryClientContext, useMutation, useQuery } from "@tanstack/react-query";
 
 export interface SiteConfig {
-  /** The tenant's settlement currency (e.g. "USD") — the currency API amounts
+  /** The tenant's settlement currency (e.g. "USD"): the currency API amounts
    * are in and payments are charged in. */
   currency: string;
   /** The language the tenant speaks ("en" | "de" today), from
@@ -16,7 +17,7 @@ export interface SiteConfig {
   locale?: string;
   /** Sales-tax display mode: true = listing prices already contain tax
    * ("incl. VAT" style, EU/UK), false/absent = tax added at checkout (US).
-   * Display-only — checkout totals come from the authoritative taxQuote. */
+   * Display-only: checkout totals come from the authoritative taxQuote. */
   pricesIncludeTax?: boolean;
   metaPixelId: string | null;
   stripeAccountId: string | null;
@@ -29,7 +30,7 @@ export interface SiteConfig {
   /** Whether Altcha proof-of-work bot protection is active. Self-hosted, so it
    * works on every tenant subdomain + custom domain with no per-domain config. */
   altchaEnabled?: boolean;
-  /** The creator's site display name — the manifest `name` fallback when the
+  /** The creator's site display name: the manifest `name` fallback when the
    * PWA identity has no explicit name. */
   siteName?: string | null;
   /** The profile-level PWA identity (icons/name/screenshots) used to build the
@@ -38,10 +39,21 @@ export interface SiteConfig {
   pwa?: PwaConfig | null;
   /** Suppresses the "Powered by TribeNest" badge on released builds. Server-side
    * on purpose: the tenant owns `__root.tsx`, so anything expressed as a prop is
-   * an opt-out. Absent/false today — this is the lever a white-label plan
+   * an opt-out. Absent/false today. This is the lever a white-label plan
    * entitlement flips, and it works without waiting for a Forge bump to reach
    * every site. */
   hideTribeNestBadge?: boolean;
+  /** The privacy policy and terms of the brand the site is sold under
+   * (TribeNest's, or Mandatera's for a law firm). What a site with no policy of
+   * its own links to. Optional because an older backend sends no such field,
+   * and every reader then falls back to TribeNest's. */
+  legalUrls?: BrandLegalUrls | null;
+}
+
+/** The brand's hosted legal pages, from `site-config`. */
+export interface BrandLegalUrls {
+  privacy: string;
+  terms: string;
 }
 
 /** The PWA identity block on `site-config` (mirrors `pwaConfig` on the profile). */
@@ -58,13 +70,13 @@ export interface PwaConfig {
 
 /**
  * The tenant's mutable runtime config (settlement currency, Meta Pixel id,
- * payment provider). Fetched at runtime — NOT baked into the build — so a
+ * payment provider). Fetched at runtime (NOT baked into the build) so a
  * creator can change these in settings and the live site reflects them without
  * a rebuild/redeploy.
  *
  * If a `<SiteConfigProvider>` seeded an SSR-fetched value (see `fetchSiteConfig`
  * in `@tribe-nest/forge/server`), it's used as `initialData` so the config is
- * present on the first render — no client-fetch flash, no hydration mismatch.
+ * present on the first render: no client-fetch flash, no hydration mismatch.
  * An explicit `initialData` override still wins.
  */
 export function useSiteConfig(opts?: { initialData?: SiteConfig }) {
@@ -79,10 +91,29 @@ export function useSiteConfig(opts?: { initialData?: SiteConfig }) {
     },
     enabled: !!client && !!profileId,
     initialData: opts?.initialData ?? ssrInitial,
-    staleTime: 1000 * 60 * 5, // 5 min — settings change rarely; refetch keeps it fresh
+    staleTime: 1000 * 60 * 5, // 5 min: settings change rarely; refetch keeps it fresh
   });
 }
 
+/**
+ * The brand's hosted legal pages (`site-config.legalUrls`), or `undefined` when
+ * they are not known yet.
+ *
+ * Safe outside a `<ForgeProvider>` (returns `undefined`), because the components
+ * that read it (`CookieConsent`, `MusicLinkPage`) are also rendered standalone.
+ * Reads the SSR-seeded config first, then whatever `useSiteConfig` has cached;
+ * it never starts a fetch of its own.
+ */
+export function useBrandLegalUrls(): BrandLegalUrls | undefined {
+  const ssrInitial = useInitialSiteConfig();
+  const forge = useOptionalForge();
+  const queryClient = useContext(QueryClientContext);
+  const cached = forge?.profileId
+    ? queryClient?.getQueryData<SiteConfig>(["site-config", forge.profileId])
+    : undefined;
+  return cached?.legalUrls ?? ssrInitial?.legalUrls ?? undefined;
+}
+
 /**
  * The store's tax display mode from site config: true = prices shown to the
  * buyer already include tax (inclusive/EU display), false = tax is added at
@@ -96,7 +127,7 @@ export function usePricesIncludeTax(): boolean {
 
 // Tax-aware price rendering primitive, re-exported here (a file the root barrel
 // already star-exports) so `@tribe-nest/frontend-shared` and app code can import
-// it from "@tribe-nest/forge". Its home is `ui/format/PriceDisplay` — the
+// it from "@tribe-nest/forge". Its home is `ui/format/PriceDisplay`, and the
 // `forge/ui` barrel should export it from there as well.
 export {
   PriceDisplay,
@@ -118,7 +149,7 @@ export function useSubmitContactForm() {
 }
 
 /**
- * The rendered web page for a pathname — either the published site (by
+ * The rendered web page for a pathname: either the published site (by
  * subdomain) or a preview (by token). Keeps the previous page during navigation
  * to avoid a white flash.
  */

package/src/data/queries/useWebsiteAgent.ts

@@ -3,23 +3,33 @@ import { useQuery } from "@tanstack/react-query";
 
 export interface WebsiteAgentConfig {
   enabled: boolean;
+  /** The agent that answers on this website. */
+  agentId?: string;
   displayName?: string;
+  /** The agent's language, for example "en" or "de". */
+  language?: string;
   greeting?: string | null;
   allowAnonymous?: boolean;
   allowOrderLookup?: boolean;
   allowLeadCapture?: boolean;
   /** Paths the widget must not appear on. "/blog/*" covers every child. */
   excludedPaths?: string[];
+  /** The agent also takes calls from the browser: show "Call us". */
+  voiceEnabled?: boolean;
 }
 
-/** Widget bootstrap config for the profile. When `enabled` is false the widget
- * should render nothing. */
+/** Widget bootstrap config for the website. When `enabled` is false the widget
+ * should render nothing. `websiteId` picks the agent of THIS website, since a
+ * 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 } = useForge();
+  const { client, profileId, websiteId } = useForge();
   return useQuery<WebsiteAgentConfig>({
-    queryKey: ["website-agent-config", profileId],
+    queryKey: ["website-agent-config", profileId, websiteId ?? null],
     queryFn: async () => {
-      const res = await client.get(`/public/agent/config`, { params: { profileId } });
+      const res = await client.get(`/public/agent/config`, {
+        params: { profileId, ...(websiteId ? { websiteId } : {}) },
+      });
       return res.data;
     },
     enabled: !!profileId && !!client,
@@ -88,6 +98,7 @@ export async function createAgentConversation(params: {
   apiUrl: string;
   token?: string | null;
   profileId: string;
+  websiteId?: string;
   visitorId: string;
 }): Promise<{ id: string | null; requiresLogin?: boolean }> {
   const res = await fetch(`${params.apiUrl}/public/agent/conversations`, {
@@ -96,7 +107,126 @@ export async function createAgentConversation(params: {
       "Content-Type": "application/json",
       ...(params.token ? { authorization: `Bearer ${params.token}` } : {}),
     },
-    body: JSON.stringify({ profileId: params.profileId, visitorId: params.visitorId }),
+    body: JSON.stringify({
+      profileId: params.profileId,
+      ...(params.websiteId ? { websiteId: params.websiteId } : {}),
+      visitorId: params.visitorId,
+    }),
   });
   return res.json();
 }
+
+// "Call us": a call with the website's agent, from the browser.
+
+/** Where the call's media room is, and how to come back to it. */
+export interface AgentCallCredentials {
+  callId: string;
+  roomId: string;
+  mediaUrl: string;
+  token: string;
+  expiresAt: string;
+  /** This browser's seat in the room, reused on every reconnect. */
+  identity: string;
+  /** Proves this browser started the call: needed to rejoin or end it. */
+  callKey: string;
+}
+
+/** The bot check a call starts with. See `solveCallChallenge`. */
+export interface AgentCallChallenge {
+  challenge: string;
+  difficulty: number;
+  expiresAt: string;
+}
+
+/** A refused call request, with the HTTP status that says why. */
+export class AgentCallRequestError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "AgentCallRequestError";
+    this.status = status;
+  }
+}
+
+async function postAgentCall<T>(url: string, body: Record<string, unknown>, keepalive = false): Promise<T> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      // Lets the request outlive the page, so leaving it still hangs up.
+      keepalive,
+    });
+  } catch (err) {
+    throw new AgentCallRequestError(0, err instanceof Error ? err.message : String(err));
+  }
+  const data = (await res.json().catch(() => null)) as (T & { message?: string }) | null;
+  if (!res.ok) throw new AgentCallRequestError(res.status, data?.message || res.statusText || "Request failed");
+  return data as T;
+}
+
+const withWebsite = (websiteId?: string) => (websiteId ? { websiteId } : {});
+
+/** Step 1: ask for a bot check. 404 when the website's agent takes no calls. */
+export function requestAgentCallChallenge(params: {
+  apiUrl: string;
+  profileId: string;
+  websiteId?: string;
+  visitorId: string;
+}): Promise<AgentCallChallenge> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls/challenge`, {
+    profileId: params.profileId,
+    ...withWebsite(params.websiteId),
+    visitorId: params.visitorId,
+  });
+}
+
+/**
+ * Step 2: start the call with the solved check. Refusals carry the status:
+ * 400 failed check, 429 over the limit, 404 not available, 409 the minutes or
+ * the lines are used up, 503 the call network is down.
+ */
+export function startAgentCall(params: {
+  apiUrl: string;
+  profileId: string;
+  websiteId?: string;
+  visitorId: string;
+  challenge: string;
+  solution: string;
+}): Promise<AgentCallCredentials> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls`, {
+    profileId: params.profileId,
+    ...withWebsite(params.websiteId),
+    visitorId: params.visitorId,
+    challenge: params.challenge,
+    solution: params.solution,
+  });
+}
+
+/** A fresh join ticket for a reconnect: a ticket expires in minutes. */
+export function joinAgentCall(params: {
+  apiUrl: string;
+  callId: string;
+  callKey: string;
+  identity: string;
+}): Promise<AgentCallCredentials> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls/${params.callId}/join`, {
+    callKey: params.callKey,
+    identity: params.identity,
+  });
+}
+
+/** Hangs up. `keepalive` for a page that is going away. */
+export function endAgentCall(params: {
+  apiUrl: string;
+  callId: string;
+  callKey: string;
+  keepalive?: boolean;
+}): Promise<{ ended: boolean }> {
+  return postAgentCall(
+    `${params.apiUrl}/public/agent/calls/${params.callId}/end`,
+    { callKey: params.callKey },
+    params.keepalive,
+  );
+}

package/src/i18n/de.json

@@ -185,8 +185,25 @@
   "forge.account_dashboard.waitlist_ticket_line_other": "{title} · {quantity} Tickets",
   "forge.account_dashboard.waitlists_empty": "Du stehst auf keiner Warteliste.",
   "forge.account_dashboard.waitlists_title": "Meine Wartelisten",
+  "forge.ai_agent_call_room.connecting": "Verbindung wird hergestellt…",
+  "forge.ai_agent_call_room.listening": "{name} hört zu",
+  "forge.ai_agent_call_room.no_mic": "Wir konnten dein Mikrofon nicht verwenden. Erlaube es in deinem Browser und ruf dann erneut an.",
+  "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_open": "Chat-Assistent öffnen",
+  "forge.ai_agent_widget.aria_show_call": "Anruf anzeigen",
+  "forge.ai_agent_widget.call_again": "Erneut anrufen",
+  "forge.ai_agent_widget.call_back_to_chat": "Zurück zum Chat",
+  "forge.ai_agent_widget.call_connecting": "Verbindung wird hergestellt…",
+  "forge.ai_agent_widget.call_ended": "Anruf beendet.",
+  "forge.ai_agent_widget.call_error_busy": "Alle unsere Leitungen sind belegt. Bitte versuch es in ein paar Minuten noch einmal.",
+  "forge.ai_agent_widget.call_error_check_failed": "Wir konnten den Anruf nicht starten. Bitte versuch es noch einmal.",
+  "forge.ai_agent_widget.call_error_failed": "Wir konnten deinen Anruf nicht verbinden. Bitte versuch es noch einmal.",
+  "forge.ai_agent_widget.call_error_too_many": "Du hast in letzter Zeit mehrmals angerufen. Bitte versuch es später noch einmal.",
+  "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.default_greeting": "Hi! Frag mich, was du willst.",
   "forge.ai_agent_widget.default_title": "Assistent",
   "forge.ai_agent_widget.input_placeholder": "Nachricht schreiben…",
@@ -696,6 +713,31 @@
   "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.coaching_booking.aria_close": "Schließen",
   "forge.coaching_booking.aria_next_month": "Nächster Monat",
   "forge.coaching_booking.aria_next_week": "Nächste Woche",

package/src/i18n/en.json

@@ -185,8 +185,25 @@
   "forge.account_dashboard.waitlist_ticket_line_other": "{title} · {quantity} tickets",
   "forge.account_dashboard.waitlists_empty": "You're not on any waitlists.",
   "forge.account_dashboard.waitlists_title": "My Waitlists",
+  "forge.ai_agent_call_room.connecting": "Connecting…",
+  "forge.ai_agent_call_room.listening": "{name} is listening",
+  "forge.ai_agent_call_room.no_mic": "We could not use your microphone. Allow it in your browser, then call again.",
+  "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_open": "Open chat assistant",
+  "forge.ai_agent_widget.aria_show_call": "Show the call",
+  "forge.ai_agent_widget.call_again": "Call again",
+  "forge.ai_agent_widget.call_back_to_chat": "Back to chat",
+  "forge.ai_agent_widget.call_connecting": "Connecting…",
+  "forge.ai_agent_widget.call_ended": "Call ended.",
+  "forge.ai_agent_widget.call_error_busy": "All our lines are busy. Please try again in a few minutes.",
+  "forge.ai_agent_widget.call_error_check_failed": "We could not start the call. Please try again.",
+  "forge.ai_agent_widget.call_error_failed": "We could not connect your call. Please try again.",
+  "forge.ai_agent_widget.call_error_too_many": "You have called several times recently. Please try again later.",
+  "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.default_greeting": "Hi! Ask me anything.",
   "forge.ai_agent_widget.default_title": "Assistant",
   "forge.ai_agent_widget.input_placeholder": "Type a message…",
@@ -696,6 +713,31 @@
   "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.coaching_booking.aria_close": "Close",
   "forge.coaching_booking.aria_next_month": "Next month",
   "forge.coaching_booking.aria_next_week": "Next week",

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

@@ -55,7 +55,7 @@ export interface ForgeClientProviderProps {
 }
 
 /**
- * Low-level tenant/client provider — supplies the `useForge()` context (Axios
+ * Low-level tenant/client provider: supplies the `useForge()` context (Axios
  * client, tenant ids, token). Most sites use the all-in-one `<ForgeProvider>`
  * (which wraps this plus query/content/auth/cart/audio/site-config/theme); reach
  * for `ForgeClientProvider` only when composing the tree yourself.
@@ -126,6 +126,12 @@ export const ForgeClientProvider = ({
   return <ForgeContext.Provider value={value}>{children}</ForgeContext.Provider>;
 };
 
+/**
+ * The Forge context, or `null` outside a `<ForgeProvider>`. For components that
+ * also render standalone and only enrich themselves when a provider is present.
+ */
+export const useOptionalForge = (): ForgeContextValue | null => useContext(ForgeContext);
+
 /** Access the Forge context. Throws if used outside a `<ForgeProvider>`. */
 export const useForge = (): ForgeContextValue => {
   const ctx = useContext(ForgeContext);

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/ui/headless/agent/_tests/callChallenge.spec.ts

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { leadingZeroBits, solveCallChallenge } from "../callChallenge";
+
+/**
+ * The bot check in front of "Call us". The backend (`callGuard.ts`) accepts a
+ * solution when SHA-256 of `${challenge}:${solution}` starts with `difficulty`
+ * zero bits, so the thing worth pinning is that what the browser finds is what
+ * the server would accept, checked here with Node's own hash rather than the
+ * Web Crypto the solver uses.
+ */
+
+function serverLeadingZeroBits(digest: Buffer): number {
+  let bits = 0;
+  for (const byte of digest) {
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    let b = byte;
+    while ((b & 0x80) === 0) {
+      bits++;
+      b <<= 1;
+    }
+    break;
+  }
+  return bits;
+}
+
+describe("leadingZeroBits", () => {
+  it("counts whole zero bytes and the zero bits of the first non-zero byte", () => {
+    expect(leadingZeroBits(new Uint8Array([0xff]))).toBe(0);
+    expect(leadingZeroBits(new Uint8Array([0x01]))).toBe(7);
+    expect(leadingZeroBits(new Uint8Array([0x00, 0x80]))).toBe(8);
+    expect(leadingZeroBits(new Uint8Array([0x00, 0x00, 0x0f]))).toBe(20);
+  });
+
+  it("counts every bit of an all-zero digest", () => {
+    expect(leadingZeroBits(new Uint8Array(4))).toBe(32);
+  });
+});
+
+describe("solveCallChallenge", () => {
+  it("finds a solution the server's check accepts, at the production difficulty", async () => {
+    const challenge = "v1.eyJhIjoxfQ.c2ln";
+    const solution = await solveCallChallenge(challenge, 16);
+    expect(solution).toMatch(/^\d{1,12}$/);
+    const digest = createHash("sha256").update(`${challenge}:${solution}`).digest();
+    expect(serverLeadingZeroBits(digest)).toBeGreaterThanOrEqual(16);
+  });
+
+  it("returns the SMALLEST solution, so a batch boundary changes nothing", async () => {
+    const challenge = "small-batches";
+    const a = await solveCallChallenge(challenge, 10, { batchSize: 7, yieldToPage: async () => undefined });
+    const b = await solveCallChallenge(challenge, 10, { batchSize: 1000 });
+    expect(a).toBe(b);
+    for (let n = 0; n < Number(a); n++) {
+      const digest = createHash("sha256").update(`${challenge}:${n}`).digest();
+      expect(serverLeadingZeroBits(digest)).toBeLessThan(10);
+    }
+  });
+
+  it("gives the page a turn after every batch it did not solve in", async () => {
+    const solution = Number(await solveCallChallenge("yield-check", 12, { batchSize: 64 }));
+    let yields = 0;
+    await solveCallChallenge("yield-check", 12, {
+      batchSize: 64,
+      yieldToPage: async () => {
+        yields++;
+      },
+    });
+    expect(yields).toBe(Math.floor(solution / 64));
+  });
+
+  it("stops when the call is hung up while it works", async () => {
+    const controller = new AbortController();
+    const solving = solveCallChallenge("abort-me", 40, {
+      signal: controller.signal,
+      yieldToPage: async () => {
+        controller.abort();
+      },
+    });
+    await expect(solving).rejects.toMatchObject({ name: "AbortError" });
+  });
+});