@getmicdrop/venue-calendar 4.2.19 → 4.2.21

package/dist/api/types.d.ts

@@ -1,545 +1,545 @@
-/**
- * API Types for MicDrop Public Checkout API
- *
- * These types define the shape of API requests and responses
- * for the public checkout flow (no authentication required).
- */
-
-import type { EventId, SeriesId } from '@getmicdrop/svelte-components';
-
-// ============================================================================
-// Payment & Orders
-// ============================================================================
-
-export interface PaymentIntentRequest {
-  IP?: string;
-  productQuantities: Record<string | number, number>;
-}
-
-export interface PaymentIntentResponse {
-  client_secret: string;
-  // The residual the buyer is charged via Stripe, in int cents (net of any
-  // applied gift card). This is the field the checkout Total keys off. The
-  // orders-service response has NO `amount` key — an earlier `amount` here was
-  // never populated, so Total rendered $0.00 on every paid order.
-  stripe_amount?: number;
-  amount_total: number;
-  subtotal?: number;
-  tax?: number;
-  tax_amount_exclusive?: number;
-  service_fee?: number;
-  // The buyer's SECOND fee rail (MIC-1760) — card processing, grossed up and
-  // passed through at cost, in int cents. orders-service reports it separately
-  // from `service_fee` and folds it into `stripe_amount`. The PUBLIC receipt
-  // merges the two into one "Service fees" row (Gus, 2026-08-16), which is also
-  // what the pre-server estimate (`estimateBuyerFee`) has always shown; leaving
-  // it unread made the priced total exceed the rows on screen by this amount.
-  card_processing?: number;
-  discount?: number;
-  gift_card_amount?: number;
-  gift_card_code?: string;
-  stripe_publishable_key?: string;
-  // ISO-4217 currency (Stripe returns it lowercase). Feeds the checkout totals.
-  currency?: string;
-  // The three fields the $0 path answers with. orders-service finalizes a free
-  // order in-band on this same endpoint — it generates the tickets, marks the
-  // cart completed and sends the confirmation — and reports that back here
-  // instead of on a client secret. Views/Checkout.svelte reads all three to
-  // decide whether the cart really is still free and really did finalize, so a
-  // cart that gained a chargeable amount between selection and submit is caught
-  // rather than waved through.
-  //
-  // They were undeclared, which is not a cosmetic gap: this interface has no
-  // index signature, so every one of those three reads was a hard svelte-check
-  // error against the shape the server actually sends.
-  /** False when the cart still needs a Stripe charge — i.e. it is NOT free. */
-  requires_stripe?: boolean;
-  /** 'free' on the in-band $0 finalize path. */
-  payment_type?: string;
-  /** False when the backend declined to finalize the free order. */
-  order_finalized?: boolean;
-}
-
-export interface CompleteReservationResponse {
-  success: boolean;
-  message?: string;
-  error?: string;
-}
-
-export interface CancelReservationResponse {
-  success: boolean;
-  message?: string;
-  error?: string;
-}
-
-export interface CreateOrderRequest {
-  eventId: string | number;
-  promoCode?: string;
-}
-
-export interface CreateOrderResponse {
-  uuid: string;
-}
-
-export interface ValidatePaymentRequest {
-  id: string;
-  paymentIntentId: string;
-  tickets: Record<string | number, number>;
-  firstName: string;
-  lastName: string;
-  email: string;
-  /** Buyer phone collected at checkout (MIC-1705). Persisted on the order. */
-  phone?: string;
-  /** Answer to the venue's custom checkout question (MIC-1705). */
-  questionAnswer?: string;
-  paymentMethod: string;
-  mailingList?: boolean;
-  saleType?: string;
-  attendees?: AttendeeInfo[];
-}
-
-export interface AttendeeInfo {
-  ticketId: string | number;
-  firstName: string;
-  lastName: string;
-  email: string;
-}
-
-export interface ValidatePaymentResponse {
-  success: boolean;
-  status: string;
-  orderUUID?: string;
-  error?: string;
-  /**
-   * Fail-closed FLOOR fields. When the event is canceled/postponed between
-   * cart-creation and finalize, the backend gate refuses to capture the charge
-   * and sets one of these (alongside `success: false`). Either flag means the
-   * buyer was NOT charged; the checkout raises the charge-aware
-   * EventUnavailableModal instead of navigating to success. Optional because
-   * they are only present on the rejected-finalize path.
-   */
-  eventCanceled?: boolean;
-  eventPostponed?: boolean;
-}
-
-// ============================================================================
-// Session Management
-// ============================================================================
-
-export interface ExtendSessionRequest {
-  orderUuid: string;
-}
-
-export interface ExtendSessionResponse {
-  success: boolean;
-  newExpiryTime?: string;
-  remainingExtensions?: number;
-  error?: string;
-  /**
-   * HTTP status code from the backend on failure. Populated on non-OK
-   * responses so callers can distinguish "session already expired"
-   * (typically 410 Gone) from "max extensions reached" or generic 5xx.
-   * Undefined on network errors and on success.
-   */
-  statusCode?: number;
-}
-
-export interface SessionStatus {
-  expiresAt?: string;
-  extensionCount?: number;
-  remainingExtensions?: number;
-  canExtend?: boolean;
-  reservationCount?: number;
-  error?: string;
-  // 404 from /orders/session/{uuid}: the cart's reservations are
-  // gone (expired or never existed). Callers polling on an interval
-  // MUST treat this as terminal and stop — see CartView.svelte.
-  notFound?: boolean;
-  // Live event status the session heartbeat used to piggyback so the public
-  // checkout could flip the buy button on cancel/postpone. As of MIC-1408 the
-  // checkout rides a dedicated per-event SSE stream (subscribeEventStatus)
-  // instead, flipping instantly rather than within ~30s — this field is no
-  // longer consumed there. One of the auth-service Event statuses
-  // (draft|live|started|ended|canceled|postponed). Absent if the lookup failed.
-  eventStatus?: string;
-}
-
-// ============================================================================
-// Promo Codes
-// ============================================================================
-
-export interface PromoValidationResponse {
-  valid: boolean;
-  revealHiddenTickets?: boolean;
-  revealTicketIds?: number[];
-  provideDiscount?: boolean;
-  discountType?: 'percentage' | 'fixed';
-  amount?: number;
-  code?: string;
-  /**
-   * The code's ticket scope, exactly as the server sends it — `false` here plus
-   * a non-empty `applyToTicketIds` means the code covers only those types.
-   * Dropped by validatePromoCode until MIC-2575, which is why a code scoped to
-   * one type discounted every type. Read through promoTicketIdsFromValidation,
-   * never field-by-field at a call site.
-   */
-  appliesToAllTickets?: boolean;
-  applyToTicketIds?: number[];
-  error?: string;
-}
-
-/**
- * RAW body of GET /api/v2/public/promo-codes/validate/{eventId}/{code}.
- *
- * The live endpoint reports the discount magnitude as `discount` and the code
- * as `name` — NOT `amount`/`code`. validatePromoCode normalises this into the
- * client-facing PromoValidationResponse (amount/code) so callers read one shape.
- * The legacy `amount`/`code` keys stay optional here so an older payload (or a
- * mocked one) still maps through the same fallback. Verified 2026-07-11 against
- * two live promos (seeded GUARD20PCT + pre-existing EARLY20).
- */
-export interface RawPromoValidationBody {
-  valid?: boolean;
-  revealHiddenTickets?: boolean;
-  revealTicketIds?: number[];
-  provideDiscount?: boolean;
-  discountType?: 'percentage' | 'fixed';
-  /** Discount magnitude — real server field. */
-  discount?: number;
-  /** Legacy/mocked magnitude field — fallback only. */
-  amount?: number;
-  /** Promo code — real server field. */
-  name?: string;
-  /** Legacy/mocked code field — fallback only. */
-  code?: string;
-  appliesToAllTickets?: boolean;
-  applyToTicketIds?: number[];
-  isGlobal?: boolean;
-  ticketLimit?: number;
-  error?: string;
-}
-
-export interface HasPromoCodesResponse {
-  hasPromoCodes: boolean;
-}
-
-// ============================================================================
-// Orders
-// ============================================================================
-
-export interface Order {
-  uuid: string;
-  id?: number;
-  customerEmail: string;
-  customerFirstName?: string;
-  customerLastName?: string;
-  status: string;
-  totalAmount: number;
-  subtotal?: number;
-  serviceFeesAmount: number;
-  taxAmount: number;
-  discount?: number;
-  paymentIntentId?: string;
-  paymentMethod?: string;
-  purchasedTickets: PurchasedTicket[];
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-export interface PurchasedTicket {
-  uuid: string;
-  id?: number;
-  ticketNumber?: string;
-  orderId?: string | number;
-  attendeeFirstName?: string;
-  attendeeLastName?: string;
-  attendeeEmail?: string;
-  ticketName: string;
-  ticketTypeId?: number;
-  purchasePrice: number;
-  status?: string;
-  checkedIn?: boolean;
-  checkedInAt?: string;
-}
-
-// ============================================================================
-// Events
-// ============================================================================
-
-export interface Event {
-  eventID: number;
-  id?: number;
-  name: string;
-  title?: string;
-  slug?: string;
-  description?: string;
-  date: string;
-  startDateTime?: string;
-  endDateTime?: string;
-  doorsOpenTime?: string;
-  timezone?: string;
-  venueId?: number;
-  venueName?: string;
-  venueAddress?: string;
-  location?: string;
-  imageUrl?: string;
-  imageURL?: string;
-  status?: string;
-  isPublished?: boolean;
-  isCancelled?: boolean;
-  availableTickets?: AvailableTicket[];
-  ticketsAvailable?: number;
-  ticketsSold?: number;
-  minPrice?: number;
-  maxPrice?: number;
-  ctaText?: string;
-  ctaState?: 'available' | 'sold_out' | 'coming_soon' | 'ended';
-  showPerformers?: boolean;
-  eventSeriesId?: number;
-  seriesInstanceNumber?: number;
-  // ── Passthrough seams (events convergence) ─────────────────────────────
-  // Carried verbatim from the wire by parseEvent so view-shape projections
-  // (utils/event-transform.js, public-calendar-flow/transform.ts) compose the
-  // canonical instead of reading wire fields directly. The object-valued
-  // fields are intentionally raw (see composition note in
-  // api/transformers/event.ts) — their consumers own the wire variance.
-  timeZone?: string;
-  /**
-   * The operator's sales dial — effective on public payloads (MIC-2455).
-   * `computeCtaState` refuses on `paused` / `ended` / `sold_out` and leaves
-   * `not_started` to the sale-window logic.
-   */
-  salesStatus?: string;
-  eventSummary?: string;
-  password?: string;
-  hasPassword?: boolean;
-  disclaimer?: string;
-  ticketType?: number;
-  eventTicketingType?: number;
-  ageRestriction?: number;
-  displayAgeRestriction?: boolean;
-  displayStartTime?: boolean;
-  displayEndTime?: boolean;
-  displayDoorsTime?: boolean;
-  collectionId?: number;
-  ticketsRemaining?: number;
-  ticketsTotal?: number;
-  hasHiddenTickets?: boolean;
-  stage?: { name?: string } | null;
-  stageName?: string;
-  // Widget-filter dimensions on the public month feeds (saved-widget engine):
-  // stage/category/performer/collection data the embed adapts onto the SC
-  // FilterableEvent view (lib/widget-filters.js).
-  stageId?: number;
-  eventCategoryTypes?: number[] | null;
-  publicPerformers?: Array<{
-    id?: number;
-    displayName?: string;
-    image?: string;
-  }> | null;
-  collectionIds?: number[] | null;
-  venue?: Record<string, any>;
-  performers?: Record<string, any>[];
-  faqs?: Record<string, any>[];
-  showtimes?: Record<string, any>[];
-  purchasedTickets?: Record<string, any>[];
-}
-
-export interface AvailableTicket {
-  id: number;
-  name: string;
-  description?: string;
-  price: number;
-  quantity: number;
-  quantitySold?: number;
-  quantityAvailable?: number;
-  minPerOrder?: number;
-  maxPerOrder?: number;
-  saleStartDate?: string;
-  saleEndDate?: string;
-  isHidden?: boolean;
-  revealWithPromoCode?: boolean;
-  ticketType?: number; // 0 = GA, 1 = assigned
-  sectionId?: number;
-  sortOrder?: number;
-}
-
-export interface EventPerformersResponse {
-  performers: Performer[];
-  showPerformers: boolean;
-}
-
-export interface Performer {
-  id: number;
-  displayName: string;
-  avatar?: string;
-  order?: number;
-}
-
-// ============================================================================
-// Venues
-// ============================================================================
-
-export interface Venue {
-  id: number;
-  name: string;
-  slug?: string;
-  address?: string;
-  googleLocationNameCache?: string;
-  city?: string;
-  state?: string;
-  zipCode?: string;
-  country?: string;
-  timezone?: string;
-  logoUrl?: string;
-  serviceFeePercentage?: number;
-  serviceFeeCents?: number;
-  /** True = the venue absorbs the service fee; false/absent = the buyer pays it. */
-  absorbServiceFee?: boolean;
-  taxPercentage?: number;
-  organizationId?: number;
-}
-
-// ============================================================================
-// Series
-// ============================================================================
-
-export interface SeriesOccurrence {
-  eventId: EventId;
-  date: string;
-  startDateTime: string;
-  endDateTime?: string;
-  instanceNumber: number;
-  status: string;
-  ticketsAvailable?: number;
-  ctaState?: string;
-}
-
-export interface SeriesOccurrencesResponse {
-  seriesId: SeriesId;
-  occurrences: SeriesOccurrence[];
-}
-
-// ============================================================================
-// Series Page
-// ============================================================================
-
-export interface SeriesPageData {
-  id: number;
-  title: string;
-  description: string;
-  eventSummary?: string;
-  image?: string;
-  timeZone: string;
-  venue: {
-    id: number;
-    name: string;
-    location?: string;
-    googleLocationNameCache?: string;
-    faq?: Array<{ question: string; answer: string }> | string;
-    disclaimer?: string;
-  };
-  performers: Array<{
-    displayName: string;
-    firstName?: string;
-    lastName?: string;
-    profileImage?: string;
-  }>;
-  occurrences: Array<{
-    id: number;
-    slug: string;
-    startDateTime: string;
-    endDateTime: string;
-    ctaState: {
-      text: string;
-      disabled: boolean;
-      reason?: string;
-    };
-    /**
-     * The occurrence's OWN location. The backend emits this ONLY when the
-     * occurrence has been moved off the series master venue/stage, so
-     * presence === "this showtime is not where the rest of the series is".
-     * Absent for every ordinary occurrence.
-     */
-    venue?: {
-      id: number;
-      name: string;
-      address?: string;
-      city?: string;
-      state?: string;
-      googleLocationNameCache?: string;
-      stageName?: string;
-    };
-  }>;
-}
-
-// ============================================================================
-// Entity resolution (type-agnostic public id → concrete entity)
-// ============================================================================
-
-/**
- * Response shape of `/api/v2/public/resolve/{id}`. The embed deep-link is
- * type-agnostic (`#{id}-{slug}`), so the backend resolves which kind of entity
- * the id points at; `data` is the corresponding event / series / collection
- * payload (same shape the dedicated fetchers return for that type).
- */
-export interface ResolvedEntity {
-  type: 'event' | 'series' | 'collection';
-  id: string | number;
-  title?: string;
-  data: any;
-}
-
-// ============================================================================
-// Public Collection
-// ============================================================================
-
-export interface PublicCollectionData {
-  id: number;
-  collectionTitle: string;
-  summary?: string;
-  description?: string;
-  coverImage?: string;
-  events: Array<{
-    id: number;
-    title: string;
-    slug?: string;
-    startDateTime?: string;
-    endDateTime?: string;
-    image?: string;
-    status?: string;
-    venue?: { name: string };
-    minPrice?: number;
-  }>;
-  // Password-gate variant: a protected collection responds with a gate signal
-  // instead of the collection body (either `passwordRequired: true` or an
-  // `error.code === 'PASSWORD_REQUIRED'`). Modelled here as optional wire
-  // fields so the view can read them without an `as any` escape.
-  passwordRequired?: boolean;
-  error?: { code?: string };
-}
-
-// ============================================================================
-// API Configuration
-// ============================================================================
-
-export interface ApiConfig {
-  baseUrl?: string;
-  timeout?: number;
-  /** Number of additional attempts after the first try (default: 2 = 3 total tries). */
-  retries?: number;
-  /** Base delay before the first retry; doubles each attempt (default: 500ms). */
-  retryDelay?: number;
-  onError?: (_error: Error) => void;
-}
-
-// ============================================================================
-// Generic API Response
-// ============================================================================
-
-export interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  statusCode?: number;
-}
+/**
+ * API Types for MicDrop Public Checkout API
+ *
+ * These types define the shape of API requests and responses
+ * for the public checkout flow (no authentication required).
+ */
+
+import type { EventId, SeriesId } from '@getmicdrop/svelte-components';
+
+// ============================================================================
+// Payment & Orders
+// ============================================================================
+
+export interface PaymentIntentRequest {
+  IP?: string;
+  productQuantities: Record<string | number, number>;
+}
+
+export interface PaymentIntentResponse {
+  client_secret: string;
+  // The residual the buyer is charged via Stripe, in int cents (net of any
+  // applied gift card). This is the field the checkout Total keys off. The
+  // orders-service response has NO `amount` key — an earlier `amount` here was
+  // never populated, so Total rendered $0.00 on every paid order.
+  stripe_amount?: number;
+  amount_total: number;
+  subtotal?: number;
+  tax?: number;
+  tax_amount_exclusive?: number;
+  service_fee?: number;
+  // The buyer's SECOND fee rail (MIC-1760) — card processing, grossed up and
+  // passed through at cost, in int cents. orders-service reports it separately
+  // from `service_fee` and folds it into `stripe_amount`. The PUBLIC receipt
+  // merges the two into one "Service fees" row (Gus, 2026-08-16), which is also
+  // what the pre-server estimate (`estimateBuyerFee`) has always shown; leaving
+  // it unread made the priced total exceed the rows on screen by this amount.
+  card_processing?: number;
+  discount?: number;
+  gift_card_amount?: number;
+  gift_card_code?: string;
+  stripe_publishable_key?: string;
+  // ISO-4217 currency (Stripe returns it lowercase). Feeds the checkout totals.
+  currency?: string;
+  // The three fields the $0 path answers with. orders-service finalizes a free
+  // order in-band on this same endpoint — it generates the tickets, marks the
+  // cart completed and sends the confirmation — and reports that back here
+  // instead of on a client secret. Views/Checkout.svelte reads all three to
+  // decide whether the cart really is still free and really did finalize, so a
+  // cart that gained a chargeable amount between selection and submit is caught
+  // rather than waved through.
+  //
+  // They were undeclared, which is not a cosmetic gap: this interface has no
+  // index signature, so every one of those three reads was a hard svelte-check
+  // error against the shape the server actually sends.
+  /** False when the cart still needs a Stripe charge — i.e. it is NOT free. */
+  requires_stripe?: boolean;
+  /** 'free' on the in-band $0 finalize path. */
+  payment_type?: string;
+  /** False when the backend declined to finalize the free order. */
+  order_finalized?: boolean;
+}
+
+export interface CompleteReservationResponse {
+  success: boolean;
+  message?: string;
+  error?: string;
+}
+
+export interface CancelReservationResponse {
+  success: boolean;
+  message?: string;
+  error?: string;
+}
+
+export interface CreateOrderRequest {
+  eventId: string | number;
+  promoCode?: string;
+}
+
+export interface CreateOrderResponse {
+  uuid: string;
+}
+
+export interface ValidatePaymentRequest {
+  id: string;
+  paymentIntentId: string;
+  tickets: Record<string | number, number>;
+  firstName: string;
+  lastName: string;
+  email: string;
+  /** Buyer phone collected at checkout (MIC-1705). Persisted on the order. */
+  phone?: string;
+  /** Answer to the venue's custom checkout question (MIC-1705). */
+  questionAnswer?: string;
+  paymentMethod: string;
+  mailingList?: boolean;
+  saleType?: string;
+  attendees?: AttendeeInfo[];
+}
+
+export interface AttendeeInfo {
+  ticketId: string | number;
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+
+export interface ValidatePaymentResponse {
+  success: boolean;
+  status: string;
+  orderUUID?: string;
+  error?: string;
+  /**
+   * Fail-closed FLOOR fields. When the event is canceled/postponed between
+   * cart-creation and finalize, the backend gate refuses to capture the charge
+   * and sets one of these (alongside `success: false`). Either flag means the
+   * buyer was NOT charged; the checkout raises the charge-aware
+   * EventUnavailableModal instead of navigating to success. Optional because
+   * they are only present on the rejected-finalize path.
+   */
+  eventCanceled?: boolean;
+  eventPostponed?: boolean;
+}
+
+// ============================================================================
+// Session Management
+// ============================================================================
+
+export interface ExtendSessionRequest {
+  orderUuid: string;
+}
+
+export interface ExtendSessionResponse {
+  success: boolean;
+  newExpiryTime?: string;
+  remainingExtensions?: number;
+  error?: string;
+  /**
+   * HTTP status code from the backend on failure. Populated on non-OK
+   * responses so callers can distinguish "session already expired"
+   * (typically 410 Gone) from "max extensions reached" or generic 5xx.
+   * Undefined on network errors and on success.
+   */
+  statusCode?: number;
+}
+
+export interface SessionStatus {
+  expiresAt?: string;
+  extensionCount?: number;
+  remainingExtensions?: number;
+  canExtend?: boolean;
+  reservationCount?: number;
+  error?: string;
+  // 404 from /orders/session/{uuid}: the cart's reservations are
+  // gone (expired or never existed). Callers polling on an interval
+  // MUST treat this as terminal and stop — see CartView.svelte.
+  notFound?: boolean;
+  // Live event status the session heartbeat used to piggyback so the public
+  // checkout could flip the buy button on cancel/postpone. As of MIC-1408 the
+  // checkout rides a dedicated per-event SSE stream (subscribeEventStatus)
+  // instead, flipping instantly rather than within ~30s — this field is no
+  // longer consumed there. One of the auth-service Event statuses
+  // (draft|live|started|ended|canceled|postponed). Absent if the lookup failed.
+  eventStatus?: string;
+}
+
+// ============================================================================
+// Promo Codes
+// ============================================================================
+
+export interface PromoValidationResponse {
+  valid: boolean;
+  revealHiddenTickets?: boolean;
+  revealTicketIds?: number[];
+  provideDiscount?: boolean;
+  discountType?: 'percentage' | 'fixed';
+  amount?: number;
+  code?: string;
+  /**
+   * The code's ticket scope, exactly as the server sends it — `false` here plus
+   * a non-empty `applyToTicketIds` means the code covers only those types.
+   * Dropped by validatePromoCode until MIC-2575, which is why a code scoped to
+   * one type discounted every type. Read through promoTicketIdsFromValidation,
+   * never field-by-field at a call site.
+   */
+  appliesToAllTickets?: boolean;
+  applyToTicketIds?: number[];
+  error?: string;
+}
+
+/**
+ * RAW body of GET /api/v2/public/promo-codes/validate/{eventId}/{code}.
+ *
+ * The live endpoint reports the discount magnitude as `discount` and the code
+ * as `name` — NOT `amount`/`code`. validatePromoCode normalises this into the
+ * client-facing PromoValidationResponse (amount/code) so callers read one shape.
+ * The legacy `amount`/`code` keys stay optional here so an older payload (or a
+ * mocked one) still maps through the same fallback. Verified 2026-07-11 against
+ * two live promos (seeded GUARD20PCT + pre-existing EARLY20).
+ */
+export interface RawPromoValidationBody {
+  valid?: boolean;
+  revealHiddenTickets?: boolean;
+  revealTicketIds?: number[];
+  provideDiscount?: boolean;
+  discountType?: 'percentage' | 'fixed';
+  /** Discount magnitude — real server field. */
+  discount?: number;
+  /** Legacy/mocked magnitude field — fallback only. */
+  amount?: number;
+  /** Promo code — real server field. */
+  name?: string;
+  /** Legacy/mocked code field — fallback only. */
+  code?: string;
+  appliesToAllTickets?: boolean;
+  applyToTicketIds?: number[];
+  isGlobal?: boolean;
+  ticketLimit?: number;
+  error?: string;
+}
+
+export interface HasPromoCodesResponse {
+  hasPromoCodes: boolean;
+}
+
+// ============================================================================
+// Orders
+// ============================================================================
+
+export interface Order {
+  uuid: string;
+  id?: number;
+  customerEmail: string;
+  customerFirstName?: string;
+  customerLastName?: string;
+  status: string;
+  totalAmount: number;
+  subtotal?: number;
+  serviceFeesAmount: number;
+  taxAmount: number;
+  discount?: number;
+  paymentIntentId?: string;
+  paymentMethod?: string;
+  purchasedTickets: PurchasedTicket[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface PurchasedTicket {
+  uuid: string;
+  id?: number;
+  ticketNumber?: string;
+  orderId?: string | number;
+  attendeeFirstName?: string;
+  attendeeLastName?: string;
+  attendeeEmail?: string;
+  ticketName: string;
+  ticketTypeId?: number;
+  purchasePrice: number;
+  status?: string;
+  checkedIn?: boolean;
+  checkedInAt?: string;
+}
+
+// ============================================================================
+// Events
+// ============================================================================
+
+export interface Event {
+  eventID: number;
+  id?: number;
+  name: string;
+  title?: string;
+  slug?: string;
+  description?: string;
+  date: string;
+  startDateTime?: string;
+  endDateTime?: string;
+  doorsOpenTime?: string;
+  timezone?: string;
+  venueId?: number;
+  venueName?: string;
+  venueAddress?: string;
+  location?: string;
+  imageUrl?: string;
+  imageURL?: string;
+  status?: string;
+  isPublished?: boolean;
+  isCancelled?: boolean;
+  availableTickets?: AvailableTicket[];
+  ticketsAvailable?: number;
+  ticketsSold?: number;
+  minPrice?: number;
+  maxPrice?: number;
+  ctaText?: string;
+  ctaState?: 'available' | 'sold_out' | 'coming_soon' | 'ended';
+  showPerformers?: boolean;
+  eventSeriesId?: number;
+  seriesInstanceNumber?: number;
+  // ── Passthrough seams (events convergence) ─────────────────────────────
+  // Carried verbatim from the wire by parseEvent so view-shape projections
+  // (utils/event-transform.js, public-calendar-flow/transform.ts) compose the
+  // canonical instead of reading wire fields directly. The object-valued
+  // fields are intentionally raw (see composition note in
+  // api/transformers/event.ts) — their consumers own the wire variance.
+  timeZone?: string;
+  /**
+   * The operator's sales dial — effective on public payloads (MIC-2455).
+   * `computeCtaState` refuses on `paused` / `ended` / `sold_out` and leaves
+   * `not_started` to the sale-window logic.
+   */
+  salesStatus?: string;
+  eventSummary?: string;
+  password?: string;
+  hasPassword?: boolean;
+  disclaimer?: string;
+  ticketType?: number;
+  eventTicketingType?: number;
+  ageRestriction?: number;
+  displayAgeRestriction?: boolean;
+  displayStartTime?: boolean;
+  displayEndTime?: boolean;
+  displayDoorsTime?: boolean;
+  collectionId?: number;
+  ticketsRemaining?: number;
+  ticketsTotal?: number;
+  hasHiddenTickets?: boolean;
+  stage?: { name?: string } | null;
+  stageName?: string;
+  // Widget-filter dimensions on the public month feeds (saved-widget engine):
+  // stage/category/performer/collection data the embed adapts onto the SC
+  // FilterableEvent view (lib/widget-filters.js).
+  stageId?: number;
+  eventCategoryTypes?: number[] | null;
+  publicPerformers?: Array<{
+    id?: number;
+    displayName?: string;
+    image?: string;
+  }> | null;
+  collectionIds?: number[] | null;
+  venue?: Record<string, any>;
+  performers?: Record<string, any>[];
+  faqs?: Record<string, any>[];
+  showtimes?: Record<string, any>[];
+  purchasedTickets?: Record<string, any>[];
+}
+
+export interface AvailableTicket {
+  id: number;
+  name: string;
+  description?: string;
+  price: number;
+  quantity: number;
+  quantitySold?: number;
+  quantityAvailable?: number;
+  minPerOrder?: number;
+  maxPerOrder?: number;
+  saleStartDate?: string;
+  saleEndDate?: string;
+  isHidden?: boolean;
+  revealWithPromoCode?: boolean;
+  ticketType?: number; // 0 = GA, 1 = assigned
+  sectionId?: number;
+  sortOrder?: number;
+}
+
+export interface EventPerformersResponse {
+  performers: Performer[];
+  showPerformers: boolean;
+}
+
+export interface Performer {
+  id: number;
+  displayName: string;
+  avatar?: string;
+  order?: number;
+}
+
+// ============================================================================
+// Venues
+// ============================================================================
+
+export interface Venue {
+  id: number;
+  name: string;
+  slug?: string;
+  address?: string;
+  googleLocationNameCache?: string;
+  city?: string;
+  state?: string;
+  zipCode?: string;
+  country?: string;
+  timezone?: string;
+  logoUrl?: string;
+  serviceFeePercentage?: number;
+  serviceFeeCents?: number;
+  /** True = the venue absorbs the service fee; false/absent = the buyer pays it. */
+  absorbServiceFee?: boolean;
+  taxPercentage?: number;
+  organizationId?: number;
+}
+
+// ============================================================================
+// Series
+// ============================================================================
+
+export interface SeriesOccurrence {
+  eventId: EventId;
+  date: string;
+  startDateTime: string;
+  endDateTime?: string;
+  instanceNumber: number;
+  status: string;
+  ticketsAvailable?: number;
+  ctaState?: string;
+}
+
+export interface SeriesOccurrencesResponse {
+  seriesId: SeriesId;
+  occurrences: SeriesOccurrence[];
+}
+
+// ============================================================================
+// Series Page
+// ============================================================================
+
+export interface SeriesPageData {
+  id: number;
+  title: string;
+  description: string;
+  eventSummary?: string;
+  image?: string;
+  timeZone: string;
+  venue: {
+    id: number;
+    name: string;
+    location?: string;
+    googleLocationNameCache?: string;
+    faq?: Array<{ question: string; answer: string }> | string;
+    disclaimer?: string;
+  };
+  performers: Array<{
+    displayName: string;
+    firstName?: string;
+    lastName?: string;
+    profileImage?: string;
+  }>;
+  occurrences: Array<{
+    id: number;
+    slug: string;
+    startDateTime: string;
+    endDateTime: string;
+    ctaState: {
+      text: string;
+      disabled: boolean;
+      reason?: string;
+    };
+    /**
+     * The occurrence's OWN location. The backend emits this ONLY when the
+     * occurrence has been moved off the series master venue/stage, so
+     * presence === "this showtime is not where the rest of the series is".
+     * Absent for every ordinary occurrence.
+     */
+    venue?: {
+      id: number;
+      name: string;
+      address?: string;
+      city?: string;
+      state?: string;
+      googleLocationNameCache?: string;
+      stageName?: string;
+    };
+  }>;
+}
+
+// ============================================================================
+// Entity resolution (type-agnostic public id → concrete entity)
+// ============================================================================
+
+/**
+ * Response shape of `/api/v2/public/resolve/{id}`. The embed deep-link is
+ * type-agnostic (`#{id}-{slug}`), so the backend resolves which kind of entity
+ * the id points at; `data` is the corresponding event / series / collection
+ * payload (same shape the dedicated fetchers return for that type).
+ */
+export interface ResolvedEntity {
+  type: 'event' | 'series' | 'collection';
+  id: string | number;
+  title?: string;
+  data: any;
+}
+
+// ============================================================================
+// Public Collection
+// ============================================================================
+
+export interface PublicCollectionData {
+  id: number;
+  collectionTitle: string;
+  summary?: string;
+  description?: string;
+  coverImage?: string;
+  events: Array<{
+    id: number;
+    title: string;
+    slug?: string;
+    startDateTime?: string;
+    endDateTime?: string;
+    image?: string;
+    status?: string;
+    venue?: { name: string };
+    minPrice?: number;
+  }>;
+  // Password-gate variant: a protected collection responds with a gate signal
+  // instead of the collection body (either `passwordRequired: true` or an
+  // `error.code === 'PASSWORD_REQUIRED'`). Modelled here as optional wire
+  // fields so the view can read them without an `as any` escape.
+  passwordRequired?: boolean;
+  error?: { code?: string };
+}
+
+// ============================================================================
+// API Configuration
+// ============================================================================
+
+export interface ApiConfig {
+  baseUrl?: string;
+  timeout?: number;
+  /** Number of additional attempts after the first try (default: 2 = 3 total tries). */
+  retries?: number;
+  /** Base delay before the first retry; doubles each attempt (default: 500ms). */
+  retryDelay?: number;
+  onError?: (_error: Error) => void;
+}
+
+// ============================================================================
+// Generic API Response
+// ============================================================================
+
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  statusCode?: number;
+}