tixbit 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,25 @@
 # tixbit
 
-Search events, view seatmaps, browse listings, and buy tickets on [TixBit](https://tixbit.com) — from the terminal, your code, or an AI agent.
+Search events, view seatmaps, browse listings, get browser checkout links, and purchase through MPP on [TixBit](https://www.tixbit.com) — from the terminal, your code, or an AI agent.
 
-No API key required.
+No command requires a TixBit developer API key. Public discovery and links need no credentials. Purchases require user-approved payment; selling requires user sign-in and seller access.
+
+### User authorization, not API keys
+
+Run `tixbit auth` for public browser sign-in and wallet setup links. This command does not create a CLI session. Open the returned TixBit sign-in page, then complete checkout or selling in your browser. Do not copy browser cookies or bearer tokens.
+
+The public service currently has no supported browser-to-CLI seller session exchange. Website sign-in therefore does not unlock seller API calls from this CLI. The `buy` web checkout route does not issue Link spend requests; it expects a token from an authorized integration.
+
+For wallet setup, use [official Link onboarding](https://link.com/agents): install `@stripe/link-cli` and run `link-cli onboard`. This requires your Link account, not a developer API key. A Link spend request is a separate approval for a selected purchase. See [Link agent checkout](#link-agent-checkout).
+
+| Operation | Required user authorization |
+|---|---|
+| Search, browse, listings, quote, seatmap, URL, checkout link | None |
+| `buy` quote | Buyer email via `--email` or optional `TIXBIT_EMAIL` |
+| Browser purchase | Sign in and approve the final payment in the browser |
+| MPP `purchase` | Your mppx wallet, buyer email, confirmation, total cap, recovery UUID |
+| Automatic Link payment | User-approved payment credential from an authorized integration |
+| Seller API | Signed-in user credential and seller access |
 
 ## Install
 
@@ -26,7 +43,7 @@ npm install tixbit
 tixbit search "Taylor Swift"
 tixbit search "Hawks" --state GA --size 5
 tixbit search --city "New York" --category nba-basketball
-tixbit search --start-date 2025-06-01 --end-date 2025-06-30
+tixbit search --league NBA --parking exclude
 ```
 
 ### Browse local events
@@ -39,80 +56,148 @@ tixbit browse --lat 33.749 --lng -84.388 --category CONCERT
 ### Get ticket listings
 
 ```sh
-tixbit listings 4BKJMDZ
-tixbit listings 4BKJMDZ --size 5 --sort asc
+tixbit listings <event-id>
+tixbit listings <event-id> --size 5 --sort asc
 ```
 
 ### Buy tickets
 
 ```sh
 # Get a checkout link for a listing
-tixbit checkout P2JO5OBX --quantity 2
+tixbit checkout <listing-id> --quantity 2
+
+# Or pay from an agent/terminal with MPP
+npx mppx account create
+tixbit purchase <listing-id> \
+  --quantity 2 \
+  --email buyer@example.com \
+  --confirm --max-price 300.00 \
+  --idempotency-key 11111111-1111-4111-8111-111111111111 \
+  --json
 ```
 
+`checkout` remains link-only: it creates a `https://www.tixbit.com/checkout/process` URL for browser completion. `purchase` is the separate public MPP machine surface. It uses the official `mppx` client to answer the server's HTTP 402 challenge and currently selects the Tempo one-time charge rail configured by the server.
+
+### Stripe Link machine checkout
+
+Sign in to Link once, then start a purchase with a total price limit:
+
+TixBit 0.2.0 needs Node.js 22 or later. The included Link CLI uses your local Link sign-in; TixBit does not ask for a developer API key.
+
+```sh
+npx @stripe/link-cli auth login
+tixbit link start <listing-id> --quantity 1 --email buyer@example.com --max-price 25.00
+```
+
+`link start` returns the exact server total and an `approvalUrl`. Open that URL and approve the spend request in Link. Then use the returned order reference:
+
+```sh
+tixbit link complete <order-reference>
 ```
-🎟  Checkout Link
 
-   Listing: P2JO5OBX
-   Section: 214 Row E
-   Price: $23.80 × 2 = $47.60
-   Quantity: 2
+The second command checks approval, sends one Stripe MPP credential, and reports whether the ticket was issued. If approval is still pending, it returns the same URL without sending payment. If the payment result is uncertain, use `link complete` with the same order reference. The CLI stores the purchase key in a private file under `~/.local/state/tixbit/link` (or `XDG_STATE_HOME`) and never prints or saves the Link payment token. Keep that file until the order is settled. Each command returns JSON; `approval_required` and payment failures use exit code 2.
+
+`--email` is always required and is never inferred from git or local account state. If a request times out or returns `pending` or `manual_review_required`, reuse the same idempotency key and follow the returned `action`; do not start another payment.
+
+### Link agent checkout
 
-   https://tixbit.com/checkout/process?listing=P2JO5OBX&quantity=2
+Stripe's [Link CLI](https://github.com/stripe/link-cli) provides the spend-request and MPP payment tools. An agent host that supports local MCP servers can add it alongside TixBit:
 
-   Open the link above in your browser to complete checkout.
+```json
+{
+  "mcpServers": {
+    "link": {
+      "command": "npx",
+      "args": ["@stripe/link-cli", "--mcp"]
+    }
+  }
+}
 ```
 
-### View venue seatmap
+The buyer signs in with `link-cli auth login` and approves each spend request in Link. For a TixBit purchase, first POST the selected listing, quantity, buyer email, and a new UUID v4 idempotency key to `https://mcp.tixbit.com/api/purchase`. Inspect the `402` order total and Stripe challenge. Create a `shared_payment_token` spend request for that challenge's `network_id` and total in cents. After Link reports approval, use `link-cli mpp pay` with the same URL and identical POST body, including the original idempotency key. Link CLI handles the one-time credential; do not print or copy an SPT. Treat `pending` or `manual_review_required` as non-final and reconcile by the original idempotency key.
+
+This flow requires the TixBit MCP server to advertise Stripe in its `402` challenge. The published `tixbit purchase` command still selects Tempo. The `tixbit buy --confirm` command still uses the separate web checkout integration and cannot create a Link spend request. An agent host must expose Link's spend-request and MPP tools to its agent; this package cannot add tools to a third-party host such as Muse.
+
+### Live inventory, Stripe Link, and seller commands
+
+These commands are in `tixbit@0.1.2`.
 
 ```sh
-tixbit seatmap 4BKJMDZ
-tixbit seatmap 4BKJMDZ --section 214
+# Refreshed listings, not a reservation. Fails if live freshness is unavailable.
+tixbit quote <eventId> --page 1 --size 100
+
+# Buyer email is explicit; no API key or payment credential is needed.
+tixbit buy <listingId> --quantity 2 --max-price 300.00 --email buyer@example.com
+
+# Without payment authorization, returns a browser checkout handoff.
+# No payment is sent; review and approve the final total in the browser.
+tixbit buy <listingId> --quantity 2 --max-price 300.00 --email buyer@example.com --confirm
+
+# Without a signed-in integration, returns browser sign-in and seller links.
+tixbit sell list
 ```
 
+A handoff returns `success: false`, `status: "authorization_required"`, and exit code 2. It is not a completed purchase, listing, or CLI login. The CLI cap is not transferred to browser checkout; review and approve the final total there.
+
+### Optional advanced integrations
+
+Authorized applications may supply a user-approved Link payment credential or a signed-in seller's Privy access token. Optional `TIXBIT_LINK_TOKEN` and `TIXBIT_ACCESS_TOKEN` injection is for these integrations only, not normal onboarding. Neither is a TixBit API key, and no developer or infrastructure key can replace user authorization. Never pass credentials in arguments, log them, or extract them from browser storage. Seller integrations use `tixbit sell create --confirm < listing.json`.
+
+`--max-price` is the total USD charge ceiling including ticket fees, not a per-ticket price or a bid. Link checkout sends `maxAmountCents` in both POST requests and refuses payment unless the quote advertises `maxAmountCentsSupported: true`. Payment requires a public checkout deployment that advertises and enforces the total cap. The backend rechecks its actual charge before payment. Link currently accepts only 4-12 alphanumeric listing IDs. Native `sl_UUID` listings are not supported by this payment backend; use link-only `checkout` for browser completion instead.
+
+No Link payment request is automatically retried. An uncertain Link response returns `status: "unknown"` and requires reconciliation with TixBit support and Stripe Link before another attempt. A successful payment response is not a guarantee of completed ticket delivery. No negotiation API or command is provided.
+
+Seller JSON uses the existing web API schema. Example after seller approval:
+
+```json
+{"externalEventId":"AbCd12","section":"GA","quantity":2,"generalAdmission":true,"priceCents":10000,"termsAccepted":true}
 ```
-🏟  State Farm Arena
-   NBA - Atlanta Hawks
-   Capacity: 18,118
 
-  ── ⬇ Lower Level (100s) ──
-     101  102  103  ...  122
+`priceCents` is the seller's per-ticket asking price, unlike the buyer's total cap. Optional fields include `row`, `seatNumbers`, `faceValueCents`, `assetPaths`, `disclosures`, and `notes`; the server validates them and enforces seller access. Creation requires both `--confirm` and `termsAccepted: true`. Submission is not a claim that the listing is live. After uncertain creation, inspect `sell list` before retrying.
 
-  ── ⬆ Upper Level (200s) ──
-     201  202  203  ▸214◂  ...  227S
+MPP `purchase` retains the official mppx path but now requires `--confirm`, `--max-price`, and an explicit `--idempotency-key` before wallet loading. Its challenge hook checks the pathUSD atomic amount before any credential is created, rejects unknown assets/recurring intents, and permits only one payment challenge. The cap covers the ticket charge; network fees, if any, are managed separately by the wallet. SDK callers who inject their own `paymentFetch` own its authorization policy: use `assertMppChallenge` in `onChallenge` as shown below and get user approval before calling `purchaseTickets`. Do not register credential-producing event handlers that bypass this hook.
 
-  📍 Section 214: right side
+### View venue seatmap
 
-  Total sections: 142
+```sh
+tixbit seatmap <event-id>
+tixbit seatmap <event-id> --section <section-name>
 ```
 
 ### JSON output (for agents / scripting)
 
-Every command supports `--json` for machine-readable output:
+Every command now emits JSON by default, including help, version, parser errors, and request errors. `--json` remains accepted. Successful discovery results keep their existing fields and add `success: true`. Exit codes: 0 for success, 1 for invalid input/request failure, 2 for a non-final or unsuccessful result.
 
-> Event IDs are normalized to public external IDs (e.g. `36PB9ZN`) — internal provider prefixes are stripped from SDK/CLI results.
+> Event and listing IDs are case-sensitive. Copy the full ID from discovery. The SDK no longer changes case, strips prefixes, or repairs whitespace in purchase IDs.
 
 ```sh
 tixbit search "concert" --state NY --json
-tixbit listings 4BKJMDZ --json
-tixbit seatmap 4BKJMDZ --json
-tixbit checkout P2JO5OBX --quantity 2 --json
+tixbit listings <event-id> --json
+tixbit seatmap <event-id> --json
+tixbit checkout <listing-id> --quantity 2 --json
+tixbit purchase <listing-id> --quantity 2 --email buyer@example.com --confirm --max-price 300.00 --idempotency-key <uuid-v4> --json
 ```
 
 ### All commands
 
 | Command | Description |
 |---|---|
+| `auth` | Public browser sign-in and wallet setup; no CLI session is created |
 | `search [query]` | Search events by keyword, city, state, category, or date |
 | `browse` | Browse upcoming events near a location |
 | `listings <eventId>` | Get available ticket listings for an event |
 | `checkout <listingId>` | Get a checkout link to buy tickets |
+| `purchase <listingId>` | Buy a selected listing through MPP with explicit confirmation and total cap |
+| `link start <listingId>` / `link complete <orderReference>` | Approve and pay for a ticket with Stripe Link |
+| `quote <eventId>` | Refresh live listings, with freshness metadata |
+| `buy <listingId>` | Quote or confirm a capped Stripe Link purchase |
+| `sell list` / `sell create` | Use the existing gated seller API |
 | `seatmap <eventId>` | Show the venue seating chart with all sections |
 | `url <slug>` | Print the TixBit event page URL |
 
 ## SDK
 
-Use the client programmatically in any Node.js 20+ project:
+Use the client programmatically in a supported Node.js project:
 
 ```ts
 import { TixBitClient } from "tixbit";
@@ -126,22 +211,34 @@ const { events } = await tixbit.searchEvents({
   size: 5,
 });
 
+const event = events[0];
+if (!event) throw new Error("No matching events");
+
+// Get public event detail
+const detail = await tixbit.getEvent(event.external_event_id);
+
 // Get listings
 const { listings } = await tixbit.getListings({
-  eventId: events[0].external_event_id,
+  eventId: event.external_event_id,
 });
 
+const listing = listings[0];
+if (!listing) throw new Error("No available listings");
+
+// Get current public details for one listing
+const listingDetail = await tixbit.getListing(listing.id);
+
 // Create a checkout link
 const checkout = tixbit.createCheckoutLink({
-  listingId: listings[0].id,
+  listingId: listingDetail.listing.id,
   quantity: 2,
 });
 console.log(checkout.url);
-// → "https://tixbit.com/checkout/process?listing=P2JO5OBX&quantity=2"
+// Open this TixBit URL in a browser to complete checkout.
 
 // View seatmap
 const seatmap = await tixbit.getSeatmap({
-  eventId: events[0].external_event_id,
+  eventId: event.external_event_id,
 });
 console.log(seatmap.venue_name);    // "State Farm Arena"
 console.log(seatmap.section_names); // ["101", "102", ...]
@@ -153,8 +250,42 @@ const nearby = await tixbit.browse({
 });
 
 // Event URL
-const url = tixbit.eventUrl("4BKJMDZ");
-// → "https://tixbit.com/events/4BKJMDZ"
+const url = tixbit.eventUrl(event.external_event_id);
+```
+
+### SDK machine purchase
+
+Wire the official `mppx` client into `paymentFetch`. The private payment key stays in the mppx account/keychain or `MPPX_PRIVATE_KEY`; it is never passed to TixBit SDK configuration.
+
+```ts
+import { TixBitClient, assertMppChallenge } from "tixbit";
+import { Mppx, tempo } from "mppx/client";
+import { resolveAccount } from "mppx/cli";
+
+const account = await resolveAccount();
+const payments = Mppx.create({
+  methods: [tempo({ account })],
+  polyfill: false,
+  maxPaymentRetries: 1,
+  onChallenge: async (challenge) => {
+    assertMppChallenge(challenge, 30000); // approved TOTAL, in USD cents
+    return undefined;
+  },
+});
+const tixbit = new TixBitClient({
+  paymentFetch: (input, init) => payments.fetch(input, init),
+});
+
+const result = await tixbit.purchaseTickets({
+  listingId: "LISTING123",
+  quantity: 2,
+  email: "buyer@example.com",
+  idempotencyKey: "11111111-1111-4111-8111-111111111111",
+});
+
+console.log(JSON.stringify(result, null, 2));
+// fulfilled: { status, orderReference, receiptUrl, order, ... }
+// recovery:  { status: "pending" | "manual_review_required", action, ... }
 ```
 
 ## API Reference
@@ -163,9 +294,12 @@ const url = tixbit.eventUrl("4BKJMDZ");
 
 | Option | Type | Default |
 |---|---|---|
-| `baseUrl` | `string` | `https://tixbit.com` |
+| `baseUrl` | `string` | `https://www.tixbit.com` |
 | `timeoutMs` | `number` | `15000` |
-| `apiKey` | `string` | — |
+| `paymentEndpoint` | `string` | `https://mcp.tixbit.com/api/purchase`; canonical endpoint or loopback QA only |
+| `paymentFetch` | `typeof fetch` | Fetch used for MPP; supply the official `mppx.fetch` |
+
+All public TixBit SDK operations require no TixBit API key. MPP payment credentials are handled by the configured payment client and are sent only in the standard payment authorization header.
 
 ### `searchEvents(params?)`
 
@@ -175,10 +309,23 @@ const url = tixbit.eventUrl("4BKJMDZ");
 | `city` | `string` | City name |
 | `state` | `string` | 2-letter state code |
 | `category` | `string` | Category slug (e.g. `nba-basketball`) |
+| `league` | `string` | League abbreviation |
+| `categoryEventType` | `string` | `SPORT`, `CONCERT`, `THEATER`, or `ALL` |
+| `performerId` | `string` | Public performer ID |
+| `venueId` | `string` | Public venue ID |
+| `parkingFilter` | `string` | `exclude`, `only`, or `include` |
+| `nearLat` / `nearLng` | `number` | Coordinates for manual location filtering |
+| `locationMode` | `string` | `inferred`, `manual`, or `none` |
 | `startDate` | `string` | ISO date — events on/after |
 | `endDate` | `string` | ISO date — events on/before |
 | `page` | `number` | Page number (default: 1) |
-| `size` | `number` | Results per page (default: 25) |
+| `size` | `number` | Results per page, max 200 (default: 25) |
+
+The result includes normalized events plus `page`, `size`, nullable `total`/`totalPages`, `hasNext`, `hasPrev`, and `totalExact` pagination metadata.
+
+### `getEvent(eventId)`
+
+Returns the sanitized public event detail for an external event ID or event slug.
 
 ### `browse(params?)`
 
@@ -189,20 +336,37 @@ const url = tixbit.eventUrl("4BKJMDZ");
 | `latitude` | `number` | Latitude |
 | `longitude` | `number` | Longitude |
 | `categoryEventType` | `string` | `SPORT`, `CONCERT`, `THEATER`, or `ALL` |
+| `page` | `number` | Page number (default: 1) |
 | `size` | `number` | Number of results (default: 18) |
+| `query` | `string` | Optional free-text query |
+| `category` | `string` | Category slug |
+| `league` | `string` | League abbreviation |
+| `context` | `string` | `homepage`, `events`, or `category` |
+| `recommendation` | `string` | `upcoming` or `trending` |
+| `parkingFilter` | `string` | `exclude`, `only`, or `include` |
+
+The result preserves the public browse endpoint's `total`, `totalExact`, `hasMore`, `page`, `pageSize`, and optional `degraded` metadata.
 
 ### `getListings(params)`
 
 | Param | Type | Description |
 |---|---|---|
 | `eventId` | `string` | External event ID |
-| `size` | `number` | Page size (default: 50) |
+| `size` | `number` | Page size, max 100 (default: 50) |
 | `page` | `number` | Page number (default: 1) |
 | `orderByDirection` | `string` | `asc` or `desc` by price |
+| `includeAll` | `boolean` | Request all available listings |
+| `refresh` | `boolean` | Bypass cached listings for this request |
+
+The result includes cache state, freshness, expiry, and pagination metadata when returned by the public endpoint.
+
+### `getListing(listingId)`
+
+Returns one sanitized public listing and any public disclosures for it.
 
 ### `createCheckoutLink(params)`
 
-Create a checkout URL for a listing. The user opens this in a browser to complete their purchase on tixbit.com.
+Create a checkout URL for a listing. The user opens this in a browser to review and complete the purchase on TixBit. This link-only method is unchanged by machine checkout.
 
 | Param | Type | Description |
 |---|---|---|
@@ -211,28 +375,58 @@ Create a checkout URL for a listing. The user opens this in a browser to complet
 
 Returns `{ url, listingId, quantity }`.
 
+### `purchaseTickets(params)`
+
+Purchase a selected listing and quantity through the public MPP endpoint. TixBit prepares inventory and determines the listing price, currency, fees, and final amount on the server before issuing the challenge.
+
+| Param | Type | Description |
+|---|---|---|
+| `listingId` | `string` | Listing ID selected from current listings |
+| `quantity` | `number` | Number of tickets (1–8) |
+| `email` | `string` | Required buyer email; normalized and validated before the request |
+| `name` | `string` | Optional buyer/recipient name |
+| `idempotencyKey` | `string` | Unguessable UUID v4 retry/recovery identity; generated when omitted |
+
+Returns agent-readable JSON with `status`, `idempotencyKey`, `orderReference`, `receiptUrl` when available, optional server-authoritative `order`, and an `action` for non-final states. Network ambiguity resolves to `pending` instead of claiming failure.
+
+### Agent SDK methods
+
+- `quoteListings(params: GetListingsParams)` requests refreshed listings and requires live freshness. It preserves the existing listings result shape.
+- `buyTickets({ listingId, quantity, email, maxAmountCents, confirm?, sharedPaymentToken? })` quotes by default. `confirm: true` requires a Link token and server cap support. It never retries a payment; ambiguous outcomes return `success: false`, `status: "unknown"`, and a recovery action.
+- `getAuthorizationInfo()` returns public browser sign-in and wallet setup links without creating a CLI session.
+- `listSellerListings(accessToken?)` reads the gated seller API, or returns browser sign-in guidance when no user credential is supplied.
+- `createSellerListing(body, accessToken, confirm)` requires `confirm === true` and explicit `termsAccepted: true`. The web API remains the seller schema and access authority.
+- `assertMppChallenge(challenge, maxAmountCents)` rejects unsupported or over-cap MPP challenges. Use it before credential creation in an official mppx `onChallenge` hook, not after `paymentFetch` returns.
+
 ### `getSeatmap(params)`
 
 | Param | Type | Description |
 |---|---|---|
 | `eventId` | `string` | External event ID |
 
-Returns venue info, section list, zone groupings, absolute asset URLs (`background_image`, `coordinates_url`), and per-section `shape_path` data for overlay rendering.
+Returns venue info, section list, zone groupings, first-party asset URLs (`background_image`, `coordinates_url`), and per-section `shape_path` data for overlay rendering.
 
 ### `eventUrl(slugOrId)`
 
-Returns the full URL to the event page on tixbit.com.
+Returns the full URL to the event page on `www.tixbit.com`.
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |---|---|---|
-| `TIXBIT_BASE_URL` | Override the TixBit URL | `https://tixbit.com` |
-| `TIXBIT_API_KEY` | API key (reserved for future use) | — |
+| `TIXBIT_BASE_URL` | Discovery URL; credential requests accept only the canonical origin or loopback QA | `https://www.tixbit.com` |
+| `TIXBIT_EMAIL` | Optional alternative to `buy --email` | none |
+| `TIXBIT_LINK_TOKEN` | Optional advanced integration: user-approved Link credential; never an argument | none |
+| `TIXBIT_ACCESS_TOKEN` | Optional advanced integration: signed-in seller user credential, not an API key | none |
+| `TIXBIT_PAYMENT_URL` | Canonical MPP endpoint or loopback QA URL; no credentials, query, fragment, or redirects | `https://mcp.tixbit.com/api/purchase` |
+| `MPPX_PRIVATE_KEY` | Optional mppx account source; prefer the OS keychain | mppx keychain |
 
 ## Requirements
 
-- Node.js 20+
+- Runtime/tooling range: Node.js `^20.19.0 || >=22.12.0`
+- CI compatibility matrix: Node.js 20.19, 22, 24, and 26
+
+Node.js 20 is end-of-life and remains in CI only as a compatibility floor. Node.js 22 and 24 are LTS releases; Node.js 26 is the current release line.
 
 ## License