@tribe-nest/forge 1.13.0

package/src/ui/headless/donation/DonationContext.tsx

@@ -0,0 +1,223 @@
+import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
+import type { PaymentFlowResult, PublicDonation } from "../../../types/models";
+import { useGetDonation, useTrackDonationView } from "../../../data/queries/useDonations";
+import { useDonationFinalize } from "../../../data/queries/useFinalize";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { estimateProcessingFee } from "./fees";
+
+export type DonationStep = "amount" | "payment" | "result";
+export type DonationOutcome = "succeeded" | "failed" | null;
+
+export interface DonationContextValue {
+  donation: PublicDonation | undefined;
+  isLoading: boolean;
+
+  step: DonationStep;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+
+  // Amount
+  presets: number[];
+  minimum: number;
+  selectedPreset: number | null;
+  setSelectedPreset: (n: number | null) => void;
+  customAmount: string;
+  setCustomAmount: (s: string) => void;
+  effectiveAmount: number;
+  coverFees: boolean;
+  setCoverFees: (b: boolean) => void;
+  estimatedFee: number;
+  estimatedTotal: number;
+
+  // Donor
+  firstName: string;
+  setFirstName: (s: string) => void;
+  lastName: string;
+  setLastName: (s: string) => void;
+  email: string;
+  setEmail: (s: string) => void;
+  message: string;
+  setMessage: (s: string) => void;
+
+  // Flow
+  isStarting: boolean;
+  startError: string | null;
+  startResult: PaymentFlowResult | null;
+  /** The return URL passed to the payment provider. */
+  returnUrl: string;
+  continueToPayment: () => Promise<void>;
+
+  // Result
+  outcome: DonationOutcome;
+  paymentErrorMessage: string | null;
+  onPaymentSucceeded: () => Promise<void>;
+  onPaymentFailed: (message?: string) => void;
+  reset: () => void;
+}
+
+const DonationContext = createContext<DonationContextValue | null>(null);
+
+export function useDonationContext(): DonationContextValue {
+  const ctx = useContext(DonationContext);
+  if (!ctx) throw new Error("Donation components must be used within <Donation>.");
+  return ctx;
+}
+
+export interface DonationProviderProps {
+  donationId: string;
+  children: ReactNode;
+  /** Where the provider should return after payment. Defaults to /donation/finalise. */
+  returnUrl?: string;
+  /** Called once a donation is confirmed succeeded. */
+  onSuccess?: () => void;
+}
+
+export function DonationProvider({ donationId, children, returnUrl, onSuccess }: DonationProviderProps) {
+  const { data: donation, isLoading } = useGetDonation(donationId);
+  const trackView = useTrackDonationView();
+  const flow = usePaymentFlow({ path: `/public/donations/${donationId}/start-payment`, autoStart: false });
+  const donationFinalize = useDonationFinalize();
+
+  const [open, setOpenState] = useState(false);
+  const [step, setStep] = useState<DonationStep>("amount");
+
+  const presets = useMemo(() => (donation?.defaultAmounts ?? []).filter((v) => v > 0), [donation?.defaultAmounts]);
+  const minimum = donation?.minimumAmount != null ? Number(donation.minimumAmount) : 0;
+
+  const [selectedPreset, setSelectedPreset] = useState<number | null>(null);
+  const [customAmount, setCustomAmount] = useState("");
+  const [coverFees, setCoverFees] = useState(false);
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [email, setEmail] = useState("");
+  const [message, setMessage] = useState("");
+  const [startError, setStartError] = useState<string | null>(null);
+  const [outcome, setOutcome] = useState<DonationOutcome>(null);
+  const [paymentErrorMessage, setPaymentErrorMessage] = useState<string | null>(null);
+
+  const effectiveAmount = useMemo(() => {
+    if (selectedPreset != null && !customAmount) return selectedPreset;
+    const parsed = Number(customAmount);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+  }, [selectedPreset, customAmount]);
+
+  const estimatedFee = useMemo(
+    () => (donation?.coverFeesEnabled && coverFees ? estimateProcessingFee(effectiveAmount) : 0),
+    [donation?.coverFeesEnabled, coverFees, effectiveAmount],
+  );
+  const estimatedTotal = useMemo(
+    () => Math.round((effectiveAmount + estimatedFee) * 100) / 100,
+    [effectiveAmount, estimatedFee],
+  );
+
+  const resolvedReturnUrl =
+    returnUrl ?? `${typeof window !== "undefined" ? window.location.origin : ""}/donation/finalise`;
+
+  const setOpen = (next: boolean) => {
+    setOpenState(next);
+    if (next && donationId) trackView.mutate({ donationId });
+  };
+
+  const reset = () => {
+    setStep("amount");
+    setOutcome(null);
+    setPaymentErrorMessage(null);
+    setStartError(null);
+  };
+
+  const continueToPayment = async () => {
+    setStartError(null);
+    if (!effectiveAmount || effectiveAmount <= 0) {
+      setStartError("Please enter a donation amount.");
+      return;
+    }
+    if (minimum > 0 && effectiveAmount < minimum) {
+      setStartError(`Minimum donation is ${minimum}.`);
+      return;
+    }
+    if (!firstName.trim() || !lastName.trim()) {
+      setStartError("Please enter your name.");
+      return;
+    }
+    if (!email.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setStartError("Please enter a valid email.");
+      return;
+    }
+    try {
+      await flow.start({
+        amount: effectiveAmount,
+        coverFees: coverFees && !!donation?.coverFeesEnabled,
+        firstName: firstName.trim(),
+        lastName: lastName.trim(),
+        email: email.trim(),
+        message: message.trim() || null,
+        returnUrl: resolvedReturnUrl,
+      });
+      setStep("payment");
+    } catch {
+      setStartError("Could not start your donation. Please try again.");
+    }
+  };
+
+  const onPaymentSucceeded = async () => {
+    const donationPaymentId = flow.result?.donationPaymentId;
+    if (donationPaymentId) {
+      try {
+        const data = await donationFinalize.mutateAsync({ donationPaymentId });
+        setOutcome(data.status === "succeeded" ? "succeeded" : "failed");
+      } catch {
+        // The webhook will finalize; optimistically show success.
+        setOutcome("succeeded");
+      }
+    } else {
+      setOutcome("succeeded");
+    }
+    setStep("result");
+    onSuccess?.();
+  };
+
+  const onPaymentFailed = (msg?: string) => {
+    setOutcome("failed");
+    setPaymentErrorMessage(msg ?? null);
+    setStep("result");
+  };
+
+  const value: DonationContextValue = {
+    donation,
+    isLoading,
+    step,
+    open,
+    setOpen,
+    presets,
+    minimum,
+    selectedPreset,
+    setSelectedPreset,
+    customAmount,
+    setCustomAmount,
+    effectiveAmount,
+    coverFees,
+    setCoverFees,
+    estimatedFee,
+    estimatedTotal,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    message,
+    setMessage,
+    isStarting: flow.isStarting,
+    startError,
+    startResult: flow.result,
+    returnUrl: resolvedReturnUrl,
+    continueToPayment,
+    outcome,
+    paymentErrorMessage,
+    onPaymentSucceeded,
+    onPaymentFailed,
+    reset,
+  };
+
+  return <DonationContext.Provider value={value}>{children}</DonationContext.Provider>;
+}

package/src/ui/headless/donation/fees.ts

@@ -0,0 +1,15 @@
+// Pure fee math — no React, no I/O. Kept framework-agnostic so it can move into
+// a future `forge-core` unchanged.
+
+export const FEE_PERCENTAGE = 0.029;
+export const FEE_FLAT = 0.3;
+
+/**
+ * The processing fee a donor would cover so the full intended amount reaches the
+ * creator (Stripe's 2.9% + $0.30, grossed up).
+ */
+export function estimateProcessingFee(amount: number): number {
+  if (!amount || amount <= 0) return 0;
+  const total = (amount + FEE_FLAT) / (1 - FEE_PERCENTAGE);
+  return Math.round((total - amount) * 100) / 100;
+}

package/src/ui/headless/donation/index.ts

@@ -0,0 +1,10 @@
+export { Donation, type DonationPaymentRenderProps } from "./Donation";
+export {
+  DonationProvider,
+  useDonationContext,
+  type DonationContextValue,
+  type DonationProviderProps,
+  type DonationStep,
+  type DonationOutcome,
+} from "./DonationContext";
+export { estimateProcessingFee, FEE_PERCENTAGE, FEE_FLAT } from "./fees";

package/src/ui/headless/engagement/usePostEngagement.ts

@@ -0,0 +1,119 @@
+import { useEffect, useState } from "react";
+import type { EngagementEntityType, IPublicComment } from "../../../types/models";
+import {
+  useLikeStatus,
+  useSaveStatus,
+  useEngagementCounts,
+  useComments,
+  useToggleLike,
+  useToggleSave,
+  useAddComment,
+} from "../../../data/queries/useEngagement";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+export interface UsePostEngagementOptions {
+  /** Called when a logged-out visitor tries to like/save/comment. */
+  onRequireAuth?: () => void;
+  /** Initial counts (e.g. from the post payload) for instant first paint. */
+  initialLikeCount?: number;
+  initialCommentCount?: number;
+}
+
+/**
+ * Headless like / save / comment behavior for any entity (post, product, …).
+ * Owns the optimistic local state and gates writes on auth. Bring your own UI.
+ */
+export function usePostEngagement(
+  entityId: string,
+  entityType: EngagementEntityType = "post",
+  opts: UsePostEngagementOptions = {},
+) {
+  const { isAuthenticated } = usePublicAuth();
+  const { data: likedStatus } = useLikeStatus(entityId, entityType, isAuthenticated);
+  const { data: savedStatus } = useSaveStatus(entityId, entityType, isAuthenticated);
+  const { data: counts } = useEngagementCounts(entityId, entityType, isAuthenticated);
+
+  const [showComments, setShowComments] = useState(false);
+  const { data: comments = [], refetch: refetchComments } = useComments(entityId, entityType, showComments);
+
+  const toggleLikeM = useToggleLike();
+  const toggleSaveM = useToggleSave();
+  const addCommentM = useAddComment();
+
+  const [isLiked, setIsLiked] = useState(false);
+  const [isSaved, setIsSaved] = useState(false);
+  const [likeCount, setLikeCount] = useState(opts.initialLikeCount ?? 0);
+  const [commentCount, setCommentCount] = useState(opts.initialCommentCount ?? 0);
+
+  useEffect(() => {
+    if (likedStatus !== undefined) setIsLiked(likedStatus);
+  }, [likedStatus]);
+  useEffect(() => {
+    if (savedStatus !== undefined) setIsSaved(savedStatus);
+  }, [savedStatus]);
+  useEffect(() => {
+    if (counts) {
+      setLikeCount(counts.likeCount);
+      setCommentCount(counts.commentCount);
+    }
+  }, [counts]);
+
+  const requireAuth = (): boolean => {
+    if (!isAuthenticated) {
+      opts.onRequireAuth?.();
+      return false;
+    }
+    return true;
+  };
+
+  const toggleLike = async () => {
+    if (!requireAuth()) return;
+    const next = !isLiked;
+    try {
+      await toggleLikeM.mutateAsync({ entityId, entityType, liked: next });
+      setIsLiked(next);
+      setLikeCount((c) => c + (next ? 1 : -1));
+    } catch {
+      /* keep optimistic state untouched on failure */
+    }
+  };
+
+  const toggleSave = async () => {
+    if (!requireAuth()) return;
+    const next = !isSaved;
+    try {
+      await toggleSaveM.mutateAsync({ entityId, entityType, saved: next });
+      setIsSaved(next);
+    } catch {
+      /* noop */
+    }
+  };
+
+  const openComments = () => {
+    if (!requireAuth()) return;
+    setShowComments(true);
+    refetchComments();
+  };
+
+  const addComment = async (content: string) => {
+    if (!requireAuth() || !content.trim()) return;
+    await addCommentM.mutateAsync({ entityId, entityType, content });
+    await refetchComments();
+    setCommentCount((c) => c + 1);
+  };
+
+  return {
+    isAuthenticated,
+    isLiked,
+    likeCount,
+    toggleLike,
+    isSaved,
+    toggleSave,
+    commentCount,
+    showComments,
+    openComments,
+    comments: comments as IPublicComment[],
+    addComment,
+    isAddingComment: addCommentM.isPending,
+  };
+}

package/src/ui/headless/event/useEventCheckout.ts

@@ -0,0 +1,141 @@
+import { useMemo, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { readAttributionRef } from "../../../utils/attribution";
+import { readLanding } from "../../../utils/landing";
+
+export type EventCheckoutStep = "tickets" | "details" | "payment";
+
+export interface UseEventCheckoutOptions {
+  /** The URL Stripe returns to after a PAID purchase (its `return_url`). Default
+   * `/i/events/:slug/finalise`. A real URL is required for the hosted-redirect
+   * leg, so this can't be a callback. */
+  finalisePath?: (slug: string, orderId: string) => string;
+  /** Called when a FREE order completes in-app — the host navigates however it
+   * wants (e.g. its router), instead of Forge doing a `window.location` redirect.
+   * Omit to keep the default redirect. */
+  onComplete?: (info: { slug: string; orderId: string }) => void;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+/**
+ * Headless event ticket purchase: ticket selection → buyer details → payment.
+ * Composes `useEvent`, `useCreateEventOrder`, `usePaymentFlow`. The Stripe UI is
+ * rendered by `ForgePaymentProvider` from the exposed `clientSecret`; free orders
+ * redirect straight to the finalise page. Finalize via `useEventOrderFinalize`.
+ */
+export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions = {}) {
+  const { user } = usePublicAuth();
+  // The detail is resolved by slug; the order is created against the real event
+  // id (the orders endpoint looks the event up by id, not slug).
+  const { data: event, isLoading } = useEvent(slug);
+  const eventId = event?.id;
+  const createOrder = useCreateEventOrder(eventId);
+  const flow = usePaymentFlow({ path: `/public/events/${eventId}/start-payment`, autoStart: false });
+
+  const [step, setStep] = useState<EventCheckoutStep>("tickets");
+  const [selectedTickets, setSelectedTickets] = useState<Record<string, number>>({});
+  const [firstName, setFirstName] = useState(user?.firstName ?? "");
+  const [lastName, setLastName] = useState(user?.lastName ?? "");
+  const [email, setEmail] = useState(user?.email ?? "");
+  const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  const [returnUrl, setReturnUrl] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  const totalAmount = useMemo(() => {
+    if (!event) return 0;
+    return event.tickets.reduce((sum, t) => sum + t.price * (selectedTickets[t.id] ?? 0), 0);
+  }, [event, selectedTickets]);
+
+  const ticketCount = useMemo(
+    () => Object.values(selectedTickets).reduce((a, b) => a + b, 0),
+    [selectedTickets],
+  );
+
+  // Keep only positive quantities in state — a ticket dropped to 0 is removed
+  // entirely, so `items` never carries a 0-quantity entry (the orders endpoint
+  // rejects those with "quantity must be positive").
+  const setTicketQty = (ticketId: string, qty: number) =>
+    setSelectedTickets((prev) => {
+      const next = { ...prev };
+      if (qty > 0) next[ticketId] = qty;
+      else delete next[ticketId];
+      return next;
+    });
+
+  const goToDetails = () => {
+    if (ticketCount === 0) {
+      setError("Select at least one ticket.");
+      return;
+    }
+    setError(null);
+    setStep("details");
+  };
+
+  const finalisePath = opts.finalisePath ?? ((s, orderId) => `/i/events/${s}/finalise?orderId=${orderId}`);
+
+  const continueToPayment = async () => {
+    setError(null);
+    if (!slug || !eventId) return;
+    if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setError("Please enter your name and a valid email.");
+      return;
+    }
+    try {
+      const data = await createOrder.mutateAsync({
+        items: selectedTickets,
+        email,
+        firstName,
+        lastName,
+        questionnaire,
+        attributionRefId: readAttributionRef() ?? undefined,
+        ...(readLanding() ?? {}),
+      });
+      const origin = typeof window !== "undefined" ? window.location.origin : "";
+      const ru = `${origin}${finalisePath(slug, data.orderId)}`;
+      setReturnUrl(ru);
+      if (data.isFreeCheckout) {
+        // Free order — no payment. Hand navigation to the host if it asked, else
+        // default to an in-app redirect to the finalise page.
+        if (opts.onComplete) opts.onComplete({ slug, orderId: data.orderId });
+        else if (typeof window !== "undefined") window.location.href = ru;
+        return;
+      }
+      const result = await flow.start({ orderId: data.orderId, returnUrl: ru });
+      if (result.provider && result.provider !== "stripe") return; // Paystack redirected
+      setStep("payment");
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  return {
+    event,
+    isLoading,
+    step,
+    setStep,
+    selectedTickets,
+    setTicketQty,
+    ticketCount,
+    totalAmount: flow.result?.totalAmount ?? totalAmount,
+    /** Authoritative sales-tax quote from start-payment (display only). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    questionnaire,
+    setQuestionnaire,
+    goToDetails,
+    continueToPayment,
+    clientSecret: flow.clientSecret,
+    returnUrl,
+    isProcessing: createOrder.isPending || flow.isStarting,
+    error,
+  };
+}

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

@@ -0,0 +1,58 @@
+import { useState } from "react";
+import { useSubmitContactForm } from "../../../data/queries/useWebsite";
+import type { FormStatus } from "./useEmailListForm";
+
+const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Headless website contact-form behavior: form state + validation + submit.
+ * Bring your own markup (or use the styled <ContactForm>).
+ */
+export function useContactForm() {
+  const submitForm = useSubmitContactForm();
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [message, setMessage] = useState("");
+  const [joinEmailList, setJoinEmailList] = useState(false);
+  const [status, setStatus] = useState<FormStatus>("idle");
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const submit = async () => {
+    const next: Record<string, string> = {};
+    if (!name.trim()) next.name = "Name is required";
+    if (!emailRe.test(email)) next.email = "Invalid email address";
+    if (message.trim().length < 10) next.message = "Message must be at least 10 characters";
+    setErrors(next);
+    if (Object.keys(next).length > 0) return;
+
+    setStatus("submitting");
+    try {
+      await submitForm.mutateAsync({
+        name: name.trim(),
+        email: email.trim(),
+        message: message.trim(),
+        joinEmailList: joinEmailList || undefined,
+      });
+      setStatus("success");
+    } catch {
+      setErrors({ form: "Failed to send message. Please try again." });
+      setStatus("error");
+    }
+  };
+
+  return {
+    name,
+    setName,
+    email,
+    setEmail,
+    message,
+    setMessage,
+    joinEmailList,
+    setJoinEmailList,
+    status,
+    errors,
+    submit,
+    isSubmitting: status === "submitting",
+    isSuccess: status === "success",
+  };
+}

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

@@ -0,0 +1,75 @@
+import { useState } from "react";
+import { useJoinEmailList } from "../../../data/queries/useLeadMagnet";
+
+export type FormStatus = "idle" | "submitting" | "success" | "error";
+
+export interface UseEmailListFormOptions {
+  emailListId?: string;
+  leadMagnetId?: string;
+  includeName?: boolean;
+  includePhoneNumber?: boolean;
+}
+
+const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const phoneRe = /^\+?[0-9\s\-()]{7,20}$/;
+
+/**
+ * Headless email-list-join behavior: form state + validation + the join
+ * mutation. Bring your own markup (or use the styled <EmailListForm>).
+ */
+export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
+  const join = useJoinEmailList();
+  const [email, setEmail] = useState("");
+  const [name, setName] = useState("");
+  const [phoneNumber, setPhoneNumber] = useState("");
+  const [status, setStatus] = useState<FormStatus>("idle");
+  const [error, setError] = useState<string | null>(null);
+  const [requiresConfirmation, setRequiresConfirmation] = useState(false);
+
+  const submit = async () => {
+    setError(null);
+    if (!emailRe.test(email)) {
+      setError("Please enter a valid email");
+      return;
+    }
+    if (opts.includeName && !name.trim()) {
+      setError("Please enter your name");
+      return;
+    }
+    if (opts.includePhoneNumber && (!phoneNumber.trim() || !phoneRe.test(phoneNumber.trim()))) {
+      setError("Please enter a valid phone number");
+      return;
+    }
+    setStatus("submitting");
+    try {
+      const data = await join.mutateAsync({
+        email: email.trim().toLowerCase(),
+        emailListId: opts.emailListId,
+        leadMagnetId: opts.leadMagnetId,
+        firstName: opts.includeName ? name.trim() : undefined,
+        phoneNumber: opts.includePhoneNumber ? phoneNumber.trim() : undefined,
+      });
+      setRequiresConfirmation(!!data?.requiresConfirmation);
+      setStatus("success");
+    } catch (e) {
+      const message = (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+      setError(message || "Something went wrong");
+      setStatus("error");
+    }
+  };
+
+  return {
+    email,
+    setEmail,
+    name,
+    setName,
+    phoneNumber,
+    setPhoneNumber,
+    status,
+    error,
+    requiresConfirmation,
+    submit,
+    isSubmitting: status === "submitting",
+    isSuccess: status === "success",
+  };
+}