@bash-app/bash-common 30.214.0 → 30.216.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/legalTemplates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Default copy for host opt-in photo/video consent at event checkout.
+ * When `BashEvent.photoReleaseText` is null and `photoReleaseEnabled` is true, use this text.
+ * Not legal advice; hosts may supply custom text via the wizard.
+ */
+export declare const DEFAULT_PHOTO_RELEASE_TEXT = "By attending this event, you understand that photography, audio recording, and video recording may occur. You consent to being photographed, filmed, and/or recorded, and you grant the event organizer and its licensees the right to use your name, image, likeness, and voice in any media (including for promotion of this and future events), without payment or other compensation, unless prohibited by law.\n\nIf you do not wish to appear in promotional materials, contact the event organizer before or during the event. For minors, a parent or guardian must agree to this consent.";
+/**
+ * Effective photo release text for display (wizard preview, event page, checkout).
+ */
+export declare function getPhotoReleaseDisplayText(photoReleaseText: string | null | undefined): string;
+//# sourceMappingURL=legalTemplates.d.ts.map

package/dist/legalTemplates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legalTemplates.d.ts","sourceRoot":"","sources":["../src/legalTemplates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,ukBAEqI,CAAC;AAE7K;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC1C,MAAM,CAMR"}

package/dist/legalTemplates.js

@@ -0,0 +1,19 @@
+/**
+ * Default copy for host opt-in photo/video consent at event checkout.
+ * When `BashEvent.photoReleaseText` is null and `photoReleaseEnabled` is true, use this text.
+ * Not legal advice; hosts may supply custom text via the wizard.
+ */
+export const DEFAULT_PHOTO_RELEASE_TEXT = `By attending this event, you understand that photography, audio recording, and video recording may occur. You consent to being photographed, filmed, and/or recorded, and you grant the event organizer and its licensees the right to use your name, image, likeness, and voice in any media (including for promotion of this and future events), without payment or other compensation, unless prohibited by law.
+
+If you do not wish to appear in promotional materials, contact the event organizer before or during the event. For minors, a parent or guardian must agree to this consent.`;
+/**
+ * Effective photo release text for display (wizard preview, event page, checkout).
+ */
+export function getPhotoReleaseDisplayText(photoReleaseText) {
+    const trimmed = photoReleaseText?.trim();
+    if (trimmed) {
+        return trimmed;
+    }
+    return DEFAULT_PHOTO_RELEASE_TEXT;
+}
+//# sourceMappingURL=legalTemplates.js.map

package/dist/legalTemplates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legalTemplates.js","sourceRoot":"","sources":["../src/legalTemplates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;;4KAEkI,CAAC;AAE7K;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,gBAA2C;IAE3C,MAAM,OAAO,GAAG,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACzC,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,0BAA0B,CAAC;AACpC,CAAC"}

package/dist/utmAttribution.d.ts

@@ -0,0 +1,29 @@
+/**
+ * UTM / marketing attribution: first-touch capture in sessionStorage, Stripe metadata keys,
+ * and persistence on Ticket rows.
+ */
+export interface UtmFields {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+}
+/** Normalize optional UTM strings from API args (Stripe checkout / payment intent body). */
+export declare function utmFieldsFromCheckoutArgs(args: UtmFields): UtmFields | undefined;
+/** Stripe Checkout / PaymentIntent metadata (snake_case keys). */
+export declare function utmFieldsToStripeMetadata(utm: UtmFields | undefined): Record<string, string>;
+/** Prisma `Ticket` columns for persisted UTM (omit empty). */
+export declare function utmFieldsToTicketColumns(utm: UtmFields): {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+};
+/** Read UTM from Stripe object metadata into Prisma Ticket field names. */
+export declare function utmFieldsFromStripeMetadata(md: Record<string, string | undefined> | null | undefined): UtmFields;
+/**
+ * First-touch per session: store each UTM component the first time it appears in the URL.
+ * Call on route changes so client-side navigations to ?utm_*= still capture.
+ */
+export declare function captureFirstTouchUtmFromUrlSearchParams(search: string): void;
+/** Values previously captured for this tab session (for checkout API bodies). */
+export declare function getStoredUtmFields(): UtmFields;
+//# sourceMappingURL=utmAttribution.d.ts.map

package/dist/utmAttribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utmAttribution.d.ts","sourceRoot":"","sources":["../src/utmAttribution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAQD,4FAA4F;AAC5F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAkBhF;AAED,kEAAkE;AAClE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe5F;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,GAAG;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAYA;AAED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,GACxD,SAAS,CAkBX;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAkB5E;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,IAAI,SAAS,CAkB9C"}

package/dist/utmAttribution.js

@@ -0,0 +1,124 @@
+/**
+ * UTM / marketing attribution: first-touch capture in sessionStorage, Stripe metadata keys,
+ * and persistence on Ticket rows.
+ */
+const SESSION_KEYS = {
+    utmSource: "bash_utm_source",
+    utmMedium: "bash_utm_medium",
+    utmCampaign: "bash_utm_campaign",
+};
+/** Normalize optional UTM strings from API args (Stripe checkout / payment intent body). */
+export function utmFieldsFromCheckoutArgs(args) {
+    const s = args.utmSource?.trim();
+    const m = args.utmMedium?.trim();
+    const c = args.utmCampaign?.trim();
+    if (!s && !m && !c) {
+        return undefined;
+    }
+    const out = {};
+    if (s) {
+        out.utmSource = s.slice(0, 500);
+    }
+    if (m) {
+        out.utmMedium = m.slice(0, 500);
+    }
+    if (c) {
+        out.utmCampaign = c.slice(0, 500);
+    }
+    return out;
+}
+/** Stripe Checkout / PaymentIntent metadata (snake_case keys). */
+export function utmFieldsToStripeMetadata(utm) {
+    if (!utm) {
+        return {};
+    }
+    const out = {};
+    if (utm.utmSource) {
+        out.utm_source = utm.utmSource;
+    }
+    if (utm.utmMedium) {
+        out.utm_medium = utm.utmMedium;
+    }
+    if (utm.utmCampaign) {
+        out.utm_campaign = utm.utmCampaign;
+    }
+    return out;
+}
+/** Prisma `Ticket` columns for persisted UTM (omit empty). */
+export function utmFieldsToTicketColumns(utm) {
+    const out = {};
+    if (utm.utmSource) {
+        out.utmSource = utm.utmSource;
+    }
+    if (utm.utmMedium) {
+        out.utmMedium = utm.utmMedium;
+    }
+    if (utm.utmCampaign) {
+        out.utmCampaign = utm.utmCampaign;
+    }
+    return out;
+}
+/** Read UTM from Stripe object metadata into Prisma Ticket field names. */
+export function utmFieldsFromStripeMetadata(md) {
+    if (!md) {
+        return {};
+    }
+    const s = md.utm_source?.trim();
+    const m = md.utm_medium?.trim();
+    const c = md.utm_campaign?.trim();
+    const out = {};
+    if (s) {
+        out.utmSource = s.slice(0, 500);
+    }
+    if (m) {
+        out.utmMedium = m.slice(0, 500);
+    }
+    if (c) {
+        out.utmCampaign = c.slice(0, 500);
+    }
+    return out;
+}
+/**
+ * First-touch per session: store each UTM component the first time it appears in the URL.
+ * Call on route changes so client-side navigations to ?utm_*= still capture.
+ */
+export function captureFirstTouchUtmFromUrlSearchParams(search) {
+    if (typeof window === "undefined" || typeof sessionStorage === "undefined") {
+        return;
+    }
+    const q = search.startsWith("?") ? search.slice(1) : search;
+    const params = new URLSearchParams(q);
+    const pairs = [
+        ["utmSource", "utm_source"],
+        ["utmMedium", "utm_medium"],
+        ["utmCampaign", "utm_campaign"],
+    ];
+    for (const [storageField, paramName] of pairs) {
+        const v = params.get(paramName)?.trim();
+        const key = SESSION_KEYS[storageField];
+        if (v && !sessionStorage.getItem(key)) {
+            sessionStorage.setItem(key, v.slice(0, 500));
+        }
+    }
+}
+/** Values previously captured for this tab session (for checkout API bodies). */
+export function getStoredUtmFields() {
+    if (typeof sessionStorage === "undefined") {
+        return {};
+    }
+    const s = sessionStorage.getItem(SESSION_KEYS.utmSource)?.trim();
+    const m = sessionStorage.getItem(SESSION_KEYS.utmMedium)?.trim();
+    const c = sessionStorage.getItem(SESSION_KEYS.utmCampaign)?.trim();
+    const out = {};
+    if (s) {
+        out.utmSource = s;
+    }
+    if (m) {
+        out.utmMedium = m;
+    }
+    if (c) {
+        out.utmCampaign = c;
+    }
+    return out;
+}
+//# sourceMappingURL=utmAttribution.js.map

package/dist/utmAttribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utmAttribution.js","sourceRoot":"","sources":["../src/utmAttribution.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bash-app/bash-common",
-  "version": "30.214.0",
+  "version": "30.216.0",
   "description": "Common data and scripts to use on the frontend and backend",
   "type": "module",
   "main": "dist/index.js",

package/prisma/schema.prisma

@@ -615,6 +615,10 @@ model BashEvent {
   waiverUrl                String?
   waiverRequired           Boolean         @default(false)
   waiverDisplayType        String?         @default("inline")
+  /// Host opt-in: show photo/video consent at checkout; null photoReleaseText = platform default template
+  photoReleaseEnabled      Boolean         @default(false)
+  photoReleaseRequired     Boolean         @default(true)
+  photoReleaseText         String?         @db.Text
   targetAudienceId         String?         @unique
   amountOfGuestsId         String?         @unique
   vibe                     String?
@@ -793,6 +797,7 @@ model BashEvent {
   // Per-event referral rewards
   eventReferralRewards EventReferralReward[]
   eventReferrals       EventReferral[]
+  bashEventDonations   BashEventDonation[]
 
   // User night itineraries (events in user's "My Night" plan)
   userItineraryItems UserItineraryItem[]
@@ -1316,6 +1321,8 @@ model Ticket {
   waitlistJoinedAt           DateTime?
   waitlistNotifiedAt         DateTime?
   waitlistExpiresAt          DateTime?
+  /** Set when we send the "your waitlist window expires soon" reminder (once per ticket). */
+  waitlistReminderSentAt     DateTime?
   refundRequestedAt          DateTime? // Set when RefundPending; cleared once refund processes
   checkInLocation            String?
   checkOutLocation           String?
@@ -1325,12 +1332,19 @@ model Ticket {
   lastValidationAttempt      DateTime?
   lastValidatedBy            String?
   waitlistUserId             String?
+  /// Rotated when ticket is transferred; QR payload must match for check-in (null = legacy tickets, no strict check).
+  qrToken                    String?
 
   // BashPoints Purchase Tracking
   purchaseType     String? // "USD", "BashPoints", "Free", "Comp"
   pointsPaid       Int? // BashPoints amount paid (if purchaseType="BashPoints")
   stripePurchaseId String? // Stripe payment ID (if purchaseType="USD")
 
+  // Marketing attribution (from landing URL → sessionStorage → Stripe metadata → ticket row)
+  utmSource   String?
+  utmMedium   String?
+  utmCampaign String?
+
   bashEvent        BashEvent         @relation(fields: [bashEventId], references: [id])
   checkout         Checkout?         @relation(fields: [checkoutId], references: [id])
   forUser          User?             @relation("TicketsISent", fields: [forUserId], references: [id])
@@ -1340,6 +1354,7 @@ model Ticket {
   waitlistUser     User?             @relation("TicketsOnWaitlist", fields: [waitlistUserId], references: [id])
   metadata         TicketMetadata[]
   transfers        TicketTransfer[]
+  transferInvite   TicketTransferInvite?
   appliedDiscounts AppliedDiscount[] // NEW - Discounts applied to this ticket
   eventReferral    EventReferral?    // When this ticket was purchased via a referral link
 
@@ -1361,6 +1376,33 @@ model TicketTransfer {
   @@index([ticketId])
 }
 
+enum TicketTransferInviteStatus {
+  PENDING
+  ACCEPTED
+  DECLINED
+  EXPIRED
+}
+
+/// Pending peer-to-peer transfer; completes into `TicketTransfer` on accept.
+model TicketTransferInvite {
+  id         String                     @id @default(cuid())
+  ticketId   String                     @unique
+  fromUserId String
+  toEmail    String?
+  toUserId   String?
+  token      String                     @unique
+  status     TicketTransferInviteStatus @default(PENDING)
+  expiresAt  DateTime
+  createdAt  DateTime                   @default(now())
+
+  ticket     Ticket @relation(fields: [ticketId], references: [id], onDelete: Cascade)
+  fromUser   User   @relation("TicketTransferInviteFrom", fields: [fromUserId], references: [id])
+  invitedUser User? @relation("TicketTransferInviteToUser", fields: [toUserId], references: [id])
+
+  @@index([token])
+  @@index([fromUserId])
+}
+
 model TicketMetadata {
   id        String   @id @default(cuid())
   ticketId  String
@@ -1373,6 +1415,27 @@ model TicketMetadata {
   @@index([ticketId])
 }
 
+/// Stripe donation to an event (Checkout session or PaymentIntent); includes optional UTM attribution.
+model BashEventDonation {
+  id                      String   @id @default(cuid())
+  bashEventId             String
+  donorId                 String?
+  donorEmail              String?
+  amountCents             Int
+  stripeCheckoutSessionId String?  @unique
+  stripePaymentIntentId   String?  @unique
+  utmSource               String?
+  utmMedium               String?
+  utmCampaign             String?
+  createdAt               DateTime @default(now())
+
+  bashEvent BashEvent @relation(fields: [bashEventId], references: [id], onDelete: Cascade)
+  donor     User?     @relation(fields: [donorId], references: [id], onDelete: Cascade)
+
+  @@index([bashEventId])
+  @@index([donorId])
+}
+
 model unusedModelButNeededForSomeTypesToBeDefinedForTypescript {
   id                    String             @id @default(cuid())
   doNotUseVibeEnum      BashEventVibeTags  @default(Wild)
@@ -1607,6 +1670,9 @@ model Review {
   bashEventId String
   createdAt   DateTime      @default(now())
   updatedAt   DateTime      @updatedAt
+  /// Public reply from the event host (service provider) to the reviewer.
+  hostReplyText String?     @db.Text
+  hostReplyAt   DateTime?
   comments    BashComment[]
   bashEvent   BashEvent     @relation(fields: [bashEventId], references: [id], onDelete: Cascade)
   creator     User          @relation(fields: [creatorId], references: [id], onDelete: Cascade)
@@ -1724,6 +1790,8 @@ model User {
   birthdayReminderEnabled        Boolean   @default(false)
   birthdayReminderDaysAdvance      Int       @default(7)
   birthdayCategories             String[]  @default([]) // e.g. restaurant, coffee, dessert
+  /// Calendar year when we last sent the "your birthday month freebies" reminder (cron on 1st of month).
+  birthdayMonthReminderSentYear  Int?
   idDocumentUrl                  String?   // Optional: secure ID upload for verification
   gender                         Gender?
   sex                            Sex?
@@ -1905,9 +1973,12 @@ model User {
   stripeAccounts                 StripeAccount[]
   ticketsISent                   Ticket[]                   @relation("TicketsISent")
   ticketsIOwn                    Ticket[]                   @relation("TicketsIOwn")
+  bashEventDonations             BashEventDonation[]
   ticketsOnWaitlist              Ticket[]                   @relation("TicketsOnWaitlist")
   transfersFrom                  TicketTransfer[]           @relation("TransfersFrom")
   transfersTo                    TicketTransfer[]           @relation("TransfersTo")
+  ticketTransferInvitesFrom      TicketTransferInvite[]     @relation("TicketTransferInviteFrom")
+  ticketTransferInvitesToUser    TicketTransferInvite[]     @relation("TicketTransferInviteToUser")
   unblocksReceived               UnblockedUserHistory[]     @relation("UserUnblocksReceived")
   unblocksCreated                UnblockedUserHistory[]     @relation("UserUnblocksMade")
   suspendedBy                    User?                      @relation("SuspendedUsers", fields: [suspendedById], references: [id])
@@ -4075,6 +4146,7 @@ enum NotificationType {
   HostSalesAccelerating     // Host: "Your event sales increased 38% today"
   HostTopPromoter           // Host: "Top promoter: Alex (6 tickets today)"
   HostSalesSlowing          // Host: "Sales slowed today. Try sharing your event."
+  TicketSold                // Host: a ticket was purchased for your event (debounced in webhook)
 }
 
 enum NotificationPriority {

package/src/definitions.ts

@@ -21,6 +21,7 @@ import { ApiServiceCantBookReason } from "./utils/service/apiServiceBookingApiUt
 import { ServiceAttendeeOption } from "./utils/service/attendeeOptionUtils.js";
 import { FrontendServiceGetPriceToBookResult } from "./utils/service/frontendServiceBookingUtils.js";
 import { ServiceSubscriptionTier } from "./utils/userSubscriptionUtils.js";
+import type { UtmFields } from "./utmAttribution.js";
 
 export const PASSWORD_MIN_LENGTH = 8 as const;
 export const PASSWORD_REQUIREMENTS_REGEX = new RegExp(
@@ -259,6 +260,9 @@ export const SERVICE_BOOKING_DETAILS_SERVICE_VIEW_URL_PAGE =
   "/service/${serviceId}/${serviceType}/${specificId}/booking/${bookingId}/serviceView" as const;
 
 export const VERIFICATION_RETURN_URL = `/sign-up` as const;
+
+/** Stripe Identity hosted flow returns here (see `createStripeVerificationSession`). */
+export const STRIPE_IDENTITY_RETURN_URL = `/verify-id` as const;
 export const MY_SERVICES_URL = "/my-services" as const;
 export const BASH_DETAIL_URL = `/bash` as const;
 export const BASH_DETAIL_URL_PATTERN = `/bash/$bashEventIdSlug` as const;
@@ -684,7 +688,7 @@ export interface StripePaymentMethod {
   };
 }
 
-export interface StripeCreateBashEventTicketsCheckoutSessionArgs {
+export interface StripeCreateBashEventTicketsCheckoutSessionArgs extends UtmFields {
   bashEventId: string;
   currency: string;
   paymentMethodType: string;
@@ -705,11 +709,15 @@ export interface StripeCreateBashEventTicketsCheckoutSessionArgs {
   attributionRef?: string;
 }
 
-export interface StripeCreateBashEventDonationCheckoutSessionArgs {
+export interface StripeCreateBashEventDonationCheckoutSessionArgs extends UtmFields {
   bashEventId: string;
   currency: string;
   paymentMethodType: string;
   donationAmount: number;
+  /** Required for guest (unauthenticated) donation checkout — Stripe collects payment; we persist receipt to this email. */
+  guestEmail?: string;
+  guestFirstName?: string;
+  guestLastName?: string;
 }
 
 export interface StripeCreateSetupPaymentMethodSessionArgs {

package/src/extendedSchemas.ts

@@ -146,6 +146,8 @@ export const FRONT_END_USER_DATA_TO_SELECT = {
   sex: true,
   documentIDId: true,
   // documentID: true,
+  /** Set when Stripe Identity verification completes (hosted flow). */
+  idVerified: true,
   reviews: true,
   contacts: true,
   accepted: true,

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./definitions.js";
+export * from "./legalTemplates.js";
+export * from "./utmAttribution.js";
 export * from "./stripeListingSubscriptionMessages.js";
 export * from "./extendedSchemas.js";
 export * from "./bashFeedTypes.js";

package/src/legalTemplates.ts

@@ -0,0 +1,21 @@
+/**
+ * Default copy for host opt-in photo/video consent at event checkout.
+ * When `BashEvent.photoReleaseText` is null and `photoReleaseEnabled` is true, use this text.
+ * Not legal advice; hosts may supply custom text via the wizard.
+ */
+export const DEFAULT_PHOTO_RELEASE_TEXT = `By attending this event, you understand that photography, audio recording, and video recording may occur. You consent to being photographed, filmed, and/or recorded, and you grant the event organizer and its licensees the right to use your name, image, likeness, and voice in any media (including for promotion of this and future events), without payment or other compensation, unless prohibited by law.
+
+If you do not wish to appear in promotional materials, contact the event organizer before or during the event. For minors, a parent or guardian must agree to this consent.`;
+
+/**
+ * Effective photo release text for display (wizard preview, event page, checkout).
+ */
+export function getPhotoReleaseDisplayText(
+  photoReleaseText: string | null | undefined
+): string {
+  const trimmed = photoReleaseText?.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  return DEFAULT_PHOTO_RELEASE_TEXT;
+}

package/src/utmAttribution.ts

@@ -0,0 +1,142 @@
+/**
+ * UTM / marketing attribution: first-touch capture in sessionStorage, Stripe metadata keys,
+ * and persistence on Ticket rows.
+ */
+
+export interface UtmFields {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+}
+
+const SESSION_KEYS = {
+  utmSource: "bash_utm_source",
+  utmMedium: "bash_utm_medium",
+  utmCampaign: "bash_utm_campaign",
+} as const;
+
+/** Normalize optional UTM strings from API args (Stripe checkout / payment intent body). */
+export function utmFieldsFromCheckoutArgs(args: UtmFields): UtmFields | undefined {
+  const s = args.utmSource?.trim();
+  const m = args.utmMedium?.trim();
+  const c = args.utmCampaign?.trim();
+  if (!s && !m && !c) {
+    return undefined;
+  }
+  const out: UtmFields = {};
+  if (s) {
+    out.utmSource = s.slice(0, 500);
+  }
+  if (m) {
+    out.utmMedium = m.slice(0, 500);
+  }
+  if (c) {
+    out.utmCampaign = c.slice(0, 500);
+  }
+  return out;
+}
+
+/** Stripe Checkout / PaymentIntent metadata (snake_case keys). */
+export function utmFieldsToStripeMetadata(utm: UtmFields | undefined): Record<string, string> {
+  if (!utm) {
+    return {};
+  }
+  const out: Record<string, string> = {};
+  if (utm.utmSource) {
+    out.utm_source = utm.utmSource;
+  }
+  if (utm.utmMedium) {
+    out.utm_medium = utm.utmMedium;
+  }
+  if (utm.utmCampaign) {
+    out.utm_campaign = utm.utmCampaign;
+  }
+  return out;
+}
+
+/** Prisma `Ticket` columns for persisted UTM (omit empty). */
+export function utmFieldsToTicketColumns(utm: UtmFields): {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+} {
+  const out: { utmSource?: string; utmMedium?: string; utmCampaign?: string } = {};
+  if (utm.utmSource) {
+    out.utmSource = utm.utmSource;
+  }
+  if (utm.utmMedium) {
+    out.utmMedium = utm.utmMedium;
+  }
+  if (utm.utmCampaign) {
+    out.utmCampaign = utm.utmCampaign;
+  }
+  return out;
+}
+
+/** Read UTM from Stripe object metadata into Prisma Ticket field names. */
+export function utmFieldsFromStripeMetadata(
+  md: Record<string, string | undefined> | null | undefined
+): UtmFields {
+  if (!md) {
+    return {};
+  }
+  const s = md.utm_source?.trim();
+  const m = md.utm_medium?.trim();
+  const c = md.utm_campaign?.trim();
+  const out: UtmFields = {};
+  if (s) {
+    out.utmSource = s.slice(0, 500);
+  }
+  if (m) {
+    out.utmMedium = m.slice(0, 500);
+  }
+  if (c) {
+    out.utmCampaign = c.slice(0, 500);
+  }
+  return out;
+}
+
+/**
+ * First-touch per session: store each UTM component the first time it appears in the URL.
+ * Call on route changes so client-side navigations to ?utm_*= still capture.
+ */
+export function captureFirstTouchUtmFromUrlSearchParams(search: string): void {
+  if (typeof window === "undefined" || typeof sessionStorage === "undefined") {
+    return;
+  }
+  const q = search.startsWith("?") ? search.slice(1) : search;
+  const params = new URLSearchParams(q);
+  const pairs: Array<[keyof typeof SESSION_KEYS, string]> = [
+    ["utmSource", "utm_source"],
+    ["utmMedium", "utm_medium"],
+    ["utmCampaign", "utm_campaign"],
+  ];
+  for (const [storageField, paramName] of pairs) {
+    const v = params.get(paramName)?.trim();
+    const key = SESSION_KEYS[storageField];
+    if (v && !sessionStorage.getItem(key)) {
+      sessionStorage.setItem(key, v.slice(0, 500));
+    }
+  }
+}
+
+/** Values previously captured for this tab session (for checkout API bodies). */
+export function getStoredUtmFields(): UtmFields {
+  if (typeof sessionStorage === "undefined") {
+    return {};
+  }
+  const s = sessionStorage.getItem(SESSION_KEYS.utmSource)?.trim();
+  const m = sessionStorage.getItem(SESSION_KEYS.utmMedium)?.trim();
+  const c = sessionStorage.getItem(SESSION_KEYS.utmCampaign)?.trim();
+  const out: UtmFields = {};
+  if (s) {
+    out.utmSource = s;
+  }
+  if (m) {
+    out.utmMedium = m;
+  }
+  if (c) {
+    out.utmCampaign = c;
+  }
+  return out;
+}