@tribe-nest/forge 3.2.0 → 3.4.0

package/package.json

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

package/src/data/queries/useCheckouts.ts

@@ -1,5 +1,6 @@
 import { useMutation } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
+import { bundleCouponRequestBody } from "../../ui/headless/checkout/bundleCoupon";
 import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
 
 /** One line of a bundle, in the shape `POST /public/checkouts` expects. */
@@ -69,7 +70,35 @@ export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCa
   return [...ticketLines, ...productLines];
 }
 
-export type CreateCheckoutResult = { checkoutId: string; currency: string; subtotalCents: number };
+/**
+ * One discount that actually came off a bundle — entered or automatic.
+ *
+ * `discountAmount` is in MAJOR units, unlike everything else the bundle endpoint
+ * returns, because it is the same shape every other pillar's checkout answers
+ * with. Naming the coupon is what lets an AUTOMATIC bundle discount render as
+ * "SUMMER10 — $6.00 off" rather than an unexplained reduction; before the
+ * response carried this, only `discountCents` and a `couponId` came back and
+ * there is no public `couponId` → code lookup.
+ */
+export type AppliedBundleCoupon = {
+  code: string;
+  discountKind: string;
+  /** MAJOR units. */
+  discountAmount: number;
+};
+
+/** Note the units: the bundle endpoint is the only checkout answering in MINOR units. */
+export type CreateCheckoutResult = {
+  checkoutId: string;
+  currency: string;
+  /** GROSS, minor units. (Beware: `start-payment` returns a NET `subtotalCents`.) */
+  subtotalCents: number;
+  discountCents?: number;
+  couponId?: string | null;
+  /** NET = max(0, subtotalCents − discountCents), minor units. */
+  totalCents?: number;
+  appliedCoupons?: AppliedBundleCoupon[];
+};
 
 export function useCreateCheckout() {
   const { client, profileId } = useForge();
@@ -82,6 +111,60 @@ export function useCreateCheckout() {
   });
 }
 
+/**
+ * What `POST /public/checkouts/apply-coupon` answers with.
+ *
+ * The payment fields are populated only when the bundle had already started
+ * payment: applying re-prices the children AND re-mints the intent, so the
+ * caller swaps its payment element onto the new secret rather than re-running
+ * start-payment. An empty `paymentSecret` means there was no intent to replace.
+ */
+export type ApplyCheckoutCouponResult = {
+  checkoutId: string;
+  currency: string;
+  /** GROSS, minor units — what the goods cost undiscounted. */
+  subtotalCents: number;
+  discountCents: number;
+  couponId: string | null;
+  /** NET = max(0, subtotalCents − discountCents), minor units. */
+  totalCents: number;
+  appliedCoupons: AppliedBundleCoupon[];
+  paymentSecret: string;
+  paymentId: string;
+  chargedAmount: number;
+  chargedCurrency: string;
+  /** True when the re-price took the bundle to zero — it is already settled. */
+  isFreeCheckout: boolean;
+};
+
+/**
+ * Apply — or REMOVE — a discount code on a bundle that already exists.
+ *
+ * Omitting `couponCode` removes whatever is on it and restores the original
+ * total. This is the bundle's counterpart to `/public/orders/apply-coupon`, and
+ * it is why the code field on a bundle no longer has to freeze the moment the
+ * checkout is created.
+ */
+export function useApplyCheckoutCoupon() {
+  const { client, profileId } = useForge();
+
+  return useMutation<
+    ApplyCheckoutCouponResult,
+    unknown,
+    { checkoutId: string; returnUrl: string; couponCode?: string }
+  >({
+    mutationFn: async ({ checkoutId, returnUrl, couponCode }) => {
+      // The body is built by `bundleCouponRequestBody` so the "remove sends no
+      // code at all" rule is asserted in one place rather than trusted here.
+      const res = await client.post(
+        "/public/checkouts/apply-coupon",
+        bundleCouponRequestBody({ profileId, checkoutId, returnUrl, couponCode }),
+      );
+      return res.data;
+    },
+  });
+}
+
 export type FinalizeCheckoutResult = {
   checkoutId: string;
   status: string;

package/src/data/queries/useCoachingAvailability.ts

@@ -1,4 +1,4 @@
-import type { BookingSlot } from "../../types/models";
+import type { BookingSlot, PillarDiscountQuote } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -40,13 +40,28 @@ export type UpdateCoachingBookingInput = {
   confirmIfFree?: boolean;
   questionnaire?: unknown;
   attributionRefId?: string;
+  /** Omit (or send `undefined`) to CLEAR a previously applied code. */
+  couponCode?: string;
 };
 
-/** Attach buyer details to a reserved coaching booking (confirms it if free). */
+export type UpdateCoachingBookingResult = PillarDiscountQuote & {
+  bookingId: string;
+  isConfirmed: boolean;
+};
+
+/**
+ * Attach buyer details to a reserved coaching booking (confirms it if free) and
+ * (re-)price it.
+ *
+ * This doubles as the coaching pillar's quote: the gross price is re-derived
+ * from the PRODUCT on every call, so applying and then removing a discount code
+ * returns the buyer to exactly the original total instead of compounding off an
+ * already-netted figure. Only a still-`reserved` booking is re-priced.
+ */
 export function useUpdateCoachingBooking(productId?: string) {
   const { client } = useForge();
 
-  return useMutation<{ bookingId: string; isConfirmed: boolean }, unknown, UpdateCoachingBookingInput>({
+  return useMutation<UpdateCoachingBookingResult, unknown, UpdateCoachingBookingInput>({
     mutationFn: async (body) => {
       const res = await client.post(`/public/coaching/products/${productId}/booking/update`, body);
       return res.data;

package/src/data/queries/useCourses.ts

@@ -1,4 +1,4 @@
-import type { PaginatedData, PublicCourse } from "../../types/models";
+import type { PaginatedData, PillarDiscountQuote, PublicCourse } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -10,6 +10,47 @@ export type CreateCourseBookingInput = {
   attributionRefId?: string;
 };
 
+export type UpdateCourseBookingInput = {
+  bookingId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  /** Confirm the booking outright when nothing is left to charge. */
+  confirmIfFree?: boolean;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+  /** Omit (or send `undefined`) to CLEAR a previously applied code. */
+  couponCode?: string;
+};
+
+export type UpdateCourseBookingResult = PillarDiscountQuote & {
+  bookingId: string;
+  isConfirmed: boolean;
+};
+
+/**
+ * Attach buyer details to a course booking and (re-)price it.
+ *
+ * This is the course pillar's de-facto quote: it re-derives the gross price
+ * from the COURSE on every call — never from the booking's already-netted total
+ * — specifically so it can be fired repeatedly as the buyer edits the form.
+ * That is what makes apply/remove of a discount code safe here, and why
+ * removing one restores the original total rather than compounding.
+ *
+ * Only a still-`reserved` booking is re-priced; a confirmed one keeps the
+ * coupon and total it was actually charged at.
+ */
+export function useUpdateCourseBooking(courseId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<UpdateCourseBookingResult, unknown, UpdateCourseBookingInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/courses/${courseId}/booking/update`, { profileId, ...body });
+      return res.data;
+    },
+  });
+}
+
 /** Create a course booking (buyer details → bookingId; free courses skip payment). */
 export function useCreateCourseBooking(courseId?: string) {
   const { client, profileId } = useForge();

package/src/data/queries/useEvents.ts

@@ -1,4 +1,4 @@
-import type { IEvent } from "../../types/models";
+import type { AppliedDiscountCoupon, IEvent } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -48,12 +48,26 @@ export type CreateEventOrderInput = {
   lastName?: string;
   questionnaire?: unknown;
   attributionRefId?: string;
+  /**
+   * The code the buyer typed. Tickets have no apply-coupon endpoint — this call
+   * IS where a code is redeemed, so a refused one fails the whole request with
+   * the reason as its message and no order is created.
+   */
+  couponCode?: string;
 };
 
 export type CreateEventOrderResult = {
   orderId: string;
   isFreeCheckout?: boolean;
+  /** NET of any discount. */
   totalAmount?: number;
+  // Additive (S.3) — present on every response, discounted or not.
+  /** GROSS, before any discount. */
+  subTotal?: number;
+  discountAmount?: number;
+  couponId?: string | null;
+  /** Every discount that applied, entered OR automatic. */
+  appliedCoupons?: AppliedDiscountCoupon[];
 };
 
 /** Create an event ticket order (the step before start-payment). */

package/src/data/queries/usePaymentFlow.ts

@@ -76,5 +76,17 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
       startedRef.current = true;
       return mutateAsync(override);
     },
+    /**
+     * Forget the last result so nothing downstream keeps quoting it.
+     *
+     * `mutation.data` outlives the thing it described: drop a discount code and
+     * the charge that code produced is still sitting here, so a summary reading
+     * `result.totalAmount` would go on showing the discounted figure against an
+     * order that no longer has the discount.
+     */
+    reset: () => {
+      startedRef.current = false;
+      mutation.reset();
+    },
   };
 }

package/src/data/queries/useWebsite.ts

@@ -29,6 +29,12 @@ export interface SiteConfig {
    * installable manifest + head tags. `null` when the creator has no pwaConfig
    * (minimal name-only manifest, not installable). Screenshots are optional. */
   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
+   * entitlement flips, and it works without waiting for a Forge bump to reach
+   * every site. */
+  hideTribeNestBadge?: boolean;
 }
 
 /** The PWA identity block on `site-config` (mirrors `pwaConfig` on the profile). */

package/src/index.ts

@@ -37,6 +37,15 @@ export {
 export type { AuthActions } from "./contexts/PublicAuthContext";
 export { PUBLIC_REFRESH_TOKEN_KEY, APP_REFRESH_TOKEN_KEY } from "./client/tokenStorage";
 export { safeRedirectPath } from "./utils/safeRedirect";
+// Ticket-confirmation copy decision — shared so the Forge block and the client
+// app's finalise page can never tell a refunded buyer two different stories.
+export {
+  getTicketOrderOutcome,
+  isTicketOrderRefunded,
+  TICKET_ORDER_REFUNDED_COPY,
+  type TicketOrderOutcome,
+  type TicketOrderOutcomeInput,
+} from "./utils/ticketOrderOutcome";
 // App-user auth (mini-apps) + the /admin guard.
 export {
   useAppAuth,

package/src/types/models.ts

@@ -88,6 +88,44 @@ export type PaymentFlowResult = PaymentStartResponse & {
   provider?: PaymentProviderName;
 };
 
+/**
+ * One coupon that ACTUALLY applied to a checkout, exactly as the ticket,
+ * booking and course pillars report it. Entered codes and automatic (no-code)
+ * discounts are reported identically — which is the only way a buyer ever finds
+ * out an automatic discount happened, since nothing else names it.
+ *
+ * `discountKind` is the engine's kind (`simple`, `free_shipping`, `bogo`,
+ * `volume`, `membership_grant`), kept as a string so a new kind added on the
+ * server does not fail to type-check here.
+ */
+export type AppliedDiscountCoupon = {
+  code: string;
+  discountKind: string;
+  /** MAJOR units — this coupon's own contribution, not the running total. */
+  discountAmount: number;
+};
+
+/**
+ * What a pillar's pre-payment call reports about pricing after discounts.
+ * `POST /public/events/:id/orders`, `POST /public/coaching/products/:id/booking/update`
+ * and `POST /public/courses/:id/booking/update` all return this same shape
+ * (S.3, `89a721af`).
+ *
+ * Every figure here is the SERVER'S, in major units. Nothing in the UI
+ * recomputes a discount: a buyer-visible number that disagrees with the charge
+ * is worse than no number at all.
+ */
+export type PillarDiscountQuote = {
+  /** GROSS, before any discount. */
+  subTotal: number;
+  /** NET — what the buyer is being asked to pay. */
+  totalAmount: number;
+  /** The whole discount, summed across `appliedCoupons`. */
+  discountAmount: number;
+  couponId: string | null;
+  appliedCoupons: AppliedDiscountCoupon[];
+};
+
 export enum ProductDeliveryType {
   Digital = "digital",
   Physical = "physical",
@@ -813,6 +851,23 @@ export interface IEvent {
   id: string;
   profileId: string;
   dateTime: string;
+  /**
+   * When the event ends. Nullable — plenty of events are published with only a
+   * start. Calendar links fall back to a default duration when it is absent.
+   */
+  endDateTime: string | null;
+  /** Doors/arrival time, when the host publishes one separately from the start. */
+  doorsOpenAt: string | null;
+  /**
+   * Event lifecycle (mirrors the backend `EVENT_STATUS` const — Forge cannot
+   * import from the API, so the union is restated here).
+   * `draft` never reaches a public surface.
+   */
+  status: "draft" | "scheduled" | "on_sale" | "sold_out" | "cancelled" | "completed";
+  /** Set when the host cancels; distinct from `archivedAt` (a hide-from-lists flag). */
+  cancelledAt: string | null;
+  /** Host-supplied reason shown to ticket-holders on a cancelled event. */
+  cancellationReason: string | null;
   timezone?: string;
   type: "physical" | "virtual" | "hybrid";
   ticketSaleMessage?: string;
@@ -1093,6 +1148,17 @@ export type ITicketOrder = {
   taxInclusive?: boolean;
   currency?: string;
   status: OrderStatus;
+  /**
+   * Refund tracking, written by the refund service and returned by the public
+   * finalize endpoint (`getOrderById` is `selectAll` over the order row).
+   *
+   * These are what tell a refund-voided `cancelled` order apart from an
+   * abandoned one — `status` alone cannot. See `getTicketOrderOutcome`.
+   * `refundedAmountCents` is a bigint column, so it arrives as a string.
+   */
+  refundedAmountCents?: number | string | null;
+  refundState?: "none" | "partial" | "full" | string | null;
+  lastRefundedAt?: string | null;
   customerName: string;
   customerEmail: string;
   createdAt: string;

package/src/ui/headless/calendar/useAddToCalendar.ts

@@ -0,0 +1,194 @@
+import { useMemo } from "react";
+
+/**
+ * "Add to calendar" link building — the whole of it. Styled components render
+ * anchors; they never assemble a URL themselves, so a fix to (say) Google's
+ * `dates` format lands in exactly one place.
+ *
+ * Everything here is framework-free and dependency-free: Forge ships no date
+ * library, so the two formats the providers want are derived from the platform
+ * `Date` alone.
+ */
+
+export type AddToCalendarInput = {
+  /** Event/session name — becomes the calendar entry's title. */
+  title: string;
+  /** Absolute instant the thing starts (ISO-8601 with an offset or `Z`). */
+  start: string | Date;
+  /** Absolute instant it ends. Nullable — falls back to `start + defaultDurationMinutes`. */
+  end?: string | Date | null;
+  /** Fallback length when `end` is absent. Defaults to 120 minutes. */
+  defaultDurationMinutes?: number;
+  /** Long description. HTML is stripped and truncated before it goes in a URL. */
+  description?: string | null;
+  /** Human-readable place (a street address, or "Virtual"). */
+  location?: string | null;
+  /** Canonical page for the event; appended to the description body when present. */
+  url?: string | null;
+  /**
+   * Absolute URL to a downloadable `.ics` (what Apple Calendar / Outlook desktop
+   * want). Forge does not synthesize this — the host passes the endpoint it has.
+   * When absent, `ics` comes back `null` and no Apple option is offered.
+   */
+  icsUrl?: string | null;
+};
+
+export type AddToCalendarLinks = {
+  /** Google Calendar "TEMPLATE" prefill. */
+  google: string;
+  /** Outlook.com (personal accounts). */
+  outlook: string;
+  /** Outlook on the web for work/school accounts (Microsoft 365). */
+  office365: string;
+  /** Yahoo Calendar. */
+  yahoo: string;
+  /** Pass-through of `icsUrl` — the Apple/desktop route. `null` when not supplied. */
+  ics: string | null;
+  startsAt: Date;
+  endsAt: Date;
+};
+
+/** Length of a calendar entry when the caller has no end time. */
+const DEFAULT_DURATION_MINUTES = 120;
+
+/** Calendar providers put the description in a URL; keep it well under limits. */
+const MAX_DESCRIPTION_CHARS = 800;
+
+/** Parse anything the caller has to a valid `Date`, or `null` if it isn't one. */
+function toDate(value: string | Date | null | undefined): Date | null {
+  if (value === null || value === undefined || value === "") return null;
+  const d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * UTC "basic format" (RFC 5545 / what Google and Yahoo want):
+ * `2026-03-15T06:30:00.000Z` → `20260315T063000Z`.
+ */
+export function toUtcBasic(d: Date): string {
+  return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+/**
+ * Flatten an HTML description to plain text. Event/session descriptions in this
+ * codebase are rich text rendered with `dangerouslySetInnerHTML`, so the raw
+ * value is markup — pasting it into a calendar body would show tags.
+ *
+ * `&` is decoded LAST so an encoded entity (`<`) doesn't turn into a
+ * live one.
+ */
+export function stripHtml(html: string, maxLength: number = MAX_DESCRIPTION_CHARS): string {
+  const text = html
+    .replace(/<\s*br\s*\/?\s*>/gi, "\n")
+    .replace(/<\s*\/\s*(p|div|li|tr|h[1-6])\s*>/gi, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&#39;/g, "'")
+    .replace(/&quot;/gi, '"')
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&amp;/gi, "&")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1).trimEnd()}…` : text;
+}
+
+const enc = encodeURIComponent;
+
+/**
+ * Build every provider URL for one calendar entry. Returns `null` when the
+ * start is missing or unparseable — callers render nothing rather than a link
+ * that would prefill garbage.
+ */
+export function buildAddToCalendarLinks(input: AddToCalendarInput): AddToCalendarLinks | null {
+  const startsAt = toDate(input.start);
+  if (!startsAt) return null;
+
+  const durationMinutes =
+    input.defaultDurationMinutes && input.defaultDurationMinutes > 0
+      ? input.defaultDurationMinutes
+      : DEFAULT_DURATION_MINUTES;
+
+  const parsedEnd = toDate(input.end);
+  // An end at-or-before the start is as useless as no end at all.
+  const endsAt =
+    parsedEnd && parsedEnd.getTime() > startsAt.getTime()
+      ? parsedEnd
+      : new Date(startsAt.getTime() + durationMinutes * 60_000);
+
+  const title = (input.title || "").trim();
+  const location = (input.location || "").trim();
+
+  const body = [input.description ? stripHtml(input.description) : "", (input.url || "").trim()]
+    .filter(Boolean)
+    .join("\n\n");
+
+  const startBasic = toUtcBasic(startsAt);
+  const endBasic = toUtcBasic(endsAt);
+  const startIso = startsAt.toISOString();
+  const endIso = endsAt.toISOString();
+
+  const outlookQuery =
+    `path=${enc("/calendar/action/compose")}` +
+    `&rru=addevent` +
+    `&subject=${enc(title)}` +
+    `&startdt=${enc(startIso)}` +
+    `&enddt=${enc(endIso)}` +
+    `&body=${enc(body)}` +
+    `&location=${enc(location)}`;
+
+  return {
+    google:
+      `https://calendar.google.com/calendar/render?action=TEMPLATE` +
+      `&text=${enc(title)}` +
+      `&dates=${startBasic}/${endBasic}` +
+      `&details=${enc(body)}` +
+      `&location=${enc(location)}`,
+    outlook: `https://outlook.live.com/calendar/0/deeplink/compose?${outlookQuery}`,
+    office365: `https://outlook.office.com/calendar/0/deeplink/compose?${outlookQuery}`,
+    yahoo:
+      `https://calendar.yahoo.com/?v=60` +
+      `&title=${enc(title)}` +
+      `&st=${startBasic}` +
+      `&et=${endBasic}` +
+      `&desc=${enc(body)}` +
+      `&in_loc=${enc(location)}`,
+    ics: input.icsUrl || null,
+    startsAt,
+    endsAt,
+  };
+}
+
+/**
+ * React wrapper over {@link buildAddToCalendarLinks}. Memoized on the primitive
+ * inputs so an anchor's `href` is referentially stable between renders.
+ *
+ * Returns `null` for an unusable start time — safe to call unconditionally with
+ * data that may still be loading.
+ */
+export function useAddToCalendar(input: AddToCalendarInput | null | undefined): AddToCalendarLinks | null {
+  const title = input?.title;
+  const start = input?.start;
+  const end = input?.end;
+  const defaultDurationMinutes = input?.defaultDurationMinutes;
+  const description = input?.description;
+  const location = input?.location;
+  const url = input?.url;
+  const icsUrl = input?.icsUrl;
+
+  return useMemo(() => {
+    if (!start) return null;
+    return buildAddToCalendarLinks({
+      title: title ?? "",
+      start,
+      end,
+      defaultDurationMinutes,
+      description,
+      location,
+      url,
+      icsUrl,
+    });
+  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl]);
+}