@tribe-nest/forge 3.65.0 → 3.69.0

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

@@ -0,0 +1,78 @@
+import { useCallback, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCheckoutLink, useCheckoutLinkFinalize } from "../../../data/queries/useCheckoutLink";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+
+export interface UseCheckoutLinkPaymentOptions {
+  /** Where the provider returns the buyer. Default: this page with `?finalise=1`. */
+  returnPath?: string;
+  /**
+   * True on the return leg (the provider sent the buyer back): the hook then
+   * settles the link instead of offering to pay.
+   */
+  returning?: boolean;
+}
+
+type ApiError = { response?: { status?: number; data?: { message?: string; code?: string; details?: { status?: string } } } };
+
+/**
+ * Headless checkout link payment: the hosted pay page `/i/checkout/pay/<token>`.
+ *
+ * Loads the link (`open`, which extends its hold to the payment window), starts
+ * its ONE payment only when the buyer presses Pay (`start-payment` runs the
+ * server's checks first: a closed link or a hold whose items were taken is
+ * refused before any payment exists), and on the return leg settles it
+ * (`finalize`). Stripe renders from `clientSecret`; Paystack opens its modal.
+ */
+export function useCheckoutLinkPayment(token?: string | null, opts: UseCheckoutLinkPaymentOptions = {}) {
+  const queryClient = useQueryClient();
+  const link = useCheckoutLink(opts.returning ? null : token);
+  const finalize = useCheckoutLinkFinalize(token, !!opts.returning);
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const pathname = typeof window !== "undefined" ? window.location.pathname : "";
+  const returnUrl = token ? `${origin}${opts.returnPath ?? pathname}?finalise=1` : "";
+
+  const flow = usePaymentFlow({
+    path: "/public/checkout-links/start-payment",
+    body: { token },
+    returnUrl,
+    autoStart: false,
+    enabled: !!token,
+  });
+
+  const [refusal, setRefusal] = useState<{ message: string; code: string | null; status: string | null } | null>(null);
+
+  const pay = useCallback(async () => {
+    setRefusal(null);
+    try {
+      await flow.start();
+    } catch (error) {
+      const data = (error as ApiError)?.response?.data;
+      setRefusal({
+        message: data?.message ?? "",
+        code: data?.code ?? null,
+        status: data?.details?.status ?? null,
+      });
+      // The link's own state may have moved (paid in another tab, expired).
+      await queryClient.invalidateQueries({ queryKey: ["checkout-link", token] });
+    }
+  }, [flow, queryClient, token]);
+
+  return {
+    link,
+    finalize,
+    returnUrl,
+    pay,
+    isStarting: flow.isStarting,
+    clientSecret: flow.clientSecret,
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
+    /** The server's refusal of the last Pay, in its own words, with its code. */
+    refusal,
+    /** 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/index.ts

@@ -159,6 +159,7 @@ export {
 } from "./membership/membershipQuestionnaire";
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
+export { useCheckoutLinkPayment, type UseCheckoutLinkPaymentOptions } from "./checkoutLink/useCheckoutLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";
 export {
   broadcastListStatus,

package/src/ui/index.ts

@@ -94,6 +94,8 @@ export {
 export { Cart, type CartProps } from "./styled/Cart";
 /** The page a cart-recovery email lands on. Drop in at `/i/checkout/resume`. */
 export { ResumeCart, type ResumeCartProps } from "./styled/ResumeCart";
+/** The page a checkout link lands on: an item held for this person. Drop in at `/i/checkout/pay/$token`. */
+export { CheckoutLinkPayment, type CheckoutLinkPaymentProps } from "./styled/CheckoutLinkPayment";
 // The resolver is exported alongside the component because the Craft themes
 // are a separate rendering stack (Tailwind, not inline styles) and cannot use
 // the component: but the legacy `color`/`size` fallback must not diverge.
@@ -206,6 +208,17 @@ export { NewDmDialog, type NewDmDialogProps } from "./styled/chat/NewDmDialog";
 export { AiAgentWidget, type AiAgentWidgetProps } from "./styled/AiAgentWidget";
 export { Markdown } from "./styled/Markdown";
 export { useAiAgent, type AiAgentMessage } 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.
+export {
+  useAgentCall,
+  classifyAgentCallError,
+  type AgentCallState,
+  type AgentCallErrorKind,
+  type UseAgentCallOptions,
+} from "./headless/agent/useAgentCall";
+export { solveCallChallenge, leadingZeroBits, type SolveCallChallengeOptions } from "./headless/agent/callChallenge";
 export { InvoicePayment, type InvoicePaymentProps } from "./styled/InvoicePayment";
 export { PaymentLinkPayment, type PaymentLinkPaymentProps } from "./styled/PaymentLinkPayment";
 export { BlogList, type BlogListProps } from "./styled/BlogList";

package/src/ui/styled/AiAgentCallRoom.tsx

@@ -0,0 +1,76 @@
+import { useEffect, type ReactNode } from "react";
+import { useForgeT } from "../../i18n";
+import { MediaRoomProvider } from "../media";
+import { useAgentAudio, useAgentCallRoom, type AgentCallRoomStatus } from "../headless/agent/useAgentCallRoom";
+
+export interface AiAgentCallRoomProps {
+  getCredentials: () => Promise<{ mediaUrl: string; token: string }>;
+  /** This browser's identity in the room, from the start response. */
+  selfIdentity: string;
+  /** The agent's name, for the status line. */
+  agentName: string;
+  /** The room says the call is over: the agent left, or the room closed. */
+  onEnded: () => void;
+  /** Told every status change, so the widget can style around it. */
+  onStatus?: (status: AgentCallRoomStatus) => void;
+}
+
+/**
+ * The live half of "Call us": the media room, the microphone out and the
+ * agent's voice in.
+ *
+ * A DEFAULT export on purpose. `AiAgentWidget` is on every page of every site
+ * and reaches this through `React.lazy(() => import(...))`, so the media SDK
+ * and mediasoup are fetched only by a visitor who actually presses Call.
+ */
+export default function AiAgentCallRoom({ getCredentials, ...rest }: AiAgentCallRoomProps): ReactNode {
+  const t = useForgeT();
+  return (
+    <MediaRoomProvider
+      getCredentials={getCredentials}
+      fallback={<StatusLine text={t("forge.ai_agent_call_room.connecting")} />}
+    >
+      <LiveCall {...rest} />
+    </MediaRoomProvider>
+  );
+}
+
+function LiveCall({ selfIdentity, agentName, onEnded, onStatus }: Omit<AiAgentCallRoomProps, "getCredentials">) {
+  const t = useForgeT();
+  const { status, agentAudioProducerIds, setAgentSpeaking } = useAgentCallRoom({ selfIdentity, onEnded });
+
+  useEffect(() => {
+    onStatus?.(status);
+  }, [status, onStatus]);
+
+  const text =
+    status === "no_mic"
+      ? t("forge.ai_agent_call_room.no_mic")
+      : status === "speaking"
+        ? t("forge.ai_agent_call_room.speaking", { name: agentName })
+        : status === "listening"
+          ? t("forge.ai_agent_call_room.listening", { name: agentName })
+          : t("forge.ai_agent_call_room.connecting");
+
+  return (
+    <>
+      {agentAudioProducerIds.map((id) => (
+        <AgentAudio key={id} producerId={id} onSpeaking={setAgentSpeaking} />
+      ))}
+      <StatusLine text={text} alert={status === "no_mic"} />
+    </>
+  );
+}
+
+function AgentAudio({ producerId, onSpeaking }: { producerId: string; onSpeaking: (speaking: boolean) => void }) {
+  const attach = useAgentAudio(producerId, onSpeaking);
+  return <audio ref={attach} autoPlay data-testid="forge-agent-call-audio" />;
+}
+
+function StatusLine({ text, alert }: { text: string; alert?: boolean }) {
+  return (
+    <div role={alert ? "alert" : "status"} aria-live="polite" style={{ fontSize: 14, textAlign: "center" }} data-testid="forge-agent-call-status">
+      {text}
+    </div>
+  );
+}

package/src/ui/styled/AiAgentWidget.tsx

@@ -1,10 +1,29 @@
-import { useEffect, useRef, useState } from "react";
+import { lazy, Suspense, useCallback, useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { Phone, PhoneOff } from "lucide-react";
 import { useForgeT } from "../../i18n";
 import { useForgeTheme } from "../theme/ForgeThemeProvider";
 import { readableTextOn } from "../theme/contrast";
 import { useAiAgent } from "../headless/agent/useAiAgent";
+import { useAgentCall, type AgentCallErrorKind } from "../headless/agent/useAgentCall";
+import type { AgentCallRoomStatus } from "../headless/agent/useAgentCallRoom";
 import { Markdown } from "./Markdown";
 
+// The live call pulls in the media SDK and mediasoup, which no visitor needs
+// until they press Call. Split out so it stays out of every page's bundle.
+const loadCallRoom = () => import("./AiAgentCallRoom");
+const AiAgentCallRoom = lazy(loadCallRoom);
+
+/** The widget already draws errors in this red; hang up shares it. */
+const DANGER = "#c0392b";
+
+const CALL_ERROR_KEYS: Record<AgentCallErrorKind, string> = {
+  too_many: "forge.ai_agent_widget.call_error_too_many",
+  unavailable: "forge.ai_agent_widget.call_error_unavailable",
+  busy: "forge.ai_agent_widget.call_error_busy",
+  check_failed: "forge.ai_agent_widget.call_error_check_failed",
+  failed: "forge.ai_agent_widget.call_error_failed",
+};
+
 export interface AiAgentWidgetProps {
   /** Corner to anchor the floating bubble. Default "bottom-right". */
   position?: "bottom-right" | "bottom-left";
@@ -24,12 +43,24 @@ export interface AiAgentWidgetProps {
  * the profile, or when the visitor is on a page the artist excluded.
  * Appearance-only props let authors restyle it without touching behavior. For
  * custom UI, use the `useAiAgent()` hook instead.
+ *
+ * When the agent takes calls, a phone button sits beside the bubble ("Call
+ * us"): a voice call with the same agent, in the browser. `useAgentCall()` is
+ * its headless half.
  */
 export function AiAgentWidget({ position = "bottom-right", accentColor, title, zIndex = 9999 }: AiAgentWidgetProps) {
   const t = useForgeT();
   const theme = useForgeTheme();
-  const { isEnabled, config, messages, sending, error, send } = useAiAgent();
-  const [open, setOpen] = useState(false);
+  const { isEnabled, canCall, config, messages, sending, error, send, visitorId } = useAiAgent();
+  const call = useAgentCall({ visitorId });
+  const [view, setView] = useState<"chat" | "call" | null>(null);
+  const open = view === "chat";
+  const setOpen = (next: boolean | ((o: boolean) => boolean)) =>
+    setView((current) => {
+      const value = typeof next === "function" ? next(current === "chat") : next;
+      return value ? "chat" : null;
+    });
+  const [roomStatus, setRoomStatus] = useState<AgentCallRoomStatus>("connecting");
   const [input, setInput] = useState("");
   const scrollRef = useRef<HTMLDivElement>(null);
 
@@ -42,8 +73,29 @@ export function AiAgentWidget({ position = "bottom-right", accentColor, title, z
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: "smooth" });
   }, [messages, sending]);
 
+  const callPhase = call.state.phase;
+  const callActive = callPhase === "connecting" || callPhase === "live";
+
+  // On a page where the widget hides (an excluded path) the call panel goes
+  // with it, and the call would run on with no way to hang up. Hang up instead.
+  const { end: endCall } = call;
+  useEffect(() => {
+    if (!isEnabled || !canCall) endCall();
+  }, [isEnabled, canCall, endCall]);
+
+  const startCall = () => {
+    void loadCallRoom();
+    setView("call");
+    if (callActive) return;
+    setRoomStatus("connecting");
+    void call.start();
+  };
+  const onRoomStatus = useCallback((status: AgentCallRoomStatus) => setRoomStatus(status), []);
+
   if (!isEnabled) return null;
 
+  const agentName = config?.displayName || heading;
+
   const submit = () => {
     if (!input.trim()) return;
     send(input);
@@ -146,24 +198,227 @@ export function AiAgentWidget({ position = "bottom-right", accentColor, title, z
         </div>
       )}
 
-      <button
-        onClick={() => setOpen((o) => !o)}
-        aria-label={t("forge.ai_agent_widget.aria_open")}
-        style={{
-          width: 56,
-          height: 56,
-          borderRadius: "50%",
-          background: accent,
-          color: onAccent,
-          border: "none",
-          cursor: "pointer",
-          boxShadow: "0 6px 20px rgba(0,0,0,0.25)",
-          fontSize: 24,
-          float: position === "bottom-left" ? "left" : "right",
-        }}
-      >
-        {open ? "×" : "💬"}
-      </button>
+      {/* Kept mounted, only hidden, while a call is on: unmounting it would
+          leave the media room with the call still running. */}
+      {(view === "call" || callActive) && (
+        <CallPanel
+          hidden={view !== "call"}
+          heading={heading}
+          agentName={agentName}
+          accent={accent}
+          onAccent={onAccent}
+          callState={call.state}
+          roomStatus={roomStatus}
+          onRoomStatus={onRoomStatus}
+          getCredentials={call.getCredentials}
+          onHangUp={call.end}
+          onRetry={startCall}
+          onClose={() => {
+            call.reset();
+            setView(null);
+          }}
+          onChat={() => {
+            call.reset();
+            setView("chat");
+          }}
+        />
+      )}
+
+      <div style={{ display: "flex", gap: 12, alignItems: "center", justifyContent: position === "bottom-left" ? "flex-start" : "flex-end" }}>
+        {canCall && (
+          <button
+            onClick={startCall}
+            aria-label={callActive ? t("forge.ai_agent_widget.aria_show_call") : t("forge.ai_agent_widget.aria_call")}
+            data-testid="forge-agent-call-button"
+            style={{
+              width: 48,
+              height: 48,
+              borderRadius: "50%",
+              background: callActive ? DANGER : theme.colors.background,
+              color: callActive ? readableTextOn(DANGER) : accent,
+              border: `2px solid ${callActive ? DANGER : accent}`,
+              cursor: "pointer",
+              boxShadow: "0 6px 20px rgba(0,0,0,0.18)",
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              order: position === "bottom-left" ? 2 : 0,
+            }}
+          >
+            <Phone size={20} aria-hidden />
+          </button>
+        )}
+        <button
+          onClick={() => setOpen((o) => !o)}
+          aria-label={t("forge.ai_agent_widget.aria_open")}
+          style={{
+            width: 56,
+            height: 56,
+            borderRadius: "50%",
+            background: accent,
+            color: onAccent,
+            border: "none",
+            cursor: "pointer",
+            boxShadow: "0 6px 20px rgba(0,0,0,0.25)",
+            fontSize: 24,
+            order: 1,
+          }}
+        >
+          {open ? "×" : "💬"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+interface CallPanelProps {
+  hidden: boolean;
+  heading: string;
+  agentName: string;
+  accent: string;
+  onAccent: string;
+  callState: ReturnType<typeof useAgentCall>["state"];
+  roomStatus: AgentCallRoomStatus;
+  onRoomStatus: (status: AgentCallRoomStatus) => void;
+  getCredentials: () => Promise<{ mediaUrl: string; token: string }>;
+  onHangUp: () => void;
+  onRetry: () => void;
+  onClose: () => void;
+  onChat: () => void;
+}
+
+/** "Call us": the call's own card, in place of the chat panel. */
+function CallPanel({
+  hidden,
+  heading,
+  agentName,
+  accent,
+  onAccent,
+  callState,
+  roomStatus,
+  onRoomStatus,
+  getCredentials,
+  onHangUp,
+  onRetry,
+  onClose,
+  onChat,
+}: CallPanelProps) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  const active = callState.phase === "connecting" || callState.phase === "live";
+  const speaking = callState.phase === "live" && roomStatus === "speaking";
+
+  const secondary: CSSProperties = {
+    background: "transparent",
+    color: theme.colors.text,
+    border: `1px solid ${theme.colors.text}33`,
+    borderRadius: theme.cornerRadius,
+    padding: "8px 14px",
+    cursor: "pointer",
+    fontSize: 14,
+  };
+  const primary: CSSProperties = { ...secondary, background: accent, color: onAccent, border: "none", fontWeight: 600 };
+
+  let body: ReactNode;
+  if (callState.phase === "live") {
+    body = (
+      <Suspense fallback={<CallStatus text={t("forge.ai_agent_widget.call_connecting")} />}>
+        <AiAgentCallRoom
+          getCredentials={getCredentials}
+          selfIdentity={callState.call.identity}
+          agentName={agentName}
+          onEnded={onHangUp}
+          onStatus={onRoomStatus}
+        />
+      </Suspense>
+    );
+  } else if (callState.phase === "ended") {
+    body = <CallStatus text={t("forge.ai_agent_widget.call_ended")} />;
+  } else if (callState.phase === "error") {
+    body = <CallStatus text={t(CALL_ERROR_KEYS[callState.error])} color={DANGER} alert />;
+  } else {
+    body = <CallStatus text={t("forge.ai_agent_widget.call_connecting")} />;
+  }
+
+  return (
+    <div
+      data-testid="forge-agent-call-panel"
+      data-phase={callState.phase}
+      style={{
+        width: "min(380px, calc(100vw - 40px))",
+        marginBottom: 12,
+        display: hidden ? "none" : "flex",
+        flexDirection: "column",
+        background: theme.colors.background,
+        color: theme.colors.text,
+        border: `1px solid ${theme.colors.text}1a`,
+        borderRadius: theme.cornerRadius,
+        overflow: "hidden",
+        boxShadow: "0 12px 40px rgba(0,0,0,0.18)",
+      }}
+    >
+      <div style={{ background: accent, color: onAccent, padding: "12px 16px", fontWeight: 600, display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+        <span>{heading}</span>
+        {!active && (
+          <button onClick={onClose} style={{ background: "transparent", border: "none", color: onAccent, cursor: "pointer", fontSize: 20, lineHeight: 1 }} aria-label={t("forge.ai_agent_widget.aria_close")}>
+            ×
+          </button>
+        )}
+      </div>
+
+      <div style={{ padding: "24px 16px", display: "flex", flexDirection: "column", alignItems: "center", gap: 12 }}>
+        <div
+          aria-hidden
+          style={{
+            width: 64,
+            height: 64,
+            borderRadius: "50%",
+            background: accent,
+            color: onAccent,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            transform: speaking ? "scale(1.12)" : "scale(1)",
+            boxShadow: speaking ? `0 0 0 8px ${accent}33` : "none",
+            transition: "transform 150ms ease, box-shadow 150ms ease",
+            opacity: active || callState.phase === "ended" ? 1 : 0.6,
+          }}
+        >
+          <Phone size={28} />
+        </div>
+        <div style={{ fontWeight: 600 }}>{agentName}</div>
+        {body}
+      </div>
+
+      <div style={{ display: "flex", gap: 8, padding: 12, justifyContent: "center", borderTop: `1px solid ${theme.colors.text}1a` }}>
+        {active ? (
+          <button
+            onClick={onHangUp}
+            data-testid="forge-agent-call-hangup"
+            style={{ ...primary, background: DANGER, color: readableTextOn(DANGER), display: "inline-flex", alignItems: "center", gap: 8 }}
+          >
+            <PhoneOff size={16} aria-hidden />
+            {t("forge.ai_agent_widget.call_hang_up")}
+          </button>
+        ) : (
+          <>
+            <button onClick={onRetry} style={primary} data-testid="forge-agent-call-again">
+              {callState.phase === "error" ? t("forge.ai_agent_widget.call_try_again") : t("forge.ai_agent_widget.call_again")}
+            </button>
+            <button onClick={onChat} style={secondary}>
+              {t("forge.ai_agent_widget.call_back_to_chat")}
+            </button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function CallStatus({ text, color, alert }: { text: string; color?: string; alert?: boolean }) {
+  return (
+    <div role={alert ? "alert" : "status"} aria-live="polite" style={{ fontSize: 14, textAlign: "center", color }} data-testid="forge-agent-call-status">
+      {text}
     </div>
   );
 }