tixbit 0.1.0 → 0.1.2

package/dist/cli.js

@@ -3,44 +3,127 @@
 // src/cli.ts
 import { Command } from "commander";
 
+// src/safety.ts
+function usdCents(raw) {
+  if (!raw || !/^\d+(\.\d{1,2})?$/.test(raw)) throw new TypeError("--max-price must be a positive total USD amount with at most two decimals");
+  const [dollars, cents = ""] = raw.split(".");
+  const amount = BigInt(dollars) * 100n + BigInt(cents.padEnd(2, "0"));
+  if (amount <= 0n || amount > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("Invalid --max-price");
+  return Number(amount);
+}
+function positiveInteger(raw, name, max) {
+  const value = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1 || value > max) throw new TypeError(`${name} must be an integer from 1 to ${max}`);
+  return value;
+}
+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/cli.ts
+import { createRequire } from "module";
+
 // 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);
     }
@@ -64,15 +147,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) ───────────────────────────────────────────────
@@ -86,19 +194,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 ──────────────────────────────────────────────────────────────
@@ -107,27 +228,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.
@@ -138,29 +370,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 ───────────────────────────────────────────────────────────────
   /**
@@ -172,33 +523,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,
@@ -228,12 +579,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
           };
         })
       }));
@@ -242,20 +603,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)
   };
@@ -265,10 +754,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) {
@@ -276,16 +772,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
   };
@@ -308,6 +818,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);
@@ -316,13 +843,30 @@ 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";
+  }
+};
 
 // src/cli.ts
-var client = new TixBitClient({
-  baseUrl: process.env.TIXBIT_BASE_URL,
-  apiKey: process.env.TIXBIT_API_KEY
-});
+var client = (() => {
+  try {
+    return new TixBitClient({ baseUrl: process.env.TIXBIT_BASE_URL });
+  } catch (error) {
+    return handleError(error);
+  }
+})();
+var packageJson = createRequire(import.meta.url)("../package.json");
 function output(data, json) {
+  data = redact(data, [process.env.TIXBIT_LINK_TOKEN ?? "", process.env.TIXBIT_ACCESS_TOKEN ?? "", process.env.MPPX_PRIVATE_KEY ?? ""]);
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    data = { success: true, ...data };
+    if (data.success === false) process.exitCode = 2;
+  }
   if (json) {
     process.stdout.write(JSON.stringify(data, null, 2) + "\n");
     return;
@@ -335,6 +879,30 @@ function output(data, json) {
   }
   process.stdout.write(JSON.stringify(data, null, 2) + "\n");
 }
+function outputPurchaseResult(result) {
+  if (result.success && result.order) {
+    process.stdout.write(
+      `
+Purchase complete
+
+  Order: ${result.orderReference}
+  Tickets: ${result.order.quantity}
+  Total: ${result.order.currency} ${result.order.total.toFixed(2)}
+` + (result.receiptUrl ? `  Receipt: ${result.receiptUrl}
+` : "") + "\n"
+    );
+    return;
+  }
+  process.stdout.write(
+    `
+Purchase ${result.status}
+
+  Order: ${result.orderReference ?? "not assigned"}
+  Action: ${result.action ?? "Review the JSON result before retrying."}
+
+`
+  );
+}
 function formatItem(item) {
   if (!item || typeof item !== "object") return String(item);
   const e = item;
@@ -370,26 +938,33 @@ function formatItem(item) {
   return JSON.stringify(item, null, 2);
 }
 function handleError(err) {
-  const msg = err instanceof Error ? err.message : String(err);
-  process.stderr.write(`Error: ${msg}
-`);
+  const msg = err instanceof TypeError || err instanceof RangeError ? err.message : "Request failed. Check input and service availability; do not retry an uncertain write.";
+  output({ success: false, error: { code: "COMMAND_FAILED", message: msg } }, true);
   process.exit(1);
 }
-var program = new Command().name("tixbit").description("Search events, browse listings, and buy tickets on TixBit").version("0.1.0");
-program.command("search [query]").description("Search for events by keyword, city, state, or category").option("--city <city>", "Filter by city").option("--state <state>", "Filter by state (2-letter code)").option("--category <slug>", "Filter by category slug (e.g. nba-basketball)").option("--start-date <date>", "Events on or after this date (ISO)").option("--end-date <date>", "Events on or before this date (ISO)").option("--page <n>", "Page number", "1").option("--size <n>", "Results per page", "10").option("--json", "Output raw JSON (for agents)", false).action(async (query, opts) => {
+var program = new Command().name("tixbit").description("Search events, browse listings, and buy TixBit tickets").version(packageJson.version);
+program.command("search [query]").description("Search for events by keyword, city, state, or category").option("--city <city>", "Filter by city").option("--state <state>", "Filter by state (2-letter code)").option("--category <slug>", "Filter by category slug (e.g. nba-basketball)").option("--league <league>", "Filter by league abbreviation (e.g. NBA)").option("--event-type <type>", "SPORT, CONCERT, THEATER, or ALL").option("--performer-id <id>", "Filter by public performer ID").option("--venue-id <id>", "Filter by public venue ID").option("--parking <mode>", "Parking filter: exclude, only, or include").option("--near-lat <lat>", "Latitude for manual location filtering").option("--near-lng <lng>", "Longitude for manual location filtering").option("--location-mode <mode>", "Location mode: inferred, manual, or none").option("--start-date <date>", "Events on or after this date (ISO)").option("--end-date <date>", "Events on or before this date (ISO)").option("--page <n>", "Page number", "1").option("--size <n>", "Results per page", "10").option("--json", "Output raw JSON (for agents)", true).action(async (query, opts) => {
   try {
     const params = {
       query,
       city: opts.city,
       state: opts.state,
       category: opts.category,
+      league: opts.league,
+      categoryEventType: opts.eventType,
+      performerId: opts.performerId,
+      venueId: opts.venueId,
+      parkingFilter: opts.parking,
+      nearLat: opts.nearLat ? parseFloat(opts.nearLat) : void 0,
+      nearLng: opts.nearLng ? parseFloat(opts.nearLng) : void 0,
+      locationMode: opts.locationMode,
       startDate: opts.startDate,
       endDate: opts.endDate,
       page: parseInt(opts.page, 10),
       size: parseInt(opts.size, 10)
     };
     const result = await client.searchEvents(params);
-    const isJson = opts.json === true || opts.json === "true";
+    const isJson = opts.json;
     if (isJson) {
       output(result, true);
     } else {
@@ -406,7 +981,7 @@ Found ${pagination.total} event(s) \u2014 page ${pagination.page}/${pagination.t
     handleError(err);
   }
 });
-program.command("browse").description("Browse upcoming events near a location").option("--city <city>", "Preferred city").option("--state <state>", "Preferred state (2-letter code)").option("--lat <lat>", "Latitude").option("--lng <lng>", "Longitude").option("--category <type>", "SPORT, CONCERT, THEATER, or ALL", "ALL").option("--size <n>", "Number of results", "10").option("--json", "Output raw JSON (for agents)", false).action(async (opts) => {
+program.command("browse").description("Browse upcoming events near a location").option("--city <city>", "Preferred city").option("--state <state>", "Preferred state (2-letter code)").option("--lat <lat>", "Latitude").option("--lng <lng>", "Longitude").option("--category <type>", "SPORT, CONCERT, THEATER, or ALL", "ALL").option("--category-slug <slug>", "Filter by category slug").option("--query <query>", "Filter by search query").option("--league <league>", "Filter by league abbreviation").option("--date <date>", "Filter by event date (YYYY-MM-DD)").option("--page <n>", "Page number", "1").option("--context <context>", "homepage, events, or category", "homepage").option("--recommendation <kind>", "upcoming or trending", "upcoming").option("--parking <mode>", "Parking filter: exclude, only, or include").option("--location-mode <mode>", "Location mode: inferred, manual, or none").option("--size <n>", "Number of results", "10").option("--json", "Output raw JSON (for agents)", true).action(async (opts) => {
   try {
     const params = {
       city: opts.city,
@@ -414,10 +989,19 @@ program.command("browse").description("Browse upcoming events near a location").
       latitude: opts.lat ? parseFloat(opts.lat) : void 0,
       longitude: opts.lng ? parseFloat(opts.lng) : void 0,
       categoryEventType: opts.category ?? "ALL",
+      category: opts.categorySlug,
+      query: opts.query,
+      league: opts.league,
+      date: opts.date,
+      page: parseInt(opts.page, 10),
+      context: opts.context,
+      recommendation: opts.recommendation,
+      parkingFilter: opts.parking,
+      locationMode: opts.locationMode,
       size: parseInt(opts.size, 10)
     };
     const result = await client.browse(params);
-    const isJson = opts.json === true || opts.json === "true";
+    const isJson = opts.json;
     if (isJson) {
       output(result, true);
     } else {
@@ -433,16 +1017,18 @@ ${result.events.length} upcoming event(s) near ${opts.city ?? "you"}
     handleError(err);
   }
 });
-program.command("listings <eventId>").description("Get available ticket listings for an event").option("--size <n>", "Results per page", "20").option("--page <n>", "Page number", "1").option("--sort <dir>", "Price sort: asc or desc", "asc").option("--json", "Output raw JSON (for agents)", false).action(async (eventId, opts) => {
+program.command("listings <eventId>").description("Get available ticket listings for an event").option("--size <n>", "Results per page", "20").option("--page <n>", "Page number", "1").option("--sort <dir>", "Price sort: asc or desc", "asc").option("--all", "Return all available listings", false).option("--refresh", "Bypass the listings cache", false).option("--json", "Output raw JSON (for agents)", true).action(async (eventId, opts) => {
   try {
     const params = {
       eventId,
       size: parseInt(opts.size, 10),
       page: parseInt(opts.page, 10),
-      orderByDirection: opts.sort
+      orderByDirection: opts.sort,
+      includeAll: opts.all,
+      refresh: opts.refresh
     };
     const result = await client.getListings(params);
-    const isJson = opts.json === true || opts.json === "true";
+    const isJson = opts.json;
     if (isJson) {
       output(result, true);
     } else {
@@ -458,20 +1044,63 @@ ${result.listings.length} listing(s) for event ${eventId}
     handleError(err);
   }
 });
-program.command("checkout <listingId>").description("Get a checkout link to buy tickets for a listing").requiredOption("--quantity <n>", "Number of tickets to buy").option("--json", "Output raw JSON", false).action(async (listingId, opts) => {
+program.command("quote <eventId>").description("Get refreshed live listings; not a reservation or offer").option("--page <n>", "Page number", "1").option("--size <n>", "Page size (max 100)", "100").option("--json", "Output JSON", true).action(async (eventId, opts) => {
   try {
-    const quantity = parseInt(opts.quantity, 10);
-    if (!Number.isFinite(quantity) || quantity < 1) {
-      process.stderr.write("Error: --quantity must be a positive integer\n");
-      process.exit(1);
+    output(await client.quoteListings({ eventId, page: positiveInteger(opts.page, "--page", 1e4), size: positiveInteger(opts.size, "--size", 100) }), true);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("auth").description("Show public browser sign-in and wallet setup; does not create a CLI session").option("--json", "Output JSON", true).action(() => output(client.getAuthorizationInfo(), true));
+program.command("buy <listingId>").description("Quote or confirm Stripe Link checkout (4-12 alphanumeric listing IDs only)").requiredOption("--quantity <n>", "Number of tickets (1-8)").requiredOption("--max-price <total>", "Maximum TOTAL USD charge including fees").option("--email <email>", "Buyer delivery email (or TIXBIT_EMAIL)").option("--confirm", "Approve payment; return browser handoff if wallet authorization is missing", false).option("--json", "Output JSON", true).action(async (listingId, opts) => {
+  try {
+    output(await client.buyTickets({ listingId, quantity: positiveInteger(opts.quantity, "--quantity", 8), maxAmountCents: usdCents(opts.maxPrice), email: opts.email ?? process.env.TIXBIT_EMAIL ?? "", confirm: opts.confirm, sharedPaymentToken: process.env.TIXBIT_LINK_TOKEN }), true);
+  } catch (error) {
+    handleError(error);
+  }
+});
+var sell = program.command("sell").description("Seller browser sign-in or optional authorized user integration");
+sell.command("list").option("--json", "Output JSON", true).action(async () => {
+  try {
+    output(await client.listSellerListings(process.env.TIXBIT_ACCESS_TOKEN ?? ""), true);
+  } catch (error) {
+    handleError(error);
+  }
+});
+sell.command("create").option("--confirm", "Approve listing creation and seller terms", false).option("--json", "Output JSON", true).action(async (opts) => {
+  try {
+    if (!opts.confirm) throw new TypeError("sell create requires --confirm and approved listing JSON on stdin");
+    if (!process.env.TIXBIT_ACCESS_TOKEN) {
+      output(await client.listSellerListings(), true);
+      return;
+    }
+    if (process.stdin.isTTY) throw new TypeError("Provide listing JSON on stdin");
+    let input = "";
+    for await (const chunk of process.stdin) {
+      input += chunk.toString();
+      if (Buffer.byteLength(input) > 65536) throw new TypeError("Listing JSON exceeds 64 KiB");
+    }
+    let body;
+    try {
+      body = JSON.parse(input);
+    } catch {
+      throw new TypeError("Invalid listing JSON on stdin");
     }
-    const isJson = opts.json === true || opts.json === "true";
+    output(await client.createSellerListing(body, process.env.TIXBIT_ACCESS_TOKEN ?? "", opts.confirm), true);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("checkout <listingId>").description("Get a checkout link to buy tickets for a listing").requiredOption("--quantity <n>", "Number of tickets to buy").option("--json", "Output raw JSON", true).action(async (listingId, opts) => {
+  try {
+    const quantity = Number(opts.quantity);
+    if (!Number.isInteger(quantity) || quantity < 1 || quantity > 8) {
+      throw new TypeError("--quantity must be an integer from 1 to 8");
+    }
+    const isJson = opts.json === true;
     let listingInfo;
     try {
-      const result = await client.getListings({ eventId: listingId, size: 1 });
-      if (result.listings.length > 0) {
-        listingInfo = result.listings.find((l) => l.id === listingId);
-      }
+      listingInfo = (await client.getListing(listingId)).listing;
     } catch {
     }
     const link = client.createCheckoutLink({ listingId, quantity });
@@ -507,10 +1136,85 @@ program.command("checkout <listingId>").description("Get a checkout link to buy
     handleError(err);
   }
 });
-program.command("seatmap <eventId>").description("Show the seating chart / section map for an event's venue").option("--section <name>", "Highlight a specific section (case-insensitive)").option("--json", "Output raw JSON (for agents)", false).action(async (eventId, opts) => {
+program.command("purchase <listingId>").description("Buy tickets through MPP machine checkout").requiredOption("--quantity <n>", "Number of tickets to buy").option("--email <email>", "Buyer email for confirmation and delivery").option("--name <name>", "Optional buyer/recipient name").option(
+  "--idempotency-key <uuid>",
+  "Stable UUID v4 to reuse for retries and recovery"
+).option("--account <name>", "mppx account name").requiredOption("--max-price <total>", "Maximum total USD payment").option("--confirm", "Approve this MPP payment", false).option("--json", "Output agent-readable JSON", true).action(async (listingId, opts) => {
+  let publicErrorCode = "INVALID_PURCHASE_REQUEST";
+  let publicErrorMessage = "Invalid purchase request.";
+  try {
+    if (!opts.confirm) throw new TypeError("purchase requires --confirm before loading the wallet");
+    const maxAmountCents = usdCents(opts.maxPrice);
+    if (!opts.idempotencyKey) throw new TypeError("purchase requires --idempotency-key for safe recovery");
+    if (!opts.email?.trim()) {
+      throw new TypeError("--email is required for machine purchases");
+    }
+    const purchase = normalizePurchaseTicketsParams({
+      listingId,
+      quantity: Number(opts.quantity),
+      email: opts.email,
+      name: opts.name,
+      idempotencyKey: opts.idempotencyKey
+    });
+    const paymentEndpoint = process.env.TIXBIT_PAYMENT_URL;
+    new TixBitClient({ paymentEndpoint });
+    publicErrorCode = "MPP_CLIENT_SETUP_FAILED";
+    publicErrorMessage = "MPP payment client setup failed. Check the selected mppx account and local wallet configuration.";
+    const [{ Mppx, tempo }, { resolveAccount }] = await Promise.all([
+      import("mppx/client"),
+      import("mppx/cli")
+    ]);
+    const account = await resolveAccount(opts.account);
+    const payments = Mppx.create({
+      methods: [tempo({ account })],
+      polyfill: false,
+      maxPaymentRetries: 1,
+      onChallenge: async (challenge) => {
+        assertMppChallenge(challenge, maxAmountCents);
+        return void 0;
+      }
+    });
+    const purchaseClient = new TixBitClient({
+      baseUrl: process.env.TIXBIT_BASE_URL,
+      paymentEndpoint,
+      paymentFetch: (input, init) => payments.fetch(input, init)
+    });
+    const result = await purchaseClient.purchaseTickets(purchase);
+    if (opts.json) {
+      output(result, true);
+    } else {
+      outputPurchaseResult(result);
+    }
+    if (!result.success) process.exitCode = 2;
+  } catch (err) {
+    const message = publicErrorCode === "INVALID_PURCHASE_REQUEST" && err instanceof Error ? err.message : publicErrorMessage;
+    if (!opts.json) {
+      process.stderr.write(`Error: ${message}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    output(
+      {
+        success: false,
+        status: "rejected",
+        orderReference: null,
+        receiptUrl: null,
+        error: {
+          code: publicErrorCode,
+          message
+        },
+        action: publicErrorCode === "INVALID_PURCHASE_REQUEST" ? "Correct the request before attempting payment." : "Fix the local mppx account configuration, then retry with the same idempotency key."
+      },
+      true
+    );
+    process.exitCode = 1;
+  }
+});
+program.command("seatmap <eventId>").description("Show the seating chart / section map for an event's venue").option("--section <name>", "Highlight a specific section (case-insensitive)").option("--json", "Output raw JSON (for agents)", true).action(async (eventId, opts) => {
   try {
     const result = await client.getSeatmap({ eventId });
-    const isJson = opts.json === true || opts.json === "true";
+    const isJson = opts.json;
     if (isJson) {
       output(result, true);
       return;
@@ -583,8 +1287,8 @@ program.command("seatmap <eventId>").description("Show the seating chart / secti
     handleError(err);
   }
 });
-program.command("url <slug>").description("Print the TixBit event page URL for a slug or ID").action((slug) => {
-  process.stdout.write(client.eventUrl(slug) + "\n");
+program.command("url <slug>").description("Print the TixBit event page URL for a slug or ID").option("--json", "Output JSON", true).action((slug) => {
+  output({ url: client.eventUrl(slug) }, true);
 });
 function categorizeSections(sections) {
   const groups = {};
@@ -643,4 +1347,22 @@ function describePosition(section, allSections) {
   }
   return [vertical, horizontal].filter((p) => p !== "center").join(", ");
 }
-program.parse();
+function configureCommands(command) {
+  command.exitOverride();
+  command.configureOutput({
+    writeOut: (text) => output({ help: text }, true),
+    writeErr: () => {
+    }
+  });
+  for (const child of command.commands) configureCommands(child);
+}
+configureCommands(program);
+try {
+  await program.parseAsync();
+} catch (error) {
+  const code = error.code;
+  if (code !== "commander.helpDisplayed" && code !== "commander.version") {
+    output({ success: false, error: { code: "INVALID_COMMAND", message: "Invalid command or options. Use --help." } }, true);
+    process.exitCode = 1;
+  }
+}