@tribe-nest/forge 3.2.0 → 3.4.0

package/src/ui/styled/_tests/DiscountCode.spec.tsx

@@ -0,0 +1,272 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import { DiscountCodeField, DiscountSummaryLines } from "../DiscountCode";
+import type { CouponField } from "../../headless/coupon/useCouponField";
+import type { PillarDiscountQuote } from "../../../types/models";
+
+/**
+ * Rendered through `react-dom/server`, which needs no DOM — so these run in the
+ * package's existing node vitest environment with no new dependency and no
+ * jsdom project. Effects never fire under `renderToStaticMarkup`, so the
+ * `CouponField` fixture is the only data source and nothing reaches the network.
+ *
+ * `DiscountCodeField` and `DiscountSummaryLines` are the REAL components every
+ * ticket, booking, course and (client-app) checkout renders, so these assertions
+ * are about shipped behaviour, not a harness.
+ */
+
+const fmt = (n: number) => `$${n.toFixed(2)}`;
+
+/** A `CouponField` in a given state. The setters are inert — nothing clicks here. */
+function field(overrides: Partial<CouponField> = {}): CouponField {
+  const quote = overrides.quote ?? null;
+  return {
+    code: "",
+    setCode: () => {},
+    submittedCode: undefined,
+    showInput: false,
+    setShowInput: () => {},
+    error: null,
+    setError: () => {},
+    isApplying: false,
+    quote,
+    appliedCoupons: quote?.appliedCoupons ?? [],
+    discountAmount: quote?.discountAmount ?? 0,
+    hasDiscount: (quote?.discountAmount ?? 0) > 0,
+    apply: async () => {},
+    remove: async () => {},
+    record: () => {},
+    fail: () => {},
+    reset: () => {},
+    canQuote: true,
+    ...overrides,
+  };
+}
+
+/** What the server returns once SUMMER10 has been applied to a $50 course. */
+const appliedQuote: PillarDiscountQuote = {
+  subTotal: 50,
+  totalAmount: 42.5,
+  discountAmount: 7.5,
+  couponId: "coupon-1",
+  appliedCoupons: [{ code: "SUMMER10", discountKind: "simple", discountAmount: 7.5 }],
+};
+
+/** The undiscounted answer — what `remove()` puts back. */
+const clearedQuote: PillarDiscountQuote = {
+  subTotal: 50,
+  totalAmount: 50,
+  discountAmount: 0,
+  couponId: null,
+  appliedCoupons: [],
+};
+
+/** The summary as every checkout composes it: the lines, then the total. */
+function summary(coupon: CouponField, total: number) {
+  return renderToStaticMarkup(
+    <ForgeThemeProvider theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}>
+      <div>
+        <DiscountSummaryLines
+          subTotal={coupon.quote?.subTotal ?? total}
+          discountAmount={coupon.discountAmount}
+          appliedCoupons={coupon.appliedCoupons}
+          fmt={fmt}
+        />
+        <div>
+          <span>Total</span>
+          <span>{fmt(total)}</span>
+        </div>
+      </div>
+    </ForgeThemeProvider>,
+  );
+}
+
+function input(coupon: CouponField, props: Partial<{ mode: "quote" | "deferred"; disabled: boolean }> = {}) {
+  return renderToStaticMarkup(
+    <ForgeThemeProvider theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}>
+      <DiscountCodeField coupon={coupon} fmt={fmt} {...props} />
+    </ForgeThemeProvider>,
+  );
+}
+
+/** The markup carries HTML entities for the minus sign — normalise. */
+const plain = (html: string) => html.replace(/&#x2212;|&minus;/g, "−");
+
+describe("discount code — applying a valid code", () => {
+  const applied = field({ quote: appliedQuote, code: "SUMMER10", showInput: true });
+
+  it("shows a Discount LINE and the reduced total, not just a smaller number", () => {
+    const html = plain(summary(applied, appliedQuote.totalAmount));
+
+    // The line the whole feature exists for.
+    expect(html).toContain('data-testid="discount-line"');
+    expect(html).toContain("−$7.50");
+    // …with the subtotal beside it, so the buyer can see what it came off.
+    expect(html).toContain("Subtotal");
+    expect(html).toContain("$50.00");
+    // …and the reduced total.
+    expect(html).toContain("$42.50");
+    // The arithmetic on screen is the SERVER's and is self-consistent.
+    expect(appliedQuote.subTotal - appliedQuote.discountAmount).toBe(appliedQuote.totalAmount);
+  });
+
+  it("names the code that produced the discount", () => {
+    expect(plain(summary(applied, appliedQuote.totalAmount))).toContain("Discount (SUMMER10)");
+  });
+
+  it("shows the applied code with what it saved, and a way to remove it", () => {
+    const html = input(applied);
+    expect(html).toContain('data-testid="discount-code-applied"');
+    expect(html).toContain("SUMMER10");
+    expect(html).toContain("$7.50 off");
+    expect(html).toContain('data-testid="discount-code-remove"');
+    // The prompt is gone once something is applied.
+    expect(html).not.toContain('data-testid="discount-code-open"');
+  });
+});
+
+describe("discount code — an AUTOMATIC (no-code) discount", () => {
+  // The buyer typed nothing. Without this, the only evidence is a total that
+  // silently shrank.
+  const auto = field({
+    quote: {
+      subTotal: 50,
+      totalAmount: 45,
+      discountAmount: 5,
+      couponId: "coupon-auto",
+      appliedCoupons: [{ code: "AUTUMN", discountKind: "simple", discountAmount: 5 }],
+    },
+  });
+
+  it("is shown as applied even though the input was never opened", () => {
+    const html = input(auto);
+    expect(html).toContain('data-testid="discount-code-applied"');
+    expect(html).toContain("AUTUMN");
+    expect(html).toContain("$5.00 off");
+    expect(html).not.toContain('data-testid="discount-code-input"');
+  });
+
+  it("gets its own discount line", () => {
+    const html = plain(summary(auto, 45));
+    expect(html).toContain('data-testid="discount-line"');
+    expect(html).toContain("Discount (AUTUMN)");
+    expect(html).toContain("−$5.00");
+  });
+});
+
+describe("discount code — a rejected code", () => {
+  it("shows the API's own reason, not a generic 'invalid code'", () => {
+    // Exactly what `errors.coupon.min_order_value_not_met` renders to in `en`.
+    const html = input(
+      field({ code: "SUMMER10", showInput: true, error: "Your order does not reach this coupon's minimum spend" }),
+    );
+
+    expect(html).toContain('data-testid="discount-code-error"');
+    expect(html).toContain("Your order does not reach this coupon");
+    expect(html).toContain("minimum spend");
+    // The generic copy that would have thrown that reason away.
+    expect(html.toLowerCase()).not.toContain("invalid coupon code");
+    expect(html.toLowerCase()).not.toContain("invalid code");
+  });
+
+  it("carries each distinct reason through verbatim", () => {
+    for (const reason of [
+      "This coupon has expired",
+      "You have already used this coupon the maximum number of times",
+      "This coupon is only available to members of a specific tier",
+      "This coupon does not apply to anything in this order",
+    ]) {
+      expect(input(field({ code: "X", showInput: true, error: reason }))).toContain(reason);
+    }
+  });
+
+  it("does not record a discount for a code that was refused", () => {
+    // The total must keep matching the server: a refused code leaves the
+    // previous (here: absent) quote standing.
+    const html = plain(summary(field({ code: "X", showInput: true, error: "This coupon has expired" }), 50));
+    expect(html).not.toContain('data-testid="discount-line"');
+    expect(html).toContain("$50.00");
+  });
+});
+
+describe("discount code — removing a code", () => {
+  it("restores the original total and drops the discount line", () => {
+    // The state after `remove()` re-quoted with no code.
+    const html = plain(summary(field({ quote: clearedQuote }), clearedQuote.totalAmount));
+
+    expect(html).not.toContain('data-testid="discount-line"');
+    expect(html).not.toContain('data-testid="discount-summary"');
+    expect(html).toContain("$50.00");
+    expect(html).not.toContain("$42.50");
+    expect(clearedQuote.totalAmount).toBe(appliedQuote.subTotal);
+  });
+
+  it("puts the 'have a code?' prompt back", () => {
+    const html = input(field({ quote: clearedQuote }));
+    expect(html).toContain('data-testid="discount-code-open"');
+    expect(html).toContain("Have a discount code?");
+    expect(html).not.toContain('data-testid="discount-code-applied"');
+  });
+});
+
+describe("discount code — a checkout with no code (regression)", () => {
+  it("adds NOTHING to the summary", () => {
+    // The only thing inserted into every existing order summary is
+    // <DiscountSummaryLines>, and with no discount it must render nothing at
+    // all — so an undiscounted checkout looks exactly as it did before.
+    const html = renderToStaticMarkup(
+      <ForgeThemeProvider theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}>
+        <DiscountSummaryLines subTotal={50} discountAmount={0} fmt={fmt} />
+      </ForgeThemeProvider>,
+    );
+    // Only the provider's own theme <style> — the component itself emits nothing.
+    expect(html.replace(/<style>[\s\S]*?<\/style>/, "")).toBe("");
+  });
+
+  it("offers only a collapsed prompt — no input, no error, no applied block", () => {
+    const html = input(field());
+    expect(html).toContain('data-testid="discount-code-open"');
+    expect(html).not.toContain('data-testid="discount-code-input"');
+    expect(html).not.toContain('data-testid="discount-code-error"');
+    expect(html).not.toContain('data-testid="discount-code-applied"');
+  });
+
+  it("renders the untouched total", () => {
+    expect(plain(summary(field(), 50))).toContain("$50.00");
+  });
+});
+
+describe("discount code — the two apply modes", () => {
+  it("offers an Apply button where the pillar can really re-quote", () => {
+    const html = input(field({ showInput: true, code: "X" }), { mode: "quote" });
+    expect(html).toContain('data-testid="discount-code-apply"');
+    expect(html).not.toContain("applied at the next step");
+  });
+
+  it("offers no Apply button where the code can only be redeemed by the next call", () => {
+    // Tickets and bundles: `POST …/orders` and `POST /public/checkouts` CREATE
+    // the record, so there is nothing to press that would price a code without
+    // leaving a real abandoned order behind.
+    const html = input(field({ showInput: true, code: "X" }), { mode: "deferred" });
+    expect(html).not.toContain('data-testid="discount-code-apply"');
+    expect(html).toContain("Your code is applied at the next step.");
+  });
+
+  it("freezes once the code can no longer be changed", () => {
+    // A created bundle: the code was consumed by the call that made it.
+    const html = input(field({ quote: appliedQuote }), { disabled: true });
+    expect(html).toContain('data-testid="discount-code-applied"');
+    expect(html).toContain("SUMMER10");
+    expect(html).not.toContain('data-testid="discount-code-remove"');
+    expect(html).not.toContain('data-testid="discount-code-open"');
+  });
+
+  it("hides Remove for a pillar that cannot un-apply in place", () => {
+    // Event tickets expose their own "Remove discount" on the payment step,
+    // which restarts the order; the field itself must not pretend otherwise.
+    const html = input(field({ quote: appliedQuote, canQuote: false }));
+    expect(html).toContain('data-testid="discount-code-applied"');
+    expect(html).not.toContain('data-testid="discount-code-remove"');
+  });
+});

package/src/ui/styled/_tests/EventConfirmation.spec.tsx

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import { EventConfirmation } from "../EventConfirmation";
+import { OrderStatus, type ITicketOrder } from "../../../types/models";
+
+/**
+ * Rendered through `react-dom/server`, which needs no DOM — so these run in the
+ * package's existing node vitest environment with no new dependency and no
+ * jsdom project. Effects never fire under `renderToStaticMarkup`, so the seeded
+ * query cache is the only data source and nothing reaches the network.
+ */
+
+const PROFILE_ID = "profile-1";
+const ORDER_ID = "order-1";
+const EVENT_ID = "event-1";
+
+const baseOrder: ITicketOrder = {
+  id: "0f9c8b7a-1111-2222-3333-444455556666",
+  items: [{ id: "item-1", eventTicketId: "ticket-1", quantity: 2, price: 12.5, title: "General Admission" }],
+  firstName: "Ada",
+  lastName: "Lovelace",
+  email: "ada@example.com",
+  totalAmount: 25,
+  currency: "USD",
+  status: OrderStatus.Paid,
+  customerName: "Ada Lovelace",
+  customerEmail: "ada@example.com",
+  createdAt: "2026-07-01T10:00:00.000Z",
+  updatedAt: "2026-07-01T10:00:00.000Z",
+  eventTitle: "Midnight Set",
+  questionnaire: [],
+};
+
+function render(order: ITicketOrder) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  queryClient.setQueryData(["eventTicketOrderStatus", PROFILE_ID, ORDER_ID], order);
+  queryClient.setQueryData(["event", EVENT_ID, PROFILE_ID], {
+    id: EVENT_ID,
+    title: "Midnight Set",
+    description: "A set",
+    type: "virtual",
+    status: "published",
+    dateTime: "2026-09-01T20:00:00.000Z",
+    endDateTime: "2026-09-01T23:00:00.000Z",
+    timezone: "UTC",
+  });
+
+  return renderToStaticMarkup(
+    <QueryClientProvider client={queryClient}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+        <PublicAuthContext.Provider value={{ currencies: null, userSelectedCurrency: "USD" } as never}>
+          <ForgeThemeProvider
+            theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}
+          >
+            <EventConfirmation slug={EVENT_ID} orderId={ORDER_ID} formatAmount={(n) => `$${n.toFixed(2)}`} />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+/** The markup carries HTML entities for the curly apostrophes — normalise. */
+const plain = (html: string) => html.replace(/&#x27;|&#39;/g, "'").replace(/’/g, "'");
+
+describe("EventConfirmation — refunded vs abandoned", () => {
+  it("greets a refund-voided order with refunded copy, not 'order not completed'", () => {
+    const html = plain(
+      render({
+        ...baseOrder,
+        status: OrderStatus.Cancelled,
+        refundedAmountCents: "2500",
+        refundState: "full",
+      }),
+    );
+
+    expect(html).toContain("This order was refunded");
+    expect(html).toContain("bank or card issuer");
+    expect(html).toContain("will not admit entry");
+    expect(html).toContain("Refunded");
+
+    // The three things that were false for this buyer.
+    expect(html).not.toContain("Order not completed");
+    expect(html).not.toContain("contact support");
+    expect(html).not.toContain("If you were charged");
+    // ...and it must not congratulate them either.
+    expect(html).not.toContain("You're going!");
+
+    // The money line tells the truth about which direction it went.
+    expect(html).toContain("Total refunded");
+    expect(html).not.toContain("Total paid");
+
+    // Nothing that reads as a still-valid ticket: no scannable pass is rendered
+    // on this surface at all (the QR only ever lived in the emailed PDF), and
+    // the "add to calendar" prompt is paid-only.
+    expect(html.toLowerCase()).not.toContain("qr");
+    expect(html).not.toContain('data-testid="add-to-calendar"');
+    expect(html).not.toContain("E-Ticket");
+  });
+
+  it("still shows the existing 'not completed' copy for an abandoned checkout", () => {
+    // Regression guard. This path is unchanged and must stay: for a buyer who
+    // never paid, "order not completed / if you were charged, contact support"
+    // is the correct thing to say.
+    const html = plain(
+      render({
+        ...baseOrder,
+        status: OrderStatus.Cancelled,
+        refundedAmountCents: 0,
+        refundState: "none",
+      }),
+    );
+
+    expect(html).toContain("Order not completed");
+    expect(html).toContain("If you were charged, contact support.");
+    expect(html).toContain("Total"); // bare "Total", not "Total paid"
+    expect(html).not.toContain("Total paid");
+    expect(html).not.toContain("This order was refunded");
+    expect(html).not.toContain("Total refunded");
+  });
+
+  it("is unchanged for a paid order", () => {
+    const html = plain(render(baseOrder));
+
+    expect(html).toContain("You're going!");
+    expect(html).toContain("E-Ticket");
+    expect(html).toContain("We've sent your tickets to ada@example.com.");
+    expect(html).toContain("Total paid");
+    // Pins the "add to calendar" affordance as really present on the paid path,
+    // so its absence in the refunded case above is a meaningful assertion.
+    expect(html).toContain('data-testid="add-to-calendar"');
+    expect(html).not.toContain("This order was refunded");
+    expect(html).not.toContain("Order not completed");
+  });
+
+  it("keeps a partially refunded but still-valid order on the paid copy", () => {
+    // A partial refund voids nothing, so the pass still admits entry.
+    const html = plain(render({ ...baseOrder, refundedAmountCents: "500", refundState: "partial" }));
+
+    expect(html).toContain("You're going!");
+    expect(html).not.toContain("This order was refunded");
+  });
+
+  it("does not read a refund into a plain payment failure", () => {
+    const html = plain(render({ ...baseOrder, status: OrderStatus.PaymentFailed }));
+
+    expect(html).toContain("Order not completed");
+    expect(html).not.toContain("This order was refunded");
+  });
+});

package/src/utils/_tests/ticketOrderOutcome.spec.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import {
+  getTicketOrderOutcome,
+  isTicketOrderRefunded,
+  TICKET_ORDER_REFUNDED_COPY,
+} from "../ticketOrderOutcome";
+import { OrderStatus } from "../../types/models";
+
+/**
+ * The whole point of this module: `event_ticket_orders.status = cancelled`
+ * means two different things and the buyer must not be told the wrong one.
+ *
+ * The fixtures below mirror exactly what the backend writes:
+ *  - abandoned → the sweeper only ever touches `initiated_payment` rows, so the
+ *    refund columns are still at their defaults (0 / "none");
+ *  - refund-voided → `adjustPillarRefundTracking` runs BEFORE the void, and the
+ *    void is gated on a FULL refund, so the row is (>0 / "full") by then.
+ */
+const abandoned = {
+  status: OrderStatus.Cancelled,
+  refundedAmountCents: 0,
+  refundState: "none",
+};
+
+const refundVoided = {
+  status: OrderStatus.Cancelled,
+  // bigint over JSON — a string, which is the shape the API really sends.
+  refundedAmountCents: "2500",
+  refundState: "full",
+};
+
+describe("getTicketOrderOutcome", () => {
+  it("treats every fulfillment state of a successful order as paid", () => {
+    for (const status of [
+      OrderStatus.Paid,
+      OrderStatus.Processing,
+      OrderStatus.LabelPurchased,
+      OrderStatus.Shipped,
+      OrderStatus.Delivered,
+      OrderStatus.Processed,
+    ]) {
+      expect(getTicketOrderOutcome({ status })).toBe("paid");
+    }
+  });
+
+  it("calls a refund-voided cancelled order refunded, not not-completed", () => {
+    expect(getTicketOrderOutcome(refundVoided)).toBe("refunded");
+  });
+
+  it("still calls a swept, never-paid cancelled order not_completed", () => {
+    // Regression guard: this path is unchanged and MUST stay — the abandoned
+    // copy is correct for a buyer who never paid.
+    expect(getTicketOrderOutcome(abandoned)).toBe("not_completed");
+  });
+
+  it("treats a cancelled order with no refund fields at all as not_completed", () => {
+    // Rows written before the refund columns existed, and any caller that
+    // trims the payload: absence of evidence is not evidence of a refund.
+    expect(getTicketOrderOutcome({ status: OrderStatus.Cancelled })).toBe("not_completed");
+    expect(
+      getTicketOrderOutcome({ status: OrderStatus.Cancelled, refundedAmountCents: null, refundState: null }),
+    ).toBe("not_completed");
+  });
+
+  it("keeps a failed payment not_completed even though it is not cancelled", () => {
+    expect(getTicketOrderOutcome({ status: OrderStatus.PaymentFailed })).toBe("not_completed");
+    expect(getTicketOrderOutcome({ status: OrderStatus.InitiatedPayment })).toBe("not_completed");
+    expect(getTicketOrderOutcome({ status: OrderStatus.Failed })).toBe("not_completed");
+  });
+
+  it("leaves a PARTIALLY refunded, still-valid order as paid", () => {
+    // A partial refund voids nothing (786a20bc's rule) — the pass still admits
+    // entry, and this screen is about whether it does. Showing "refunded" here
+    // would be the mirror-image lie.
+    expect(
+      getTicketOrderOutcome({ status: OrderStatus.Paid, refundedAmountCents: "500", refundState: "partial" }),
+    ).toBe("paid");
+  });
+
+  it("tolerates a garbage refunded amount rather than inventing a refund", () => {
+    expect(
+      getTicketOrderOutcome({ status: OrderStatus.Cancelled, refundedAmountCents: "not-a-number" }),
+    ).toBe("not_completed");
+  });
+
+  it("falls back to refund_state when the amount is missing", () => {
+    // The two are written together, so this should not happen — but if it does,
+    // the state is still evidence money moved.
+    expect(getTicketOrderOutcome({ status: OrderStatus.Cancelled, refundState: "full" })).toBe("refunded");
+  });
+});
+
+describe("isTicketOrderRefunded", () => {
+  it("is false for an abandoned order and true for a refunded one", () => {
+    expect(isTicketOrderRefunded(abandoned)).toBe(false);
+    expect(isTicketOrderRefunded(refundVoided)).toBe(true);
+  });
+
+  it("does not treat a zero-cent refund row as a refund", () => {
+    expect(isTicketOrderRefunded({ status: OrderStatus.Cancelled, refundedAmountCents: "0", refundState: "none" })).toBe(
+      false,
+    );
+  });
+});
+
+describe("TICKET_ORDER_REFUNDED_COPY", () => {
+  it("never tells a refunded buyer their order was not completed", () => {
+    const all = Object.values(TICKET_ORDER_REFUNDED_COPY).join(" ").toLowerCase();
+    expect(all).not.toContain("not completed");
+    expect(all).not.toContain("contact support");
+    expect(all).not.toContain("if you were charged");
+  });
+
+  it("promises no settlement deadline we do not control", () => {
+    const body = TICKET_ORDER_REFUNDED_COPY.body.toLowerCase();
+    // No "5-10 business days" style claim: settlement is the provider's and the
+    // buyer's bank's, not ours.
+    expect(body).not.toMatch(/\d+\s*(-|–|to)?\s*\d*\s*(business\s+)?days?/);
+    expect(body).not.toContain("working days");
+    expect(body).toContain("bank or card issuer");
+  });
+
+  it("says the tickets no longer admit entry", () => {
+    expect(TICKET_ORDER_REFUNDED_COPY.body.toLowerCase()).toContain("will not admit entry");
+  });
+});

package/src/utils/ticketOrderOutcome.ts

@@ -0,0 +1,125 @@
+import { OrderStatus } from "../types/models";
+
+/**
+ * What a buyer looking at their ticket confirmation should be told.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * `event_ticket_orders.status = cancelled` means TWO different things, and the
+ * schema carries no discriminator column for them:
+ *
+ *   1. **Abandoned** — the buyer opened checkout, never paid, and
+ *      `SWEEP_ABANDONED_TICKET_ORDERS_JOB` retired the row. No money ever moved.
+ *   2. **Refund-voided** — the buyer DID pay, was refunded in full, and the
+ *      refund voided the order so the released seat cannot also scan at the
+ *      door (see `releaseInventoryForSource` / `voidTicketOrder`).
+ *
+ * Both surfaces used to render case 1's copy for both: "Order not completed —
+ * if you were charged, contact support." Told to someone who was charged and
+ * refunded, that is simply false.
+ *
+ * ── The signal, and why it is trustworthy ────────────────────────────────────
+ * `refunded_amount_cents` (> 0 once any money has gone back) and `refund_state`
+ * ("none" | "partial" | "full"). Both live on `event_ticket_orders` and both
+ * reach the buyer already: the public finalize endpoint answers with
+ * `EventTicketOrder.getOrderById`, which is `selectAll("eto")` — the whole row.
+ * No serializer change was needed to read them.
+ *
+ * They separate the two cases cleanly because of where each is written:
+ *
+ *   • The sweeper matches ONLY `status = initiated_payment` — an order that was
+ *     never paid — and touches no refund column. An abandoned order therefore
+ *     always carries `refunded_amount_cents = 0` / `refund_state = 'none'`
+ *     (the column defaults), and it is the only other writer of `cancelled` on
+ *     this table.
+ *   • Every path that voids a paid ticket order runs through the refund
+ *     service, which writes `adjustPillarRefundTracking` BEFORE it voids
+ *     (`recordRefund`: pillar sync, then `releaseInventoryForSource`). Both void
+ *     triggers — the seat release and an explicit `revokeAccess` — are gated on
+ *     `isFullyRefunded`, which requires `capturedAmountCents > 0`, so the state
+ *     written is always `"full"`, never `"partial"`.
+ *
+ * So the order of writes guarantees that a refund-voided order is never
+ * observed with zero refunded, and the sweeper guarantees an abandoned order is
+ * never observed with more than zero.
+ *
+ * `refunded_amount_cents > 0` is the primary test rather than
+ * `refund_state === "full"`: it is the value money is actually counted in, and
+ * it stays honest if a future partial-refund flow ever voids an order.
+ */
+export type TicketOrderOutcome =
+  /** Paid (or free) and still valid — the ticket admits entry. */
+  | "paid"
+  /** Was paid, money has gone back, the ticket no longer admits entry. */
+  | "refunded"
+  /** Never paid — abandoned checkout or a failed payment. */
+  | "not_completed";
+
+/** The only fields of a ticket order this decision reads. */
+export interface TicketOrderOutcomeInput {
+  status: OrderStatus | string;
+  /** Bigint column — arrives over JSON as a string. */
+  refundedAmountCents?: number | string | null;
+  refundState?: string | null;
+}
+
+/**
+ * A paid (or free) order advances through fulfillment — processing → shipped /
+ * delivered / processed. All of these mean the order succeeded, so the ticket
+ * confirmation treats them as "paid"; only failed/pending-payment states are
+ * "not completed". (A free order can be `delivered` by the time this loads.)
+ */
+const PAID_STATES = new Set<string>([
+  OrderStatus.Paid,
+  OrderStatus.Processing,
+  OrderStatus.LabelPurchased,
+  OrderStatus.Shipped,
+  OrderStatus.Delivered,
+  OrderStatus.Processed,
+]);
+
+/** Has any money gone back on this order? */
+export function isTicketOrderRefunded(order: TicketOrderOutcomeInput): boolean {
+  const cents = Number(order.refundedAmountCents ?? 0);
+  if (Number.isFinite(cents) && cents > 0) return true;
+  // Belt and braces: a `refund_state` of full/partial without a positive amount
+  // should not happen (they are written together), but if it ever does, the
+  // state is still evidence that money moved — and saying "refunded" to someone
+  // who was refunded is the failure we can afford.
+  return order.refundState === "full" || order.refundState === "partial";
+}
+
+/**
+ * Which of the three things happened to this ticket order.
+ *
+ * A still-valid order that carries a PARTIAL refund stays `"paid"` — the pass
+ * still admits entry, which is what this screen is about. Only an order that no
+ * longer admits entry AND has money back is `"refunded"`.
+ */
+export function getTicketOrderOutcome(order: TicketOrderOutcomeInput): TicketOrderOutcome {
+  if (PAID_STATES.has(order.status)) return "paid";
+  if (isTicketOrderRefunded(order)) return "refunded";
+  return "not_completed";
+}
+
+/**
+ * The refunded copy, shared verbatim by both rendering surfaces (the Forge
+ * `EventConfirmation` block and the client app's `/events/:id/finalise` page)
+ * so the two can never drift.
+ *
+ * Deliberately says nothing about how many days the money takes: settlement is
+ * the payment provider's and the buyer's bank's, not ours, and a number we
+ * cannot honour is the same kind of lie as "contact support" was.
+ *
+ * Equally deliberately does NOT invite the buyer to contact support: nothing
+ * went wrong here. The refund is the intended outcome.
+ */
+export const TICKET_ORDER_REFUNDED_COPY = {
+  /** Small uppercase label above the heading. */
+  eyebrow: "Refunded",
+  heading: "This order was refunded",
+  body:
+    "Your payment has been sent back to the original payment method — how long it takes to appear is up to your bank or card issuer. " +
+    "These tickets have been cancelled and will not admit entry.",
+  /** Replaces "Total paid" on the amount line. */
+  totalLabel: "Total refunded",
+} as const;