@tribe-nest/forge 3.2.0 → 3.9.0

package/package.json

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

package/src/data/queries/_tests/eventWaitlist.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  forgetWaitlistEntry,
+  getRememberedWaitlistEntries,
+  isEventWaitlistOpen,
+  isLiveWaitlistEntry,
+  isTicketSoldOut,
+  rememberWaitlistEntry,
+  ticketSeatsRemaining,
+} from "../useEventWaitlist";
+import type { IEvent, ITicket } from "../../../types/models";
+
+/**
+ * Events 2.6 — the pure decisions behind the buyer-facing waitlist.
+ *
+ * Only the total functions are exercised here; everything else in the module is
+ * a thin transport whose behaviour belongs to the API's own specs.
+ */
+
+const tier = (overrides: Partial<ITicket> = {}): ITicket =>
+  ({
+    id: "t1",
+    title: "Standing",
+    description: "",
+    price: 25,
+    quantity: 100,
+    order: 0,
+    sold: 0,
+    maxPerPerson: 4,
+    ...overrides,
+  }) as ITicket;
+
+describe("ticketSeatsRemaining", () => {
+  it("counts what is left, floored at zero", () => {
+    expect(ticketSeatsRemaining(tier({ quantity: 100, sold: 40 }))).toBe(60);
+    expect(ticketSeatsRemaining(tier({ quantity: 100, sold: 100 }))).toBe(0);
+    // Oversold (a refund race, a manual capacity cut) is still zero, never negative.
+    expect(ticketSeatsRemaining(tier({ quantity: 100, sold: 120 }))).toBe(0);
+  });
+});
+
+describe("isTicketSoldOut — where a join control may be drawn", () => {
+  it("is false while anything is left to sell", () => {
+    expect(isTicketSoldOut(tier({ quantity: 10, sold: 9 }))).toBe(false);
+  });
+
+  it("is true once nothing is left", () => {
+    expect(isTicketSoldOut(tier({ quantity: 10, sold: 10 }))).toBe(true);
+  });
+
+  it("never offers a queue for an archived tier", () => {
+    expect(isTicketSoldOut(tier({ quantity: 10, sold: 10, archivedAt: "2026-01-01T00:00:00Z" }))).toBe(false);
+  });
+
+  it("never offers a queue once the sale window has closed", () => {
+    const now = new Date("2026-08-01T12:00:00Z");
+    // Waiting for a release that can no longer be sold is waiting for an email
+    // that will never arrive.
+    expect(isTicketSoldOut(tier({ quantity: 10, sold: 10, expiresAt: "2026-07-31T00:00:00Z" }), now)).toBe(false);
+    expect(isTicketSoldOut(tier({ quantity: 10, sold: 10, expiresAt: "2026-08-02T00:00:00Z" }), now)).toBe(true);
+  });
+});
+
+describe("isEventWaitlistOpen", () => {
+  const withStatus = (status: IEvent["status"]) => ({ status });
+
+  it("accepts the statuses a sign-up can still mean something on", () => {
+    expect(isEventWaitlistOpen(withStatus("scheduled"))).toBe(true);
+    expect(isEventWaitlistOpen(withStatus("on_sale"))).toBe(true);
+    expect(isEventWaitlistOpen(withStatus("sold_out"))).toBe(true);
+  });
+
+  it("refuses a show that is over or called off", () => {
+    expect(isEventWaitlistOpen(withStatus("cancelled"))).toBe(false);
+    expect(isEventWaitlistOpen(withStatus("completed"))).toBe(false);
+    expect(isEventWaitlistOpen(withStatus("draft"))).toBe(false);
+  });
+});
+
+describe("isLiveWaitlistEntry", () => {
+  it("counts a held offer as being on the list", () => {
+    expect(isLiveWaitlistEntry({ status: "waiting" })).toBe(true);
+    // An open offer IS a place in the queue, just a better one.
+    expect(isLiveWaitlistEntry({ status: "notified" })).toBe(true);
+  });
+
+  it("excludes every terminal status", () => {
+    expect(isLiveWaitlistEntry({ status: "converted" })).toBe(false);
+    expect(isLiveWaitlistEntry({ status: "left" })).toBe(false);
+    expect(isLiveWaitlistEntry({ status: "expired" })).toBe(false);
+  });
+});
+
+describe("the anonymous joiner's remembered capability ids", () => {
+  beforeEach(() => {
+    for (const entry of getRememberedWaitlistEntries()) forgetWaitlistEntry(entry.entryId);
+  });
+
+  it("remembers an entry and narrows by event", () => {
+    rememberWaitlistEntry({ eventId: "e1", entryId: "a" });
+    rememberWaitlistEntry({ eventId: "e2", entryId: "b" });
+
+    expect(getRememberedWaitlistEntries().map((e) => e.entryId)).toEqual(["a", "b"]);
+    expect(getRememberedWaitlistEntries("e1").map((e) => e.entryId)).toEqual(["a"]);
+  });
+
+  it("does not duplicate a re-join of the same entry", () => {
+    // Joining is idempotent server-side, so the SAME id comes back a second
+    // time — it must not become two places in the UI.
+    rememberWaitlistEntry({ eventId: "e1", entryId: "a" });
+    rememberWaitlistEntry({ eventId: "e1", entryId: "a" });
+
+    expect(getRememberedWaitlistEntries("e1")).toHaveLength(1);
+  });
+
+  it("forgets an entry once it is left", () => {
+    rememberWaitlistEntry({ eventId: "e1", entryId: "a" });
+    forgetWaitlistEntry("a");
+
+    expect(getRememberedWaitlistEntries("e1")).toEqual([]);
+  });
+});

package/src/data/queries/_tests/passTransfers.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  forgetPassTransfer,
+  getRememberedPassTransfers,
+  isPendingPassTransfer,
+  rememberPassTransfer,
+} from "../usePassTransfers";
+import { myTicketPassIds } from "../useMyTickets";
+
+/**
+ * Events 2.2 — the pure decisions behind the buyer-facing transfer surface.
+ *
+ * Only the total functions are exercised; the hooks themselves are thin
+ * transport whose behaviour belongs to the API's own specs. The local store is
+ * the one thing here with real logic, and it exists because there is NO
+ * buyer-readable list endpoint — the transfer history is operator-only — so a
+ * bug in it is a pending transfer the sender can never withdraw.
+ */
+
+const clear = () => {
+  for (const entry of getRememberedPassTransfers()) forgetPassTransfer(entry.transferId);
+};
+
+beforeEach(clear);
+
+describe("isPendingPassTransfer", () => {
+  it("is true only for the one status a cancel can act on", () => {
+    expect(isPendingPassTransfer({ status: "pending" })).toBe(true);
+    for (const status of ["claimed", "cancelled", "expired"]) {
+      expect(isPendingPassTransfer({ status })).toBe(false);
+    }
+  });
+});
+
+describe("the remembered-send store", () => {
+  it("keeps a send and reads it back, narrowed to its pass", () => {
+    rememberPassTransfer({ passId: "TN-1", transferId: "a", toEmail: "x@y.com", expiresAt: null });
+    rememberPassTransfer({ passId: "TN-2", transferId: "b", toEmail: "z@y.com", expiresAt: null });
+
+    expect(getRememberedPassTransfers()).toHaveLength(2);
+    expect(getRememberedPassTransfers("TN-1")).toEqual([
+      { passId: "TN-1", transferId: "a", toEmail: "x@y.com", expiresAt: null },
+    ]);
+  });
+
+  it("keeps at most ONE row per pass — the database allows no more", () => {
+    // A partial unique index enforces one live transfer per pass, so a second
+    // remembered row for the same pass could only ever be stale. The newest
+    // send wins; a stale id would offer a cancel that answers 400.
+    rememberPassTransfer({ passId: "TN-1", transferId: "old", toEmail: "x@y.com", expiresAt: null });
+    rememberPassTransfer({ passId: "TN-1", transferId: "new", toEmail: "q@y.com", expiresAt: null });
+
+    expect(getRememberedPassTransfers("TN-1")).toEqual([
+      { passId: "TN-1", transferId: "new", toEmail: "q@y.com", expiresAt: null },
+    ]);
+  });
+
+  it("forgets by transfer id and leaves the others alone", () => {
+    rememberPassTransfer({ passId: "TN-1", transferId: "a", toEmail: "x@y.com", expiresAt: null });
+    rememberPassTransfer({ passId: "TN-2", transferId: "b", toEmail: "z@y.com", expiresAt: null });
+
+    forgetPassTransfer("a");
+
+    expect(getRememberedPassTransfers().map((entry) => entry.transferId)).toEqual(["b"]);
+    // Forgetting something that was never there is a no-op, not a throw — a
+    // cancel whose row had already been dropped must still resolve.
+    expect(() => forgetPassTransfer("a")).not.toThrow();
+  });
+});
+
+describe("the ids a transfer can be addressed by", () => {
+  it("only ever sends a TN-… pass id, which is what the endpoint accepts", () => {
+    // The send endpoint is `/public/events/passes/:passId/transfers` and 404s on
+    // an order or order-item id. `myTicketPassIds` is the only source the portal
+    // has, so this is the contract the affordance is drawn from.
+    const ids = myTicketPassIds({
+      items: [
+        { id: "order-item-uuid", quantity: 2, price: 25, ticketTitle: "GA", passes: [{ id: "TN-11" }, { id: "TN-12" }] },
+        { id: "another-item", quantity: 1, price: 25, ticketTitle: "GA", passes: [{ id: "not-a-pass" }] },
+      ],
+    });
+
+    expect(ids).toEqual(["TN-11", "TN-12"]);
+  });
+
+  it("yields nothing when the API build emits no passes — draw no affordance", () => {
+    expect(myTicketPassIds({ items: [{ id: "i", quantity: 1, price: 10, ticketTitle: null }] })).toEqual([]);
+  });
+});

package/src/data/queries/_tests/walletPass.spec.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { hasWalletPass, isEventPassId, type WalletPassStatus } from "../useWalletPass";
+import { myTicketPassIds, type MyTicket } from "../useMyTickets";
+
+/**
+ * Events 2.3 — the pure decisions behind the wallet affordance.
+ *
+ * `hasWalletPass` is the single predicate that decides whether a buyer ever
+ * learns the feature exists, so it gets exhaustive coverage of the ways it must
+ * answer NO. Everything else in the module is transport, and belongs to the
+ * API's own specs.
+ */
+
+const status = (overrides: Partial<WalletPassStatus> = {}): WalletPassStatus => ({
+  passId: "TN-1001",
+  available: true,
+  reason: null,
+  apple: { available: true, downloadUrl: "/public/events/passes/TN-1001/wallet/apple?profileId=p1" },
+  google: { available: true, saveUrl: "https://pay.google.com/gp/v/save/jwt" },
+  ...overrides,
+});
+
+describe("hasWalletPass", () => {
+  it("is false for anything that is not a settled, positive answer", () => {
+    // No answer yet, or a query that 401'd / 404'd / failed. Absence of data is
+    // absence of the feature — never a placeholder.
+    expect(hasWalletPass(undefined)).toBe(false);
+    expect(hasWalletPass(null)).toBe(false);
+  });
+
+  it("is false for the state production is actually in today", () => {
+    // No signing credentials configured. This is a 200 — a successful "the
+    // feature is off" — and it must be indistinguishable from the feature not
+    // existing at all.
+    expect(
+      hasWalletPass(
+        status({
+          available: false,
+          reason: "not_configured",
+          apple: { available: false, downloadUrl: null },
+          google: { available: false, saveUrl: null },
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("is false for every other refusal the API can give", () => {
+    for (const reason of ["rotating_qr", "order_not_active"] as const) {
+      expect(
+        hasWalletPass(
+          status({
+            available: false,
+            reason,
+            apple: { available: false, downloadUrl: null },
+            google: { available: false, saveUrl: null },
+          }),
+        ),
+      ).toBe(false);
+    }
+  });
+
+  it("is false when the API says available but neither provider produced anything", () => {
+    // Belt and braces: a provider can throw AFTER the credential gate passed
+    // (a certificate that parses but will not sign), and the API degrades the
+    // two providers independently. `available` alone is not enough to draw on.
+    expect(
+      hasWalletPass(
+        status({ apple: { available: false, downloadUrl: null }, google: { available: false, saveUrl: null } }),
+      ),
+    ).toBe(false);
+  });
+
+  it("is true as soon as EITHER provider has something real", () => {
+    expect(hasWalletPass(status({ google: { available: false, saveUrl: null } }))).toBe(true);
+    expect(hasWalletPass(status({ apple: { available: false, downloadUrl: null } }))).toBe(true);
+    expect(hasWalletPass(status())).toBe(true);
+  });
+});
+
+describe("isEventPassId", () => {
+  it("accepts only `TN-` plus digits, matching the API's own guard", () => {
+    expect(isEventPassId("TN-1")).toBe(true);
+    expect(isEventPassId("TN-000000123")).toBe(true);
+  });
+
+  it("rejects the ids a caller is most likely to reach for by mistake", () => {
+    // An order id and an order-item id are what `useMyTickets` actually hands
+    // back; sending either would be a guaranteed 404.
+    expect(isEventPassId("0f9c8b7a-1111-2222-3333-444455556666")).toBe(false);
+    expect(isEventPassId("TN-")).toBe(false);
+    expect(isEventPassId("TN-12a")).toBe(false);
+    expect(isEventPassId("tn-12")).toBe(false);
+    expect(isEventPassId(" TN-12")).toBe(false);
+    expect(isEventPassId(undefined)).toBe(false);
+    expect(isEventPassId(null)).toBe(false);
+    expect(isEventPassId(12)).toBe(false);
+  });
+});
+
+const ticket = (overrides: Partial<MyTicket> = {}): MyTicket =>
+  ({
+    id: "order-1",
+    items: [],
+    ...overrides,
+  }) as MyTicket;
+
+describe("myTicketPassIds", () => {
+  it("is empty when the payload carries no passes at all", () => {
+    // An older API build, before `/public/events/my-tickets` nested passes
+    // under each item. The affordance must simply not appear rather than error.
+    expect(
+      myTicketPassIds(
+        ticket({ items: [{ id: "item-1", quantity: 2, price: 10, ticketTitle: "General Admission" }] }),
+      ),
+    ).toEqual([]);
+  });
+
+  it("reads pass ids from the order level", () => {
+    expect(myTicketPassIds(ticket({ passes: [{ id: "TN-1" }, { id: "TN-2" }] }))).toEqual(["TN-1", "TN-2"]);
+  });
+
+  it("reads pass ids nested under items — the shape the API actually emits", () => {
+    expect(
+      myTicketPassIds(
+        ticket({
+          items: [
+            { id: "item-1", quantity: 1, price: 10, ticketTitle: "GA", passes: [{ id: "TN-3" }] },
+            { id: "item-2", quantity: 1, price: 20, ticketTitle: "VIP", passes: [{ id: "TN-4" }] },
+          ],
+        }),
+      ),
+    ).toEqual(["TN-3", "TN-4"]);
+  });
+
+  it("de-duplicates across both shapes, so a payload carrying both draws one set of buttons", () => {
+    expect(
+      myTicketPassIds(
+        ticket({
+          passes: [{ id: "TN-5" }],
+          items: [{ id: "item-1", quantity: 1, price: 10, ticketTitle: "GA", passes: [{ id: "TN-5" }] }],
+        }),
+      ),
+    ).toEqual(["TN-5"]);
+  });
+
+  it("drops anything that is not a pass id rather than sending a request that must 404", () => {
+    expect(
+      myTicketPassIds(
+        ticket({
+          passes: [{ id: "order-1" }, { id: "" }, { id: "TN-6" }] as never,
+        }),
+      ),
+    ).toEqual(["TN-6"]);
+  });
+
+  it("survives a payload with no items array at all", () => {
+    expect(myTicketPassIds({ items: undefined as never, passes: undefined })).toEqual([]);
+  });
+});

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();