tcgpriser 0.7.0 → 0.13.0

package/README.md

@@ -14,6 +14,7 @@ A typed Node.js / browser client for the [tcgpriser.se](https://tcgpriser.se) AP
 - ⚡ **Async/await** on every method, no callbacks
 - 🛠️ **Full IntelliSense** for every method and response field
 - 📦 **Zero runtime dependencies**, built on the standard `fetch` API, ships as ESM and CJS
+- ⏱️ **Timeouts and `AbortSignal`** on every call, with a sane default rather than none
 - 🔄 **Types stay in sync with the API**: `yarn generate:types` regenerates them from a live instance
 
 ## Installation
@@ -51,7 +52,8 @@ Public methods need no token. A handful of premium methods do, see [Authenticati
 ### Cards
 
 ```typescript
-await tcgpriser.cards.list({ search: 'pikachu', limit: 10 });
+await tcgpriser.cards.list({ limit: 10 }); // newest first, no free-text search
+await tcgpriser.cards.search({ search: 'pikachu' }); // premium
 await tcgpriser.cards.get('mega-evolution-ascended-heroes-fezandipiti-ex'); // id or technicalName
 await tcgpriser.cards.matches('fezandipiti-ex', { inStock: true });
 ```
@@ -61,23 +63,28 @@ await tcgpriser.cards.matches('fezandipiti-ex', { inStock: true });
 Booster boxes, ETBs, tins and the like. Single cards live under `cards`, not here.
 
 ```typescript
-await tcgpriser.products.list({ search: 'booster box' });
+await tcgpriser.products.list({ limit: 10 }); // newest first, no free-text search
+await tcgpriser.products.search({ search: 'booster box' }); // premium
 await tcgpriser.products.get('scarlet-violet-booster-pack');
 await tcgpriser.products.matches('scarlet-violet-booster-pack');
 ```
 
 ### Expansions
 
+Cards and sealed products are never merged into one response — fetch each separately.
+
 ```typescript
 await tcgpriser.expansions.list();
-await tcgpriser.expansions.products('eng-scarlet-violet-journey-together'); // { expansion, cards, sealed } — content only
+await tcgpriser.expansions.get('eng-scarlet-violet-journey-together'); // metadata only
+await tcgpriser.expansions.cards('eng-scarlet-violet-journey-together'); // content only
+await tcgpriser.expansions.sealedProducts('eng-scarlet-violet-journey-together'); // content only
 ```
 
 ### Pricing
 
-`list()`/`get()`/`expansions.products()` all return catalog content only — name, images, brand,
-expansion, rarity. Pricing (`retailPrice`, `estimatedValue`, `lowestShopOffer`,
-`referencePriceSnapshotsByProvider`) is a separate, shorter-cached call: content changes on an
+`list()`/`get()`/`expansions.cards()`/`expansions.sealedProducts()` all return catalog content
+only — name, images, brand, expansion, rarity. Pricing (`retailPrice`, `estimatedValue`,
+`lowestShopOffer`, `referencePriceSnapshotsByProvider`) is a separate, shorter-cached call: content changes on an
 admin edit or catalog import, pricing refreshes daily, so each is cached at the TTL its own
 freshness supports.
 
@@ -86,7 +93,7 @@ await tcgpriser.cards.pricing('fezandipiti-ex'); // id or technicalName
 await tcgpriser.products.pricing('scarlet-violet-booster-pack');
 
 // Batch form, up to 200 ids at once — ids only, not technicalNames.
-const { data: cards } = await tcgpriser.cards.list({ search: 'pikachu' });
+const { data: cards } = await tcgpriser.cards.list({ limit: 20 });
 await tcgpriser.cards.pricingBatch(cards.map((card) => card.id));
 ```
 
@@ -106,6 +113,26 @@ await tcgpriser.priceStats.estimatedValues({ expansion: 'eng-scarlet-violet-jour
 await tcgpriser.bargains.list({ type: 'sealed' }); // 'sealed' | 'card' | 'all'
 ```
 
+`priceStats` covers cards and sealed products together. To scope to one kind — so an `expansion`
+filter doesn't pull in that set's single cards alongside its booster boxes — use the equivalents on
+`cards` and `products`:
+
+```typescript
+await tcgpriser.cards.dailyStats({ expansion: 'eng-scarlet-violet-journey-together' });
+await tcgpriser.products.estimatedValues({ expansion: 'eng-scarlet-violet-journey-together' });
+```
+
+### Enumerating the catalog
+
+`technicalNames()` returns every slug with its `updatedAt` and nothing else — no pricing joins, no
+paging through full documents. It's what you want for a sitemap, or to work out which items have
+changed since your last sync:
+
+```typescript
+const { data: slugs } = await tcgpriser.cards.technicalNames();
+const stale = slugs.filter((slug) => slug.updatedAt > lastSyncedAt);
+```
+
 ### Pack rates
 
 ```typescript
@@ -115,35 +142,57 @@ await tcgpriser.packRates.get(expansionId);
 
 ## Available Methods
 
+🔒 = premium, 🏢 = business. Both need an API token — see [Authentication](#authentication). The
+Credits column applies only to calls that draw from your weekly allowance; see [Credits](#credits).
+
 ### `cards`
 
-| Method | Description |
-|---|---|
-| `list(params)` | Search or list cards |
-| `get(id)` | Fetch one card by id or technicalName |
-| `matches(id, params)` | Current shop listings matched to this card |
-| `prices(id, params)` 🔒 | Individual marketplace sale records |
-| `referencePrices(id, params)` 🔒 | Cardmarket / TCGplayer / eBay / Tradera price history |
-| `livePricing(id)` 🔒 | Pricing computed fresh for this request |
+| Method | Description | Credits |
+|---|---|---|
+| `list(params)` | List cards, newest first | — |
+| `search(params)` 🔒 | Free-text search on card and set names | 5 |
+| `get(id)` | Fetch one card by id or technicalName | — |
+| `matches(id, params)` | Current shop listings matched to this card | — |
+| `pricing(id)` | This card's current pricing snapshot | — |
+| `pricingBatch(ids)` | Pricing for up to 200 cards at once, by id | — |
+| `technicalNames()` | Every card's slug and `updatedAt`, for sitemaps and syncs | — |
+| `dailyStats(params)` | Daily average price history, cards only | — |
+| `estimatedValues(params)` | Current estimated market value, cards only | — |
+| `prices(id, params)` 🔒 | Individual marketplace sale records | 2 |
+| `referencePrices(id, params)` 🔒 | Cardmarket / TCGplayer / eBay / Tradera price history | 2 |
+| `livePricing(id)` 🔒 | Pricing computed fresh for this request | 3 |
 
 ### `products`
 
-| Method | Description |
-|---|---|
-| `list(params)` | Search or list sealed products |
-| `get(id)` | Fetch one product by id or technicalName |
-| `matches(id, params)` | Current shop listings matched to this product |
-| `prices(id, params)` 🔒 | Individual marketplace sale records |
-| `referencePrices(id, params)` 🔒 | Cardmarket / TCGplayer / Tradera price history |
-| `livePricing(id)` 🔒 | Pricing computed fresh for this request |
+Sealed products only. Single cards live under `cards`.
+
+| Method | Description | Credits |
+|---|---|---|
+| `list(params)` | List sealed products, newest first | — |
+| `search(params)` 🔒 | Free-text search on the product name | 5 |
+| `get(id)` | Fetch one product by id or technicalName | — |
+| `matches(id, params)` | Current shop listings matched to this product | — |
+| `pricing(id)` | This product's current pricing snapshot | — |
+| `pricingBatch(ids)` | Pricing for up to 200 products at once, by id | — |
+| `technicalNames()` | Every product's slug and `updatedAt` | — |
+| `dailyStats(params)` | Daily average price history, sealed only | — |
+| `estimatedValues(params)` | Current estimated market value, sealed only | — |
+| `prices(id, params)` 🔒 | Individual marketplace sale records | 2 |
+| `referencePrices(id, params)` 🔒 | Cardmarket / TCGplayer / Tradera price history | 2 |
+| `livePricing(id)` 🔒 | Pricing computed fresh for this request | 3 |
 
 ### `expansions`
 
-| Method | Description |
-|---|---|
-| `list()` | Every expansion |
-| `products(technicalName)` | Every card and sealed product in one expansion |
-| `livePricing(technicalName)` 🔒 | Fresh pricing for every item in one expansion |
+Cards and sealed products are always separate calls — nothing here merges them.
+
+| Method | Description | Credits |
+|---|---|---|
+| `list()` | Every expansion, with counts | — |
+| `get(technicalName)` | One expansion's metadata (no contents) | — |
+| `cards(technicalName)` | Every card in the expansion, content only | — |
+| `sealedProducts(technicalName)` | Every sealed product in the expansion, content only | — |
+| `cardsLivePricing(technicalName)` 🔒 | Fresh pricing for every card in the expansion | 8 |
+| `productsLivePricing(technicalName)` 🔒 | Fresh pricing for every sealed product in it | 8 |
 
 ### `shops`
 
@@ -162,33 +211,36 @@ await tcgpriser.packRates.get(expansionId);
 
 ### `shopMatchStats` 🔒
 
-| Method | Description |
-|---|---|
-| `forProduct(id, params)` | One product's price history, broken out per shop |
-| `forShop(shop, params)` | One shop's price history, broken out per product |
-| `compare(params)` | One product's price at every shop that carries it |
+| Method | Description | Credits |
+|---|---|---|
+| `forProduct(id, params)` | One product's price history, broken out per shop | 3 |
+| `forShop(shop, params)` | One shop's price history, broken out per product | 3 |
+| `compare(params)` | One product's price at every shop that carries it | 3 |
 
 ### `priceStats`
 
-| Method | Description |
-|---|---|
-| `daily(params)` | Daily average price history |
-| `estimatedValues(params)` | Current estimated market value |
-| `topProducts(params)` | Items ranked by shop availability |
-| `product(id)` 🔒 | Daily history, estimate and variant summary for one product |
-| `productFull(id)` 🔒 | `product()` plus the item's current shop matches |
-| `productDaily(id, params)` 🔒 | Daily history for one product, custom window |
-| `productDailyLast30(id)` 🔒 | Daily history, fixed to the last 30 days |
-| `productEstimatedValue(id)` 🔒 | Current estimated value only |
-| `productByVariant(id, params)` 🔒 | Price stats per card condition/grade |
-| `productDailyByVariant(id, params)` 🔒 | Daily history for one condition/grade |
+`daily()` and `estimatedValues()` cover cards and sealed products together. For one or the other,
+use `cards.dailyStats()` / `products.dailyStats()` and their `estimatedValues()` counterparts.
+
+| Method | Description | Credits |
+|---|---|---|
+| `daily(params)` | Daily average price history | — |
+| `estimatedValues(params)` | Current estimated market value | — |
+| `topProducts(params)` | Items ranked by shop availability | — |
+| `product(id)` 🔒 | Daily history, estimate and variant summary for one product | 2 |
+| `productFull(id)` 🔒 | `product()` plus the item's current shop matches | 5 |
+| `productDaily(id, params)` 🔒 | Daily history for one product, custom window | 1 |
+| `productDailyLast30(id)` 🔒 | Daily history, fixed to the last 30 days | 1 |
+| `productEstimatedValue(id)` 🔒 | Current estimated value only | 2 |
+| `productByVariant(id, params)` 🔒 | Price stats per card condition/grade | 3 |
+| `productDailyByVariant(id, params)` 🔒 | Daily history for one condition/grade | 1 |
 
 ### `bargains`
 
-| Method | Description |
-|---|---|
-| `list(params)` | Current listings priced below their reference price |
-| `search(params)` 🔒 | Same, with real pagination and filters |
+| Method | Description | Credits |
+|---|---|---|
+| `list(params)` | Current listings priced below their reference price | — |
+| `search(params)` 🔒 | Same, with real pagination and filters | 5 |
 
 ### `packRates`
 
@@ -204,13 +256,24 @@ await tcgpriser.packRates.get(expansionId);
 | `submit(params)` | Submit a shop URL for scraping |
 | `assignProduct(id, params)` | Manually assign (or clear) the product a URL resolves to |
 
+### `webhooks` 🏢
+
+Business tier. See [Webhooks](#webhooks) below.
+
+| Method | Description |
+|---|---|
+| `create(params)` | Register a webhook; returns its signing secret once |
+| `list()` | Every webhook on the account |
+| `delete(id)` | Revoke a webhook |
+| `test(id)` | Send a sample delivery |
+
 ### `stats`
 
 | Method | Description |
 |---|---|
 | `platform()` | Platform-wide overview counts |
 
-🔒 = premium, needs an API token. See below.
+Every method also takes `signal` and `timeoutMs` — see [Timeouts and cancellation](#timeouts-and-cancellation).
 
 ## Authentication
 
@@ -242,6 +305,47 @@ try {
 }
 ```
 
+## Credits
+
+Methods marked with a credit count in the tables above draw from your account's weekly credit
+allowance when called with an API token (Premium: 1500/week, Business: 6000/week, both reset Monday
+00:00 UTC). Cost is weighted by how much work the call does server-side: a cached single-item lookup
+costs less than a whole-expansion recompute. `expansions.cardsLivePricing()` and
+`expansions.productsLivePricing()` are the most expensive calls in the API at 8 credits, since each
+recomputes pricing for every item in the set.
+
+Once the week's credits run out, further calls reject with `429 creditsExhausted`, surfaced the same
+way as any other error:
+
+```typescript
+try {
+  await tcgpriser.cards.livePricing('fezandipiti-ex');
+} catch (error) {
+  if (error instanceof TcgPriserError && error.code === 'creditsExhausted') {
+    console.log('Out of credits for this week:', error.message);
+  }
+}
+```
+
+To track your balance mid-week, read `creditsRemaining` off the client. It's updated from the
+`X-Credits-Remaining` header the API returns on every charged response, so it costs no extra
+request — but it's only as current as your last premium call, and `undefined` until you make one:
+
+```typescript
+await tcgpriser.cards.livePricing('fezandipiti-ex');
+console.log(tcgpriser.creditsRemaining); // 1487
+```
+
+It's also on the error, which is where it matters most:
+
+```typescript
+catch (error) {
+  if (error instanceof TcgPriserError && error.code === 'creditsExhausted') {
+    console.log(error.creditsRemaining); // 0
+  }
+}
+```
+
 ## Options
 
 ```typescript
@@ -256,10 +360,83 @@ new TcgPriser({
     baseUrl: 'https://api.tcgpriser.se', // default; point at a local dev server instead
     headers: { 'User-Agent': 'my-app/1.0' },
     fetch: myCustomFetch, // defaults to global fetch (Node 18+)
+    timeoutMs: 60_000,    // default; 0 disables the timeout entirely
   },
 });
 ```
 
+## Timeouts and cancellation
+
+Every method takes `timeoutMs` and `signal`, either as a second argument or alongside the other
+params:
+
+```typescript
+await tcgpriser.cards.get('fezandipiti-ex', { timeoutMs: 5000 });
+await tcgpriser.cards.list({ limit: 10, timeoutMs: 5000 });
+```
+
+Requests time out after 60 seconds by default. A timeout rejects with a `TcgPriserError` whose
+`code` is `'timeout'` — the one code this package raises itself, so a stalled connection is always
+distinguishable from a server that actually answered:
+
+```typescript
+try {
+  await tcgpriser.expansions.cardsLivePricing('eng-scarlet-violet-journey-together');
+} catch (error) {
+  if (error instanceof TcgPriserError && error.code === 'timeout') {
+    // A whole-expansion recompute on a large set is the one call worth raising the limit for.
+    await tcgpriser.expansions.cardsLivePricing('eng-scarlet-violet-journey-together', {
+      timeoutMs: 0, // no timeout
+    });
+  }
+}
+```
+
+Pass a `signal` to cancel from outside — a user navigating away, a request being abandoned. Whichever
+fires first wins, and aborting through your own signal rejects with the standard `AbortError` rather
+than a `TcgPriserError`, since that's you getting what you asked for:
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 1000);
+await tcgpriser.cards.list({ limit: 10, signal: controller.signal });
+```
+
+## Rate limits
+
+Anonymous traffic is capped per IP, and premium reads per token (Premium 30/min, Business 120/min).
+Going over rejects with `429 rateLimited`, carrying the seconds to wait:
+
+```typescript
+if (error instanceof TcgPriserError && error.code === 'rateLimited') {
+  await sleep((error.retryAfter ?? 60) * 1000);
+}
+```
+
+## Webhooks
+
+Business tier only — a Premium token gets `403 businessRequired`. Instead of polling, the API POSTs
+to a URL you register when a catalog event fires.
+
+```typescript
+const tcgpriser = new TcgPriser(myBusinessApiToken);
+
+const webhook = await tcgpriser.webhooks.create({
+  url: 'https://example.com/hooks/tcgpriser', // must be https
+  events: ['price.updated', 'bargain.found'],
+});
+
+// The only time you will ever see this. Store it now — deliveries are signed with it, and no
+// endpoint reads it back. Lost it? Delete the webhook and register a new one.
+await saveSecret(webhook.secret);
+
+await tcgpriser.webhooks.test(webhook.id); // sample delivery, so you can verify your endpoint
+await tcgpriser.webhooks.list();           // never includes secrets
+await tcgpriser.webhooks.delete(webhook.id);
+```
+
+Available events: `price.updated`, `bargain.found`, `product.created`, `card.created`.
+
 ## Types
 
 Every response type is exported from the package root:
@@ -361,7 +538,19 @@ Runs `examples/rehost-images.ts` — the "Images" section's rehosting pattern ag
 
 ## Scope
 
-Covers the API's full documented surface: public catalog, price and bargain reads, plus the premium endpoints above. Not covered: the admin/scraper/auth surface, which isn't part of any published contract.
+Covers everything on the API's two published documentation pages: the public catalog, price and
+bargain reads at [/docs](https://api.tcgpriser.se/docs), and the premium and business endpoints at
+[/premium-docs](https://api.tcgpriser.se/premium-docs).
+
+Not covered, deliberately:
+
+- **The admin, scraper and ingest surface.** Ours, not a customer's — no API token reaches it, and
+  it isn't part of any published contract.
+- **Account management** (login, subscriptions, API-token minting, referrals). These authenticate
+  with the website's session JWT, which comes from an OAuth flow this client can't drive. Generate
+  your API token from your account page instead.
+- **`/bulk-export`.** Feeds our own static build, answers a non-standard shape, and is not
+  documented for third parties. Page the documented endpoints instead.
 
 ## License