tixbit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+/** Configuration for the TixBit client. */
+interface TixBitConfig {
+    /**
+     * Base URL of the TixBit web app.
+     * @default "https://tixbit.com"
+     */
+    baseUrl?: string;
+    /**
+     * Optional request timeout in milliseconds.
+     * @default 15000
+     */
+    timeoutMs?: number;
+    /**
+     * Optional API key for authenticated endpoints (future use).
+     */
+    apiKey?: string;
+}
+interface SearchEventsParams {
+    /** Free-text search query (e.g. "Hawks", "Taylor Swift"). */
+    query?: string;
+    /** City name (e.g. "Atlanta"). */
+    city?: string;
+    /** Two-letter US state code (e.g. "GA"). */
+    state?: string;
+    /** Category slug (e.g. "nba-basketball", "mlb-baseball"). */
+    category?: string;
+    /** ISO date string — only events on or after this date. */
+    startDate?: string;
+    /** ISO date string — only events on or before this date. */
+    endDate?: string;
+    /** Page number (1-indexed). @default 1 */
+    page?: number;
+    /** Page size. @default 25 */
+    size?: number;
+}
+interface TixBitEvent {
+    id: string;
+    external_event_id: string;
+    slug: string;
+    name: string;
+    date: string;
+    venue_name: string | null;
+    venue_city: string | null;
+    venue_state: string | null;
+    image_url: string | null;
+    category_name: string | null;
+    category_event_type: string | null;
+    has_listings: boolean;
+    inventory: {
+        total_available: number;
+        min_price: number;
+        max_price: number;
+    };
+}
+interface SearchEventsResult {
+    events: TixBitEvent[];
+    pagination: {
+        page: number;
+        size: number;
+        total: number;
+        totalPages: number;
+        hasNext: boolean;
+        hasPrev: boolean;
+    };
+}
+interface GetListingsParams {
+    /** External event ID (from search results). */
+    eventId: string;
+    /** Page size. @default 50 */
+    size?: number;
+    /** Page number. @default 1 */
+    page?: number;
+    /** Sort direction for price. @default "asc" */
+    orderByDirection?: "asc" | "desc";
+}
+interface TixBitListing {
+    id: string;
+    price: number;
+    quantity: number;
+    quantities_list: number[];
+    section: string | null;
+    row: string | null;
+    seat_numbers: string | null;
+    listing_hash: string;
+    notes: string | null;
+    delivery_method: string | null;
+    splits: number[];
+    raw: Record<string, unknown>;
+}
+interface GetListingsResult {
+    listings: TixBitListing[];
+    meta: {
+        total: number;
+        page: number;
+        size: number;
+        cacheSource?: string;
+    };
+}
+interface CheckoutParams {
+    /** Listing ID to purchase (from getListings results). */
+    listingId: string;
+    /** Number of tickets to buy. */
+    quantity: number;
+}
+/** A checkout link that the user opens in a browser to complete purchase. */
+interface CheckoutLink {
+    /** Full URL to the checkout page on tixbit.com. */
+    url: string;
+    /** Listing ID being purchased. */
+    listingId: string;
+    /** Ticket quantity. */
+    quantity: number;
+}
+interface BrowseEventsParams {
+    /** User latitude for location-aware results. */
+    latitude?: number;
+    /** User longitude for location-aware results. */
+    longitude?: number;
+    /** Preferred city. */
+    city?: string;
+    /** Preferred state. */
+    state?: string;
+    /** Number of results. @default 18 */
+    size?: number;
+    /** Category event type: SPORT, CONCERT, THEATER. */
+    categoryEventType?: "SPORT" | "CONCERT" | "THEATER" | "ALL";
+}
+interface BrowseEventsResult {
+    events: TixBitEvent[];
+    total: number;
+}
+interface GetSeatmapParams {
+    /** External event ID (from search results). */
+    eventId: string;
+}
+/** A single section in the venue's seating chart. */
+interface SeatmapSection {
+    /** Section ID (e.g. "80841"). */
+    id: string;
+    /** 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.
+     */
+    x: number;
+    y: number;
+}
+/** A zone grouping sections (e.g. "Section", "Floor", "Suite"). */
+interface SeatmapZone {
+    id: string;
+    name: string;
+    sections: SeatmapSection[];
+}
+/** Venue metadata returned with the seatmap. */
+interface SeatmapVenue {
+    name: string;
+    address?: string;
+    city: string;
+    region: string;
+    country: string;
+    time_zone: string;
+}
+/** Result from the seating chart API. */
+interface SeatmapResult {
+    success: boolean;
+    event_id: string;
+    venue_id: string;
+    venue_name: string;
+    configuration_id: string;
+    configuration_name: string;
+    /** URL to the background SVG image of the venue map. */
+    background_image: string | null;
+    /** URL to the coordinates JSON (section polygons). */
+    coordinates_url: string | null;
+    has_coordinates: boolean;
+    capacity: number | null;
+    venue: SeatmapVenue;
+    /** Parsed section data from coordinates (when available). */
+    zones: SeatmapZone[];
+    /** All section names for quick reference. */
+    section_names: string[];
+}
+
+declare class TixBitClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly apiKey;
+    constructor(config?: TixBitConfig);
+    private request;
+    private qs;
+    /**
+     * Search for events by keyword, city, state, category, or date range.
+     *
+     * @example
+     * ```ts
+     * const results = await client.searchEvents({ query: "Hawks", state: "GA" });
+     * ```
+     */
+    searchEvents(params?: SearchEventsParams): Promise<SearchEventsResult>;
+    /**
+     * Browse upcoming events near a location (homepage-style).
+     *
+     * @example
+     * ```ts
+     * const nearby = await client.browse({ city: "Atlanta", state: "GA" });
+     * ```
+     */
+    browse(params?: BrowseEventsParams): Promise<BrowseEventsResult>;
+    /**
+     * Get available ticket listings for an event.
+     *
+     * @example
+     * ```ts
+     * const listings = await client.getListings({ eventId: "abc123" });
+     * ```
+     */
+    getListings(params: GetListingsParams): Promise<GetListingsResult>;
+    /**
+     * Create a checkout link for a listing.
+     *
+     * Returns a URL to the TixBit checkout page where the user can
+     * sign in and complete their purchase (card, crypto, etc.).
+     *
+     * @example
+     * ```ts
+     * const link = client.createCheckoutLink({
+     *   listingId: "P2JO5OBX",
+     *   quantity: 2,
+     * });
+     *
+     * console.log(link.url);
+     * // → "https://tixbit.com/checkout/process?listing=P2JO5OBX&quantity=2"
+     * ```
+     */
+    createCheckoutLink(params: CheckoutParams): CheckoutLink;
+    /**
+     * Build the direct URL to an event page on tixbit.com.
+     */
+    eventUrl(slugOrId: string): string;
+    /**
+     * Get the seating chart for an event's venue.
+     *
+     * Returns section-level data including section names, positions, and
+     * the venue background image URL. Use this to help users understand
+     * where their tickets are located.
+     *
+     * @example
+     * ```ts
+     * const seatmap = await client.getSeatmap({ eventId: "4BKJMDZ" });
+     * console.log(seatmap.venue_name); // "State Farm Arena"
+     * console.log(seatmap.section_names); // ["101", "102", ...]
+     * ```
+     */
+    getSeatmap(params: GetSeatmapParams): Promise<SeatmapResult>;
+    /**
+     * Fetch the coordinates JSON and parse it into zones/sections.
+     */
+    private fetchAndParseCoordinates;
+}
+declare class TixBitApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(message: string, status: number, url: string);
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,317 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://tixbit.com";
+var DEFAULT_TIMEOUT_MS = 15e3;
+var USER_AGENT = "@tixbit/sdk";
+var TixBitClient = class {
+  baseUrl;
+  timeoutMs;
+  apiKey;
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.apiKey = config.apiKey;
+  }
+  // ── HTTP helpers ──────────────────────────────────────────────────────────
+  async request(path, init) {
+    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}` } : {}
+    };
+    try {
+      const res = await fetch(url, {
+        ...init,
+        headers: { ...headers, ...init?.headers },
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new TixBitApiError(
+          `${res.status} ${res.statusText}: ${text.slice(0, 300)}`,
+          res.status,
+          url
+        );
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  qs(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null && v !== "").map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    return entries.length ? `?${entries.join("&")}` : "";
+  }
+  // ── Search Events ─────────────────────────────────────────────────────────
+  /**
+   * Search for events by keyword, city, state, category, or date range.
+   *
+   * @example
+   * ```ts
+   * const results = await client.searchEvents({ query: "Hawks", state: "GA" });
+   * ```
+   */
+  async searchEvents(params = {}) {
+    const query = this.qs({
+      q: params.query,
+      city: params.city,
+      state: params.state,
+      category: params.category,
+      startDate: params.startDate,
+      endDate: params.endDate,
+      page: params.page,
+      size: params.size ?? 25
+    });
+    const data = await this.request(`/api/events/search${query}`);
+    return {
+      events: (data.events ?? []).map(normalizeEvent),
+      pagination: data.pagination
+    };
+  }
+  // ── Browse (Location-Aware) ───────────────────────────────────────────────
+  /**
+   * Browse upcoming events near a location (homepage-style).
+   *
+   * @example
+   * ```ts
+   * const nearby = await client.browse({ city: "Atlanta", state: "GA" });
+   * ```
+   */
+  async browse(params = {}) {
+    const query = this.qs({
+      size: params.size ?? 18,
+      context: "homepage",
+      recommendation: "upcoming",
+      nearLat: params.latitude,
+      nearLng: params.longitude,
+      preferCity: params.city,
+      preferState: params.state,
+      categoryEventType: params.categoryEventType
+    });
+    const data = await this.request(`/api/events${query}`);
+    return {
+      events: (data.events ?? []).map(normalizeEvent),
+      total: data.total
+    };
+  }
+  // ── Listings ──────────────────────────────────────────────────────────────
+  /**
+   * Get available ticket listings for an event.
+   *
+   * @example
+   * ```ts
+   * const listings = await client.getListings({ eventId: "abc123" });
+   * ```
+   */
+  async getListings(params) {
+    const query = this.qs({
+      size: params.size ?? 50,
+      page: params.page ?? 1,
+      order_by_direction: params.orderByDirection ?? "asc"
+    });
+    const data = await this.request(`/api/events/${encodeURIComponent(params.eventId)}/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,
+        cacheSource: data.meta?.cacheSource
+      }
+    };
+  }
+  // ── Checkout Link ──────────────────────────────────────────────────────────
+  /**
+   * Create a checkout link for a listing.
+   *
+   * Returns a URL to the TixBit checkout page where the user can
+   * sign in and complete their purchase (card, crypto, etc.).
+   *
+   * @example
+   * ```ts
+   * const link = client.createCheckoutLink({
+   *   listingId: "P2JO5OBX",
+   *   quantity: 2,
+   * });
+   *
+   * console.log(link.url);
+   * // → "https://tixbit.com/checkout/process?listing=P2JO5OBX&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}`;
+    return {
+      url,
+      listingId: params.listingId,
+      quantity
+    };
+  }
+  // ── Event URL helper ──────────────────────────────────────────────────────
+  /**
+   * Build the direct URL to an event page on tixbit.com.
+   */
+  eventUrl(slugOrId) {
+    return `${this.baseUrl}/events/${slugOrId}`;
+  }
+  // ── Seatmap ───────────────────────────────────────────────────────────────
+  /**
+   * Get the seating chart for an event's venue.
+   *
+   * Returns section-level data including section names, positions, and
+   * the venue background image URL. Use this to help users understand
+   * where their tickets are located.
+   *
+   * @example
+   * ```ts
+   * const seatmap = await client.getSeatmap({ eventId: "4BKJMDZ" });
+   * 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`);
+    let zones = [];
+    let sectionNames = [];
+    if (data.has_coordinates && data.coordinates) {
+      try {
+        zones = await this.fetchAndParseCoordinates(data.coordinates);
+        sectionNames = zones.flatMap(
+          (z) => z.sections.map((s) => s.name)
+        );
+      } catch {
+      }
+    }
+    return {
+      success: data.success,
+      event_id: 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,
+      has_coordinates: data.has_coordinates,
+      capacity: data.capacity ?? null,
+      venue: data.venue_data,
+      zones,
+      section_names: sectionNames
+    };
+  }
+  /**
+   * Fetch the coordinates JSON and parse it into zones/sections.
+   */
+  async fetchAndParseCoordinates(coordinatesUrl) {
+    const fullUrl = coordinatesUrl.startsWith("http") ? coordinatesUrl : `${this.baseUrl}${coordinatesUrl}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(fullUrl, {
+        headers: {
+          Accept: "application/json",
+          "User-Agent": USER_AGENT
+        },
+        signal: controller.signal
+      });
+      if (!res.ok) return [];
+      const coords = await res.json();
+      if (!coords.zones) return [];
+      return coords.zones.map((zone) => ({
+        id: zone.id,
+        name: zone.name,
+        sections: (zone.sections ?? []).map((section) => {
+          const label = section.labels?.[0];
+          return {
+            id: section.id,
+            name: section.name,
+            x: label?.x ?? 0,
+            y: label?.y ?? 0
+          };
+        })
+      }));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function normalizeEvent(raw) {
+  const e = raw;
+  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) ?? "",
+    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,
+    image_url: str(e.image_url) ?? str(e.imageUrl) ?? null,
+    category_name: str(e.category_name) ?? str(e.categoryName) ?? null,
+    category_event_type: str(e.category_event_type) ?? str(e.categoryEventType) ?? null,
+    has_listings: Boolean(e.has_listings),
+    inventory: normalizeInventory(e.inventory)
+  };
+}
+function normalizeInventory(raw) {
+  if (!raw || typeof raw !== "object") {
+    return { total_available: 0, min_price: 0, max_price: 0 };
+  }
+  const inv = raw;
+  return {
+    total_available: num(inv.total_available) ?? 0,
+    min_price: num(inv.min_price) ?? 0,
+    max_price: num(inv.max_price) ?? 0
+  };
+}
+function normalizeListing(raw) {
+  const outer = raw;
+  const attrs = outer.attributes ?? outer;
+  return {
+    id: str(outer.id) ?? str(attrs.id) ?? "",
+    // price_per_ticket is the fee-inclusive per-ticket price (in dollars, not cents)
+    price: num(attrs.price_per_ticket) ?? num(attrs.price) ?? 0,
+    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_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,
+    splits: Array.isArray(attrs.splits) ? attrs.splits : [],
+    raw: outer
+  };
+}
+function resolveDate(e) {
+  if (typeof e.date === "string") return e.date;
+  if (typeof e.date === "number") return new Date(e.date).toISOString();
+  if (e.date && typeof e.date === "object") {
+    const d = e.date;
+    if (d.month && d.day && d.year) {
+      return `${d.month} ${d.day}, ${d.year}`;
+    }
+  }
+  if (typeof e.date_ms === "number") return new Date(e.date_ms).toISOString();
+  return "";
+}
+function str(v) {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+var TixBitApiError = class extends Error {
+  constructor(message, status, url) {
+    super(message);
+    this.status = status;
+    this.url = url;
+    this.name = "TixBitApiError";
+  }
+};
+export {
+  TixBitApiError,
+  TixBitClient
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "tixbit",
+  "version": "0.1.0",
+  "description": "Search events, view seatmaps, browse listings, and buy tickets on TixBit",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tixbit": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "tixbit",
+    "tickets",
+    "events",
+    "seatmap",
+    "seating-chart",
+    "cli",
+    "sdk",
+    "concerts",
+    "sports",
+    "nba",
+    "mlb",
+    "nfl"
+  ],
+  "homepage": "https://tixbit.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tixbit/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tixbit/sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}