@tribe-nest/forge 3.4.0 → 3.9.0

package/src/data/queries/useMyTickets.ts

@@ -0,0 +1,154 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { PaginatedData } from "../../types/models";
+
+/**
+ * The signed-in buyer's own event tickets, and cancelling one (S.6).
+ *
+ * Lives in Forge rather than in either app because both rendering surfaces —
+ * the client PWA and code websites — need exactly this, and a second copy is
+ * how the two drift.
+ */
+
+/** Why the buyer cannot cancel, when they cannot. */
+export type TicketCancellationReason = "no_policy" | "not_allowed" | "window_closed" | "event_started";
+
+export type TicketCancellation = {
+  policy: "none" | "until" | "anytime" | null;
+  cutoffHours: number | null;
+  terms: string | null;
+  /** One sentence, already phrased for a buyer. Null when no policy was set. */
+  description: string | null;
+  canCancel: boolean;
+  reason: TicketCancellationReason | null;
+  /** The instant the window shuts. */
+  deadline: string | null;
+};
+
+/**
+ * One admitted person — an `event_passes` row, which is what a QR code, a
+ * transfer and a wallet pass are each *of*.
+ *
+ * The distinction matters because it is the one that trips people up: an order
+ * is a purchase, an ITEM is a purchase line ("2 × General Admission"), and a
+ * PASS is a single human being at a door. `MyTicket.id` is an order id and
+ * `MyTicketItem.id` is an order-item id, and NEITHER is accepted by any
+ * pass-scoped endpoint — `/public/events/passes/:passId/wallet` and
+ * `/public/events/passes/:passId/transfers` both take a `TN-…` id and answer
+ * 404 for anything else.
+ *
+ * Optional because the field is newer than the endpoint that reads it, and
+ * because a site pinned to an older API build would not have it. Always read it
+ * through `myTicketPassIds`, which tolerates its absence and yields `[]` — the
+ * "draw nothing" answer the wallet affordance needs anyway.
+ */
+export type MyTicketPass = {
+  /** `event_passes.id` — the string `TN-` followed by digits. */
+  id: string;
+  ownerName?: string | null;
+  ownerEmail?: string | null;
+  /** Set once the pass has been scanned at the door. */
+  checkedInAt?: string | null;
+};
+
+export type MyTicketItem = {
+  id: string;
+  quantity: number;
+  price: string | number;
+  ticketTitle: string | null;
+  /** The individual admissions on this line — where the API puts them. */
+  passes?: MyTicketPass[];
+};
+
+export type MyTicket = {
+  id: string;
+  status: string;
+  totalAmount: string | number;
+  currency: string | null;
+  createdAt: string;
+  refundState: string;
+  refundedAmountCents: string | number;
+  selfCancelledAt: string | null;
+  eventId: string;
+  eventTitle: string;
+  eventSlug: string | null;
+  eventDateTime: string;
+  eventEndDateTime: string | null;
+  eventTimezone: string | null;
+  eventStatus: string | null;
+  items: MyTicketItem[];
+  cancellation: TicketCancellation;
+  /**
+   * Not emitted by the API, which nests passes under each ITEM. Tolerated by
+   * `myTicketPassIds` so an order-level shape would not need a frontend change.
+   */
+  passes?: MyTicketPass[];
+};
+
+/**
+ * Every pass id on an order.
+ *
+ * Reads the item-level passes the API emits, and tolerates an order-level array
+ * as well — de-duplicated, because a payload carrying both would otherwise draw
+ * each ticket's wallet buttons twice.
+ *
+ * Anything that is not a `TN-…` id is dropped rather than sent: the pass-scoped
+ * endpoints 404 on the wrong shape, and a request that cannot succeed is not
+ * worth making. An older API build with no passes in the payload yields `[]`,
+ * which callers must treat as "draw nothing" rather than as a failure.
+ */
+export function myTicketPassIds(ticket: Pick<MyTicket, "passes" | "items">): string[] {
+  const seen = new Set<string>();
+  const collect = (passes?: MyTicketPass[]) => {
+    for (const pass of passes ?? []) {
+      if (typeof pass?.id === "string" && /^TN-\d+$/.test(pass.id)) seen.add(pass.id);
+    }
+  };
+
+  collect(ticket.passes);
+  for (const item of ticket.items ?? []) collect(item.passes);
+
+  return [...seen];
+}
+
+/**
+ * The buyer is resolved from the SESSION server-side — `accountId` here only
+ * gates the query on being signed in and keys the cache. It is never sent, and
+ * sending it would not help: the API ignores any buyer identity from input.
+ */
+export function useMyTickets(accountId?: string, page = 1, limit = 20) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<MyTicket>>({
+    queryKey: ["my-tickets", accountId, profileId, page, limit],
+    queryFn: async () => {
+      const res = await client.get("/public/events/my-tickets", {
+        params: { profileId, page, limit },
+      });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+/**
+ * Cancel one of the buyer's own tickets.
+ *
+ * Invalidates the list on success so the row reflects its new state rather than
+ * offering a button that would now be refused — the server is the authority on
+ * eligibility, and re-reading is cheaper than mirroring its rules here.
+ */
+export function useCancelMyTicket() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<{ orderId: string; refunded: boolean }, unknown, { orderId: string }>({
+    mutationFn: async ({ orderId }) => {
+      const res = await client.post(`/public/events/my-tickets/${orderId}/cancel`, { profileId });
+      return res.data;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["my-tickets"] });
+    },
+  });
+}

package/src/data/queries/usePassTransfers.ts

@@ -0,0 +1,318 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Events 2.2 — handing a ticket to somebody else, and taking one.
+ *
+ * Lives in Forge rather than in either app because both rendering surfaces —
+ * the client PWA and code websites — need exactly this, and a second copy is
+ * how the two drift (the same reason `useMyTickets` and `useEventWaitlist` are
+ * here).
+ *
+ * ## The endpoints
+ *
+ * ```
+ * POST /public/events/passes/:passId/transfers   send    → PassTransfer (201)
+ * POST /public/events/transfers/claim            claim   → PassTransfer & { eventPassId }
+ * POST /public/events/transfers/:id/cancel       cancel  → PassTransfer
+ * GET  /public/events/passes/:passId/transfers   history → OPERATOR ONLY (see below)
+ * ```
+ *
+ * `:passId` is an `event_passes` id — the string `TN-` followed by digits, NOT
+ * an order or order-item id. `myTicketPassIds()` in `useMyTickets` is how a
+ * buyer's portal gets one.
+ *
+ * ## Three things the server owns, which this file deliberately does not mirror
+ *
+ * 1. **Who may send.** The current holder, resolved from the SESSION against
+ *    the pass's `owner_email`. No identity is ever sent from here; a `fromEmail`
+ *    parameter is exactly the vulnerability the endpoint is shaped to avoid.
+ * 2. **Whether a pass may be handed on at all.** Checked-in, refunded, cancelled
+ *    show, finished show — all refused server-side, at SEND and again at CLAIM
+ *    because days pass in between. The UI draws the affordance and surfaces the
+ *    server's own message on refusal; it never pre-judges the answer.
+ * 3. **Whether a claim succeeds.** The token is the capability and the claim is
+ *    one atomic conditional UPDATE. A second click, an expired window and a
+ *    cancelled transfer are all its answers to give, each with a distinct
+ *    message.
+ *
+ * ## Why there is a local store for pending sends
+ *
+ * `GET /public/events/passes/:passId/transfers` is gated on the operator
+ * permission `events.read` — the chain names every previous holder, which the
+ * current one has no business reading — and nothing on `/public/events/my-tickets`
+ * carries transfer state. So a BUYER has no endpoint that lists their own
+ * pending transfer back to them: the only place a transfer id ever appears is
+ * the response to their own send.
+ *
+ * That id is remembered in `localStorage`, exactly as `useEventWaitlist` does
+ * for an anonymous joiner's entry id and for the same reason — it is the only
+ * way the browser that performed an action can show it again. It is a
+ * convenience, not a source of truth: the durable copy is the recipient's email,
+ * and every cancel is still decided by the server. A buyer on another device
+ * sees no pending transfer, which is a gap in the API rather than in this file.
+ */
+
+/** The lifecycle, restated (Forge cannot import from the API). */
+export type PassTransferStatus = "pending" | "claimed" | "cancelled" | "expired";
+
+/** The live claim window, computed server-side on every read. */
+export type PassTransferWindow = {
+  /** The claim link still works right now. */
+  open: boolean;
+  /** Whole seconds left when the server answered. `null` when there is no window. */
+  secondsRemaining: number | null;
+  /** The instant the link dies. */
+  expiresAt: string | null;
+};
+
+export type PassTransfer = {
+  id: string;
+  /** The `TN-…` pass this transfer is of. */
+  eventPassId: string;
+  eventId: string;
+  status: PassTransferStatus | string;
+  /** Denormalised at send time — the pass's own columns have moved on by now. */
+  fromName: string | null;
+  fromEmail: string;
+  toName: string | null;
+  toEmail: string;
+  expiresAt: string;
+  claimedAt: string | null;
+  cancelledAt: string | null;
+  createdAt: string;
+  window: PassTransferWindow;
+};
+
+export type SendPassTransferInput = {
+  /** The pass to hand over — a `TN-…` id from `myTicketPassIds()`. */
+  passId: string;
+  /** Where it goes. The only address the endpoint accepts. */
+  toEmail: string;
+  toName?: string;
+  /**
+   * How long the claim link lives, in hours. Bounded [1, 720] server-side and
+   * defaulted to 72 there; omit it and take the server's default rather than
+   * restating a number that would then have two definitions.
+   */
+  expiresInHours?: number;
+};
+
+export type ClaimPassTransferInput = {
+  /** 64 hex characters, out of the recipient's email link. */
+  token: string;
+  /** What the claimant is called at the door. Optional; the server falls back. */
+  name?: string;
+};
+
+/** Still live — the only status a cancel can act on. */
+export const isPendingPassTransfer = (transfer: Pick<PassTransfer, "status">): boolean =>
+  transfer.status === "pending";
+
+// ── The sender's own pending transfers, remembered locally ──────────────────
+//
+// See the file docblock: there is no buyer-readable list endpoint, so this is
+// the only way the browser that sent a transfer can offer to cancel it.
+
+const STORAGE_KEY = "tn.pass-transfers.pending";
+
+export type RememberedPassTransfer = {
+  passId: string;
+  transferId: string;
+  toEmail: string;
+  /** The server's window end, kept so the row can say when the link dies. */
+  expiresAt: string | null;
+};
+
+const isRemembered = (item: unknown): item is RememberedPassTransfer =>
+  !!item &&
+  typeof (item as RememberedPassTransfer).passId === "string" &&
+  typeof (item as RememberedPassTransfer).transferId === "string" &&
+  typeof (item as RememberedPassTransfer).toEmail === "string";
+
+const readRemembered = (): RememberedPassTransfer[] => {
+  if (typeof window === "undefined") return [];
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(isRemembered);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Cached so `useSyncExternalStore` gets a STABLE snapshot — returning a fresh
+ * array from every read would re-render forever. Invalidated on every write.
+ */
+let cache: RememberedPassTransfer[] | null = null;
+const listeners = new Set<() => void>();
+
+const snapshot = (): RememberedPassTransfer[] => {
+  if (!cache) cache = readRemembered();
+  return cache;
+};
+
+/** The server-rendered pass has no browser store; it must be empty and stable. */
+const EMPTY: RememberedPassTransfer[] = [];
+const serverSnapshot = (): RememberedPassTransfer[] => EMPTY;
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const writeRemembered = (entries: RememberedPassTransfer[]) => {
+  cache = entries;
+  if (typeof window !== "undefined") {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(entries));
+    } catch {
+      /* private mode / quota — the recipient's email is still the durable copy. */
+    }
+  }
+  listeners.forEach((listener) => listener());
+};
+
+export const getRememberedPassTransfers = (passId?: string): RememberedPassTransfer[] => {
+  const all = snapshot();
+  return passId ? all.filter((entry) => entry.passId === passId) : all;
+};
+
+export const rememberPassTransfer = (entry: RememberedPassTransfer) => {
+  const all = snapshot();
+  // One live transfer per pass is a DATABASE guarantee (a partial unique index),
+  // so a second remembered row for the same pass could only ever be stale.
+  const next = all.filter((item) => item.passId !== entry.passId && item.transferId !== entry.transferId);
+  writeRemembered([...next, entry]);
+};
+
+export const forgetPassTransfer = (transferId: string) => {
+  const all = snapshot();
+  if (!all.some((item) => item.transferId === transferId)) return;
+  writeRemembered(all.filter((item) => item.transferId !== transferId));
+};
+
+/**
+ * The remembered pending sends, as a REACTIVE read.
+ *
+ * There is no query to invalidate, so a plain read would leave a just-sent
+ * transfer invisible until a reload.
+ */
+export function usePendingPassTransfers(passId?: string): RememberedPassTransfer[] {
+  const all = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
+  return useMemo(() => (passId ? all.filter((entry) => entry.passId === passId) : all), [all, passId]);
+}
+
+// ── Hooks ───────────────────────────────────────────────────────────────────
+
+/**
+ * Hand a pass to an email address.
+ *
+ * A pass that already has a live transfer is refused (the partial unique index
+ * is the double-spend guard), as is a pass the caller does not currently hold —
+ * which answers 404, not 403, so the endpoint cannot be used to probe pass ids.
+ * Both come back as the server's own message; render it rather than replacing
+ * it with a guess at which rule fired.
+ *
+ * The created transfer is remembered locally so this browser can offer to
+ * cancel it, and `my-tickets` is invalidated because a claim will move the
+ * pass's owner out from under the buyer's list.
+ */
+export function useSendPassTransfer() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<PassTransfer, unknown, SendPassTransferInput>({
+    mutationFn: async ({ passId, toEmail, toName, expiresInHours }) => {
+      const res = await client.post(`/public/events/passes/${passId}/transfers`, {
+        profileId,
+        toEmail,
+        // Sent only when there is one — an empty string is not the same as "unset"
+        // to a `.max()`-bounded optional, and the server falls back sensibly.
+        ...(toName ? { toName } : {}),
+        ...(expiresInHours ? { expiresInHours } : {}),
+      });
+      return res.data;
+    },
+    onSuccess: (transfer) => {
+      rememberPassTransfer({
+        passId: transfer.eventPassId,
+        transferId: transfer.id,
+        toEmail: transfer.toEmail,
+        expiresAt: transfer.expiresAt ?? null,
+      });
+      void queryClient.invalidateQueries({ queryKey: ["my-tickets"] });
+    },
+  });
+}
+
+/**
+ * Withdraw an unclaimed transfer. Current holder only.
+ *
+ * `profileId` goes in the QUERY here, not the body — the endpoint validates
+ * `req.query`, and a body would be ignored and the request refused.
+ *
+ * A transfer that was claimed in the meantime is a 400 with the server's own
+ * wording, which is the correct outcome: the sender no longer holds the ticket,
+ * so there is nothing left to withdraw. The local record is dropped either way —
+ * whatever became of it, it is no longer pending.
+ */
+export function useCancelPassTransfer() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<PassTransfer, unknown, { transferId: string }>({
+    mutationFn: async ({ transferId }) => {
+      const res = await client.post(
+        `/public/events/transfers/${transferId}/cancel`,
+        {},
+        { params: { profileId } },
+      );
+      return res.data;
+    },
+    onSuccess: (transfer) => {
+      forgetPassTransfer(transfer.id);
+      void queryClient.invalidateQueries({ queryKey: ["my-tickets"] });
+    },
+  });
+}
+
+/**
+ * Take a ticket somebody sent you. **Deliberately usable while signed out.**
+ *
+ * The recipient is a stranger who may have no account here; requiring one would
+ * strand most transfers. The token IS the capability — a signed-in claimant is
+ * merely recorded against the row. So this hook sends no identity and must
+ * never be gated on `user`.
+ *
+ * Every refusal (already claimed, expired, cancelled, the show was called off,
+ * the sender walked through the door) arrives as a distinct server message.
+ * Surface it verbatim: the states are not enumerable from here, and "expired"
+ * versus "already claimed" is a materially different thing to somebody standing
+ * outside a venue.
+ */
+export function useClaimPassTransfer() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<PassTransfer & { eventPassId: string }, unknown, ClaimPassTransferInput>({
+    mutationFn: async ({ token, name }) => {
+      const res = await client.post("/public/events/transfers/claim", {
+        profileId,
+        token,
+        ...(name ? { name } : {}),
+      });
+      return res.data;
+    },
+    onSuccess: () => {
+      // The claimant may also be a ticket-holder here; the pass just moved.
+      void queryClient.invalidateQueries({ queryKey: ["my-tickets"] });
+    },
+  });
+}