tcgpriser 0.5.0 → 0.10.0

package/README.md

@@ -36,7 +36,12 @@ import { TcgPriser } from 'tcgpriser';
 const tcgpriser = new TcgPriser();
 
 const card = await tcgpriser.cards.get('mega-evolution-ascended-heroes-fezandipiti-ex');
-console.log(card.retailPrice, card.lowestShopOffer?.shop.name);
+console.log(card.name, card.expansion?.name);
+
+// Content (name, images, expansion, ...) and pricing (retailPrice, lowestShopOffer, ...) are
+// separate, differently-cached calls — see "Pricing" below.
+const pricing = await tcgpriser.cards.pricing('mega-evolution-ascended-heroes-fezandipiti-ex');
+console.log(pricing.retailPrice, pricing.lowestShopOffer?.shop.name);
 
 const { data: bargains } = await tcgpriser.bargains.list({ type: 'card' });
 ```
@@ -63,9 +68,30 @@ 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 }
+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.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.
+
+```typescript
+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' });
+await tcgpriser.cards.pricingBatch(cards.map((card) => card.id));
 ```
 
 ### Shops
@@ -95,33 +121,33 @@ await tcgpriser.packRates.get(expansionId);
 
 ### `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)` | 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 | 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 |
+| Method | Description | Credits |
+|---|---|---|
+| `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 | 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 |
+| Method | Description | Credits |
+|---|---|---|
+| `list()` | Every expansion | — |
+| `products(technicalName)` | Every card and sealed product in one expansion | — |
+| `livePricing(technicalName)` 🔒 | Fresh pricing for every item in one expansion | 8 |
 
 ### `shops`
 
@@ -140,33 +166,33 @@ 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 |
+| 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`
 
@@ -188,14 +214,16 @@ await tcgpriser.packRates.get(expansionId);
 |---|---|
 | `platform()` | Platform-wide overview counts |
 
-🔒 = premium, needs a subscriber's token. See below.
+🔒 = premium, needs an API token. See below. The Credits column applies only to methods that draw
+from your weekly credit allowance when called with an API token. A session login (not available to
+this client) and `shopUrls` are exempt. See [Credits](#credits).
 
 ## Authentication
 
-Public methods work with no setup. Premium methods (marked 🔒 above) need a signed-in subscriber's JWT from tcgpriser.se. This package doesn't handle login itself; the site's sign-in is OAuth-based, so a headless client can't drive it. Pass a token your own app already has:
+Public methods work with no setup. Premium methods (marked 🔒 above) need a Premium subscriber's API token, generated from **tcgpriser.se/account/api-token**. Unlike the site's own session login, which is OAuth-based and can't be driven headlessly, the API token is a long-lived, revocable secret made specifically for scripts and other programmatic callers. Generate it once from your account page and pass it in:
 
 ```typescript
-const tcgpriser = new TcgPriser(myJwt); // shorthand for { authToken: myJwt }
+const tcgpriser = new TcgPriser(myApiToken); // shorthand for { authToken: myApiToken }
 await tcgpriser.cards.livePricing('fezandipiti-ex');
 ```
 
@@ -203,7 +231,7 @@ Or set no default and pass a token per call, which fits better when one client i
 
 ```typescript
 const tcgpriser = new TcgPriser();
-await tcgpriser.cards.livePricing('fezandipiti-ex', { authToken: requestUserJwt });
+await tcgpriser.cards.livePricing('fezandipiti-ex', { authToken: requestUserApiToken });
 ```
 
 A missing or invalid token gets `401 unauthorized`. A valid token without an active subscription gets `403 premiumRequired`. Both come back as `TcgPriserError`:
@@ -220,14 +248,39 @@ 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.livePricing` is the most expensive call in
+the API at 8 credits, since it recomputes pricing for every card or product 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);
+  }
+}
+```
+
+This client doesn't currently surface the `X-Credits-Remaining` response header. To track your
+remaining balance mid-week, read it off the raw HTTP response yourself outside this SDK, or poll
+`GET /subscription` on the main API.
+
 ## Options
 
 ```typescript
-new TcgPriser(myJwt);  // shorthand for { authToken: myJwt }
-new TcgPriser();       // no token, public methods only
+new TcgPriser(myApiToken);  // shorthand for { authToken: myApiToken }
+new TcgPriser();            // no token, public methods only
 
 new TcgPriser({
-  authToken: myJwt,
+  authToken: myApiToken,
 
   // Local dev, self-hosting or tests only. Leave this out for normal use.
   advanced: {
@@ -256,6 +309,47 @@ type CardSchema = components['schemas']['CardWithPricing'];
 
 Most types in `tcgpriser` are direct aliases onto that generated schema, so a field in your code and a field in the API docs are the same field, always.
 
+## Images
+
+`imageUrl`, `logoUrl` and `symbolUrl` fields point at tcgpriser.se's own CDN, which is sized for
+tcgpriser.se's own traffic, not for hotlinking from other sites and apps. **For best performance,
+rehost these images on your own storage/CDN and cache them there** instead of linking to them
+directly — one less hop, tuned to your own traffic and geography, and no dependency on
+infrastructure that isn't yours.
+
+A simple way to do this: fetch the image once, save it under the URL's path (e.g.
+`products/eng-scarlet-violet-booster-pack.png`) as a stable local key, serve it from your own
+storage from then on, and periodically re-fetch (a nightly job is plenty) using a conditional
+`GET` so you only pay for images that actually changed:
+
+```typescript
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+const etags = new Map<string, string>(); // persist this however you persist anything else
+
+async function rehostImage(imageUrl: string, cacheDir: string): Promise<string> {
+  const key = new URL(imageUrl).pathname.replace(/^\/[^/]+\//, ''); // "products/....webp"
+  const localPath = join(cacheDir, key);
+  const knownEtag = etags.get(key);
+
+  const res = await fetch(imageUrl, { headers: knownEtag ? { 'If-None-Match': knownEtag } : {} });
+  if (res.status === 304) return localPath; // unchanged since last sync
+
+  if (!res.ok) throw new Error(`Failed to fetch ${imageUrl}: ${res.status}`);
+  await mkdir(dirname(localPath), { recursive: true });
+  await writeFile(localPath, Buffer.from(await res.arrayBuffer()));
+
+  const etag = res.headers.get('etag');
+  if (etag) etags.set(key, etag);
+  return localPath;
+}
+```
+
+Swap the `fs`/`mkdir`/`writeFile` calls for your own storage's SDK (S3, R2, Cloudflare Images, ...)
+if you're not caching to local disk. See `examples/rehost-images.ts` for a runnable version of this
+against a live `tcgpriser` response.
+
 ## Scripts
 
 ### Build
@@ -290,6 +384,12 @@ yarn example
 
 Runs `examples/basic.ts` against a local dev API. Set `TCGPRISER_AUTH_TOKEN` to see the premium call succeed instead of the expected 401.
 
+```bash
+yarn example:rehost-images
+```
+
+Runs `examples/rehost-images.ts` — the "Images" section's rehosting pattern against a handful of real product images. Run it twice to see the second pass come back as `304`s.
+
 ## 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.

package/dist/index.cjs

@@ -44,6 +44,8 @@ var KNOWN_ERROR_CODES = /* @__PURE__ */ new Set([
   "readOnlyField",
   "rateLimited",
   "premiumRequired",
+  "businessRequired",
+  "creditsExhausted",
   "internalError"
 ]);
 async function toApiError(res, url) {
@@ -169,6 +171,21 @@ var CardsResource = class {
   livePricing(idOrTechnicalName, options = {}) {
     return this.http.get(`/cards/${encodeURIComponent(idOrTechnicalName)}/pricing/live`, options);
   }
+  /** `GET /cards/{id}/pricing`: this card's current pricing snapshot — `retailPrice`,
+   * `estimatedValue`, `lowestShopOffer`, `referencePriceSnapshotsByProvider` — refreshed once a day
+   * by the nightly pricing/scraper jobs. `get()` returns content only; this is the separate,
+   * shorter-cached call for the part of a card that actually changes day to day. */
+  pricing(idOrTechnicalName) {
+    return this.http.get(`/cards/${encodeURIComponent(idOrTechnicalName)}/pricing`);
+  }
+  /** `GET /cards/pricing`: pricing for up to 200 cards in one request, keyed by `id` — the batch
+   * counterpart to `pricing()`, for a page of results (a search page, an expansion's contents) that
+   * needs pricing for many items at once. Unlike `get()`/`pricing()`, this only accepts `id`s, not
+   * technicalNames — pass the `id`s already on the cards you fetched. Ids with no match are
+   * silently omitted from the result rather than causing an error. */
+  pricingBatch(ids) {
+    return this.http.get(`/cards/pricing?ids=${ids.map(encodeURIComponent).join(",")}`);
+  }
 };
 
 // src/resources/expansions.ts
@@ -182,14 +199,38 @@ var ExpansionsResource = class {
     const res = await this.http.get("/expansions");
     return res.data;
   }
-  /** `GET /expansions/{technicalName}/products`: every card and sealed product in one
-   * expansion, kept as separate `cards`/`sealed` groups. */
-  products(technicalName) {
-    return this.http.get(`/expansions/${encodeURIComponent(technicalName)}/products?grouped=true`);
+  /** `GET /expansions/{technicalName}`: metadata only — no cards or sealed products. Returns the
+   * smaller `ExpansionRef`, not the full `Expansion`: this is a plain lookup by technicalName, not
+   * the aggregation `list()` runs, so `sealedCount`/`cardCount`/`productCount` aren't available
+   * here. See `cards()` and `sealedProducts()` for this expansion's contents. */
+  get(technicalName) {
+    return this.http.get(`/expansions/${encodeURIComponent(technicalName)}`);
+  }
+  /** `GET /expansions/{technicalName}/cards`: every card in this expansion. Content only, no
+   * pricing fields — pass the `id`s from the result to `client.cards.pricingBatch()` if you need
+   * pricing too. Sealed products are a separate call — see `sealedProducts()` — never merged into
+   * this one. */
+  cards(technicalName) {
+    return this.http.get(`/expansions/${encodeURIComponent(technicalName)}/cards`);
+  }
+  /** `GET /expansions/{technicalName}/products`: every sealed product in this expansion. Content
+   * only, no pricing fields — pass the `id`s from the result to `client.products.pricingBatch()`
+   * if you need pricing too. Cards are a separate call — see `cards()` — never merged into this
+   * one. */
+  sealedProducts(technicalName) {
+    return this.http.get(`/expansions/${encodeURIComponent(technicalName)}/products`);
+  }
+  /** `GET /expansions/{technicalName}/cards/live-pricing`: computed fresh for every card in this
+   * expansion, not read from the last stats job. Premium. */
+  cardsLivePricing(technicalName, options = {}) {
+    return this.http.get(
+      `/expansions/${encodeURIComponent(technicalName)}/cards/live-pricing`,
+      options
+    );
   }
-  /** `GET /expansions/{technicalName}/products/live-pricing`: computed fresh for every item in
-   * this expansion, not read from the last stats job. Premium. */
-  livePricing(technicalName, options = {}) {
+  /** `GET /expansions/{technicalName}/products/live-pricing`: computed fresh for every sealed
+   * product in this expansion, not read from the last stats job. Premium. */
+  productsLivePricing(technicalName, options = {}) {
     return this.http.get(
       `/expansions/${encodeURIComponent(technicalName)}/products/live-pricing`,
       options
@@ -331,6 +372,21 @@ var ProductsResource = class {
   livePricing(idOrTechnicalName, options = {}) {
     return this.http.get(`/product/${encodeURIComponent(idOrTechnicalName)}/pricing/live`, options);
   }
+  /** `GET /product/{id}/pricing`: this product's current pricing snapshot — `retailPrice`,
+   * `estimatedValue`, `lowestShopOffer`, `referencePriceSnapshotsByProvider` — refreshed once a day
+   * by the nightly pricing/scraper jobs. `get()` returns content only; this is the separate,
+   * shorter-cached call for the part of a product that actually changes day to day. */
+  pricing(idOrTechnicalName) {
+    return this.http.get(`/product/${encodeURIComponent(idOrTechnicalName)}/pricing`);
+  }
+  /** `GET /product/pricing`: pricing for up to 200 sealed products in one request, keyed by `id` —
+   * the batch counterpart to `pricing()`, for a page of results (a search page, an expansion's
+   * contents) that needs pricing for many items at once. Unlike `get()`/`pricing()`, this only
+   * accepts `id`s, not technicalNames — pass the `id`s already on the products you fetched. Ids with
+   * no match are silently omitted from the result rather than causing an error. */
+  pricingBatch(ids) {
+    return this.http.get(`/product/pricing?ids=${ids.map(encodeURIComponent).join(",")}`);
+  }
 };
 
 // src/resources/shopMatchStats.ts
@@ -448,7 +504,7 @@ var TcgPriser = class {
   packRates;
   stats;
   /**
-   * @param optionsOrAuthToken A subscriber JWT (`new TcgPriser(myJwt)`), a full
+   * @param optionsOrAuthToken A subscriber's API token (`new TcgPriser(myApiToken)`), a full
    * `TcgPriserOptions` object, or omit it entirely for an anonymous, public-only client.
    */
   constructor(optionsOrAuthToken) {