@tribe-nest/forge 3.4.0 → 3.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.4.0",
+  "version": "3.11.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/useCoachingAvailability.ts

@@ -1,4 +1,4 @@
-import type { BookingSlot, PillarDiscountQuote } from "../../types/models";
+import type { BookingSlot, CancellationTermsView, PillarDiscountQuote } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -18,11 +18,22 @@ export function useCoachingAvailability(productId?: string, fromDate?: string, t
   });
 }
 
-/** Reserve a coaching booking slot. Returns the created booking id. */
+export type ReserveCoachingBookingResult = {
+  bookingId: string;
+  totalAmount?: number;
+  /**
+   * The cancellation terms SNAPSHOTTED onto this booking (S.6). Authoritative
+   * from here on — the product's live policy may be edited while the hour is
+   * held, and the buyer's rights are governed by this copy, not by that read.
+   */
+  cancellation?: CancellationTermsView | null;
+};
+
+/** Reserve a coaching booking slot. Returns the created booking + its agreed terms. */
 export function useReserveCoachingBooking(productId?: string) {
   const { client } = useForge();
 
-  return useMutation<{ bookingId: string }, unknown, { slotId: string }>({
+  return useMutation<ReserveCoachingBookingResult, unknown, { slotId: string }>({
     mutationFn: async ({ slotId }) => {
       const res = await client.post(`/public/coaching/products/${productId}/booking/reserve`, {
         slotId,

package/src/data/queries/useEventSeries.ts

@@ -0,0 +1,42 @@
+import type { IEventSeries } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * A named, multi-date event series by slug (or id).
+ *
+ * ## There is deliberately no `useEventSeriesList`
+ *
+ * Every event belongs to a series, so a list endpoint would be a list of every
+ * event on the site wearing a different hat — and the ones the API refuses to
+ * publish (unnamed containers, single-date shows) would show up as holes in it.
+ * A series is a DESTINATION the operator shares, not a browsable index; the
+ * events list is already the browsable index.
+ *
+ * ## A 404 is the normal answer
+ *
+ * The API refuses any series that nobody named or that holds fewer than two
+ * publicly-visible dates. That is not an error state to surface as "something
+ * went wrong" — it means there is no such page — so a renderer should treat
+ * `isError` here the same way it treats a missing event.
+ *
+ * Pass `initialData` (a series fetched server-side in a route loader) to seed
+ * the query, so the page server-renders for SEO with no client spinner.
+ */
+export function useEventSeries(slugOrId?: string, options?: { initialData?: IEventSeries }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IEventSeries>({
+    queryKey: ["event-series", slugOrId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/event-series/${encodeURIComponent(slugOrId!)}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!slugOrId && !!profileId && !!client,
+    initialData: options?.initialData,
+    // A 404 here means "no such page", which no amount of retrying changes.
+    retry: false,
+  });
+}