@tribe-nest/forge 3.2.0 → 3.4.0

package/src/ui/headless/coupon/_tests/couponFailureMessage.spec.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { apiErrorMessage, couponFailureMessage } from "../useCouponField";
+
+/**
+ * The one decision that determines whether a buyer learns anything from a
+ * refused code. The backend answers with the reason ALREADY translated —
+ * "This coupon has expired", "Your order does not reach this coupon's minimum
+ * spend" — so the only correct behaviour is to pass that string through.
+ */
+
+/** An axios-shaped rejection, which is what every checkout actually catches. */
+const axiosError = (message: string) => {
+  const e = new Error("Request failed with status code 400") as Error & {
+    response: { status: number; data: { status: number; message: string } };
+  };
+  e.response = { status: 400, data: { status: 400, message } };
+  return e;
+};
+
+describe("apiErrorMessage", () => {
+  it("reads the server's message off the response body", () => {
+    expect(apiErrorMessage(axiosError("This coupon has expired"))).toBe("This coupon has expired");
+  });
+
+  it("returns nothing for a failure that carried no server message", () => {
+    expect(apiErrorMessage(new Error("boom"))).toBeUndefined();
+    expect(apiErrorMessage(undefined)).toBeUndefined();
+    expect(apiErrorMessage(null)).toBeUndefined();
+    expect(apiErrorMessage({ response: {} })).toBeUndefined();
+  });
+});
+
+describe("couponFailureMessage", () => {
+  it("shows the API's reason verbatim, never the house fallback", () => {
+    // Every distinct reason the three pillars can produce for an ENTERED code.
+    for (const reason of [
+      "This coupon is no longer active",
+      "This coupon is not available yet",
+      "This coupon has expired",
+      "This coupon is not valid for your email",
+      "This coupon can only be used with an email address",
+      "Your order does not reach this coupon's minimum spend",
+      "Your order does not reach this coupon's minimum quantity",
+      "This coupon is only valid on a first order",
+      "This coupon is only available to members of a specific tier",
+      "This coupon is not available to you",
+      "This coupon has reached its maximum redemptions",
+      "You have already used this coupon the maximum number of times",
+      "This coupon does not apply to anything in this order",
+      "This coupon is not set up correctly and cannot be used",
+      "This coupon cannot be combined with another discount on this order",
+      "Invalid coupon code",
+      "This coupon cannot be used here",
+    ]) {
+      expect(couponFailureMessage(axiosError(reason), "This code could not be applied.")).toBe(reason);
+    }
+  });
+
+  it("never surfaces axios's own transport wording", () => {
+    // `Error.message` on a 400 is "Request failed with status code 400" — a
+    // string that tells the buyer nothing and looks like a bug.
+    const shown = couponFailureMessage(axiosError("This coupon has expired"), "fallback");
+    expect(shown).not.toContain("status code");
+    expect(shown).not.toBe("fallback");
+  });
+
+  it("suppresses the transport wording even when the body carried no message", () => {
+    const e = new Error("Request failed with status code 500") as Error & { response: { data: unknown } };
+    e.response = { data: {} };
+    expect(couponFailureMessage(e, "This code could not be applied.")).toBe("This code could not be applied.");
+  });
+
+  it("keeps a locally thrown precondition, which is ours to word", () => {
+    // "Reserve a slot first" is not a coupon rejection and has no server key.
+    expect(couponFailureMessage(new Error("Reserve a time slot before entering a code."), "fallback")).toBe(
+      "Reserve a time slot before entering a code.",
+    );
+  });
+
+  it("falls back only when there is genuinely nothing to say", () => {
+    expect(couponFailureMessage({}, "This code could not be applied.")).toBe("This code could not be applied.");
+    expect(couponFailureMessage(undefined, "This code could not be applied.")).toBe("This code could not be applied.");
+  });
+});

package/src/ui/headless/coupon/useCouponField.ts

@@ -0,0 +1,164 @@
+import { useCallback, useState } from "react";
+import type { AppliedDiscountCoupon, PillarDiscountQuote } from "../../../types/models";
+
+/**
+ * Re-quote a pillar with (or, with `null`, without) a discount code and return
+ * what the SERVER says the buyer now owes.
+ *
+ * Only the pillars whose pre-payment step is re-runnable can supply one:
+ * coaching and courses both hang a `booking/update` endpoint off an already
+ * reserved booking, and that endpoint re-derives the gross price from the
+ * product on every call precisely so it can be fired repeatedly.
+ *
+ * Event tickets and bundles have no such endpoint — `POST /public/events/:id/orders`
+ * and `POST /public/checkouts` CREATE the record, so calling either one twice
+ * to preview a code would leave a real abandoned order behind. Those two pass
+ * no quote function and instead stage the code, hand it to the one call they do
+ * make, and record the quote that call returns via `record()`.
+ */
+export type CouponQuoteFn = (code: string | null) => Promise<PillarDiscountQuote>;
+
+/**
+ * The API's own message for a failed request.
+ *
+ * A coupon rejection comes back as a 400 whose body carries the reason ALREADY
+ * translated ("This coupon has expired", "Your order does not reach this
+ * coupon's minimum spend", …) — the server sends the rendered string, not the
+ * `errors.coupon.*` key, so there is nothing to map and nothing to invent.
+ * Replacing it with a house "invalid code" would throw away the only
+ * explanation the buyer is ever given.
+ */
+export function apiErrorMessage(e: unknown): string | undefined {
+  return (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+}
+
+/**
+ * The message to show for a failure: the API's own wording when the failure
+ * came from the server, otherwise a locally thrown precondition ("reserve a
+ * slot first"). A transport `Error` from axios carries a `response`, so its
+ * useless "Request failed with status code 400" is never surfaced.
+ */
+export function couponFailureMessage(e: unknown, fallback: string): string {
+  const fromApi = apiErrorMessage(e);
+  if (fromApi) return fromApi;
+  const hasResponse = !!(e as { response?: unknown })?.response;
+  if (!hasResponse && e instanceof Error && e.message) return e.message;
+  return fallback;
+}
+
+export interface CouponField {
+  /** The raw code in the input (upper-cased by the UI, trimmed on send). */
+  code: string;
+  setCode: (code: string) => void;
+  /** Trimmed code, or `undefined` when the field is empty — send this. */
+  submittedCode: string | undefined;
+  /** Whether the "Have a discount code?" affordance has been expanded. */
+  showInput: boolean;
+  setShowInput: (show: boolean) => void;
+  /** The API's verbatim rejection message, or a local precondition message. */
+  error: string | null;
+  setError: (message: string | null) => void;
+  isApplying: boolean;
+  /** The server's last pricing answer — `null` until something has quoted. */
+  quote: PillarDiscountQuote | null;
+  /** Every discount that applied, entered OR automatic. */
+  appliedCoupons: AppliedDiscountCoupon[];
+  /** MAJOR units. `0` when nothing applied. */
+  discountAmount: number;
+  /** True once the server has confirmed a discount is on this checkout. */
+  hasDiscount: boolean;
+  /** Re-quote with the entered code. No-op without a quote function. */
+  apply: () => Promise<void>;
+  /** Re-quote with NO code, restoring the undiscounted total. */
+  remove: () => Promise<void>;
+  /** Record a quote produced by a call this field did not make. */
+  record: (quote: PillarDiscountQuote | null) => void;
+  /** Report a failure, taking the API's own wording. */
+  fail: (e: unknown, fallback?: string) => void;
+  /** Forget everything — used when the underlying record is discarded. */
+  reset: () => void;
+  /** Whether an Apply/Remove button should be offered at all. */
+  canQuote: boolean;
+}
+
+/**
+ * The discount-code field shared by every checkout: the input, the API's
+ * rejection message, and the server-computed quote that lets the summary show
+ * the buyer a Discount LINE rather than a total that silently shrank.
+ */
+export function useCouponField(quoteFn?: CouponQuoteFn): CouponField {
+  const [code, setCode] = useState("");
+  const [showInput, setShowInput] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isApplying, setIsApplying] = useState(false);
+  const [quote, setQuote] = useState<PillarDiscountQuote | null>(null);
+
+  const submittedCode = code.trim() ? code.trim() : undefined;
+
+  const fail = useCallback((e: unknown, fallback = "Something went wrong.") => {
+    setError(couponFailureMessage(e, fallback));
+  }, []);
+
+  const run = useCallback(
+    async (next: string | null) => {
+      if (!quoteFn) return;
+      setError(null);
+      setIsApplying(true);
+      try {
+        setQuote(await quoteFn(next));
+      } catch (e) {
+        // The failed code is NOT retained as applied: the previous quote stands
+        // (or none does), so the total on screen keeps matching the server.
+        setError(couponFailureMessage(e, "This code could not be applied."));
+      } finally {
+        setIsApplying(false);
+      }
+    },
+    [quoteFn],
+  );
+
+  const apply = useCallback(async () => {
+    const trimmed = code.trim();
+    if (!trimmed) return;
+    await run(trimmed);
+  }, [code, run]);
+
+  const remove = useCallback(async () => {
+    await run(null);
+    setCode("");
+    setShowInput(false);
+  }, [run]);
+
+  const record = useCallback((next: PillarDiscountQuote | null) => {
+    setError(null);
+    setQuote(next);
+  }, []);
+
+  const reset = useCallback(() => {
+    setCode("");
+    setShowInput(false);
+    setError(null);
+    setQuote(null);
+  }, []);
+
+  return {
+    code,
+    setCode,
+    submittedCode,
+    showInput,
+    setShowInput,
+    error,
+    setError,
+    isApplying,
+    quote,
+    appliedCoupons: quote?.appliedCoupons ?? [],
+    discountAmount: quote?.discountAmount ?? 0,
+    hasDiscount: (quote?.discountAmount ?? 0) > 0,
+    apply,
+    remove,
+    record,
+    fail,
+    reset,
+    canQuote: !!quoteFn,
+  };
+}

package/src/ui/headless/course/useCourseCheckout.ts

@@ -1,7 +1,8 @@
-import { useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { useGetCourse, useCreateCourseBooking } from "../../../data/queries/useCourses";
+import { useGetCourse, useCreateCourseBooking, useUpdateCourseBooking } from "../../../data/queries/useCourses";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -21,8 +22,15 @@ const errMessage = (e: unknown) =>
 
 /**
  * Headless course purchase: buyer details → payment. Composes `useGetCourse`,
- * `useCreateCourseBooking`, `usePaymentFlow`. Free courses skip payment and
- * redirect to the finalise page. Finalize via `useCourseBookingFinalize`.
+ * `useCreateCourseBooking`, `useUpdateCourseBooking`, `usePaymentFlow`. Free
+ * courses skip payment and redirect to the finalise page. Finalize via
+ * `useCourseBookingFinalize`.
+ *
+ * `POST /public/courses/:id/bookings` takes NO coupon code — the course pillar
+ * accepts one only on `booking/update`, which exists to be called repeatedly and
+ * re-derives the gross price from the course each time. So a booking is created
+ * as soon as the buyer applies a code, and reused from then on. A buyer who
+ * never touches the discount field takes exactly the path this hook always took.
  */
 export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions = {}) {
   const { user } = usePublicAuth();
@@ -30,6 +38,7 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
   const { data: course, isLoading } = useGetCourse(slug);
   const courseId = course?.id;
   const createBooking = useCreateCourseBooking(courseId);
+  const updateBooking = useUpdateCourseBooking(courseId);
   const flow = usePaymentFlow({ path: `/public/courses/${courseId}/start-payment`, autoStart: false });
 
   const [step, setStep] = useState<CourseCheckoutStep>("details");
@@ -39,10 +48,58 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /** The booking created for quoting, reused so a code never mints a second one. */
+  const bookingIdRef = useRef<string | null>(null);
 
   const finalisePath =
     opts.finalisePath ?? ((s, bookingId) => `/i/courses/${s}/finalise?bookingId=${bookingId}`);
 
+  const requireBuyerDetails = () => {
+    if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      throw new Error("Enter your name and a valid email before applying a code.");
+    }
+  };
+
+  /** Create the booking once; every later call reuses it. */
+  const ensureBooking = async (): Promise<string> => {
+    if (bookingIdRef.current) return bookingIdRef.current;
+    const created = await createBooking.mutateAsync({
+      email,
+      firstName,
+      lastName,
+      questionnaire,
+      attributionRefId: readAttributionRef() ?? undefined,
+      ...(readLanding() ?? {}),
+    });
+    bookingIdRef.current = created.bookingId;
+    return created.bookingId;
+  };
+
+  /**
+   * `confirmIfFree` is false here on purpose: quoting a code must never be able
+   * to complete an enrollment. Only "Continue" confirms.
+   */
+  const quoteCoupon: CouponQuoteFn = useCallback(
+    async (code) => {
+      if (!courseId) throw new Error("This course is not available.");
+      requireBuyerDetails();
+      const bookingId = await ensureBooking();
+      return updateBooking.mutateAsync({
+        bookingId,
+        email,
+        firstName,
+        lastName,
+        confirmIfFree: false,
+        questionnaire,
+        couponCode: code ?? undefined,
+      });
+    },
+    // `createBooking`/`updateBooking` are stable react-query mutation objects.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [courseId, firstName, lastName, email, questionnaire],
+  );
+  const coupon = useCouponField(quoteCoupon);
+
   const continueToPayment = async () => {
     setError(null);
     if (!slug || !courseId) return;
@@ -51,27 +108,56 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
       return;
     }
     try {
-      const data = await createBooking.mutateAsync({
-        email,
-        firstName,
-        lastName,
-        questionnaire,
-        attributionRefId: readAttributionRef() ?? undefined,
-        ...(readLanding() ?? {}),
-      });
+      // A discount can only be recorded through `booking/update`, so any buyer
+      // who touched the code field settles through that endpoint. Everyone else
+      // keeps the original create-only path, unchanged.
+      const usesCoupon = !!coupon.submittedCode || !!bookingIdRef.current;
+      let bookingId: string;
+      let isFree: boolean;
+
+      if (usesCoupon) {
+        bookingId = await ensureBooking();
+        const updated = await updateBooking.mutateAsync({
+          bookingId,
+          email,
+          firstName,
+          lastName,
+          confirmIfFree: true,
+          questionnaire,
+          couponCode: coupon.submittedCode,
+        });
+        coupon.record(updated);
+        isFree = updated.isConfirmed;
+      } else {
+        const data = await createBooking.mutateAsync({
+          email,
+          firstName,
+          lastName,
+          questionnaire,
+          attributionRefId: readAttributionRef() ?? undefined,
+          ...(readLanding() ?? {}),
+        });
+        bookingIdRef.current = data.bookingId;
+        bookingId = data.bookingId;
+        isFree = !!data.isFree;
+      }
+
       const origin = typeof window !== "undefined" ? window.location.origin : "";
-      const ru = `${origin}${finalisePath(slug, data.bookingId)}`;
+      const ru = `${origin}${finalisePath(slug, bookingId)}`;
       setReturnUrl(ru);
-      if (data.isFree) {
-        if (opts.onComplete) opts.onComplete({ slug, bookingId: data.bookingId });
+      if (isFree) {
+        if (opts.onComplete) opts.onComplete({ slug, bookingId });
         else if (typeof window !== "undefined") window.location.href = ru;
         return;
       }
-      const result = await flow.start({ bookingId: data.bookingId, returnUrl: ru });
+      const result = await flow.start({ bookingId, returnUrl: ru });
       if (result.provider && result.provider !== "stripe") return;
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // With a code entered, the API's rejection reason belongs at the field the
+      // buyer used, not in the generic error slot.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
@@ -90,10 +176,19 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
     setQuestionnaire,
     continueToPayment,
     clientSecret: flow.clientSecret,
+    // The booking quote WINS over start-payment: every `continueToPayment`
+    // re-quotes before starting the payment, and applying or removing a code
+    // re-quotes again — so the quote is never staler, and preferring the
+    // payment result would leave a removed discount on screen.
+    totalAmount: coupon.quote?.totalAmount ?? flow.result?.totalAmount ?? (course ? Number(course.price) : undefined),
+    /** GROSS course price, before any discount. */
+    subTotal: coupon.quote?.subTotal ?? (course ? Number(course.price) : undefined),
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     returnUrl,
-    isProcessing: createBooking.isPending || flow.isStarting,
+    isProcessing: createBooking.isPending || updateBooking.isPending || flow.isStarting,
     error,
   };
 }

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

@@ -3,6 +3,7 @@ import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useCart } from "../../../contexts/CartContext";
 import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -47,6 +48,19 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
 
+  /**
+   * Discount code — STAGED, not quoted.
+   *
+   * Tickets have no apply-coupon endpoint and no quote endpoint: `POST
+   * /public/events/:id/orders` is what redeems a code, and it creates the order
+   * row. Pricing a code by calling it would leave a real abandoned order (and a
+   * released inventory hold) behind every keystroke, so no quote function is
+   * passed here. The code rides along on `continueToPayment`, and the order
+   * response — which carries `subTotal`, `discountAmount` and every applied
+   * coupon — is recorded as the quote.
+   */
+  const coupon = useCouponField();
+
   const totalAmount = useMemo(() => {
     if (!event) return 0;
     return event.tickets.reduce((sum, t) => sum + t.price * (selectedTickets[t.id] ?? 0), 0);
@@ -124,9 +138,19 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         firstName,
         lastName,
         questionnaire,
+        couponCode: coupon.submittedCode,
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
+      // What the server actually charged and why — including any AUTOMATIC
+      // discount the buyer never asked for, which nothing else would reveal.
+      coupon.record({
+        subTotal: data.subTotal ?? data.totalAmount ?? totalAmount,
+        totalAmount: data.totalAmount ?? totalAmount,
+        discountAmount: data.discountAmount ?? 0,
+        couponId: data.couponId ?? null,
+        appliedCoupons: data.appliedCoupons ?? [],
+      });
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
@@ -141,10 +165,29 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       if (result.provider && result.provider !== "stripe") return; // Paystack redirected
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // A refused code fails the whole request, so with one entered the message
+      // belongs next to the field the buyer just used. The message is the API's
+      // own — "This coupon has expired", "…does not reach this coupon's minimum
+      // spend" — never a house "invalid code" that hides which it was.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
+  /**
+   * Drop the code and go back to re-enter details. There is nothing to un-apply
+   * server-side: the order was created WITH the discount and is simply left
+   * behind, exactly as pressing "Back" already does. The next
+   * `continueToPayment` creates a fresh, undiscounted order.
+   */
+  const clearCoupon = () => {
+    coupon.reset();
+    // The started payment described the DISCOUNTED order; leaving it would keep
+    // the reduced total on screen after the discount is gone.
+    flow.reset();
+    setStep("details");
+  };
+
   return {
     event,
     isLoading,
@@ -153,7 +196,15 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     selectedTickets,
     setTicketQty,
     ticketCount,
-    totalAmount: flow.result?.totalAmount ?? totalAmount,
+    // The server's figure wins the moment there is one: start-payment first,
+    // then the order response (which is already net of any discount), and only
+    // the locally summed ticket prices before either exists.
+    totalAmount: flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount,
+    /** GROSS ticket total, before any discount. */
+    subTotal: coupon.quote?.subTotal ?? totalAmount,
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
+    clearCoupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     firstName,

package/src/ui/headless/index.ts

@@ -23,6 +23,13 @@ export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 // Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
 export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export {
+  useCouponField,
+  apiErrorMessage,
+  couponFailureMessage,
+  type CouponField,
+  type CouponQuoteFn,
+} from "./coupon/useCouponField";
 export { useCourseCheckout, type UseCourseCheckoutOptions, type CourseCheckoutStep } from "./course/useCourseCheckout";
 export {
   useCoachingBooking,
@@ -43,6 +50,14 @@ export { useMessageThread, type UseMessageThreadResult } from "./chat/useMessage
 export { useChatAttachmentUpload, type PendingAttachment } from "./chat/useChatAttachmentUpload";
 export { attachmentKind, formatBytes, type AttachmentKind } from "./chat/attachmentKind";
 export { useCookieConsent, type UseCookieConsentResult } from "./consent/useCookieConsent";
+export {
+  useAddToCalendar,
+  buildAddToCalendarLinks,
+  toUtcBasic,
+  stripHtml,
+  type AddToCalendarInput,
+  type AddToCalendarLinks,
+} from "./calendar/useAddToCalendar";
 
 export { usePodcastPlayer, type UsePodcastPlayerOptions, type PodcastPlayerState } from "./podcast/usePodcastPlayer";
 

package/src/ui/index.ts

@@ -45,6 +45,12 @@ export {
 export { DonationButton, type DonationButtonProps } from "./styled/DonationButton";
 export { OfferButton, type OfferButtonProps } from "./styled/OfferButton";
 export { Checkout, type CheckoutProps } from "./styled/Checkout";
+export {
+  DiscountCodeField,
+  type DiscountCodeFieldProps,
+  DiscountSummaryLines,
+  type DiscountSummaryLinesProps,
+} from "./styled/DiscountCode";
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
@@ -67,6 +73,7 @@ export { EventsList, type EventsListProps } from "./styled/EventsList";
 export { EventTickets, type EventTicketsProps } from "./styled/EventTickets";
 export { EventCountdown, type EventCountdownProps } from "./styled/EventCountdown";
 export { EventDetail, type EventDetailProps } from "./styled/EventDetail";
+export { AddToCalendar, type AddToCalendarProps } from "./styled/AddToCalendar";
 export { CoachingBooking, type CoachingBookingProps } from "./styled/CoachingBooking";
 export { CoachingDetail, type CoachingDetailProps } from "./styled/CoachingDetail";
 export { CourseCheckout, type CourseCheckoutProps } from "./styled/CourseCheckout";

package/src/ui/shell/PoweredBy.tsx

@@ -0,0 +1,60 @@
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+
+/** Where the badge points. utm params so the referral traffic is attributable. */
+const HREF = "https://tribenest.co/?utm_source=powered_by&utm_medium=badge&utm_campaign=creator_site";
+
+export interface PoweredByProps {
+  /** Live released build only — see `shellPoweredByEnabled`. */
+  enabled?: boolean;
+}
+
+/**
+ * The "Powered by TribeNest" line every released site and app carries.
+ *
+ * Rendered by `TribeNestApp` after the page tree, so it lands BELOW the tenant's
+ * own footer and needs no edit to the tenant-owned `__root.tsx` — a Forge bump
+ * distributes it to every existing site. Both starters (`apps/site-starter` and
+ * `apps/app-starter`) wrap in `TribeNestApp`, so websites and mini-apps are
+ * covered by the same component.
+ *
+ * Deliberately NOT a prop on `TribeNestApp`: the tenant owns `__root.tsx`, so an
+ * opt-out prop is an opt-out. Removal is a server-side decision instead —
+ * `siteConfig.hideTribeNestBadge`, which is how a white-label plan entitlement
+ * will switch it off without waiting for a Forge release to propagate.
+ *
+ * Styled from theme tokens and kept in the normal document flow (not fixed), so
+ * it inherits the site's palette and never collides with the pinned AudioPlayer.
+ */
+export function PoweredBy({ enabled = true }: PoweredByProps) {
+  const t = useThemeTokens();
+  if (!enabled) return null;
+  return (
+    <div
+      style={{
+        display: "flex",
+        justifyContent: "center",
+        padding: "14px 16px",
+        borderTop: `1px solid ${t.border}`,
+        background: t.background,
+      }}
+    >
+      <a
+        href={HREF}
+        target="_blank"
+        // nofollow: the same link on every site we host is exactly the pattern
+        // Google reads as a link scheme. Drop it if the SEO value is judged
+        // worth that risk — it is a one-word change.
+        rel="noopener noreferrer nofollow"
+        style={{
+          fontSize: 12,
+          lineHeight: 1,
+          color: t.muted,
+          textDecoration: "none",
+          letterSpacing: 0.2,
+        }}
+      >
+        Powered by <span style={{ fontWeight: 600 }}>TribeNest</span>
+      </a>
+    </div>
+  );
+}

package/src/ui/shell/TribeNestApp.tsx

@@ -6,7 +6,9 @@ import { PwaRegistration } from "../styled/PwaRegistration";
 import { InstallBanner } from "../styled/InstallBanner";
 import { CookieConsent } from "../styled/CookieConsent";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
-import { shellPwaEnabled } from "./shellGating";
+import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
+import { PoweredBy } from "./PoweredBy";
+import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
 import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
 
@@ -65,6 +67,15 @@ function PwaHeadClient({ enabled, manifestHref }: { enabled: boolean; manifestHr
   return null;
 }
 
+// Reads the server-supplied site config, so the white-label entitlement can turn
+// the badge off without a Forge release. Must live INSIDE ForgeProvider (that is
+// what mounts SiteConfigProvider), hence a component rather than a call in the
+// TribeNestApp body.
+function PoweredByGate({ editable, state }: { editable?: boolean; state?: "draft" | "published" }) {
+  const siteConfig = useInitialSiteConfig();
+  return <PoweredBy enabled={shellPoweredByEnabled({ editable, state, hideBadge: siteConfig?.hideTribeNestBadge })} />;
+}
+
 /**
  * The single root component for a TribeNest code website. Wrap the page tree once
  * — it owns the whole provider tree (via `ForgeProvider`) PLUS the global shell
@@ -100,6 +111,9 @@ export function TribeNestApp({
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
       {children}
+      {/* "Powered by TribeNest" — last in the page flow, so it sits below the
+          tenant's own footer. Released builds only (live + published). */}
+      <PoweredByGate editable={editable} state={state} />
       {/* Global playback bar — self-pins to the viewport bottom, renders nothing
           until a track loads. */}
       <AudioPlayer />