tixbit 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,41 +1,109 @@
+// src/safety.ts
+function trustedWebBase(base) {
+  const url = new URL(base);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || !(url.origin === "https://www.tixbit.com" || local && ["http:", "https:"].includes(url.protocol))) {
+    throw new TypeError("Credential requests require https://www.tixbit.com or a loopback QA origin");
+  }
+  return url.origin;
+}
+function assertMppChallenge(challenge, maxAmountCents) {
+  const { amount, currency } = challenge.request;
+  if (!Number.isSafeInteger(maxAmountCents) || maxAmountCents <= 0 || challenge.method !== "tempo" || challenge.intent !== "charge" || currency !== "0x20c0000000000000000000000000000000000000" || typeof amount !== "string" || !/^\d{1,30}$/.test(amount) || BigInt(amount) <= 0n || BigInt(amount) > BigInt(maxAmountCents) * 10000n || challenge.request.splits !== void 0 || challenge.request.methodDetails !== void 0 && (!challenge.request.methodDetails || typeof challenge.request.methodDetails !== "object" || "splits" in challenge.request.methodDetails)) {
+    throw new TypeError("MPP challenge exceeds the approved total or uses an unsupported payment asset or intent");
+  }
+}
+function redact(value, secrets = []) {
+  if (typeof value === "string") {
+    let result = value.replace(/\bspt_[A-Za-z0-9_]+/g, "[REDACTED]");
+    for (const secret of secrets.filter(Boolean)) result = result.split(secret).join("[REDACTED]");
+    return result;
+  }
+  if (Array.isArray(value)) return value.map((item) => redact(item, secrets));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, /token|secret|authorization|private.?key|password|credential/i.test(key) ? "[REDACTED]" : redact(item, secrets)]));
+  return value;
+}
+
 // src/client.ts
-var DEFAULT_BASE_URL = "https://tixbit.com";
+var DEFAULT_BASE_URL = "https://www.tixbit.com";
+var DEFAULT_PAYMENT_ENDPOINT = "https://mcp.tixbit.com/api/purchase";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var USER_AGENT = "@tixbit/sdk";
+function normalizePaymentEndpoint(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("paymentEndpoint must be an absolute URL");
+  }
+  const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  const isTixBitHost = url.origin === "https://mcp.tixbit.com" && url.pathname === "/api/purchase";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new TypeError(
+      "paymentEndpoint must use HTTPS (HTTP is allowed only for loopback QA)"
+    );
+  }
+  if (url.username || url.password || url.hash || url.search) {
+    throw new TypeError("paymentEndpoint must not contain credentials or a fragment");
+  }
+  if (!isLoopback && !isTixBitHost) {
+    throw new TypeError(
+      "paymentEndpoint must use a TixBit host or a loopback address for local QA"
+    );
+  }
+  return url.toString().replace(/\/$/, "");
+}
+function normalizeExternalEventId(eventId) {
+  return eventId;
+}
+function toAbsoluteUrl(baseUrl, value) {
+  if (!value) return null;
+  if (value.startsWith("http://") || value.startsWith("https://")) {
+    return value;
+  }
+  return `${baseUrl}${value.startsWith("/") ? "" : "/"}${value}`;
+}
 var TixBitClient = class {
   baseUrl;
   timeoutMs;
-  apiKey;
+  paymentEndpoint;
+  paymentFetch;
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    this.apiKey = config.apiKey;
+    this.paymentEndpoint = normalizePaymentEndpoint(
+      config.paymentEndpoint ?? DEFAULT_PAYMENT_ENDPOINT
+    );
+    this.paymentFetch = config.paymentFetch ?? ((input, init) => fetch(input, init));
   }
   // ── HTTP helpers ──────────────────────────────────────────────────────────
-  async request(path, init) {
+  async request(path) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     const headers = {
       Accept: "application/json",
-      "User-Agent": USER_AGENT,
-      ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}
+      "User-Agent": USER_AGENT
     };
     try {
       const res = await fetch(url, {
-        ...init,
-        headers: { ...headers, ...init?.headers },
+        redirect: "error",
+        headers,
         signal: controller.signal
       });
       if (!res.ok) {
-        const text = await res.text().catch(() => "");
         throw new TixBitApiError(
-          `${res.status} ${res.statusText}: ${text.slice(0, 300)}`,
+          `Request failed (HTTP ${res.status})`,
           res.status,
           url
         );
       }
       return await res.json();
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new TixBitTimeoutError(url, this.timeoutMs);
+      }
+      throw error;
     } finally {
       clearTimeout(timer);
     }
@@ -59,15 +127,40 @@ var TixBitClient = class {
       city: params.city,
       state: params.state,
       category: params.category,
+      league: params.league,
+      categoryEventType: params.categoryEventType,
+      performerId: params.performerId,
+      venueId: params.venueId,
+      parkingFilter: params.parkingFilter,
+      nearLat: params.nearLat,
+      nearLng: params.nearLng,
+      locationMode: params.locationMode,
       startDate: params.startDate,
       endDate: params.endDate,
       page: params.page,
       size: params.size ?? 25
     });
     const data = await this.request(`/api/events/search${query}`);
+    const pagination = data.pagination;
     return {
       events: (data.events ?? []).map(normalizeEvent),
-      pagination: data.pagination
+      pagination: {
+        ...pagination,
+        totalExact: pagination.totalExact ?? pagination.total !== null
+      }
+    };
+  }
+  /** Get one public event by ID or slug. */
+  async getEvent(eventId) {
+    const normalizedEventId = normalizeExternalEventId(eventId);
+    const data = await this.request(
+      `/api/events/${encodeURIComponent(normalizedEventId)}`
+    );
+    const publicEventId = normalizeExternalEventId(data.external_id ?? data.id);
+    return {
+      ...data,
+      id: publicEventId,
+      external_id: publicEventId
     };
   }
   // ── Browse (Location-Aware) ───────────────────────────────────────────────
@@ -81,19 +174,32 @@ var TixBitClient = class {
    */
   async browse(params = {}) {
     const query = this.qs({
+      page: params.page ?? 1,
       size: params.size ?? 18,
-      context: "homepage",
-      recommendation: "upcoming",
+      query: params.query,
+      category: params.category,
+      league: params.league,
+      date: params.date,
+      context: params.context ?? "homepage",
+      recommendation: params.recommendation ?? "upcoming",
       nearLat: params.latitude,
       nearLng: params.longitude,
       preferCity: params.city,
       preferState: params.state,
-      categoryEventType: params.categoryEventType
+      categoryEventType: params.categoryEventType,
+      locationMode: params.locationMode,
+      searchScope: params.searchScope,
+      parkingFilter: params.parkingFilter
     });
     const data = await this.request(`/api/events${query}`);
     return {
       events: (data.events ?? []).map(normalizeEvent),
-      total: data.total
+      total: data.total,
+      totalExact: data.totalExact ?? data.total !== null,
+      hasMore: data.hasMore ?? false,
+      page: data.page ?? params.page ?? 1,
+      pageSize: data.pageSize ?? params.size ?? 18,
+      ...data.degraded === void 0 ? {} : { degraded: data.degraded }
     };
   }
   // ── Listings ──────────────────────────────────────────────────────────────
@@ -102,27 +208,138 @@ var TixBitClient = class {
    *
    * @example
    * ```ts
-   * const listings = await client.getListings({ eventId: "abc123" });
+   * const listings = await client.getListings({ eventId: "EVENT123" });
    * ```
    */
   async getListings(params) {
     const query = this.qs({
       size: params.size ?? 50,
       page: params.page ?? 1,
-      order_by_direction: params.orderByDirection ?? "asc"
+      order_by_direction: params.orderByDirection ?? "asc",
+      includeAll: params.includeAll,
+      refresh: params.refresh
     });
-    const data = await this.request(`/api/events/${encodeURIComponent(params.eventId)}/listings${query}`);
+    const normalizedEventId = normalizeExternalEventId(params.eventId);
+    const data = await this.request(`/api/events/${encodeURIComponent(normalizedEventId)}/listings${query}`);
     const listings = (data.data ?? []).map(normalizeListing);
     return {
       listings,
       meta: {
-        total: data.meta?.total ?? listings.length,
-        page: data.meta?.page ?? params.page ?? 1,
-        size: data.meta?.size ?? params.size ?? 50,
+        total: readListingMetaNumber(data.meta, "total_count", "total") ?? listings.length,
+        page: readListingMetaNumber(data.meta, "current_page_number", "page") ?? params.page ?? 1,
+        size: readListingMetaNumber(data.meta, "current_page_size", "size") ?? params.size ?? 50,
+        totalPages: readListingMetaNumber(data.meta, "total_pages") ?? void 0,
+        currentPageTotalCount: readListingMetaNumber(data.meta, "current_page_total_count") ?? void 0,
+        cache: readBoolean(data.meta?.cache) ?? void 0,
+        cacheExpiresAt: readNullableString(data.meta?.cache_expires_at),
+        cacheState: readEnum(data.meta?.cache_state, ["fresh", "stale", "unavailable"]),
+        freshness: readEnum(data.meta?.freshness, ["live", "cached"]),
         cacheSource: data.meta?.cacheSource
       }
     };
   }
+  /** Get one public listing by listing ID. */
+  async getListing(listingId) {
+    const data = await this.request(`/api/listings/${encodeURIComponent(listingId)}`);
+    return {
+      listing: normalizeListing(data.listing),
+      disclosures: data.disclosures ?? []
+    };
+  }
+  /** Refreshed inventory, not a reservation or negotiated offer. */
+  async quoteListings(params) {
+    if (!params.eventId || params.eventId !== params.eventId.trim()) throw new TypeError("Copy the exact event ID from search");
+    if (params.size !== void 0 && (!Number.isInteger(params.size) || params.size < 1 || params.size > 100)) throw new RangeError("size must be 1-100");
+    const result = await this.getListings({ ...params, refresh: true });
+    if (result.meta.freshness !== "live") throw new Error("Live inventory is unavailable; no live quote can be provided");
+    return result;
+  }
+  async agentRequest(path, body, token) {
+    const base = trustedWebBase(this.baseUrl);
+    const headers = { Accept: "application/json", "Content-Type": "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const response = await fetch(`${base}${path}`, {
+      method: body === void 0 ? "GET" : "POST",
+      headers,
+      redirect: "error",
+      signal: AbortSignal.timeout(this.timeoutMs),
+      ...body === void 0 ? {} : { body: JSON.stringify(body) }
+    }).catch(() => {
+      throw new Error("Request did not complete; reconcile any write before retrying");
+    });
+    if (!response.ok) throw new TixBitApiError(`Request failed (HTTP ${response.status})`, response.status, `${base}${path}`);
+    const result = await response.json().catch(() => {
+      throw new Error("Invalid server response");
+    });
+    if (result?.success !== true || !result.data || typeof result.data !== "object" || Array.isArray(result.data)) throw new Error("Invalid server response");
+    return redact(result, [token ?? ""]);
+  }
+  /** Public browser entry points. This does not create or import a CLI session. */
+  getAuthorizationInfo() {
+    return {
+      apiKeyRequired: false,
+      cliSessionSupported: false,
+      signInUrl: "https://www.tixbit.com/sign-in",
+      sellerUrl: "https://www.tixbit.com/sell",
+      linkWalletUrl: "https://link.com/agents",
+      action: "Sign in in your browser for selling or browser checkout. Browser sign-in does not authenticate this CLI. No TixBit developer API key is needed."
+    };
+  }
+  sellerAuthorizationRequired() {
+    return {
+      success: false,
+      status: "authorization_required",
+      data: this.getAuthorizationInfo(),
+      error: { code: "SELLER_SIGN_IN_REQUIRED", message: "Seller operations require your signed-in user and seller access." },
+      action: "Open the sign-in URL, then continue on the seller page. Browser-to-CLI session authorization is not supported. No listing was read or submitted; do not copy browser cookies or tokens."
+    };
+  }
+  /** Stripe Link checkout. No confirmation means quote only. Never retries payment. */
+  async buyTickets(params) {
+    trustedWebBase(this.baseUrl);
+    if (!/^[A-Za-z0-9]{4,12}$/.test(params.listingId)) throw new TypeError("Link supports 4-12 alphanumeric listing IDs only; use browser checkout for native listings");
+    if (!Number.isInteger(params.quantity) || params.quantity < 1 || params.quantity > 8) throw new RangeError("quantity must be 1-8");
+    if (!Number.isSafeInteger(params.maxAmountCents) || params.maxAmountCents <= 0) throw new RangeError("A positive total maxAmountCents is required");
+    const email = normalizeBuyerEmail(params.email);
+    if (params.confirm === true && !params.sharedPaymentToken) {
+      return {
+        success: false,
+        status: "authorization_required",
+        data: { checkoutUrl: this.createCheckoutLink(params).url, maxAmountCents: params.maxAmountCents, automaticPayment: false },
+        error: { code: "PAYMENT_AUTHORIZATION_REQUIRED", message: "A user-approved payment method is required, not a TixBit API key." },
+        action: "Open the checkout URL to sign in and pay in your browser. Review and approve the final total there; this CLI cap is not transferred to browser checkout. No payment was sent. Automatic Link authorization is unavailable without public merchant discovery."
+      };
+    }
+    if (params.confirm === true && !/^spt_[A-Za-z0-9_]+$/.test(params.sharedPaymentToken ?? "")) throw new TypeError("Invalid user-approved Link payment credential");
+    const body = { listingId: params.listingId, quantity: params.quantity, email, maxAmountCents: params.maxAmountCents };
+    const quote = await this.agentRequest("/api/agentic/checkout", body);
+    const validQuote = (data) => data && data.listingId === params.listingId && data.quantity === params.quantity && data.currency === "usd" && Number.isSafeInteger(data.amountCents) && data.amountCents > 0 && data.amountCents <= params.maxAmountCents;
+    if (!validQuote(quote.data)) throw new Error("Checkout quote is invalid or exceeds the approved total; no payment sent");
+    if (params.confirm !== true) return quote;
+    if (quote.data?.maxAmountCentsSupported !== true) throw new Error("Server does not support the total cap; no payment sent");
+    try {
+      const paid = await this.agentRequest("/api/agentic/checkout", { ...body, sharedPaymentToken: params.sharedPaymentToken });
+      if (!validQuote(paid.data) || typeof paid.data?.orderId !== "string" || typeof paid.data?.status !== "string") throw new Error("Invalid payment outcome");
+      return { success: true, data: { listingId: params.listingId, quantity: params.quantity, amountCents: paid.data.amountCents, currency: "usd", orderId: paid.data.orderId, status: paid.data.status }, action: "Payment accepted. Check order fulfillment before any further purchase." };
+    } catch {
+      return { success: false, status: "unknown", error: { code: "PAYMENT_OUTCOME_UNKNOWN", message: "Payment or fulfillment status is unknown." }, action: "Do not retry or send another token. Reconcile this purchase with TixBit support and Stripe Link first." };
+    }
+  }
+  async listSellerListings(accessToken = "") {
+    if (!accessToken) return this.sellerAuthorizationRequired();
+    return this.agentRequest("/api/sell/listings", void 0, accessToken);
+  }
+  async createSellerListing(body, accessToken, confirm) {
+    trustedWebBase(this.baseUrl);
+    if (confirm !== true) throw new TypeError("Seller creation requires explicit confirmation");
+    if (!accessToken) return this.sellerAuthorizationRequired();
+    if (!body || typeof body !== "object" || Array.isArray(body) || !("termsAccepted" in body) || body.termsAccepted !== true) throw new TypeError("Listing JSON must explicitly include termsAccepted: true after seller approval");
+    try {
+      return await this.agentRequest("/api/sell/listings", body, accessToken);
+    } catch {
+      return { success: false, status: "unknown", error: { code: "SELLER_CREATE_UNCONFIRMED", message: "Listing creation was not confirmed." }, action: "Read sell list and reconcile before retrying. Submission does not guarantee a live listing." };
+    }
+  }
   // ── Checkout Link ──────────────────────────────────────────────────────────
   /**
    * Create a checkout link for a listing.
@@ -133,29 +350,148 @@ var TixBitClient = class {
    * @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) {
-    const quantity = Math.max(1, Math.min(8, Math.round(params.quantity)));
-    const url = `${this.baseUrl}/checkout/process?listing=${encodeURIComponent(params.listingId)}&quantity=${quantity}`;
+    const listingId = params.listingId;
+    if (!/^[A-Za-z0-9_-]{2,50}$/.test(listingId)) {
+      throw new TypeError(
+        "listingId must be 2-50 letters, numbers, hyphens, or underscores"
+      );
+    }
+    if (!Number.isInteger(params.quantity) || params.quantity < 1 || params.quantity > 8) {
+      throw new RangeError("quantity must be an integer from 1 to 8");
+    }
+    const url = `${this.baseUrl}/checkout/process?listing=${encodeURIComponent(listingId)}&quantity=${params.quantity}`;
     return {
       url,
-      listingId: params.listingId,
-      quantity
+      listingId,
+      quantity: params.quantity
     };
   }
+  // ── Machine checkout ─────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async purchaseTickets(params) {
+    const { listingId, quantity, email, idempotencyKey, name } = normalizePurchaseTicketsParams(params);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.paymentFetch(this.paymentEndpoint, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT
+        },
+        body: JSON.stringify({
+          listingId,
+          quantity,
+          email,
+          idempotencyKey,
+          ...name ? { name } : {}
+        }),
+        signal: controller.signal
+      });
+      const body = await response.json().catch(() => ({}));
+      const orderReference = normalizeOrderReference(body.orderReference);
+      const receiptUrl = normalizeReceiptUrl(body.receiptUrl);
+      if (response.status === 402) {
+        const order = normalizePurchaseOrder(
+          body.order,
+          orderReference,
+          "payment_required"
+        );
+        return {
+          success: false,
+          status: "payment_required",
+          idempotencyKey,
+          orderReference,
+          receiptUrl,
+          ...order ? { order } : {},
+          action: "Configure the official mppx payment client, then retry with the same idempotency key."
+        };
+      }
+      if (isPurchaseStatus(body.status)) {
+        if (body.status === "fulfilled" && response.ok && body.success === true && !orderReference) {
+          return {
+            success: false,
+            status: "pending",
+            idempotencyKey,
+            orderReference: null,
+            receiptUrl,
+            error: {
+              code: "PURCHASE_OUTCOME_AMBIGUOUS",
+              message: "The purchase response did not include an order reference."
+            },
+            action: "Retry with the same idempotency key. Do not create a new payment or purchase attempt."
+          };
+        }
+        if (body.status === "fulfilled" && (!response.ok || body.success !== true)) {
+          return rejectedPurchaseResult(
+            idempotencyKey,
+            orderReference,
+            receiptUrl,
+            response.status
+          );
+        }
+        const order = normalizePurchaseOrder(body.order, orderReference, body.status);
+        return {
+          success: body.status === "fulfilled",
+          status: body.status,
+          idempotencyKey,
+          orderReference,
+          receiptUrl,
+          ...order ? { order } : {},
+          ...body.status === "manual_review_required" ? { paid: true } : {},
+          ...safePurchaseOutcomeDetails(body.status)
+        };
+      }
+      return rejectedPurchaseResult(
+        idempotencyKey,
+        orderReference,
+        receiptUrl,
+        response.status
+      );
+    } catch {
+      return {
+        success: false,
+        status: "pending",
+        idempotencyKey,
+        orderReference: null,
+        receiptUrl: null,
+        error: {
+          code: controller.signal.aborted ? "PURCHASE_TIMEOUT" : "PURCHASE_NETWORK_ERROR",
+          message: controller.signal.aborted ? `Purchase status is unknown after ${this.timeoutMs}ms.` : "Purchase status is unknown because the request did not complete."
+        },
+        action: "Retry with the same idempotency key. Do not create a new payment or purchase attempt."
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   // ── Event URL helper ──────────────────────────────────────────────────────
   /**
-   * Build the direct URL to an event page on tixbit.com.
+   * Build the direct URL to an event page on www.tixbit.com.
    */
   eventUrl(slugOrId) {
-    return `${this.baseUrl}/events/${slugOrId}`;
+    if (slugOrId.includes("/")) {
+      return `${this.baseUrl}/events/${slugOrId}`;
+    }
+    const normalized = normalizeExternalEventId(slugOrId);
+    return `${this.baseUrl}/events/${normalized}`;
   }
   // ── Seatmap ───────────────────────────────────────────────────────────────
   /**
@@ -167,33 +503,33 @@ var TixBitClient = class {
    *
    * @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", ...]
    * ```
    */
   async getSeatmap(params) {
-    const data = await this.request(`/api/events/${encodeURIComponent(params.eventId)}/seating-chart`);
+    const normalizedEventId = normalizeExternalEventId(params.eventId);
+    const data = await this.request(`/api/events/${encodeURIComponent(normalizedEventId)}/seating-chart`);
     let zones = [];
     let sectionNames = [];
-    if (data.has_coordinates && data.coordinates) {
+    const coordinatesUrl = data.coordinates_url ?? data.coordinates ?? null;
+    if (data.has_coordinates && coordinatesUrl) {
       try {
-        zones = await this.fetchAndParseCoordinates(data.coordinates);
-        sectionNames = zones.flatMap(
-          (z) => z.sections.map((s) => s.name)
-        );
+        zones = await this.fetchAndParseCoordinates(coordinatesUrl);
+        sectionNames = zones.flatMap((z) => z.sections.map((s) => s.name));
       } catch {
       }
     }
     return {
       success: data.success,
-      event_id: data.event_id,
+      event_id: normalizeExternalEventId(data.event_id),
       venue_id: data.venue_id,
       venue_name: data.venue_name,
       configuration_id: data.configuration_id,
       configuration_name: data.configuration_name,
-      background_image: data.background_image ?? null,
-      coordinates_url: data.coordinates ?? null,
+      background_image: toAbsoluteUrl(this.baseUrl, data.background_image ?? null),
+      coordinates_url: toAbsoluteUrl(this.baseUrl, coordinatesUrl),
       has_coordinates: data.has_coordinates,
       capacity: data.capacity ?? null,
       venue: data.venue_data,
@@ -223,12 +559,22 @@ var TixBitClient = class {
         id: zone.id,
         name: zone.name,
         sections: (zone.sections ?? []).map((section) => {
-          const label = section.labels?.[0];
+          const labels = Array.isArray(section.labels) ? section.labels.filter((label) => label && typeof label.text === "string").map((label) => ({
+            text: label.text,
+            x: typeof label.x === "number" ? label.x : 0,
+            y: typeof label.y === "number" ? label.y : 0,
+            size: typeof label.size === "number" ? label.size : void 0,
+            angle: typeof label.angle === "number" ? label.angle : void 0
+          })) : [];
+          const primaryLabel = labels.find((label) => label.text.toUpperCase() === section.name.toUpperCase()) ?? labels[0];
+          const shapePath = section.shape && typeof section.shape.path === "string" ? section.shape.path : null;
           return {
             id: section.id,
             name: section.name,
-            x: label?.x ?? 0,
-            y: label?.y ?? 0
+            x: primaryLabel?.x ?? 0,
+            y: primaryLabel?.y ?? 0,
+            labels,
+            shape_path: shapePath
           };
         })
       }));
@@ -237,20 +583,148 @@ var TixBitClient = class {
     }
   }
 };
+function normalizeBuyerEmail(value) {
+  const email = value.trim().toLowerCase();
+  const match = email.match(/^([^\s@]{1,64})@([^\s@]{1,253})$/);
+  if (!match || email.length > 254 || match[1].startsWith(".") || match[1].endsWith(".") || match[1].includes("..") || !match[2].includes(".") || match[2].split(".").some(
+    (label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)
+  )) {
+    throw new TypeError("email must be a valid email address");
+  }
+  return email;
+}
+function normalizePurchaseTicketsParams(params) {
+  const listingId = params.listingId;
+  if (!/^[A-Za-z0-9_-]{2,100}$/.test(listingId)) {
+    throw new TypeError(
+      "listingId must be 2-100 letters, numbers, hyphens, or underscores"
+    );
+  }
+  if (!Number.isInteger(params.quantity) || params.quantity < 1 || params.quantity > 8) {
+    throw new RangeError("quantity must be an integer from 1 to 8");
+  }
+  const email = normalizeBuyerEmail(params.email);
+  const idempotencyKey = params.idempotencyKey ?? crypto.randomUUID();
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    idempotencyKey
+  )) {
+    throw new TypeError("idempotencyKey must be an unguessable UUID v4");
+  }
+  const name = params.name?.trim();
+  if (name && name.length > 120) {
+    throw new TypeError("name must be at most 120 characters");
+  }
+  return { listingId, quantity: params.quantity, email, idempotencyKey, name };
+}
+function normalizePurchaseOrder(value, orderReference, status) {
+  if (!value || typeof value !== "object" || !orderReference) return void 0;
+  const order = value;
+  if (order.reference !== orderReference || order.status !== status || typeof order.listingId !== "string" || !/^[A-Za-z0-9_-]{2,100}$/.test(order.listingId) || !Number.isInteger(order.quantity) || order.quantity < 1 || order.quantity > 8 || !isNonNegativeNumber(order.pricePerTicket) || !isNonNegativeNumber(order.subtotal) || !isNonNegativeNumber(order.fees) || !isNonNegativeNumber(order.total) || typeof order.currency !== "string" || !/^[A-Z]{3}$/.test(order.currency)) {
+    return void 0;
+  }
+  return {
+    reference: orderReference,
+    status,
+    listingId: order.listingId,
+    quantity: order.quantity,
+    pricePerTicket: order.pricePerTicket,
+    subtotal: order.subtotal,
+    fees: order.fees,
+    total: order.total,
+    currency: order.currency,
+    ...typeof order.section === "string" && order.section.length <= 120 ? { section: order.section } : {},
+    ...typeof order.row === "string" && order.row.length <= 120 ? { row: order.row } : {}
+  };
+}
+function isNonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function normalizeOrderReference(value) {
+  return typeof value === "string" && /^TBM-[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{10}$/.test(value) ? value : null;
+}
+function normalizeReceiptUrl(value) {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+function safePurchaseOutcomeDetails(status) {
+  switch (status) {
+    case "pending":
+      return {
+        error: {
+          code: "PURCHASE_PENDING",
+          message: "Purchase status is still pending."
+        },
+        action: "Retry with the same idempotency key. Do not create a new payment or purchase attempt."
+      };
+    case "manual_review_required":
+      return {
+        error: {
+          code: "FULFILLMENT_REVIEW_REQUIRED",
+          message: "Payment was received, but fulfillment requires manual review."
+        },
+        action: "Do not submit another payment or purchase. Contact TixBit support with the order reference."
+      };
+    case "payment_failed":
+      return {
+        error: {
+          code: "PAYMENT_VERIFICATION_FAILED",
+          message: "Payment verification failed."
+        },
+        action: "Obtain a new MPP credential for the same idempotency key."
+      };
+    case "rejected":
+      return {
+        error: {
+          code: "PURCHASE_REJECTED",
+          message: "The purchase request was rejected."
+        },
+        action: "Correct the request and retry with the same idempotency key."
+      };
+    default:
+      return {};
+  }
+}
+function rejectedPurchaseResult(idempotencyKey, orderReference, receiptUrl, httpStatus) {
+  return {
+    success: false,
+    status: "rejected",
+    idempotencyKey,
+    orderReference,
+    receiptUrl,
+    error: {
+      code: `HTTP_${httpStatus}`,
+      message: "Purchase request was rejected or returned an invalid response."
+    },
+    action: "Review the request and retry with the same idempotency key if appropriate."
+  };
+}
+function isPurchaseStatus(value) {
+  return value === "fulfilled" || value === "payment_required" || value === "pending" || value === "manual_review_required" || value === "payment_failed" || value === "rejected";
+}
 function normalizeEvent(raw) {
   const e = raw;
+  const rawId = str(e.external_event_id) ?? str(e.externalEventId) ?? str(e.id) ?? "";
+  const externalEventId = normalizeExternalEventId(rawId);
   return {
-    id: str(e.id) ?? str(e.external_event_id) ?? "",
-    external_event_id: str(e.external_event_id) ?? str(e.externalEventId) ?? str(e.id) ?? "",
-    slug: str(e.slug) ?? str(e.external_event_id) ?? "",
+    id: externalEventId,
+    external_event_id: externalEventId,
+    slug: str(e.slug) ?? externalEventId,
     name: str(e.name) ?? str(e.performer) ?? "",
     date: resolveDate(e),
     venue_name: str(e.venue_name) ?? str(e.venueName) ?? null,
     venue_city: str(e.venue_city) ?? str(e.venueCity) ?? null,
     venue_state: str(e.venue_state) ?? str(e.venueState) ?? null,
+    venue_country: str(e.venue_country) ?? str(e.venueCountry) ?? null,
     image_url: str(e.image_url) ?? str(e.imageUrl) ?? null,
+    category_slug: str(e.category_slug) ?? str(e.categorySlug) ?? null,
     category_name: str(e.category_name) ?? str(e.categoryName) ?? null,
     category_event_type: str(e.category_event_type) ?? str(e.categoryEventType) ?? null,
+    metadata: e.metadata && typeof e.metadata === "object" ? e.metadata : null,
     has_listings: Boolean(e.has_listings),
     inventory: normalizeInventory(e.inventory)
   };
@@ -260,10 +734,17 @@ function normalizeInventory(raw) {
     return { total_available: 0, min_price: 0, max_price: 0 };
   }
   const inv = raw;
+  const sources = inv.sources;
   return {
     total_available: num(inv.total_available) ?? 0,
     min_price: num(inv.min_price) ?? 0,
-    max_price: num(inv.max_price) ?? 0
+    max_price: num(inv.max_price) ?? 0,
+    ...sources ? {
+      sources: {
+        local: num(sources.local) ?? 0,
+        marketplace: num(sources.marketplace) ?? 0
+      }
+    } : {}
   };
 }
 function normalizeListing(raw) {
@@ -271,16 +752,30 @@ function normalizeListing(raw) {
   const attrs = outer.attributes ?? outer;
   return {
     id: str(outer.id) ?? str(attrs.id) ?? "",
+    event_id: str(attrs.event_id) ?? null,
     // price_per_ticket is the fee-inclusive per-ticket price (in dollars, not cents)
     price: num(attrs.price_per_ticket) ?? num(attrs.price) ?? 0,
+    total_price: num(attrs.total_price),
+    base_price_per_ticket: num(attrs.base_price_per_ticket),
+    base_total_price: num(attrs.base_total_price),
+    face_value: num(attrs.face_value),
+    fee_amount_per_ticket: num(attrs.fee_amount_per_ticket),
+    fee_amount_total: num(attrs.fee_amount_total),
+    fee_percent: num(attrs.fee_percent),
+    currency: str(attrs.currency) ?? "USD",
     quantity: num(attrs.quantity) ?? num(attrs.available_quantity) ?? 0,
     quantities_list: Array.isArray(attrs.quantities_list) ? attrs.quantities_list : [],
     section: str(attrs.section) ?? null,
     row: str(attrs.row) ?? null,
+    seat_from: str(attrs.seat_from) ?? null,
+    seat_to: str(attrs.seat_to) ?? null,
     seat_numbers: str(attrs.seat_numbers) ?? null,
     listing_hash: str(attrs.listing_hash) ?? "",
     notes: str(attrs.notes) ?? null,
     delivery_method: str(attrs.delivery_method) ?? str(attrs.delivery_type) ?? null,
+    in_hand_date: str(attrs.in_hand_date) ?? null,
+    stock_type: str(attrs.stock_type) ?? null,
+    disclosure_ids: Array.isArray(attrs.disclosure_ids) ? attrs.disclosure_ids.filter((id) => typeof id === "string") : [],
     splits: Array.isArray(attrs.splits) ? attrs.splits : [],
     raw: outer
   };
@@ -303,6 +798,23 @@ function str(v) {
 function num(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : null;
 }
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : null;
+}
+function readNullableString(value) {
+  return value === null ? null : typeof value === "string" ? value : void 0;
+}
+function readEnum(value, choices) {
+  return typeof value === "string" && choices.includes(value) ? value : void 0;
+}
+function readListingMetaNumber(meta, ...keys) {
+  if (!meta) return null;
+  for (const key of keys) {
+    const value = num(meta[key]);
+    if (value !== null) return value;
+  }
+  return null;
+}
 var TixBitApiError = class extends Error {
   constructor(message, status, url) {
     super(message);
@@ -311,7 +823,17 @@ var TixBitApiError = class extends Error {
     this.name = "TixBitApiError";
   }
 };
+var TixBitTimeoutError = class extends Error {
+  constructor(url, timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms: ${url}`);
+    this.url = url;
+    this.timeoutMs = timeoutMs;
+    this.name = "TixBitTimeoutError";
+  }
+};
 export {
   TixBitApiError,
-  TixBitClient
+  TixBitClient,
+  TixBitTimeoutError,
+  assertMppChallenge
 };