@bash-app/bash-common 30.374.0 → 30.377.0

package/prisma/schema.prisma

@@ -1181,6 +1181,8 @@ model BashEvent {
   merchOrders             BashEventMerchOrder[]
   coatCheckEntitlements   CoatCheckEntitlement[]
   experienceOpportunities ExperienceOpportunity[]
+  ticketPrintOrders       TicketPrintOrder[]
+  ticketDeliverySettings  TicketDeliverySettings?
 
   /// Latest AI moderator verdict
   /// Null = never reviewed by AI. Recomputed each time the bash transitions to Pending
@@ -3316,6 +3318,9 @@ model TicketTier {
   tierReleaseReminders   TierReleaseReminder[]
   entryCompetition       Competition? @relation("CompetitionEntryTicketTier")
 
+  /// Host opt-in: buyers of this tier may choose mailed or venue will-call physical delivery (see TicketPrintOrder).
+  allowsPhysicalDelivery Boolean @default(false)
+
   @@unique([bashEventId, title])
   @@index([availableAt])
 }
@@ -3464,6 +3469,7 @@ model Ticket {
   eventReferral      EventReferral? // When this ticket was purchased via a referral link
   flyerConversions   FlyerConversion[]
   coatCheckEntitlements CoatCheckEntitlement[]
+  printOrder            TicketPrintOrder?
 
   @@index([bashEventId])
   @@index([bashEventId, seatId])
@@ -3556,6 +3562,94 @@ model TicketMetadata {
   @@index([ticketId])
 }
 
+enum TicketDeliveryMethod {
+  Digital
+  PhysicalMail
+  VenueWillCall
+}
+
+enum TicketPrintOrderStatus {
+  Queued
+  Submitted
+  Printed
+  InTransit
+  Delivered
+  Failed
+  CancelledBeforeSubmit
+  CancelledAfterSubmit
+}
+
+/// One row per physical ticket piece mailed or held for venue will-call via Lob.
+/// Mirrors FlyerCampaign's Lob usage and CoatCheckEntitlement's per-unit purchase/status pattern.
+model TicketPrintOrder {
+  id          String @id @default(cuid())
+  ticketId    String @unique
+  bashEventId String
+
+  deliveryMethod TicketDeliveryMethod
+  status         TicketPrintOrderStatus @default(Queued)
+
+  /// Ship-to snapshot: buyer address (PhysicalMail, from Stripe shipping_details) or
+  /// venue will-call address (VenueWillCall, from TicketDeliverySettings) at submit time.
+  shipToName  String?
+  shipToLine1 String?
+  shipToLine2 String?
+  shipToCity  String?
+  shipToState String?
+  shipToZip   String?
+
+  lobPostcardSize LobPostcardSize @default(LOB_4X6)
+  lobPostcardId   String?
+  vendorStatus    String?
+  /// Groups will-call pieces submitted together for host tracking ("Batch #3 — 42 pieces").
+  willCallBatchId String?
+
+  surchargeCents          Int     @default(0)
+  stripeCheckoutSessionId String?
+  checkoutId              String?
+
+  submittedAt DateTime?
+  printedAt   DateTime?
+  shippedAt   DateTime?
+  deliveredAt DateTime?
+  cancelledAt DateTime?
+
+  lastVendorStatusSyncAt DateTime?
+  lastLobWebhookId       String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  ticket    Ticket    @relation(fields: [ticketId], references: [id], onDelete: Cascade)
+  bashEvent BashEvent @relation(fields: [bashEventId], references: [id], onDelete: Cascade)
+
+  @@index([bashEventId, deliveryMethod, status])
+  @@index([willCallBatchId])
+}
+
+/// Per-event opt-in + venue will-call address for physical ticket delivery; kept separate
+/// from BashEvent (already very large) — one row per event, created on first opt-in.
+model TicketDeliverySettings {
+  id          String @id @default(cuid())
+  bashEventId String @unique
+
+  physicalMailEnabled Boolean         @default(false)
+  willCallEnabled     Boolean         @default(false)
+  lobPostcardSize     LobPostcardSize @default(LOB_4X6)
+
+  willCallAddressName  String?
+  willCallAddressLine1 String?
+  willCallAddressLine2 String?
+  willCallAddressCity  String?
+  willCallAddressState String?
+  willCallAddressZip   String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  bashEvent BashEvent @relation(fields: [bashEventId], references: [id], onDelete: Cascade)
+}
+
 /// Stripe donation to an event (Checkout session or PaymentIntent); includes optional UTM attribution.
 model BashEventDonation {
   id                      String   @id @default(cuid())

package/src/definitions.ts

@@ -1101,6 +1101,14 @@ export interface StripeCreateBashEventTicketsCheckoutSessionArgs extends UtmFiel
   coatCheckOversized?: boolean;
   /** Optional tip cents for coat check (when host enables tips). */
   coatCheckTipCents?: number;
+
+  /**
+   * Physical ticket delivery via Lob (mail-to-buyer or venue will-call).
+   * Undefined = digital ticket only (existing flow, unchanged). Server
+   * validates against the event's `TicketDeliverySettings` + each tier's
+   * `allowsPhysicalDelivery` before charging the surcharge.
+   */
+  ticketDeliveryMethod?: "PhysicalMail" | "VenueWillCall";
 }
 
 export interface StripeCreateBashEventDonationCheckoutSessionArgs extends UtmFields {

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/service/__tests__/apiServiceBookingApiUtils.test.ts

@@ -148,6 +148,12 @@ describe("servicePriceToBookToApiPackages", () => {
     expect(servicePriceToBookToApiPackages(priceToBook)).toEqual([]);
   });
 
+  it("returns empty array when priceToBook.packages is undefined", () => {
+    const priceToBook = {} as unknown as FrontendServiceGetPriceToBookResult;
+
+    expect(servicePriceToBookToApiPackages(priceToBook)).toEqual([]);
+  });
+
   it("maps priceToBook packages to ApiServicePackageParams", () => {
     const priceToBook = {
       packages: [

package/src/utils/service/apiServiceBookingApiUtils.ts

@@ -270,7 +270,7 @@ export function servicePriceToBookToApiDays(
 export function servicePriceToBookToApiPackages(
   priceToBook: FrontendServiceGetPriceToBookResult
 ): ApiServicePackageParams[] {
-  return priceToBook.packages.map(
+  return (priceToBook.packages ?? []).map(
     (pkg): ApiServicePackageParams => ({
       packageId: pkg.packageId,
       chosenQuantity: pkg.chosenQuantity,
@@ -304,7 +304,7 @@ export function servicePriceToBookToApiBookingBase({
       costPQCents: addOn.costPQCents,
     })
   );
-  const packages = priceToBook.packages.map(
+  const packages = (priceToBook.packages ?? []).map(
     (pkg): Partial<ServiceBookingPackageExt> => ({
       packageId: pkg.packageId,
       package: pkg.package,

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";
+  }
+}