@getmicdrop/venue-calendar 4.0.112 → 4.0.114

package/dist/api/api/client.d.ts

@@ -0,0 +1,17 @@
+import { ApiConfig, ApiResponse } from './types.js';
+export declare function configureApi(config: Partial<ApiConfig>): void;
+export declare function getApiConfig(): Required<ApiConfig>;
+export declare function getPublicBaseUrl(): string;
+export declare function getLegacyPublicUrl(): string;
+export declare function getOrdersV2Url(): string;
+/** @deprecated IP is now resolved server-side via request headers. */
+export declare function getClientIP(): Promise<string>;
+export declare function apiGet<T>(endpoint: string, options?: RequestInit): Promise<ApiResponse<T>>;
+export declare function apiPost<T>(endpoint: string, body?: unknown, options?: RequestInit): Promise<ApiResponse<T>>;
+export declare function apiPut<T>(endpoint: string, body?: unknown, options?: RequestInit): Promise<ApiResponse<T>>;
+export declare function apiDelete<T>(endpoint: string, options?: RequestInit): Promise<ApiResponse<T>>;
+/**
+ * Simple fetch wrapper that returns parsed JSON or null on error.
+ * Inherits the global timeout + retry policy for GETs.
+ */
+export declare function simpleFetch<T>(url: string, options?: RequestInit): Promise<T | null>;

package/dist/api/api/cta.d.ts

@@ -0,0 +1,34 @@
+import { isHiddenTicketPurchasable } from '@getmicdrop/svelte-components/transforms';
+export interface CtaStateOptions {
+    cancelled?: boolean;
+    isRegistration?: boolean;
+    waitlistEnabled?: boolean;
+}
+export interface CtaState {
+    text: string;
+    disabled: boolean;
+    reason: 'cancelled' | 'event_past' | 'no_tickets' | 'available' | 'coming_soon' | 'sold_out_waitlist' | 'sold_out' | 'sales_ended' | 'hidden_only';
+}
+interface CtaEvent {
+    startDateTime?: string | null;
+    endDateTime?: string | null;
+    hasPurchasableHiddenTickets?: boolean;
+}
+interface CtaTicket {
+    salesChannel?: number;
+    salesBegin?: string | null;
+    salesStart?: string | null;
+    saleBegin?: string | null;
+    onSaleStart?: string | null;
+    salesEnd?: string | null;
+    saleEnd?: string | null;
+    onSaleEnd?: string | null;
+    remainingCapacity?: number | null;
+    quantityRemaining?: number | null;
+    quantity?: number | null;
+    soldOut?: boolean;
+    isHidden?: boolean;
+    visibility?: number;
+}
+export { isHiddenTicketPurchasable };
+export declare function computeCtaState(event: CtaEvent, tickets: CtaTicket[] | undefined, options?: CtaStateOptions): CtaState;

package/dist/api/api/events.d.ts

@@ -0,0 +1,183 @@
+import { Result } from './result.js';
+import { Event, AvailableTicket, EventPerformersResponse, SeriesOccurrencesResponse, PublicCollectionData, ResolvedEntity } from './types.js';
+/**
+ * Fetch event details, discriminating a real 404 from a transient failure.
+ *
+ * The SSR loader (`[id]/[slug]/+page.js`) gates its HTTP status on this: only an
+ * upstream 404 (`errNotFound`) becomes a page 404. A 5xx, a network error, or a
+ * timeout is `err(...)` (transient) so the loader can answer 503/retry instead
+ * of rendering a permanent-looking 404 to a buyer or crawler on a backend blip.
+ *
+ * @param eventId - The event ID
+ * @param customFetch - Optional custom fetch function (for SSR)
+ * @param password - Optional password for gated events
+ * @returns `ok(event)`, `errNotFound(...)` for a real 404, or `err(...)` transient
+ */
+export declare function fetchEventDetailsResult(eventId: string | number, customFetch?: typeof fetch, password?: string): Promise<Result<Event>>;
+/**
+ * Fetch event details
+ *
+ * Gets full event information including venue and ticket data.
+ *
+ * Fail-open adapter over {@link fetchEventDetailsResult}: existing in-widget
+ * callers (Checkout, CartView, EventPage) keep degrading to `null` on any
+ * failure. SSR loaders that need to answer 404-vs-503 use the Result variant.
+ *
+ * @param eventId - The event ID
+ * @param customFetch - Optional custom fetch function (for SSR)
+ * @returns Event details or null on error
+ */
+export declare function fetchEventDetails(eventId: string | number, customFetch?: typeof fetch, password?: string): Promise<Event | null>;
+/**
+ * Fetch available tickets for an event
+ *
+ * Returns all ticket types that are currently available for sale.
+ *
+ * @param eventId - The event ID
+ * @returns Array of available tickets
+ */
+export declare function fetchEventTicketsResult(eventId: string | number): Promise<Result<AvailableTicket[]>>;
+export declare function fetchEventTickets(eventId: string | number): Promise<AvailableTicket[]>;
+/**
+ * Fetch performers for an event
+ *
+ * Returns the lineup with pre-resolved avatar URLs.
+ *
+ * @param eventId - The event ID
+ * @returns Performers list and visibility flag
+ */
+export declare function fetchEventPerformersResult(eventId: string | number): Promise<Result<EventPerformersResponse>>;
+export declare function fetchEventPerformers(eventId: string | number): Promise<EventPerformersResponse>;
+/**
+ * Fetch all venues for an organization
+ *
+ * @param orgId - The organization ID
+ * @returns Array of venues
+ */
+export declare function fetchAllVenuesResult(orgId: string | number): Promise<Result<any[]>>;
+export declare function fetchAllVenues(orgId: string | number): Promise<any[]>;
+/**
+ * Fetch events for a venue
+ *
+ * @param venueId - The venue ID
+ * @returns Array of events
+ */
+export declare function fetchVenueEventsResult(venueId: string | number): Promise<Result<Event[]>>;
+export declare function fetchVenueEvents(venueId: string | number): Promise<Event[]>;
+export declare function getMonthEventsResult(venueId: string | number, year: number, month: number): Promise<Result<Event[]>>;
+export declare function getMonthEvents(venueId: string | number, year: number, month: number): Promise<Event[]>;
+/**
+ * Get events for an organization for a specific month
+ *
+ * @param orgId - The organization ID
+ * @param year - The year (e.g., 2024)
+ * @param month - The month (1-12)
+ * @returns Array of events for the month
+ */
+export declare function getOrgMonthEventsResult(orgId: string | number, year: number, month: number): Promise<Result<Event[]>>;
+export declare function getOrgMonthEvents(orgId: string | number, year: number, month: number): Promise<Event[]>;
+/**
+ * Get series occurrences for date selector
+ *
+ * Returns all instances of a recurring event series.
+ *
+ * @param eventSeriesId - The series ID
+ * @returns Series occurrences
+ */
+export declare function getSeriesOccurrencesResult(eventSeriesId: number): Promise<Result<SeriesOccurrencesResponse>>;
+export declare function getSeriesOccurrences(eventSeriesId: number): Promise<SeriesOccurrencesResponse | null>;
+/**
+ * Fetch series occurrences with CTA state
+ *
+ * Returns full series data including availability status.
+ *
+ * @param eventSeriesId - The series ID
+ * @param venueId - The venue ID
+ * @returns Series occurrences with CTA state
+ */
+export declare function fetchSeriesOccurrencesResult(eventSeriesId: number, venueId: string | number): Promise<Result<SeriesOccurrencesResponse>>;
+export declare function fetchSeriesOccurrences(eventSeriesId: number, venueId: string | number): Promise<SeriesOccurrencesResponse | null>;
+/**
+ * Resolve an entity-agnostic public id to its concrete type + data.
+ *
+ * The embed deep-link (`#{id}-{slug}`) carries no type prefix, so a cold
+ * deep link (the show isn't in the loaded calendar month) needs the backend
+ * to say whether the id is an event, series, or collection before the widget
+ * can render the right view. This is the same `/api/v2/public/resolve/{id}`
+ * endpoint get-micdrop.com's `/e/{slugId}` page resolves server-side; here we
+ * call it cross-origin from the venue's page (the public API already serves
+ * the calendar cross-origin, so CORS is in place).
+ *
+ * @param id - The entity id (numeric, type-agnostic)
+ * @param slug - Optional slug hint (lets the backend canonicalize)
+ * @returns `{ type, id, title, data }` or null on failure
+ */
+export declare function resolvePublicEntity(id: string | number, slug?: string): Promise<ResolvedEntity | null>;
+/**
+ * Fetch public collection data
+ *
+ * Returns collection info including events list.
+ * For password-protected collections, pass the password to authenticate.
+ *
+ * @param collectionId - The collection ID
+ * @param password - Optional password for protected collections
+ * @returns Collection data or null on error
+ */
+export declare function fetchPublicCollection(collectionId: string | number, password?: string): Promise<PublicCollectionData | null>;
+/**
+ * Check collection password
+ *
+ * Validates password for password-protected collections.
+ *
+ * @param collectionId - The collection ID
+ * @param password - The password to check
+ * @returns Whether the password is valid
+ */
+export declare function checkCollectionPassword(collectionId: string | number, password: string): Promise<boolean>;
+/**
+ * Check event password
+ *
+ * Validates password for password-protected events.
+ *
+ * @param eventId - The event ID
+ * @param password - The password to check
+ * @returns Whether the password is valid
+ */
+export declare function checkEventPassword(eventId: string | number, password: string): Promise<{
+    valid: boolean;
+}>;
+/**
+ * Test network connection
+ *
+ * Asks whether the public API is reachable.
+ *
+ * THE QUESTION IS "DID THE ROUTER ANSWER", NOT "DID THE RESOURCE EXIST" — the
+ * same distinction route-manifest.ts is built on. Under the old `response.ok`
+ * rule this probe reported the API DOWN on a healthy backend on EVERY branch,
+ * for EVERY input, always. Measured against production: HEAD answers 405 on
+ * every route the backend serves — including `HEAD /events/venue/42` for a venue
+ * that EXISTS — and the old `HEAD /health` branch answered 404, because the
+ * router does not serve /health at all. None of those are `ok`. A liveness check
+ * that always fails is worse than none.
+ *
+ * Two changes fix two different things, and they are separable:
+ *
+ *   1. THE STATUS RULE is what fixes liveness. Reachable means ANSWERED, not
+ *      `response.ok`. A 400, a 404 or a 405 is the backend talking: it is up.
+ *      Only a transport failure (DNS, TLS, CORS, offline) or a 5xx means it is
+ *      not serving. This rule alone would have made liveness report up, even on
+ *      the old /health probe (404 < 500).
+ *   2. THE REPOINT is what stops this naming a route the router does not serve —
+ *      the name-resolution gate, and #444. Every branch now names a route the
+ *      backend actually SERVES. There is no id-free public route, so the no-ids
+ *      branch asks a served route about an id that cannot exist: we do not care
+ *      what it says about the venue, only that it said anything at all. This is
+ *      not what fixes liveness.
+ *
+ * Do not "simplify" `status < 500` back to `response.ok`. That is the bug.
+ *
+ * @param orgId - Optional org ID
+ * @param venueId - Optional venue ID
+ * @returns Whether the API answered
+ */
+export declare function testNetworkConnection(orgId?: string | number, venueId?: string | number): Promise<boolean>;

package/dist/api/api/gift-cards.d.ts

@@ -0,0 +1,108 @@
+import { VenueId } from '@getmicdrop/svelte-components';
+import { Result } from './result.js';
+/**
+ * Request payload for creating a gift card purchase
+ */
+export interface GiftCardPurchaseRequest {
+    venueId: number | VenueId;
+    amount: number;
+    recipientEmail: string;
+    recipientName: string;
+    personalMessage?: string;
+    purchaserEmail: string;
+    purchaserName: string;
+    scheduledDeliveryAt?: string | null;
+}
+/**
+ * Response from gift card purchase creation
+ */
+export interface GiftCardPurchaseResponse {
+    giftCardUUID: string;
+    clientSecret: string;
+    amount: number;
+    stripePublishableKey: string;
+}
+/**
+ * Venue information needed for gift card purchase
+ */
+export interface VenueInfo {
+    id: VenueId;
+    name: string;
+    slug: string;
+    stripePublishableKey?: string;
+}
+/**
+ * Create a gift card purchase and get Stripe client secret
+ * @param req - Gift card purchase request details
+ * @returns Gift card UUID and Stripe client secret, or null on failure
+ */
+export declare function createGiftCardPurchase(req: GiftCardPurchaseRequest): Promise<GiftCardPurchaseResponse | null>;
+/**
+ * Result shape consumed by the Checkout component / GiftCardInput.
+ * Monetary fields here are in DOLLARS (formatCurrency-ready).
+ */
+export interface ApplyGiftCardResult {
+    valid: boolean;
+    giftCardCode?: string;
+    giftCardAmount?: number;
+    giftCardBalance?: number;
+    paymentType?: string;
+    stripeAmount?: number;
+    orderTotal?: number;
+    requiresStripe?: boolean;
+    error?: string;
+}
+/**
+ * Apply a gift card to a cart.
+ */
+export declare function applyGiftCard(cartId: string, code: string): Promise<ApplyGiftCardResult>;
+export interface RemoveGiftCardResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Remove a gift card from a cart. Pass a `code` to remove a single stacked card;
+ * omit it to remove all applied gift cards.
+ */
+export declare function removeGiftCard(cartId: string, code?: string): Promise<RemoveGiftCardResult>;
+export interface CompleteGiftCardPaymentInput {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phoneNumber?: string | null;
+    mailingList?: boolean;
+}
+export interface CompleteGiftCardPaymentResult {
+    success: boolean;
+    orderId?: string;
+    confirmationNumber?: string;
+    error?: string;
+}
+/**
+ * Complete a gift-card-only payment (no Stripe required when balance >= total).
+ */
+export declare function completeGiftCardPayment(cartId: string, customerDetails: CompleteGiftCardPaymentInput): Promise<CompleteGiftCardPaymentResult>;
+/**
+ * Fetch venue information by slug, discriminating a real 404 from a transient
+ * failure.
+ *
+ * The gift-card SSR loader (`v/[venueSlug]/gift-cards/purchase/+page.ts`) gates
+ * its HTTP status on this: only an upstream 404 (`errNotFound`) becomes a page
+ * 404. A 5xx, network error, or timeout is `err(...)` (transient) so the loader
+ * answers 503/retry rather than a permanent-looking 404 on a backend blip.
+ *
+ * @param slug - Venue slug
+ * @param customFetch - Optional custom fetch function (for SSR)
+ * @returns `ok(venue)`, `errNotFound(...)` for a real 404, or `err(...)` transient
+ */
+export declare function getVenueBySlugResult(slug: string, customFetch?: typeof fetch): Promise<Result<VenueInfo>>;
+/**
+ * Fetch venue information by slug
+ *
+ * Fail-open adapter over {@link getVenueBySlugResult}: returns `null` on any
+ * failure. SSR loaders that need 404-vs-503 use the Result variant.
+ *
+ * @param slug - Venue slug
+ * @returns Venue info or null on failure
+ */
+export declare function getVenueBySlug(slug: string, customFetch?: typeof fetch): Promise<VenueInfo | null>;

package/dist/api/api/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MicDrop Public Checkout API
+ *
+ * This module provides a complete API layer for the public checkout flow:
+ * - Order creation and management
+ * - Payment processing with Stripe
+ * - Promo code validation
+ * - Event and venue data fetching
+ * - Session management
+ *
+ * All endpoints are public (no authentication required) and use
+ * the /api/v2/public base path.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createPaymentIntent,
+ *   validatePromoCode,
+ *   transformOrder,
+ * } from '@getmicdrop/venue-calendar/api';
+ *
+ * // Create payment intent
+ * const intent = await createPaymentIntent(cartId, { 123: 2 });
+ *
+ * // Validate promo code
+ * const promo = await validatePromoCode(eventId, 'DISCOUNT10');
+ *
+ * // Transform order for display
+ * const order = transformOrder(apiResponse);
+ * ```
+ */
+export { configureApi, getApiConfig, getPublicBaseUrl, getLegacyPublicUrl, getOrdersV2Url, getClientIP, apiGet, apiPost, apiPut, apiDelete, } from './client.js';
+export { createPaymentIntent, validatePaymentIntent, updateCartQuantities, getCartByUUID, createOrder, getOrder, completeReservation, cancelReservation, extendCheckoutSession, getSessionStatus, initiateOrder, trackUTMSource, } from './orders.js';
+export type { CartReservationView, CartView } from './orders.js';
+export { validatePromoCode, hasPromoCodes, applyPromoCode, removePromoCode, } from './promo.js';
+export { fetchEventDetails, fetchEventTickets, fetchEventPerformers, fetchAllVenues, fetchVenueEvents, getMonthEvents, getOrgMonthEvents, getSeriesOccurrences, fetchSeriesOccurrences, fetchPublicCollection, resolvePublicEntity, checkEventPassword, checkCollectionPassword, testNetworkConnection, fetchEventDetailsResult, fetchEventTicketsResult, fetchEventPerformersResult, fetchAllVenuesResult, fetchVenueEventsResult, getMonthEventsResult, getOrgMonthEventsResult, getSeriesOccurrencesResult, fetchSeriesOccurrencesResult, } from './events.js';
+export { ok, err, errNotFound, isOk, isErr, unwrapOr, type Result, } from './result.js';
+export { getVenue, getVenueFees, getVenueBySlug } from './venues.js';
+export { createGiftCardPurchase, applyGiftCard, removeGiftCard, completeGiftCardPayment, } from './gift-cards.js';
+export type { GiftCardPurchaseRequest, GiftCardPurchaseResponse, ApplyGiftCardResult, RemoveGiftCardResult, CompleteGiftCardPaymentInput, CompleteGiftCardPaymentResult, } from './gift-cards.js';
+export { joinWaitlist, getWaitlistStatus, validateWaitlistToken, } from './waitlist.js';
+export type { JoinWaitlistResult, WaitlistStatusResult, ValidateWaitlistTokenResult, } from './waitlist.js';
+export { computeCtaState } from './cta.js';
+export type { CtaState, CtaStateOptions } from './cta.js';
+export { transformOrder, transformTicket, transformOrderForDisplay, transformEvent, transformEventData, transformAvailableTicket, getCDNImageUrl, getEventImageUrl, calculateCtaState, transformVenue, extractVenueFees, formatVenueAddress, } from './transformers/index.js';
+export type { ApiConfig, ApiResponse, PaymentIntentRequest, PaymentIntentResponse, CompleteReservationResponse, CancelReservationResponse, CreateOrderRequest, CreateOrderResponse, ValidatePaymentRequest, ValidatePaymentResponse, AttendeeInfo, ExtendSessionRequest, ExtendSessionResponse, SessionStatus, PromoValidationResponse, HasPromoCodesResponse, Order, PurchasedTicket, Event, AvailableTicket, EventPerformersResponse, Performer, Venue, SeriesOccurrence, SeriesOccurrencesResponse, SeriesPageData, PublicCollectionData, } from './types.js';

package/dist/api/api/orders.d.ts

@@ -0,0 +1,149 @@
+import { PaymentIntentResponse, CompleteReservationResponse, CancelReservationResponse, CreateOrderResponse, ValidatePaymentRequest, ValidatePaymentResponse, ExtendSessionResponse, SessionStatus, Order } from './types.js';
+/**
+ * Create a payment intent for the cart
+ *
+ * This initiates the Stripe payment flow by creating a PaymentIntent
+ * on the backend. The response includes the client_secret needed
+ * for Stripe Elements.
+ *
+ * @param cartId - The cart/order UUID
+ * @param quantities - Map of ticketId -> quantity
+ * @param donationAmounts - Map of ticketId -> donation amount in dollars (for type=2 tickets)
+ * @returns Payment intent data including client_secret, or null on error
+ */
+export declare function createPaymentIntent(cartId: string, quantities: Record<string | number, number>, donationAmounts?: Record<string | number, number>): Promise<PaymentIntentResponse | null>;
+/**
+ * Fetch an existing cart by UUID (cross-device pre-fill — §1.3).
+ *
+ * Returns the server's authoritative view of a cart so a second device
+ * visiting the tickets page can see the in-progress reservation it created
+ * on another device. Returns `null` if:
+ *   - the cart no longer exists (404)
+ *   - the cart belongs to a different event than `expectedEventID` (when
+ *     supplied) — we don't want to mix carts across events
+ *   - the cart status is no longer `reserved` / `active` (e.g. expired,
+ *     completed, abandoned) — caller should treat the local cookie as stale
+ *   - any network/decode failure (caller falls back to localStorage only)
+ *
+ * Returned shape matches the orders-service `GET /v2Public/cart/{uuid}`
+ * response: a Cart model with embedded Reservations.
+ */
+export interface CartReservationView {
+    ticketID: number;
+    quantity: number;
+    priceAtReservation: number;
+    status: string;
+}
+export interface CartView {
+    uuid: string;
+    eventID: number;
+    status: string;
+    expiresAt: string;
+    reservations: CartReservationView[];
+}
+export declare function getCartByUUID(cartUUID: string, expectedEventID?: string | number): Promise<CartView | null>;
+/**
+ * Update cart quantities after the cart already exists.
+ *
+ * Replaces all reservations on the cart with the new quantities.
+ * The orders-service handler releases old reservations (returning
+ * inventory) and creates new ones (decrementing inventory) atomically.
+ *
+ * Use this when the user changes ticket counts AFTER the initial
+ * cart was created via initiateOrder. The cart UUID is preserved,
+ * so the timer and extension state stay intact.
+ *
+ * @returns true on success, false on failure
+ */
+export declare function updateCartQuantities(cartId: string, quantities: Record<string | number, number>, donationAmounts?: Record<string | number, number>): Promise<boolean>;
+/**
+ * Complete reservation after successful payment
+ *
+ * Called after Stripe confirms the payment to finalize the order
+ * and generate tickets.
+ *
+ * @param orderUuid - The order UUID
+ * @returns Success status and message
+ */
+export declare function completeReservation(orderUuid: string): Promise<CompleteReservationResponse>;
+/**
+ * Cancel reservation and release tickets back to inventory
+ *
+ * Called when user abandons checkout or session expires.
+ *
+ * @param orderUuid - The order UUID
+ * @returns Success status and message
+ */
+export declare function cancelReservation(orderUuid: string): Promise<CancelReservationResponse>;
+/**
+ * Create a new order/cart
+ *
+ * This creates an empty order that can be used for checkout.
+ * The order UUID is used for all subsequent operations.
+ *
+ * @param eventId - The event ID
+ * @param promoCode - Optional promo code to apply
+ * @returns The order UUID, or null on error
+ */
+export declare function createOrder(eventId: string | number, promoCode?: string): Promise<CreateOrderResponse | null>;
+/**
+ * Get order details (public, no auth required)
+ *
+ * Fetches the order details for displaying on the success page.
+ *
+ * @param orderId - The order UUID or ID
+ * @returns The order details, or null on error
+ */
+export declare function getOrder(orderId: string): Promise<Order | null>;
+/**
+ * Validate payment intent and complete the order
+ *
+ * This is an alternative to completeReservation that accepts
+ * additional payment details. Used by micdrop-frontend.
+ *
+ * @param cartId - The cart/order UUID
+ * @param payload - Payment validation payload
+ * @returns Validation result
+ */
+export declare function validatePaymentIntent(cartId: string, payload: ValidatePaymentRequest): Promise<ValidatePaymentResponse | null>;
+/**
+ * Extend the checkout session by 15 minutes
+ *
+ * Users get a limited number of extensions (typically 2-3).
+ *
+ * @param orderUuid - The order UUID
+ * @returns Extension result with new expiry time
+ */
+export declare function extendCheckoutSession(orderUuid: string): Promise<ExtendSessionResponse>;
+/**
+ * Get current session status including expiry time
+ *
+ * Used to display countdown timer and check if extensions are available.
+ *
+ * @param orderUuid - The order UUID
+ * @returns Session status including expiry time
+ */
+export declare function getSessionStatus(orderUuid: string): Promise<SessionStatus>;
+/**
+ * Initiate a new order (alias for createOrder)
+ *
+ * This function provides backwards compatibility with micdrop-frontend.
+ * It accepts the same parameters as the legacy initiateOrder function.
+ *
+ * @param cartData - Object containing eventID and optional quantities/promoCode
+ * @returns The order UUID, or null on error
+ */
+export declare function initiateOrder(cartData?: {
+    eventID: string | number;
+    promoCode?: string;
+    quantities?: Record<string | number, number>;
+}): Promise<string | null>;
+/**
+ * Track UTM source for analytics
+ *
+ * Records the traffic source (utm_source parameter) for marketing analytics.
+ *
+ * @param venueId - The venue ID
+ * @returns Promise that resolves when tracking is complete
+ */
+export declare function trackUTMSource(venueId: string | number): Promise<void>;

package/dist/api/api/promo.d.ts

@@ -0,0 +1,45 @@
+import { PromoValidationResponse } from './types.js';
+/**
+ * Validate a promo code for an event
+ *
+ * Checks if a promo code is valid and returns its effects:
+ * - Discount amount and type
+ * - Hidden ticket reveal
+ *
+ * @param eventId - The event ID
+ * @param code - The promo code to validate
+ * @returns Validation result with discount info
+ */
+export declare function validatePromoCode(eventId: string | number, code: string): Promise<PromoValidationResponse>;
+/**
+ * Check if promo codes are available for an event
+ *
+ * Used to conditionally show/hide the promo code input field.
+ *
+ * @param eventId - The event ID
+ * @returns Whether promo codes exist for this event
+ */
+export declare function hasPromoCodes(eventId: string | number): Promise<boolean>;
+/**
+ * Apply a promo code to a cart
+ *
+ * This updates the cart with the promo code discount.
+ *
+ * @param cartId - The cart UUID
+ * @param code - The promo code to apply
+ * @returns Success status
+ */
+export declare function applyPromoCode(cartId: string, code: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Remove a promo code from a cart
+ *
+ * @param cartId - The cart UUID
+ * @returns Success status
+ */
+export declare function removePromoCode(cartId: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;

package/dist/api/api/result.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Result — the canonical error channel for API loaders.
+ *
+ * The public loaders in this package historically collapsed a failed fetch
+ * to an empty value (`[]`, `{ performers: [], showPerformers: false }`, or
+ * `null`), which is indistinguishable from a genuinely empty result. A buyer
+ * hitting a live event during a transient endpoint blip then sees a dead
+ * "No tickets available" button with no retry; a failed calendar month
+ * renders dark, so the venue looks like it has nothing on.
+ *
+ * `Result<T>` gives loaders a typed error channel so callers can tell
+ * "the request failed" apart from "there is genuinely nothing here", and
+ * offer a retry instead of silently degrading. Loaders expose a `*Result`
+ * variant returning this; the array/object-returning public functions stay
+ * as thin fail-open adapters over that variant (single source of truth for
+ * the fetch + validation logic).
+ *
+ * Not to be confused with `ApiResponse<T>` (types.ts) — that is the write-path
+ * HTTP envelope returned by `apiPost`/`apiGet`/etc. (`{ success, data?, error?,
+ * statusCode? }`, discriminated on `.success`). `Result<T>` is the read-path
+ * loader channel, discriminated on `.ok`. They are deliberately separate:
+ * `ApiResponse` carries transport metadata, `Result` carries only "loaded vs
+ * failed". Check `.ok` on a Result, `.success` on an ApiResponse — never mix.
+ */
+export type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    notFound?: boolean;
+};
+/** Wrap a successful value. */
+export declare function ok<T>(data: T): Result<T>;
+/**
+ * Wrap a failure with a short, stable error code (used for i18n/render).
+ *
+ * This is a TRANSIENT failure by default (`notFound` is unset) — the request
+ * couldn't complete (network, timeout, 5xx). Loaders that gate an SSR 404 on a
+ * Result must treat a plain `err(...)` as retryable (503), not "gone" (404), so
+ * a backend blip never renders a permanent-looking 404 to a buyer or crawler.
+ */
+export declare function err(error: string): Result<never>;
+/**
+ * Wrap a genuine "this resource does not exist" failure (upstream 404).
+ *
+ * Distinct from `err(...)`: only this warrants an SSR 404. A transient upstream
+ * failure must NOT collapse to `errNotFound` — that is exactly the bug this
+ * channel exists to prevent (a fetch blip becoming a permanent 404).
+ */
+export declare function errNotFound(error: string): Result<never>;
+/** Narrowing guard — true when the result carries data. */
+export declare function isOk<T>(result: Result<T>): result is {
+    ok: true;
+    data: T;
+};
+/**
+ * Narrowing guard — true when the result is a failure (transient OR not-found).
+ *
+ * This package typechecks with `strictNullChecks` off, where the ELSE flow of a
+ * discriminated union does NOT narrow (`if (r.ok) {…}` narrows the positive
+ * branch, but the fall-through keeps the full union). Consumers that need the
+ * failure branch's `error`/`notFound` must narrow POSITIVELY through this guard
+ * rather than relying on `!r.ok` control flow.
+ */
+export declare function isErr<T>(result: Result<T>): result is {
+    ok: false;
+    error: string;
+    notFound?: boolean;
+};
+/**
+ * Collapse a Result to its data, substituting `fallback` on failure.
+ *
+ * This is the fail-open bridge the legacy array/object-returning loaders use
+ * so existing callers keep their current "degrade to empty" behaviour until
+ * they adopt the Result variant and render an error/retry state.
+ */
+export declare function unwrapOr<T>(result: Result<T>, fallback: T): T;