@tribe-nest/forge 3.53.0 → 3.54.0

package/src/utils/ticketOrderOutcome.ts

@@ -51,15 +51,40 @@ export type TicketOrderOutcome =
   | "paid"
   /** Was paid, money has gone back, the ticket no longer admits entry. */
   | "refunded"
-  /** Never paid — abandoned checkout or a failed payment. */
+  /**
+   * A ticket REQUEST the organiser has not decided yet (curated access,
+   * feature 3). The charge is committed but not taken, the seat is held, and
+   * no pass exists. Covers `pending_approval` and the transient `approved`,
+   * because from the fan's side "approved, settling" is still "waiting".
+   */
+  | "awaiting_approval"
+  /** The organiser said no. Nothing was charged and the hold was released. */
+  | "declined"
+  /** Never paid: abandoned checkout, a failed payment, or a request that lapsed or could not settle. */
   | "not_completed";
 
+/**
+ * Why a request ended without a sale, when it did. Picks the copy on a
+ * `not_completed` or `declined` outcome; `null` for an ordinary abandoned or
+ * declined-card order, whose copy is unchanged.
+ */
+export type TicketRequestFailureKind = "declined" | "expired" | "payment_failed";
+
 /** 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;
+  /**
+   * Set when this order was a ticket request that ended without a sale:
+   * `"expired"` on a `cancelled` row whose window lapsed undecided, the
+   * provider's reason on a `payment_failed` row that was approved but could
+   * not settle. Absent on an ordinary sale and on an older API build.
+   */
+  approvalFailureReason?: string | null;
+  /** Stamped when the request was lodged. A second signal that a `payment_failed` row was a request. */
+  approvalRequestedAt?: string | null;
 }
 
 /**
@@ -77,6 +102,9 @@ const PAID_STATES = new Set<string>([
   OrderStatus.Processed,
 ]);
 
+/** A request the organiser has not finished deciding. `approved` is transient: settlement is in flight. */
+const AWAITING_APPROVAL_STATES = new Set<string>([OrderStatus.PendingApproval, OrderStatus.Approved]);
+
 /** Has any money gone back on this order? */
 export function isTicketOrderRefunded(order: TicketOrderOutcomeInput): boolean {
   const cents = Number(order.refundedAmountCents ?? 0);
@@ -97,10 +125,38 @@ export function isTicketOrderRefunded(order: TicketOrderOutcomeInput): boolean {
  */
 export function getTicketOrderOutcome(order: TicketOrderOutcomeInput): TicketOrderOutcome {
   if (PAID_STATES.has(order.status)) return "paid";
+  // Before the refund test: nothing has been captured on a request, so the
+  // refund columns are at their defaults and cannot say anything about it.
+  if (AWAITING_APPROVAL_STATES.has(order.status)) return "awaiting_approval";
+  if (order.status === OrderStatus.Declined) return "declined";
   if (isTicketOrderRefunded(order)) return "refunded";
   return "not_completed";
 }
 
+/**
+ * Which way a ticket request ended, for an order that is `declined` or
+ * `not_completed`. `null` when the order was never a request, or is still one
+ * (`awaiting_approval`), or succeeded (`paid`), so an ordinary abandoned
+ * checkout keeps its ordinary copy.
+ *
+ *   declined        the organiser said no
+ *   expired         the window lapsed with no decision; the sweep cancelled it
+ *   payment_failed  approved, but the deferred charge could not be settled
+ *
+ * `payment_failed` is recognised by `approvalFailureReason` OR
+ * `approvalRequestedAt`: the contract sets the reason on that row, and the
+ * requested-at stamp is a belt-and-braces signal for a provider that reports
+ * no reason. An ordinary declined card carries neither.
+ */
+export function ticketRequestFailureKind(order: TicketOrderOutcomeInput): TicketRequestFailureKind | null {
+  if (order.status === OrderStatus.Declined) return "declined";
+  if (order.status === OrderStatus.Cancelled && order.approvalFailureReason === "expired") return "expired";
+  if (order.status === OrderStatus.PaymentFailed && (order.approvalFailureReason || order.approvalRequestedAt)) {
+    return "payment_failed";
+  }
+  return null;
+}
+
 /**
  * The refunded copy, shared verbatim by both rendering surfaces (the Forge
  * `EventConfirmation` block and the client app's `/events/:id/finalise` page)