@bash-app/bash-common 30.375.0 → 30.377.0

package/src/extendedSchemas.ts

@@ -78,6 +78,10 @@ import {
   TicketTier,
   TicketTransfer,
   TicketTransferInvite,
+  TicketDeliverySettings,
+  TicketDeliveryMethod,
+  TicketPrintOrder,
+  TicketPrintOrderStatus,
   User,
   UserPreferences,
   UserStats,
@@ -1729,6 +1733,8 @@ export type TicketFlexible = Ticket & {
   transfers?: TicketTransfer[];
   metadata?: TicketMetadata[];
   transferInvite?: TicketTransferInviteTeaser | null;
+  /** Physical delivery (mail / venue will-call) status, when the ticket opted in at checkout. */
+  printOrder?: TicketPrintOrder | null;
 };
 
 /**
@@ -2114,6 +2120,64 @@ export interface FlyerAnalyticsSummary {
 
 export type PostalCarrierRouteExt = PostalCarrierRoute;
 
+// --- Physical ticket delivery (mail / venue will-call via Lob) ---
+
+/** Delivery method a buyer picks at checkout when the tier allows physical delivery. */
+export interface TicketDeliverySelection {
+  deliveryMethod: TicketDeliveryMethod;
+}
+
+export const TICKET_PRINT_ORDER_WITH_TICKET_INCLUDE = {
+  ticket: {
+    select: {
+      id: true,
+      fullName: true,
+      email: true,
+      ticketTier: { select: { id: true, title: true } },
+    },
+  },
+} satisfies Prisma.TicketPrintOrderInclude;
+
+export type TicketPrintOrderExt = Prisma.TicketPrintOrderGetPayload<{
+  include: typeof TICKET_PRINT_ORDER_WITH_TICKET_INCLUDE;
+}>;
+
+/** Host-facing form for enabling/configuring physical delivery on an event. */
+export interface TicketDeliverySettingsFormData {
+  physicalMailEnabled: boolean;
+  willCallEnabled: boolean;
+  lobPostcardSize: TicketDeliverySettings["lobPostcardSize"];
+  willCallAddressName?: string;
+  willCallAddressLine1?: string;
+  willCallAddressLine2?: string;
+  willCallAddressCity?: string;
+  willCallAddressState?: string;
+  willCallAddressZip?: string;
+}
+
+/** Response from the host "send queued will-call tickets to venue" action. */
+export interface WillCallBatchSubmitResult {
+  willCallBatchId: string;
+  submittedCount: number;
+  failedCount: number;
+}
+
+/** Summary counts for the host Tickets tab "Print & Mail" panel. */
+export interface TicketPrintOrderSummary {
+  deliveryMethod: TicketDeliveryMethod;
+  status: TicketPrintOrderStatus;
+  count: number;
+}
+
+/** Public-safe checkout-time read of an event's physical delivery settings. */
+export interface TicketDeliveryAvailability {
+  physicalMailEnabled: boolean;
+  willCallEnabled: boolean;
+  lobPostcardSize: TicketDeliverySettings["lobPostcardSize"];
+  /** Buyer-facing surcharge (integer cents) for one physical ticket piece. */
+  surchargeCentsPerTicket: number;
+}
+
 // === Talent Agency selects/types ============================================
 
 /// Public-safe roster entry for an agency's artist (agency detail page + cards).

package/src/index.ts

@@ -416,6 +416,7 @@ export * from "./utils/ticketCheckInDisplay.js";
 export * from "./utils/coatCheckUtils.js";
 export * from "./utils/ticketTierSchedule.js";
 export * from "./utils/lobFlyerUtils.js";
+export * from "./utils/ticketPrintPostageUtils.js";
 export * from "./utils/generalDateTimeUtils.js";
 export * from "./utils/locationVisibility.js";
 export * from "./utils/luxonUtils.js";

package/src/utils/__tests__/ticketPrintPostageUtils.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "@jest/globals";
+import { TicketDeliveryMethod, TicketPrintOrderStatus } from "@prisma/client";
+
+import {
+  ticketDeliveryStatusLabel,
+  ticketPrintSurchargeCentsForQuantity,
+  ticketPrintSurchargeCentsPerPiece,
+} from "../ticketPrintPostageUtils.js";
+
+describe("ticketPrintPostageUtils", () => {
+  describe("ticketPrintSurchargeCentsPerPiece", () => {
+    it("matches the per-piece quote for quantity 1", () => {
+      expect(ticketPrintSurchargeCentsPerPiece("LOB_4X6")).toBe(
+        ticketPrintSurchargeCentsForQuantity("LOB_4X6", 1)
+      );
+    });
+  });
+
+  describe("ticketPrintSurchargeCentsForQuantity", () => {
+    it("is zero for quantity < 1", () => {
+      expect(ticketPrintSurchargeCentsForQuantity("LOB_4X6", 0)).toBe(0);
+      expect(ticketPrintSurchargeCentsForQuantity("LOB_4X6", -1)).toBe(0);
+    });
+
+    it("scales with quantity", () => {
+      const one = ticketPrintSurchargeCentsForQuantity("LOB_6X9", 1);
+      const five = ticketPrintSurchargeCentsForQuantity("LOB_6X9", 5);
+      expect(five).toBeGreaterThan(one);
+    });
+  });
+
+  describe("ticketDeliveryStatusLabel", () => {
+    it("returns null for Digital (no print order)", () => {
+      expect(ticketDeliveryStatusLabel(null)).toBeNull();
+      expect(ticketDeliveryStatusLabel(undefined)).toBeNull();
+    });
+
+    it("returns a cancelled label regardless of delivery method (before submit)", () => {
+      expect(
+        ticketDeliveryStatusLabel({
+          deliveryMethod: TicketDeliveryMethod.PhysicalMail,
+          status: TicketPrintOrderStatus.CancelledBeforeSubmit,
+        })
+      ).toBe("Physical ticket cancelled");
+    });
+
+    it("returns a cancelled label (after submit)", () => {
+      expect(
+        ticketDeliveryStatusLabel({
+          deliveryMethod: TicketDeliveryMethod.VenueWillCall,
+          status: TicketPrintOrderStatus.CancelledAfterSubmit,
+        })
+      ).toBe("Physical ticket cancelled");
+    });
+
+    it("returns a failure label", () => {
+      expect(
+        ticketDeliveryStatusLabel({
+          deliveryMethod: TicketDeliveryMethod.PhysicalMail,
+          status: TicketPrintOrderStatus.Failed,
+        })
+      ).toBe("Physical ticket delivery failed — contact the host");
+    });
+
+    it.each([
+      [TicketPrintOrderStatus.Queued, "Pick up at venue: will-call (printing soon)"],
+      [TicketPrintOrderStatus.Submitted, "Pick up at venue: will-call"],
+      [TicketPrintOrderStatus.Printed, "Pick up at venue: will-call"],
+      [TicketPrintOrderStatus.InTransit, "Pick up at venue: will-call"],
+      [TicketPrintOrderStatus.Delivered, "Pick up at venue: will-call (ready)"],
+    ])("VenueWillCall %s -> %s", (status, expected) => {
+      expect(
+        ticketDeliveryStatusLabel({
+          deliveryMethod: TicketDeliveryMethod.VenueWillCall,
+          status,
+        })
+      ).toBe(expected);
+    });
+
+    it.each([
+      [TicketPrintOrderStatus.Queued, "Mailed ticket: printing"],
+      [TicketPrintOrderStatus.Submitted, "Mailed ticket: printing"],
+      [TicketPrintOrderStatus.Printed, "Mailed ticket: printed"],
+      [TicketPrintOrderStatus.InTransit, "Mailed ticket: in transit"],
+      [TicketPrintOrderStatus.Delivered, "Mailed ticket: delivered"],
+    ])("PhysicalMail %s -> %s", (status, expected) => {
+      expect(
+        ticketDeliveryStatusLabel({
+          deliveryMethod: TicketDeliveryMethod.PhysicalMail,
+          status,
+        })
+      ).toBe(expected);
+    });
+  });
+});

package/src/utils/lobFlyerUtils.ts

@@ -13,6 +13,13 @@
 
 export type LobPostcardSizeKey = "LOB_4X6" | "LOB_6X9" | "LOB_6X11";
 
+/** Narrows the Prisma `LobPostcardSize` enum value to the string-literal key used by these utils. */
+export function lobPostcardSizeEnumToKey(size: LobPostcardSizeKey | string): LobPostcardSizeKey {
+  if (size === "LOB_6X9") return "LOB_6X9";
+  if (size === "LOB_6X11") return "LOB_6X11";
+  return "LOB_4X6";
+}
+
 /** Trim width × height in inches (portrait), matching Lob postcard products. */
 export const LOB_POSTCARD_TRIM_IN: Record<
   LobPostcardSizeKey,

package/src/utils/qrCodeUtils.ts

@@ -24,3 +24,29 @@ export async function createQrCodeImage(qrData: string): Promise<string> {
     errorCorrectionLevel: 'high',
   });
 }
+
+/**
+ * Door-scan admission QR payload for a ticket — the same shape the buyer's
+ * "show at door" QR encodes (bash-app `MyTicketInlineQr.tsx`, built inline as
+ * `checkInData` for `encodeTicketQrPayload`) and what the API's door-verify
+ * parser reads (`parseTicketQrScanPayload` in `ticketApi.ts`, which requires
+ * string `eventId`/`ticketId` and reads an optional `qrToken`).
+ *
+ * Server-side callers (e.g. printed ticket artwork) MUST use this so a
+ * physical ticket's QR scans identically to the in-app one — no new
+ * verification path, no schema changes to `qrToken` handling.
+ */
+export function encodeTicketDoorQrPayload(args: {
+  eventId: string;
+  ticketId: string;
+  ownerUserId?: string | null;
+  qrToken?: string | null;
+}): string {
+  return JSON.stringify({
+    eventId: args.eventId,
+    userId: args.ownerUserId ?? "",
+    ticketId: args.ticketId,
+    qrToken: args.qrToken ?? undefined,
+    timestamp: new Date().toISOString(),
+  });
+}

package/src/utils/ticketPrintPostageUtils.ts

@@ -0,0 +1,81 @@
+/**
+ * Buyer-facing surcharge for physical ticket delivery (mail-to-buyer or venue
+ * will-call), both fulfilled as individually-addressed Lob postcards — one
+ * ticket = one piece, same product used by Flyer Blast's addressed mail path.
+ *
+ * Reuses the Lob per-piece cost table from `lobFlyerUtils.ts` rather than
+ * duplicating pricing — same "verify before production" caveat applies here.
+ */
+
+import { TicketDeliveryMethod, TicketPrintOrderStatus } from "@prisma/client";
+
+import {
+  quoteLobAddressedPostageCents,
+  type LobPostcardSizeKey,
+} from "./lobFlyerUtils.js";
+
+/** Surcharge for a single printed/mailed ticket piece (integer cents). */
+export function ticketPrintSurchargeCentsPerPiece(size: LobPostcardSizeKey): number {
+  return quoteLobAddressedPostageCents(size, 1);
+}
+
+/**
+ * Total buyer-facing surcharge (integer cents) for `quantity` physical ticket
+ * pieces of the given size — used as the Stripe checkout line item amount.
+ */
+export function ticketPrintSurchargeCentsForQuantity(
+  size: LobPostcardSizeKey,
+  quantity: number
+): number {
+  if (quantity < 1) return 0;
+  return quoteLobAddressedPostageCents(size, quantity);
+}
+
+/**
+ * Buyer-facing badge copy for a ticket's physical delivery status — shared by
+ * My Tickets and the ticket details view so both surfaces stay in sync.
+ * `null`/`undefined` (Digital) means no badge should render.
+ */
+export function ticketDeliveryStatusLabel(
+  printOrder:
+    | { deliveryMethod: TicketDeliveryMethod; status: TicketPrintOrderStatus }
+    | null
+    | undefined
+): string | null {
+  if (!printOrder) return null;
+  const { deliveryMethod, status } = printOrder;
+
+  if (
+    status === TicketPrintOrderStatus.CancelledBeforeSubmit ||
+    status === TicketPrintOrderStatus.CancelledAfterSubmit
+  ) {
+    return "Physical ticket cancelled";
+  }
+  if (status === TicketPrintOrderStatus.Failed) {
+    return "Physical ticket delivery failed — contact the host";
+  }
+  if (deliveryMethod === TicketDeliveryMethod.VenueWillCall) {
+    switch (status) {
+      case TicketPrintOrderStatus.Queued:
+        return "Pick up at venue: will-call (printing soon)";
+      case TicketPrintOrderStatus.Delivered:
+        return "Pick up at venue: will-call (ready)";
+      default:
+        return "Pick up at venue: will-call";
+    }
+  }
+  // PhysicalMail
+  switch (status) {
+    case TicketPrintOrderStatus.Queued:
+    case TicketPrintOrderStatus.Submitted:
+      return "Mailed ticket: printing";
+    case TicketPrintOrderStatus.Printed:
+      return "Mailed ticket: printed";
+    case TicketPrintOrderStatus.InTransit:
+      return "Mailed ticket: in transit";
+    case TicketPrintOrderStatus.Delivered:
+      return "Mailed ticket: delivered";
+    default:
+      return "Mailed ticket";
+  }
+}