tixbit 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 interface TixBitConfig {
     /**
      * Base URL of the TixBit web app.
-     * @default "https://tixbit.com"
+     * @default "https://www.tixbit.com"
      */
     baseUrl?: string;
     /**
@@ -11,9 +11,16 @@ interface TixBitConfig {
      */
     timeoutMs?: number;
     /**
-     * Optional API key for authenticated endpoints (future use).
+     * Public TixBit MPP purchase endpoint.
+     * Only the canonical endpoint is accepted; loopback HTTP is allowed for local QA.
+     * @default "https://mcp.tixbit.com/api/purchase"
      */
-    apiKey?: string;
+    paymentEndpoint?: string;
+    /**
+     * Fetch implementation used for purchases. Supply `mppx.fetch` to
+     * automatically answer an MPP 402 challenge and retry with a credential.
+     */
+    paymentFetch?: typeof fetch;
 }
 interface SearchEventsParams {
     /** Free-text search query (e.g. "Hawks", "Taylor Swift"). */
@@ -24,6 +31,22 @@ interface SearchEventsParams {
     state?: string;
     /** Category slug (e.g. "nba-basketball", "mlb-baseball"). */
     category?: string;
+    /** League abbreviation (for example "NBA" or "MLB"). */
+    league?: string;
+    /** High-level event type. */
+    categoryEventType?: "SPORT" | "CONCERT" | "THEATER" | "ALL";
+    /** Public performer ID. */
+    performerId?: string;
+    /** Public venue ID. */
+    venueId?: string;
+    /** Parking-event behavior. */
+    parkingFilter?: ParkingFilter;
+    /** Latitude used with manual location filtering. */
+    nearLat?: number;
+    /** Longitude used with manual location filtering. */
+    nearLng?: number;
+    /** Whether location values are inferred, manual, or disabled. */
+    locationMode?: LocationMode;
     /** ISO date string — only events on or after this date. */
     startDate?: string;
     /** ISO date string — only events on or before this date. */
@@ -42,14 +65,21 @@ interface TixBitEvent {
     venue_name: string | null;
     venue_city: string | null;
     venue_state: string | null;
+    venue_country: string | null;
     image_url: string | null;
+    category_slug: string | null;
     category_name: string | null;
     category_event_type: string | null;
+    metadata: Record<string, unknown> | null;
     has_listings: boolean;
     inventory: {
         total_available: number;
         min_price: number;
         max_price: number;
+        sources?: {
+            local: number;
+            marketplace: number;
+        };
     };
 }
 interface SearchEventsResult {
@@ -57,10 +87,35 @@ interface SearchEventsResult {
     pagination: {
         page: number;
         size: number;
-        total: number;
-        totalPages: number;
+        total: number | null;
+        totalPages: number | null;
         hasNext: boolean;
         hasPrev: boolean;
+        totalExact: boolean;
+    };
+}
+/** Public event detail returned by `GET /api/events/:eventId`. */
+interface TixBitEventDetail {
+    success: boolean;
+    id: string;
+    external_id: string;
+    slug?: string;
+    name?: string;
+    url?: string;
+    images?: Array<Record<string, unknown> & {
+        url: string;
+    }>;
+    dates?: Record<string, unknown>;
+    sales?: Record<string, unknown>;
+    priceRanges?: unknown[];
+    classifications?: unknown[];
+    info?: string;
+    pleaseNote?: string;
+    seatmap?: {
+        staticUrl: string;
+    };
+    _embedded?: {
+        venues?: Array<Record<string, unknown>>;
     };
 }
 interface GetListingsParams {
@@ -72,19 +127,39 @@ interface GetListingsParams {
     page?: number;
     /** Sort direction for price. @default "asc" */
     orderByDirection?: "asc" | "desc";
+    /** Return all currently available listings. */
+    includeAll?: boolean;
+    /** Bypass the listings cache for this request. */
+    refresh?: boolean;
 }
 interface TixBitListing {
     id: string;
+    event_id: string | null;
     price: number;
+    total_price: number | null;
+    base_price_per_ticket: number | null;
+    base_total_price: number | null;
+    face_value: number | null;
+    fee_amount_per_ticket: number | null;
+    fee_amount_total: number | null;
+    fee_percent: number | null;
+    currency: string;
     quantity: number;
     quantities_list: number[];
     section: string | null;
     row: string | null;
+    seat_from: string | null;
+    seat_to: string | null;
     seat_numbers: string | null;
+    /** @deprecated The public API no longer returns listing hashes. */
     listing_hash: string;
     notes: string | null;
     delivery_method: string | null;
+    in_hand_date: string | null;
+    stock_type: string | null;
+    disclosure_ids: string[];
     splits: number[];
+    /** Sanitized public response fields not normalized above. */
     raw: Record<string, unknown>;
 }
 interface GetListingsResult {
@@ -93,9 +168,29 @@ interface GetListingsResult {
         total: number;
         page: number;
         size: number;
+        totalPages?: number;
+        currentPageTotalCount?: number;
+        cache?: boolean;
+        cacheExpiresAt?: string | null;
+        cacheState?: "fresh" | "stale" | "unavailable";
+        freshness?: "live" | "cached";
         cacheSource?: string;
     };
 }
+interface TixBitListingDisclosure {
+    id: string;
+    description: string;
+    type?: {
+        id: string;
+        name?: string;
+        severity?: string;
+        slug?: string;
+    };
+}
+interface GetListingResult {
+    listing: TixBitListing;
+    disclosures: TixBitListingDisclosure[];
+}
 interface CheckoutParams {
     /** Listing ID to purchase (from getListings results). */
     listingId: string;
@@ -104,13 +199,73 @@ interface CheckoutParams {
 }
 /** A checkout link that the user opens in a browser to complete purchase. */
 interface CheckoutLink {
-    /** Full URL to the checkout page on tixbit.com. */
+    /** Full URL to the checkout page on www.tixbit.com. */
     url: string;
     /** Listing ID being purchased. */
     listingId: string;
     /** Ticket quantity. */
     quantity: number;
 }
+interface BuyTicketsParams {
+    listingId: string;
+    quantity: number;
+    email: string;
+    /** Total USD charge ceiling, including fees. */
+    maxAmountCents: number;
+    confirm?: boolean;
+    sharedPaymentToken?: string;
+}
+interface AgentResult {
+    success: boolean;
+    status?: string;
+    data?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+    action?: string;
+}
+interface PurchaseTicketsParams {
+    /** Listing ID selected from `getListings`. */
+    listingId: string;
+    /** Number of tickets to purchase (1–8). */
+    quantity: number;
+    /** Required buyer email for confirmation and ticket delivery. */
+    email: string;
+    /** Optional buyer/recipient name. */
+    name?: string;
+    /** Stable value to reuse across retries and recovery checks. */
+    idempotencyKey?: string;
+}
+type PurchaseStatus = "fulfilled" | "payment_required" | "pending" | "manual_review_required" | "payment_failed" | "rejected";
+interface PurchaseOrder {
+    reference: string;
+    status: PurchaseStatus;
+    listingId: string;
+    quantity: number;
+    pricePerTicket: number;
+    subtotal: number;
+    fees: number;
+    total: number;
+    currency: string;
+    section?: string;
+    row?: string;
+}
+/** Agent-readable outcome from the MPP machine checkout flow. */
+interface PurchaseTicketsResult {
+    success: boolean;
+    status: PurchaseStatus;
+    idempotencyKey: string;
+    orderReference: string | null;
+    receiptUrl: string | null;
+    order?: PurchaseOrder;
+    paid?: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+    action?: string;
+}
 interface BrowseEventsParams {
     /** User latitude for location-aware results. */
     latitude?: number;
@@ -122,17 +277,51 @@ interface BrowseEventsParams {
     state?: string;
     /** Number of results. @default 18 */
     size?: number;
+    /** Page number (1-indexed). @default 1 */
+    page?: number;
+    /** Optional free-text query. */
+    query?: string;
+    /** Category slug. */
+    category?: string;
+    /** League abbreviation. */
+    league?: string;
+    /** Event date in YYYY-MM-DD format. */
+    date?: string;
     /** Category event type: SPORT, CONCERT, THEATER. */
     categoryEventType?: "SPORT" | "CONCERT" | "THEATER" | "ALL";
+    /** Response context used by the public browse endpoint. */
+    context?: "homepage" | "events" | "category";
+    /** Location-selection behavior. */
+    locationMode?: LocationMode;
+    /** Local-only or broadened search behavior. */
+    searchScope?: "local" | "broadened";
+    /** Parking-event behavior. */
+    parkingFilter?: ParkingFilter;
+    /** Upcoming or trending recommendation order. */
+    recommendation?: "upcoming" | "trending";
 }
 interface BrowseEventsResult {
     events: TixBitEvent[];
-    total: number;
+    total: number | null;
+    totalExact: boolean;
+    hasMore: boolean;
+    page: number;
+    pageSize: number;
+    degraded?: boolean;
 }
+type ParkingFilter = "exclude" | "only" | "include";
+type LocationMode = "inferred" | "manual" | "none";
 interface GetSeatmapParams {
     /** External event ID (from search results). */
     eventId: string;
 }
+interface SeatmapLabel {
+    text: string;
+    x: number;
+    y: number;
+    size?: number;
+    angle?: number;
+}
 /** A single section in the venue's seating chart. */
 interface SeatmapSection {
     /** Section ID (e.g. "80841"). */
@@ -140,11 +329,18 @@ interface SeatmapSection {
     /** Human-readable section name (e.g. "101", "FLOOR3", "201"). */
     name: string;
     /**
-     * Center coordinates of the section label on the map.
-     * Useful for understanding relative position.
+     * Primary label anchor for simple renderers and relative position helpers.
      */
     x: number;
     y: number;
+    /**
+     * All labels from the seatmap payload (useful for richer rendering).
+     */
+    labels: SeatmapLabel[];
+    /**
+     * SVG path for drawing the section shape overlay.
+     */
+    shape_path: string | null;
 }
 /** A zone grouping sections (e.g. "Section", "Floor", "Suite"). */
 interface SeatmapZone {
@@ -185,7 +381,8 @@ interface SeatmapResult {
 declare class TixBitClient {
     private readonly baseUrl;
     private readonly timeoutMs;
-    private readonly apiKey;
+    private readonly paymentEndpoint;
+    private readonly paymentFetch;
     constructor(config?: TixBitConfig);
     private request;
     private qs;
@@ -198,6 +395,8 @@ declare class TixBitClient {
      * ```
      */
     searchEvents(params?: SearchEventsParams): Promise<SearchEventsResult>;
+    /** Get one public event by ID or slug. */
+    getEvent(eventId: string): Promise<TixBitEventDetail>;
     /**
      * Browse upcoming events near a location (homepage-style).
      *
@@ -212,10 +411,29 @@ declare class TixBitClient {
      *
      * @example
      * ```ts
-     * const listings = await client.getListings({ eventId: "abc123" });
+     * const listings = await client.getListings({ eventId: "EVENT123" });
      * ```
      */
     getListings(params: GetListingsParams): Promise<GetListingsResult>;
+    /** Get one public listing by listing ID. */
+    getListing(listingId: string): Promise<GetListingResult>;
+    /** Refreshed inventory, not a reservation or negotiated offer. */
+    quoteListings(params: GetListingsParams): Promise<GetListingsResult>;
+    private agentRequest;
+    /** Public browser entry points. This does not create or import a CLI session. */
+    getAuthorizationInfo(): {
+        apiKeyRequired: boolean;
+        cliSessionSupported: boolean;
+        signInUrl: string;
+        sellerUrl: string;
+        linkWalletUrl: string;
+        action: string;
+    };
+    private sellerAuthorizationRequired;
+    /** Stripe Link checkout. No confirmation means quote only. Never retries payment. */
+    buyTickets(params: BuyTicketsParams): Promise<AgentResult>;
+    listSellerListings(accessToken?: string): Promise<AgentResult>;
+    createSellerListing(body: unknown, accessToken: string, confirm: boolean): Promise<AgentResult>;
     /**
      * Create a checkout link for a listing.
      *
@@ -225,17 +443,25 @@ declare class TixBitClient {
      * @example
      * ```ts
      * const link = client.createCheckoutLink({
-     *   listingId: "P2JO5OBX",
+     *   listingId: "LISTING123",
      *   quantity: 2,
      * });
      *
      * console.log(link.url);
-     * // → "https://tixbit.com/checkout/process?listing=P2JO5OBX&quantity=2"
+     * // → "https://www.tixbit.com/checkout/process?listing=LISTING123&quantity=2"
      * ```
      */
     createCheckoutLink(params: CheckoutParams): CheckoutLink;
     /**
-     * Build the direct URL to an event page on tixbit.com.
+     * Purchase tickets through the public MPP endpoint.
+     *
+     * Configure `paymentFetch` with the official mppx client to automatically
+     * answer the server's 402 challenge. Reuse the returned idempotency key for
+     * any recovery check after a timeout or pending result.
+     */
+    purchaseTickets(params: PurchaseTicketsParams): Promise<PurchaseTicketsResult>;
+    /**
+     * Build the direct URL to an event page on www.tixbit.com.
      */
     eventUrl(slugOrId: string): string;
     /**
@@ -247,7 +473,7 @@ declare class TixBitClient {
      *
      * @example
      * ```ts
-     * const seatmap = await client.getSeatmap({ eventId: "4BKJMDZ" });
+     * const seatmap = await client.getSeatmap({ eventId: "EVENT123" });
      * console.log(seatmap.venue_name); // "State Farm Arena"
      * console.log(seatmap.section_names); // ["101", "102", ...]
      * ```
@@ -263,5 +489,19 @@ declare class TixBitApiError extends Error {
     readonly url: string;
     constructor(message: string, status: number, url: string);
 }
+declare class TixBitTimeoutError extends Error {
+    readonly url: string;
+    readonly timeoutMs: number;
+    constructor(url: string, timeoutMs: number);
+}
+
+/** Run in mppx onChallenge, before signing or transferring any funds.
+ * pathUSD uses six atomic decimals. Unknown tokens and recurring intents fail closed.
+ */
+declare function assertMppChallenge(challenge: {
+    method: string;
+    intent: string;
+    request: Record<string, unknown>;
+}, maxAmountCents: number): void;
 
-export { type BrowseEventsParams, type BrowseEventsResult, type CheckoutLink, type CheckoutParams, type GetListingsParams, type GetListingsResult, type GetSeatmapParams, type SearchEventsParams, type SearchEventsResult, type SeatmapResult, type SeatmapSection, type SeatmapVenue, type SeatmapZone, TixBitApiError, TixBitClient, type TixBitConfig, type TixBitEvent, type TixBitListing };
+export { type AgentResult, type BrowseEventsParams, type BrowseEventsResult, type BuyTicketsParams, type CheckoutLink, type CheckoutParams, type GetListingResult, type GetListingsParams, type GetListingsResult, type GetSeatmapParams, type LocationMode, type ParkingFilter, type PurchaseOrder, type PurchaseStatus, type PurchaseTicketsParams, type PurchaseTicketsResult, type SearchEventsParams, type SearchEventsResult, type SeatmapLabel, type SeatmapResult, type SeatmapSection, type SeatmapVenue, type SeatmapZone, TixBitApiError, TixBitClient, type TixBitConfig, type TixBitEvent, type TixBitEventDetail, type TixBitListing, type TixBitListingDisclosure, TixBitTimeoutError, assertMppChallenge };