@tribe-nest/forge 3.20.0 → 3.22.0

package/package.json

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

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

@@ -3,18 +3,19 @@ import {
   forgetPassTransfer,
   getRememberedPassTransfers,
   isPendingPassTransfer,
+  mergePendingTransfer,
   rememberPassTransfer,
 } from "../usePassTransfers";
-import { myTicketPassIds } from "../useMyTickets";
+import { myTicketHeldPassIds, myTicketPassIds, type MyTicket } 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.
+ * the one thing here with real logic; it used to be the ONLY record a buyer had
+ * of their own send, and is now demoted to a bridge across the refetch that
+ * follows one, with `my-tickets`' `pendingTransfer` as the source of truth.
  */
 
 const clear = () => {
@@ -87,3 +88,98 @@ describe("the ids a transfer can be addressed by", () => {
     expect(myTicketPassIds({ items: [{ id: "i", quantity: 1, price: 10, ticketTitle: null }] })).toEqual([]);
   });
 });
+
+
+/**
+ * One live transfer per pass is a DATABASE guarantee (a partial unique index),
+ * so exactly one row may ever be drawn. Two would be a lie about the ticket's
+ * state and would offer two "withdraw" buttons for one thing.
+ */
+describe("mergePendingTransfer", () => {
+  const remembered = {
+    passId: "TN-1",
+    transferId: "local-1",
+    toEmail: "local@example.com",
+    expiresAt: "2026-04-01T00:00:00.000Z",
+  };
+
+  const fromServer = {
+    id: "server-1",
+    status: "pending",
+    toName: null,
+    toEmail: "server@example.com",
+    expiresAt: "2026-04-02T00:00:00.000Z",
+    createdAt: "2026-03-30T00:00:00.000Z",
+    window: { open: true, secondsRemaining: 3600, expiresAt: "2026-04-02T00:00:00.000Z" },
+  };
+
+  it("is null when nothing is in flight anywhere", () => {
+    expect(mergePendingTransfer(null, [])).toBeNull();
+  });
+
+  it("THE POINT: the server's row is what a second device sees", () => {
+    // `localStorage` is empty here — this browser never sent anything. Before
+    // the API carried `pendingTransfer` this returned nothing, which is why a
+    // sender on another device had no transfer to withdraw.
+    const merged = mergePendingTransfer(fromServer, [])!;
+
+    expect(merged.transferId).toBe("server-1");
+    expect(merged.toEmail).toBe("server@example.com");
+    expect(merged.fromServer).toBe(true);
+    expect(merged.open).toBe(true);
+  });
+
+  it("the server WINS over a stale local record, rather than drawing both", () => {
+    const merged = mergePendingTransfer(fromServer, [remembered])!;
+    expect(merged.transferId).toBe("server-1");
+    expect(merged.fromServer).toBe(true);
+  });
+
+  it("falls back to the local bridge before the refetch lands", () => {
+    const merged = mergePendingTransfer(null, [remembered])!;
+    expect(merged.transferId).toBe("local-1");
+    expect(merged.fromServer).toBe(false);
+    // Optimistic: a just-sent transfer is live by construction, and the server
+    // corrects it on the very next read.
+    expect(merged.open).toBe(true);
+  });
+
+  it("reports a lapsed-but-unswept transfer as closed, and still withdrawable", () => {
+    const lapsed = { ...fromServer, window: { open: false, secondsRemaining: 0, expiresAt: fromServer.expiresAt } };
+    const merged = mergePendingTransfer(lapsed, [])!;
+
+    // Hiding it would put the sender back where they started: a live row they
+    // cannot address. The row stays, the copy changes.
+    expect(merged.open).toBe(false);
+    expect(merged.transferId).toBe("server-1");
+  });
+});
+
+/**
+ * Which passes may an affordance be drawn on?
+ *
+ * Every pass-scoped endpoint — transfer, wallet, QR — resolves the current
+ * HOLDER, and a purchaser sees passes they do not hold: named guests at
+ * checkout, and (until the read was fixed) tickets already claimed by somebody
+ * else. A control on one of those could only ever answer 404.
+ */
+describe("myTicketHeldPassIds", () => {
+  const ticket = (passes: { id: string; isHolder?: boolean }[]) =>
+    ({ items: [{ id: "item-1", quantity: passes.length, price: 10, ticketTitle: "GA", passes }] }) as unknown as MyTicket;
+
+  it("keeps only the passes the caller holds", () => {
+    const t = ticket([
+      { id: "TN-1", isHolder: true },
+      { id: "TN-2", isHolder: false },
+    ]);
+
+    expect(myTicketHeldPassIds(t)).toEqual(["TN-1"]);
+    // The unfiltered helper still reports everything on the order — the wallet
+    // and transfer controls are the things that need narrowing, not the list.
+    expect(myTicketPassIds(t)).toEqual(["TN-1", "TN-2"]);
+  });
+
+  it("treats an ABSENT flag as held, so an older API build is unchanged", () => {
+    expect(myTicketHeldPassIds(ticket([{ id: "TN-9" }]))).toEqual(["TN-9"]);
+  });
+});

package/src/data/queries/useAccountSettings.ts

@@ -69,13 +69,26 @@ export function useUpdateAccount() {
   });
 }
 
-/** Change the member's password. */
+/**
+ * Change the member's password.
+ *
+ * Tenant-scoped (`/public/sessions/password`), because that is where a fan's
+ * credential lives — see the note at the top of `useAuthActions.ts`. The global
+ * `/public/accounts/password` this used to call wrote a hash that login never
+ * reads: it returned 200, invalidated the session, and left the old password
+ * working.
+ *
+ * Requires an association-scoped session (the endpoint is behind
+ * `requireAssociation`). Every current login path mints one; a member still
+ * holding a pre-cutover account-scoped token gets a 401 and needs to sign in
+ * again — honest, where the old call was silently a no-op.
+ */
 export function useChangePassword() {
   const { client } = useForge();
 
   return useMutation<unknown, unknown, { currentPassword: string; newPassword: string }>({
     mutationFn: async (body) => {
-      const res = await client.put("/public/accounts/password", body);
+      const res = await client.put("/public/sessions/password", body);
       return res.data;
     },
   });

package/src/data/queries/useAuthActions.ts

@@ -2,26 +2,70 @@ import { useForge } from "../../provider/ForgeProvider";
 import { useMutation } from "@tanstack/react-query";
 
 // Stateless account actions (no session state) — kept out of PublicAuthContext.
+//
+// ## Why these hit `/public/sessions/*` and not `/public/accounts/*`
+//
+// A member's credential for a tenant lives on their `account_associations` row,
+// not on `accounts` — that is the hash `POST /public/sessions` checks at login
+// (see `resolveAssociationLogin` on the backend). `accounts.password` is the
+// CREATOR/admin-dashboard credential; for a fan it is at most a lazy-heal
+// fallback, gated on the account having some other relationship to the profile.
+//
+// These three calls used to point at the global `/public/accounts/*` endpoints,
+// which write `accounts.password`. Every one of them returned 200 and changed
+// nothing that login reads:
+//
+//   - "Change password" logged the member out (a credential change invalidates
+//     sessions), then refused the new password and kept accepting the old one.
+//   - "Forgot password" was worse: it reset a hash login never consults, so the
+//     member — who by definition no longer knows the old password — was locked
+//     out with a reset link that appeared to work.
+//
+// The tenant-scoped endpoints below are the ones the credential actually lives
+// behind, and they invalidate only this context's sessions.
 
-/** Request a password-reset email. */
+/**
+ * Request a password-reset email for this tenant.
+ *
+ * `profileId` comes from the provider (one deploy = one tenant); pass it
+ * explicitly only when rendering outside a pinned context.
+ */
 export function useForgotPassword() {
-  const { client } = useForge();
+  const { client, profileId } = useForge();
 
-  return useMutation<unknown, unknown, { email: string; origin?: string }>({
-    mutationFn: async ({ email, origin }) => {
-      const res = await client.post("/public/accounts/forgot-password", { email, origin });
+  return useMutation<unknown, unknown, { email: string; origin?: string; profileId?: string }>({
+    mutationFn: async ({ email, origin, profileId: overrideProfileId }) => {
+      const contextId = overrideProfileId ?? profileId;
+      if (!contextId) {
+        // Better than posting without it: the endpoint would 400 on schema
+        // validation and the form would show "something went wrong".
+        throw new Error("useForgotPassword: no profileId — pass one or render inside a ForgeProvider with profileId");
+      }
+      const res = await client.post("/public/sessions/forgot-password", {
+        profileId: contextId,
+        email,
+        // The reset link is built server-side from this, and the association
+        // endpoint requires it (the global one treated it as optional).
+        origin: origin ?? (typeof window !== "undefined" ? window.location.origin : undefined),
+      });
       return res.data;
     },
   });
 }
 
-/** Complete a password reset with the emailed token. */
+/**
+ * Complete a password reset with the emailed token.
+ *
+ * The token is looked up on the association row, so it must be redeemed against
+ * the same surface that issued it — a token minted by the hook above will not
+ * resolve on `/public/accounts/reset-password`, and vice versa.
+ */
 export function useResetPassword() {
   const { client } = useForge();
 
   return useMutation<unknown, unknown, { token: string; password: string }>({
     mutationFn: async ({ token, password }) => {
-      const res = await client.post("/public/accounts/reset-password", { token, password });
+      const res = await client.post("/public/sessions/reset-password", { token, password });
       return res.data;
     },
   });

package/src/data/queries/useEvents.ts

@@ -25,19 +25,48 @@ export function useEvents() {
  * seed the query — the hook then returns data on first render with no loading
  * state, so the page can be server-rendered for SEO with no client spinner.
  */
-export function useEvent(id?: string, options?: { initialData?: IEvent }) {
+export function useEvent(
+  id?: string,
+  options?: {
+    initialData?: IEvent;
+    /**
+     * A presale code the buyer holds (1.2). A correct one reveals the hidden
+     * tiers it unlocks, in this same response, and sets `presale.codeAccepted`.
+     *
+     * Part of the query KEY, so entering a code refetches rather than serving
+     * the unrevealed cache — and so the seeded `initialData` (fetched without a
+     * code) is not mistaken for a coded response.
+     */
+    accessCode?: string | null;
+  },
+) {
   const { client, profileId } = useForge();
+  const accessCode = options?.accessCode || undefined;
+  // Only callers that pass the option at all — presale-aware ones — get the
+  // hold-the-last-page behaviour below. Everyone else keeps the old semantics
+  // exactly, including "the event goes undefined while a DIFFERENT event
+  // loads", which is what a router navigation wants.
+  const presaleAware = !!options && "accessCode" in options;
 
   return useQuery<IEvent>({
-    queryKey: ["event", id, profileId],
+    queryKey: ["event", id, profileId, accessCode ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/events/${id}`, {
-        params: { profileId },
+        params: { profileId, ...(accessCode ? { accessCode } : {}) },
       });
       return res.data;
     },
     enabled: !!id && !!profileId && !!client,
-    initialData: options?.initialData,
+    // Seeding only applies to the uncoded query: `initialData` came from a
+    // loader that had no code, so handing it to a coded key would show an
+    // unrevealed tier list and claim the code was applied.
+    initialData: accessCode ? undefined : options?.initialData,
+    // Applying a code changes the query key, which would otherwise blank the
+    // whole event page back to a spinner while the coded read is in flight —
+    // the buyer presses Apply and the show they were reading disappears. Keep
+    // the last event on screen and let `isFetching` drive the field's own
+    // "Checking…".
+    placeholderData: presaleAware ? (previous?: IEvent) => previous : undefined,
   });
 }
 
@@ -49,6 +78,21 @@ export type CreateEventOrderInput = {
    * the tier's own `price` — it can raise what is charged, never lower it.
    */
   amounts?: Record<string, number>;
+  /**
+   * Who is actually coming, keyed by ticket id exactly as `items` is, one entry
+   * per seat of that tier in issue order (Events 2.1).
+   *
+   * Send it only when the event has `collectAttendeeDetails` on — the server
+   * does not read it otherwise. A list whose length does not equal that tier's
+   * quantity is REFUSED (a short list would leave a silent extra pass in the
+   * purchaser's name), so build it with `attendeesPayload` from
+   * `forge/ui`'s attendee helpers rather than by hand.
+   *
+   * `email` is accepted per attendee and deliberately not sent by either
+   * storefront: it is the pass's OWNER, so naming another address hands that
+   * seat away. Handing a ticket to somebody else is what transfer is for.
+   */
+  attendees?: Record<string, { name: string; email?: string }[]>;
   email: string;
   firstName?: string;
   lastName?: string;
@@ -60,6 +104,16 @@ export type CreateEventOrderInput = {
    * the reason as its message and no order is created.
    */
   couponCode?: string;
+  /**
+   * The PRESALE code (1.2) — not the discount code above. It buys access to a
+   * tier, it does not change a price.
+   *
+   * The sell guard runs against the tier's own column on every order, so this
+   * has to travel with the purchase and not merely with the read that revealed
+   * the tier: a buyer who unlocks a presale and then checks out without it gets
+   * their order refused after entering their card details.
+   */
+  accessCode?: string;
 };
 
 export type CreateEventOrderResult = {
@@ -83,6 +137,14 @@ export type CreateEventOrderResult = {
   couponId?: string | null;
   /** Every discount that applied, entered OR automatic. */
   appliedCoupons?: AppliedDiscountCoupon[];
+  /**
+   * When these tickets stop being reserved, ISO-8601.
+   *
+   * `null` for a free order — its hold has already converted by the time this
+   * returns, so a countdown on it would be counting something that no longer
+   * exists — and for a profile with inventory holds switched off.
+   */
+  holdExpiresAt?: string | null;
 };
 
 /** Create an event ticket order (the step before start-payment). */

package/src/data/queries/useMembership.ts

@@ -2,7 +2,13 @@ import type { MembershipTier } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useQuery } from "@tanstack/react-query";
 
-export function useGetMembershipTiers() {
+/**
+ * `opts.enabled` gates the request on top of the usual profile/client checks —
+ * for a caller that only needs tier NAMES when something is actually gated, and
+ * must not add a request to every ungated storefront. Defaults to on, so every
+ * existing caller is unchanged.
+ */
+export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
   const { client, profileId } = useForge();
 
   return useQuery<MembershipTier[]>({
@@ -15,6 +21,6 @@ export function useGetMembershipTiers() {
       });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!client && opts.enabled !== false,
   });
 }

package/src/data/queries/useMyBookings.ts

@@ -111,6 +111,18 @@ export type MyBooking = {
   /** The server's answer. Never recomputed here. */
   canReschedule: boolean;
   rescheduleReason: RescheduleRefusal | null;
+  /**
+   * The session's `.ics`, both forms — what lets the portal offer Apple
+   * Calendar rather than only Google/Outlook/Microsoft 365. `null` unless the
+   * booking is confirmed.
+   *
+   * The address is stable across a RESCHEDULE (it is HMAC(kind:id) and the
+   * booking id does not change), which is the mechanism by which a re-fetch
+   * moves the entry already in the buyer's calendar instead of adding a second
+   * one. Optional: an older API build does not emit it.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
 };
 
 export type CancelBookingResult = {

package/src/data/queries/useMyTickets.ts

@@ -49,8 +49,65 @@ export type MyTicketPass = {
   ownerEmail?: string | null;
   /** Set once the pass has been scanned at the door. */
   checkedInAt?: string | null;
+  /**
+   * Does the CALLER hold this pass right now?
+   *
+   * Not the same question as "is it on my order", and the difference is the one
+   * that trips people up. A purchaser who named guests at checkout owns passes
+   * carrying their guests' addresses from the moment they are written, and a
+   * transfer moves the holder without touching the order. Every pass-scoped
+   * endpoint — transfer, wallet, QR — resolves the HOLDER, so a control drawn
+   * on a pass the caller does not hold can only ever 404.
+   *
+   * Optional because it is newer than the endpoint. `myTicketHeldPassIds`
+   * treats its absence as "assume held", which is the old behaviour.
+   */
+  isHolder?: boolean;
+  /**
+   * The caller's OWN live transfer on this pass, straight from the API.
+   *
+   * Only ever a transfer THIS reader sent (the server matches `from_email`) and
+   * only while it is `pending`, so it never exposes the operator-only chain of
+   * previous holders. `null` when nothing is in flight.
+   *
+   * This is what replaced `localStorage` as the source of truth for "you have a
+   * transfer out on this ticket": the id used to exist nowhere but the response
+   * to the sender's own send, so the same person on a second device had nothing
+   * to withdraw.
+   */
+  pendingTransfer?: MyTicketPendingTransfer | null;
+};
+
+/** The live claim window, computed server-side on every read. */
+export type MyTicketTransferWindow = {
+  /** 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;
+};
+
+/**
+ * A pending transfer as the SENDER may see it — deliberately narrow.
+ *
+ * An id to address the withdraw endpoint with, the recipient THIS caller typed
+ * themselves, and the two timestamps that make "sent 2 hours ago, expires in
+ * 46" renderable. No token, no previous holder, no account ids.
+ */
+export type MyTicketPendingTransfer = {
+  id: string;
+  status: string;
+  toName: string | null;
+  toEmail: string;
+  expiresAt: string;
+  createdAt: string;
+  window: MyTicketTransferWindow;
 };
 
+/** How the caller comes to be looking at an order. */
+export type MyTicketRole = "purchaser" | "holder";
+
 export type MyTicketItem = {
   id: string;
   quantity: number;
@@ -78,6 +135,27 @@ export type MyTicket = {
   eventStatus: string | null;
   items: MyTicketItem[];
   cancellation: TicketCancellation;
+  /**
+   * `purchaser` — they paid for this order. `holder` — a pass out of it was
+   * TRANSFERRED to them and they bought nothing.
+   *
+   * A holder's row is scrubbed server-side: `totalAmount` and every line price
+   * are null, lines they hold no pass on are gone, and `cancellation.canCancel`
+   * is false (cancelling refunds the sender's money and voids every seat, which
+   * is not a gift recipient's call). Render the money block only for a
+   * purchaser — `Number(null)` is `0`, and a confident "$0.00" on somebody
+   * else's purchase is worse than saying nothing.
+   *
+   * Optional: an older API build emits no role, and treating that as
+   * `purchaser` reproduces exactly the previous behaviour.
+   */
+  role?: MyTicketRole;
+  /**
+   * The event's `.ics`, both forms — what lets the portal offer Apple Calendar
+   * rather than only the three template providers. Null for a cancelled show.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
   /**
    * 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.
@@ -111,6 +189,40 @@ export function myTicketPassIds(ticket: Pick<MyTicket, "passes" | "items">): str
   return [...seen];
 }
 
+/** Every pass on an order, flattened — the objects, not just the ids. */
+export function myTicketPasses(ticket: Pick<MyTicket, "passes" | "items">): MyTicketPass[] {
+  const seen = new Map<string, MyTicketPass>();
+  const collect = (passes?: MyTicketPass[]) => {
+    for (const pass of passes ?? []) {
+      if (typeof pass?.id === "string" && /^TN-\d+$/.test(pass.id) && !seen.has(pass.id)) {
+        seen.set(pass.id, pass);
+      }
+    }
+  };
+
+  collect(ticket.passes);
+  for (const item of ticket.items ?? []) collect(item.passes);
+
+  return [...seen.values()];
+}
+
+/**
+ * The passes the caller can actually ACT on — transfer, wallet, QR.
+ *
+ * Every pass-scoped endpoint resolves the current HOLDER, so drawing those
+ * controls on a pass the caller merely paid for (a named guest's seat, a ticket
+ * already claimed by somebody else) produced a 404 with no explanation. The
+ * affordance is now drawn from the server's own `isHolder`.
+ *
+ * A pass with no `isHolder` at all is treated as held: that is an older API
+ * build, and the previous behaviour was to offer the control for every pass.
+ */
+export function myTicketHeldPassIds(ticket: Pick<MyTicket, "passes" | "items">): string[] {
+  return myTicketPasses(ticket)
+    .filter((pass) => pass.isHolder !== false)
+    .map((pass) => pass.id);
+}
+
 /**
  * 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

package/src/data/queries/useOrders.ts

@@ -56,6 +56,16 @@ export type CreateOrderResult = {
   totalAmount: number;
   subTotal: number;
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
+  /**
+   * When the stock reserved for this cart goes back on sale, ISO-8601.
+   *
+   * `null` when nothing was reserved — an order that already settled (a free
+   * one), a cart of digital/service items, or a profile with inventory holds
+   * switched off. `start-payment` restarts this clock and reports the newer
+   * instant, so treat that one as authoritative once it arrives; this is what
+   * bridges the gap while it is in flight.
+   */
+  holdExpiresAt?: string | null;
 };
 
 /** Create a cart/product order (the step before start-payment). */

package/src/data/queries/usePassTransfers.ts

@@ -37,21 +37,27 @@ import { useForge } from "../../provider/ForgeProvider";
  *    cancelled transfer are all its answers to give, each with a distinct
  *    message.
  *
- * ## Why there is a local store for pending sends
+ * ## Where a pending transfer comes from — the SERVER, now
  *
  * `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.
+ * permission `events.read` and stays that way: the chain names every previous
+ * holder, which the current one has no business reading. For a while that left
+ * a buyer with no endpoint listing their own pending transfer back to them —
+ * the id existed nowhere but the response to their own send — so this file
+ * remembered it in `localStorage`, exactly as `useEventWaitlist` does for an
+ * anonymous joiner's entry id.
  *
- * 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.
+ * `/public/events/my-tickets` now carries `pendingTransfer` on each pass:
+ * `status = 'pending'` AND a `from_email` match on the reader, so the only row
+ * that can surface is one the reader sent. **That is the source of truth.** A
+ * sender who signed in on a second device can see and withdraw a transfer they
+ * started on the first, which is the case `localStorage` could never serve.
+ *
+ * The local store is KEPT, demoted to what it always really was: a same-render
+ * bridge. `my-tickets` is a paginated query that has to round-trip before the
+ * new row appears, and a just-sent transfer vanishing for a second reads as a
+ * failed send. `mergePendingTransfers` below prefers the server's copy whenever
+ * it has one, so the two can never both draw a row.
  */
 
 /** The lifecycle, restated (Forge cannot import from the API). */
@@ -202,13 +208,67 @@ export const forgetPassTransfer = (transferId: string) => {
  * 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.
+ * transfer invisible until `my-tickets` refetches.
  */
 export function usePendingPassTransfers(passId?: string): RememberedPassTransfer[] {
   const all = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
   return useMemo(() => (passId ? all.filter((entry) => entry.passId === passId) : all), [all, passId]);
 }
 
+/** One pending transfer, however the caller came by it. */
+export type PendingTransferView = {
+  /** The id the withdraw endpoint takes. */
+  transferId: string;
+  toEmail: string;
+  /** The instant the claim link dies. `null` when unknown (a local-only row). */
+  expiresAt: string | null;
+  /** False once the window has lapsed — server-computed, never re-derived. */
+  open: boolean;
+  /** True when this came off `my-tickets` rather than out of `localStorage`. */
+  fromServer: boolean;
+};
+
+/**
+ * The pending transfer to DRAW for one pass — the server's if it has one, the
+ * local bridge otherwise.
+ *
+ * De-duplication matters more than it looks: one live transfer per pass is a
+ * DATABASE guarantee (a partial unique index), so two rows on screen would be a
+ * lie about the ticket's state and would offer two "withdraw" buttons for one
+ * thing. The server wins whenever it answers, because it also knows whether the
+ * window is still open.
+ *
+ * `null` means nothing is in flight — a pass with no outstanding transfer, on
+ * any device.
+ */
+export function mergePendingTransfer(
+  serverTransfer: { id: string; toEmail: string; expiresAt: string; window?: { open: boolean } } | null | undefined,
+  remembered: RememberedPassTransfer[],
+): PendingTransferView | null {
+  if (serverTransfer) {
+    return {
+      transferId: serverTransfer.id,
+      toEmail: serverTransfer.toEmail,
+      expiresAt: serverTransfer.expiresAt ?? null,
+      // A lapsed-but-unswept transfer is still `pending` and still withdrawable;
+      // the server says `open: false` and the UI says so too rather than hiding
+      // a live row the sender cannot otherwise address.
+      open: serverTransfer.window?.open ?? true,
+      fromServer: true,
+    };
+  }
+
+  const local = remembered[0];
+  if (!local) return null;
+  return {
+    transferId: local.transferId,
+    toEmail: local.toEmail,
+    expiresAt: local.expiresAt,
+    open: true,
+    fromServer: false,
+  };
+}
+
 // ── Hooks ───────────────────────────────────────────────────────────────────
 
 /**