keepa-api 0.3.0 → 0.3.2

package/README.md

@@ -1,50 +1,20 @@
 # keepa-api
 
-Lightweight TypeScript SDK for the [Keepa](https://keepa.com) REST API. Mirrors the organizational style of [openai-node](https://github.com/openai/openai-node) — a single `KeepaClient` class exposes resources (`products`, etc.) that wrap each endpoint with typed inputs and responses.
-
-Phase 1 ships the **Products** resource only. Categories, Search, and Bestsellers are planned but not yet implemented.
-
-## Requirements
-
-- Node.js **≥ 18** (uses native `fetch`)
-- A Keepa API key — sign up at [keepa.com/api](https://keepa.com/api.html)
-- ESM consumer (your `package.json` should have `"type": "module"`, or you must be able to `import()` an ESM package)
+Lightweight TypeScript SDK for the [Keepa](https://keepa.com) REST API. A single `KeepaClient` class exposes typed resources (currently `products`) with parsed responses, friendly currency units, and live rate-limit visibility.
 
 ## Installation
 
-This package is **not yet published to npm**. Install it locally or from GitHub.
-
-### From a local checkout (during development)
-
 ```bash
-# In keepa-api/
-npm install
-npm run build
-npm link
-
-# In your other project:
-npm link keepa-api
+npm install keepa-api
+# or
+pnpm add keepa-api
+# or
+yarn add keepa-api
+# or
+bun add keepa-api
 ```
 
-After this, edits in `keepa-api/src/` only need `npm run build` — the consumer sees the new `dist/` immediately.
-
-### From GitHub (no npm publish needed)
-
-```bash
-npm install github:bilalyasin1616/keepa-api#feature/keepa-products-package
-```
-
-(Replace the branch with `main` once the work is merged.)
-
-### From a tarball
-
-```bash
-# In keepa-api/
-npm pack          # produces keepa-api-0.1.0.tgz
-
-# In your other project:
-npm install /absolute/path/to/keepa-api-0.1.0.tgz
-```
+Requires Node 18+. Ships both ESM and CJS — works with `import` and `require`.
 
 ## Quickstart
 
@@ -53,19 +23,18 @@ import KeepaClient from 'keepa-api';
 
 const keepa = new KeepaClient({ apiKey: process.env.KEEPA_API_KEY });
 
-const products = await keepa.products.list({
-  asins: ['B00MNV8E0C'],
-  marketplace: 'US',
-});
+const [product] = await keepa.products.list({ asins: ['B00MNV8E0C'] });
 
-console.log(products[0]?.title);
+console.log(product?.title, product?.bsr, product?.images[0]);
 ```
 
-The client reads `process.env.KEEPA_API_KEY` if you don't pass `apiKey` explicitly. Put your key in a gitignored `.env` (see `.env.example` for the shape).
+`apiKey` falls back to `process.env.KEEPA_API_KEY` when omitted.
 
-## API
+## Client
 
-### `new KeepaClient(options?)`
+```ts
+new KeepaClient(options?)
+```
 
 | Option | Type | Default | Notes |
 |--------|------|---------|-------|
@@ -73,138 +42,167 @@ The client reads `process.env.KEEPA_API_KEY` if you don't pass `apiKey` explicit
 | `baseURL` | `string` | `'https://api.keepa.com'` | Override for testing/proxying. |
 | `fetch` | `typeof fetch` | `globalThis.fetch` | Plug in a custom fetch (mocks, retries, etc.). |
 
+## Products
+
 ### `keepa.products.list(params)` → `Promise<KeepaProduct[]>`
 
 | Param | Type | Default | Notes |
 |-------|------|---------|-------|
 | `asins` | `string[]` | (required) | Validated + uppercased. Throws on malformed input. |
-| `marketplace` | `'US' \| 'GB' \| 'DE' \| 'FR' \| 'JP' \| 'CA' \| 'IT' \| 'ES' \| 'IN' \| 'MX' \| 'BR'` | `'US'` | Case-insensitive. Throws on unknown. |
-| `days` | `number` | `1` | Days of price history. Must be a positive integer (validated pre-flight). |
+| `marketplace` | `Marketplace` | `'US'` | Case-insensitive. See [marketplaces](#marketplaces). |
+| `days` | `number` | `1` | Days of csv history when `history: true`. |
+| `history` | `boolean` | `false` | Populates `history.price.*` + scalar `amazonPrice` / `newPrice` / `listPrice`. Costs extra tokens. |
+
+### `keepa.products.retrieve(params)` → `Promise<KeepaProduct>`
+
+Same options as `list`, but takes a single `asin: string` and returns one product. Throws `ProductNotFoundError` when Keepa has no record (stub with `title === null`, or no product returned at all).
 
-The SDK maps Keepa's raw wire shape into a friendlier `KeepaProduct`:
+### `KeepaProduct`
 
-- `images: string[]` — full image URLs (region-neutral CDN). Replaces Keepa's awkward `imagesCSV` string.
-- `bsr: number | null` — most recent real BSR for the product's `rootCategory`. `null` when missing or every history entry is Keepa's `-1` "no data captured" sentinel.
+The SDK reshapes Keepa's wire format into something usable:
 
-The raw `salesRanks` record is preserved for consumers that need to walk the full rank history. Other Keepa fields (`title`, `parentAsin`, `categoryTree`, `variations`, `features`, …) pass through unchanged.
+| Field | Type | Notes |
+|-------|------|-------|
+| `images` | `string[]` | Full image URLs (region-neutral CDN). |
+| `bsr` | `number \| null` | Latest non-sentinel BSR for `rootCategory`. |
+| `amazonPrice` | `number \| null` | Latest price Amazon itself sells the product for (csv[0]) in the marketplace's **major unit** — dollars/pounds/yen/…. Null without `history: true`. |
+| `newPrice` | `number \| null` | Latest lowest-3rd-party-new offer price (csv[1]). Distinct from `amazonPrice` — Amazon isn't always the cheapest new seller. |
+| `listPrice` | `number \| null` | Latest list price / MSRP (csv[4]). |
+| `history.price.amazon` | `PriceHistoryEntry[]` | Amazon's own price over time. Empty without `history: true`. |
+| `history.price.new` | `PriceHistoryEntry[]` | Lowest-3rd-party-new price over time. |
+| `history.price.list` | `PriceHistoryEntry[]` | List price (MSRP) over time. |
 
-**Stub records:** Keepa returns one record per requested ASIN even when it has no data — these stubs have `title === null`. Filter with `isFoundProduct` (below).
+`title`, `description`, `parentAsin`, `categoryTree`, `salesRanks`, `variations`, `features` pass through from Keepa unchanged.
 
-### Helpers
+**Stub records:** Keepa returns one entry per requested ASIN even for unknown ASINs — those stubs have `title === null`. Filter them out:
 
 ```ts
 import { isFoundProduct } from 'keepa-api';
 
-const real = products.filter(isFoundProduct);
+const found = products.filter(isFoundProduct);
+```
 
-for (const product of real) {
-  console.log(product.bsr);          // already populated by the SDK
-  console.log(product.images[0]);    // already populated by the SDK
-}
+### Price history
+
+```ts
+const [product] = await keepa.products.list({
+  asins: ['B00MNV8E0C'],
+  history: true,
+  days: 30,
+});
+
+product.amazonPrice;              // 18.99 (USD) — Amazon's own latest
+product.newPrice;                 // 16.99       — cheapest 3rd-party new
+product.listPrice;                // 29.99       — MSRP
+product.history.price.amazon[0];  // { timestamp: Date, price: 19.49 }
 ```
 
-| Helper | Signature | Returns |
-|--------|-----------|---------|
-| `isFoundProduct(product)` | `(product: KeepaProduct) => boolean` | `true` only if Keepa returned real data (stubs have `title === null`). |
-| `parseImagesCsv(csv)` | `(csv: string \| undefined) => string[]` | Build the full image-URL list from a raw Keepa imagesCSV. Used internally to fill `images`; exported for advanced use. |
-| `extractBsr(salesRanks, rootCategory)` | `(salesRanks: Record<string, number[]> \| undefined, rootCategory: number \| undefined) => number \| null` | Most recent real BSR from Keepa's raw `[ts, rank, ...]` history. Used internally to fill `bsr`; exported for advanced use. |
-| `extractImageUrl(imagesCSV)` | `(imagesCSV: string \| undefined) => string \| null` | Single URL — equivalent to `parseImagesCsv(imagesCSV)[0] ?? null`. Exported for advanced use. |
+Prices are in the marketplace's major unit (USD dollars for `'US'`, GBP for `'GB'`, JPY for `'JP'`, …). Keepa's `-1` "no data captured" entries are filtered out.
 
-### ASIN validation
+For csv types beyond Amazon / list price (`NEW`, `USED`, `REFURBISHED`, `RATING`, …), pull the row off the raw response and parse it:
 
 ```ts
-import { ASIN_REGEX, ASIN_LENGTH, isValidAsin, normalizeAsins } from 'keepa-api';
+import { CsvType, parsePriceHistory } from 'keepa-api';
 
-isValidAsin('B00MNV8E0C');           // true
-isValidAsin('b00mnv8e0c');           // false (lowercase — use normalizeAsins to coerce)
-isValidAsin('B07XYZ');               // false (too short)
+const usedPrices = parsePriceHistory(rawProduct.csv?.[CsvType.USED]);
+```
 
-normalizeAsins(['  b00mnv8e0c ']);   // ['B00MNV8E0C']
-normalizeAsins(['B07XYZ']);          // throws: Invalid ASIN(s): B07XYZ. ...
+`CsvType` covers all 36 of Keepa's csv series names verbatim.
+
+## Marketplaces
+
+```ts
+import { resolveDomainId } from 'keepa-api';
+
+resolveDomainId('gb');      // 2 (case-insensitive)
+resolveDomainId(undefined); // 1 (defaults to US)
 ```
 
-`Products.list` calls `normalizeAsins` for you, so you don't need to pre-validate unless you're doing form-level checking.
+| Code | Domain | Code | Domain |
+|------|--------|------|--------|
+| US | 1 | IT | 8 |
+| GB | 2 | ES | 9 |
+| DE | 3 | IN | 10 |
+| FR | 4 | MX | 11 |
+| JP | 5 | BR | 12 |
+| CA | 6 |  |  |
 
-**Caveat:** The regex catches *malformed* input. It cannot catch "Keepa has no record" — for example `1234567890` is a structurally valid ISBN-10 shape and passes the regex, but Keepa returns a stub record. Use `isFoundProduct` to filter those.
+Codes are ISO 3166-1 alpha-2. Domain 7 is reserved (formerly Amazon China, retired by Keepa).
 
-### Marketplaces
+## Rate limits
+
+The client tracks Keepa's token bucket on every response — success and 429 alike — and exposes the latest snapshot:
 
 ```ts
-import { MARKETPLACE_DOMAINS, resolveDomainId } from 'keepa-api';
+await keepa.products.list({ asins });
 
-MARKETPLACE_DOMAINS.US;   // 1
-resolveDomainId('gb');    // 2 (case-insensitive)
-resolveDomainId(undefined); // 1 (defaults to US)
+if (keepa.rateLimit && keepa.rateLimit.tokensLeft < 50) {
+  await sleep(keepa.rateLimit.refillIn); // ms until next token refills
+}
+```
+
+On a 429, the snapshot is also attached to the thrown error:
+
+```ts
+import { RateLimitError } from 'keepa-api';
+
+try {
+  await keepa.products.list({ asins: bigBatch });
+} catch (err) {
+  if (err instanceof RateLimitError && err.rateLimit) {
+    await sleep(err.rateLimit.refillIn);
+    // retry…
+  }
+}
 ```
 
-| Code | Domain ID | Code | Domain ID |
-|------|-----------|------|-----------|
-| US   | 1         | IT   | 8         |
-| GB   | 2         | ES   | 9         |
-| DE   | 3         | IN   | 10        |
-| FR   | 4         | MX   | 11        |
-| JP   | 5         | BR   | 12        |
-| CA   | 6         |      |           |
+`RateLimitInfo`: `tokensLeft`, `refillIn` (ms), `refillRate` (tokens/min), `tokenFlowReduction`, `receivedAt`.
 
-### Errors
+The SDK does **not** auto-retry on 429. Handling that is your call.
 
-All errors thrown by API calls extend `KeepaError`. Catch the specific subclasses for status-aware handling:
+## Errors
+
+All errors extend `KeepaError`:
 
 ```ts
 import {
+  KeepaError,
+  APIError,
   RateLimitError,
   AuthenticationError,
-  APIError,
   NetworkError,
-  KeepaError,
 } from 'keepa-api';
 
 try {
-  await keepa.products.list({ asins: ['B00MNV8E0C'] });
+  await keepa.products.list({ asins });
 } catch (err) {
-  if (err instanceof RateLimitError) /* 429 */;
-  else if (err instanceof AuthenticationError) /* 401 — bad API key */;
-  else if (err instanceof APIError) /* 4xx/5xx — err.status, err.body */;
-  else if (err instanceof NetworkError) /* DNS/ECONNREFUSED/abort — err.cause has the original */;
-  else if (err instanceof KeepaError) /* something else from this SDK */;
+  if (err instanceof RateLimitError)           /* 429 — err.rateLimit */;
+  else if (err instanceof AuthenticationError) /* 401 — invalid API key */;
+  else if (err instanceof APIError)            /* 4xx/5xx — err.status, err.body */;
+  else if (err instanceof NetworkError)        /* transport — err.cause */;
   else throw err;
 }
 ```
 
-### API key handling
-
-Keepa's REST API requires the key as a `?key=...` query parameter — that's their contract, not a choice we made. Practical implications:
+## ASIN utilities
 
-- **Server-side proxy / access logs** will record full URLs (key included). Configure log scrubbing if you can't trust the layer.
-- **Don't run this in the browser.** A client-side request would expose your key in DevTools' Network tab and to any browser extension or middlebox.
-- The `NetworkError.body` and `APIError.body` fields capture Keepa's response body. Keepa doesn't echo your key in error bodies, but if you log them to a customer-facing surface, sanity-check the contents first.
-
-## Scripts
+```ts
+import { isValidAsin, normalizeAsins } from 'keepa-api';
 
-```bash
-npm test            # vitest run — unit tests
-npm run test:watch  # vitest watch
-npm run build       # tsc → dist/
-npm run example     # runs examples/basic.ts against real Keepa (needs .env)
-npm run clean       # rm -rf dist
+isValidAsin('B00MNV8E0C');           // true
+normalizeAsins(['  b00mnv8e0c ']);   // ['B00MNV8E0C']
+normalizeAsins(['B07XYZ']);          // throws — too short
 ```
 
-## Roadmap
+`products.list` / `products.retrieve` call `normalizeAsins` for you. The regex catches malformed ASINs but can't tell you whether Keepa has the record — use `isFoundProduct` for that.
 
-**Resources**
-- [ ] `Categories` resource (`fetchKeepaCategories`)
-- [ ] `Categories.search` (`searchKeepaCategories`)
-- [ ] `Bestsellers.retrieve` (`fetchKeepaBestSeller`)
+## Security note
 
-**Request layer**
-- [ ] `AbortSignal` / configurable timeout on `Products.list` (default ~30s) — currently a hung Keepa server keeps the request pending forever
-- [ ] Pass-through `init` (method, headers, signal) on `core/request` for resources that need POST or custom headers
-- [ ] Cap `asins.length` at Keepa's per-call limit (100) instead of letting Keepa silently truncate
-- [ ] Optional `retryOn429` (with backoff) — currently we throw `RateLimitError` immediately; consumers handle pacing in their own code
+Keepa's API authenticates via `?key=...` query parameter (not a header), so:
 
-**Distribution**
-- [ ] CommonJS build alongside ESM
-- [ ] Publish to npm
+- **Don't run this in a browser.** Your key would be visible in DevTools and to any browser extension or middlebox.
+- Server-side access logs will record full URLs (with key). Configure log scrubbing if the layer isn't trusted.
+- `APIError.body` and `NetworkError.message` are scrubbed of the key before being thrown.
 
 ## License
 

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   ASIN_LENGTH: () => ASIN_LENGTH,
   ASIN_REGEX: () => ASIN_REGEX,
   AuthenticationError: () => AuthenticationError,
+  CsvType: () => CsvType,
   DEFAULT_DAYS: () => DEFAULT_DAYS,
   KEEPA_NO_DATA_SENTINEL: () => KEEPA_NO_DATA_SENTINEL,
   KeepaClient: () => KeepaClient,
@@ -43,6 +44,7 @@ __export(index_exports, {
   isFoundProduct: () => isFoundProduct,
   isValidAsin: () => isValidAsin,
   normalizeAsins: () => normalizeAsins,
+  parsePriceHistory: () => parsePriceHistory,
   resolveDomainId: () => resolveDomainId
 });
 module.exports = __toCommonJS(index_exports);
@@ -69,22 +71,25 @@ var APIError = class _APIError extends KeepaError {
     this.context = context;
     this.body = safeBody;
   }
-  static async from(response, context) {
-    const body = await response.text().catch(() => "");
-    switch (response.status) {
+  static from(status, context, body, rateLimit = null) {
+    switch (status) {
       case 429:
-        return new RateLimitError(context, body);
+        return new RateLimitError(context, body, rateLimit);
       case 401:
         return new AuthenticationError(context, body);
       default:
-        return new _APIError(response.status, context, body);
+        return new _APIError(status, context, body);
     }
   }
 };
 var RateLimitError = class extends APIError {
-  constructor(context, body) {
+  /** Bucket snapshot at the moment the 429 was returned. Null if Keepa's body
+   *  didn't carry the usual rate-limit fields. */
+  rateLimit;
+  constructor(context, body, rateLimit = null) {
     super(429, context, body, "Keepa rate limit exceeded, please wait or upgrade plan");
     this.name = "RateLimitError";
+    this.rateLimit = rateLimit;
   }
 };
 var AuthenticationError = class extends APIError {
@@ -110,6 +115,20 @@ var NetworkError = class extends KeepaError {
   }
 };
 
+// src/core/rate-limit.ts
+function extractRateLimit(body) {
+  if (!body || typeof body !== "object") return null;
+  const b = body;
+  if (typeof b.tokensLeft !== "number") return null;
+  return {
+    tokensLeft: b.tokensLeft,
+    refillIn: typeof b.refillIn === "number" ? b.refillIn : 0,
+    refillRate: typeof b.refillRate === "number" ? b.refillRate : 0,
+    tokenFlowReduction: typeof b.tokenFlowReduction === "number" ? b.tokenFlowReduction : 0,
+    receivedAt: /* @__PURE__ */ new Date()
+  };
+}
+
 // src/core/request.ts
 function buildUrl(baseURL, path, query) {
   if (!query) return `${baseURL}${path}`;
@@ -133,8 +152,19 @@ async function request(config, args) {
   } catch (cause) {
     throw new NetworkError(args.context, cause);
   }
-  if (!res.ok) throw await APIError.from(res, args.context);
-  return await res.json();
+  const text = await res.text().catch(() => "");
+  const body = safeJsonParse(text);
+  const rl = extractRateLimit(body);
+  if (rl) config.onRateLimit?.(rl);
+  if (!res.ok) throw APIError.from(res.status, args.context, text, rl);
+  return body;
+}
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
 }
 
 // src/core/resource.ts
@@ -194,6 +224,45 @@ var PRODUCT_LIST_CONTEXT = "products.list";
 var DEFAULT_DAYS = 1;
 var AMAZON_IMAGE_BASE = "https://m.media-amazon.com/images/I";
 var KEEPA_NO_DATA_SENTINEL = -1;
+var CsvType = {
+  AMAZON: 0,
+  NEW: 1,
+  USED: 2,
+  SALES: 3,
+  LISTPRICE: 4,
+  COLLECTIBLE: 5,
+  REFURBISHED: 6,
+  NEW_FBM_SHIPPING: 7,
+  LIGHTNING_DEAL: 8,
+  WAREHOUSE: 9,
+  NEW_FBA: 10,
+  COUNT_NEW: 11,
+  COUNT_USED: 12,
+  COUNT_REFURBISHED: 13,
+  COUNT_COLLECTIBLE: 14,
+  EXTRA_INFO_UPDATES: 15,
+  RATING: 16,
+  COUNT_REVIEWS: 17,
+  BUY_BOX_SHIPPING: 18,
+  USED_NEW_SHIPPING: 19,
+  USED_VERY_GOOD_SHIPPING: 20,
+  USED_GOOD_SHIPPING: 21,
+  USED_ACCEPTABLE_SHIPPING: 22,
+  COLLECTIBLE_NEW_SHIPPING: 23,
+  COLLECTIBLE_VERY_GOOD_SHIPPING: 24,
+  COLLECTIBLE_GOOD_SHIPPING: 25,
+  COLLECTIBLE_ACCEPTABLE_SHIPPING: 26,
+  REFURBISHED_SHIPPING: 27,
+  EBAY_NEW_SHIPPING: 28,
+  EBAY_USED_SHIPPING: 29,
+  TRADE_IN: 30,
+  RENTAL: 31,
+  BUY_BOX_USED_SHIPPING: 32,
+  PRIME_EXCL: 33,
+  COUNT_NEW_FBA: 34,
+  COUNT_NEW_FBM: 35
+};
+var KEEPA_EPOCH_UNIX_MS = 129384e7;
 var VALID_IMAGE_FILENAME = /^[A-Za-z0-9._-]+\.(jpg|jpeg|png|webp)$/i;
 
 // src/resources/products/error.ts
@@ -208,6 +277,9 @@ var ProductNotFoundError = class extends KeepaError {
 
 // src/resources/products/product.util.ts
 function toKeepaProduct(raw) {
+  const amazon = parsePriceHistory(raw.csv?.[CsvType.AMAZON]);
+  const new_ = parsePriceHistory(raw.csv?.[CsvType.NEW]);
+  const list = parsePriceHistory(raw.csv?.[CsvType.LISTPRICE]);
   return {
     asin: raw.asin,
     title: raw.title,
@@ -219,9 +291,34 @@ function toKeepaProduct(raw) {
     variations: raw.variations,
     features: raw.features,
     images: rawImagesToUrls(raw.images),
-    bsr: extractBsr(raw.salesRanks, raw.rootCategory)
+    bsr: extractBsr(raw.salesRanks, raw.rootCategory),
+    amazonPrice: amazon.at(-1)?.price ?? null,
+    newPrice: new_.at(-1)?.price ?? null,
+    listPrice: list.at(-1)?.price ?? null,
+    history: {
+      price: { amazon, new: new_, list }
+    }
   };
 }
+function pairKeepaSeries(series) {
+  if (!series) return [];
+  const points = [];
+  for (let i = 0; i + 1 < series.length; i += 2) {
+    const value = series[i + 1];
+    if (value === KEEPA_NO_DATA_SENTINEL) continue;
+    points.push({ timestamp: series[i], value });
+  }
+  return points;
+}
+function keepaMinutesToDate(minutes) {
+  return new Date(minutes * 6e4 + KEEPA_EPOCH_UNIX_MS);
+}
+function parsePriceHistory(series) {
+  return pairKeepaSeries(series).map(({ timestamp, value }) => ({
+    timestamp: keepaMinutesToDate(timestamp),
+    price: value / 100
+  }));
+}
 function rawImagesToUrls(images) {
   if (!images || images.length === 0) return [];
   return images.filter((img) => typeof img.l === "string" && VALID_IMAGE_FILENAME.test(img.l)).map((img) => `${AMAZON_IMAGE_BASE}/${img.l}`);
@@ -231,14 +328,7 @@ function isFoundProduct(product) {
 }
 function extractBsr(salesRanks, rootCategory) {
   if (!salesRanks || rootCategory === void 0) return null;
-  const ranks = salesRanks[String(rootCategory)];
-  if (!ranks || ranks.length < 2) return null;
-  const start = ranks.length % 2 === 0 ? ranks.length - 1 : ranks.length - 2;
-  for (let i = start; i >= 1; i -= 2) {
-    const rank = ranks[i];
-    if (rank !== void 0 && rank !== KEEPA_NO_DATA_SENTINEL) return rank;
-  }
-  return null;
+  return pairKeepaSeries(salesRanks[String(rootCategory)]).at(-1)?.value ?? null;
 }
 
 // src/resources/products/products.ts
@@ -257,14 +347,14 @@ var Products = class extends APIResource {
       query: {
         domain,
         asin: asins,
-        days: params.days ?? DEFAULT_DAYS
+        days: params.days ?? DEFAULT_DAYS,
+        history: params.history ? 1 : 0
       },
       context: PRODUCT_LIST_CONTEXT
     });
     return (data.products ?? []).map(toKeepaProduct);
   }
-  /** Fetch a single product by ASIN. Throws `ProductNotFoundError` when Keepa
-   *  has no record for the ASIN (no product returned, or a stub with no title). */
+  /** Throws `ProductNotFoundError` when Keepa returns no product or a stub. */
   async retrieve(params) {
     const { asin, ...rest } = params;
     const [product] = await this.list({ ...rest, asins: [asin] });
@@ -282,6 +372,9 @@ var KeepaClient = class {
   baseURL;
   fetch;
   products;
+  /** Latest rate-limit snapshot from Keepa, updated after every response.
+   *  Null until the first request completes. */
+  rateLimit = null;
   constructor(options = {}) {
     const envApiKey = typeof process !== "undefined" ? process.env?.KEEPA_API_KEY : void 0;
     const apiKey = options.apiKey || envApiKey;
@@ -295,12 +388,14 @@ var KeepaClient = class {
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.products = new Products(this);
   }
-  /** Internal: used by APIResource subclasses to perform a request. */
   _request(args) {
     const config = {
       apiKey: this.apiKey,
       baseURL: this.baseURL,
-      fetch: this.fetch
+      fetch: this.fetch,
+      onRateLimit: (info) => {
+        this.rateLimit = info;
+      }
     };
     return request(config, args);
   }
@@ -316,6 +411,7 @@ var VERSION = "0.1.0";
   ASIN_LENGTH,
   ASIN_REGEX,
   AuthenticationError,
+  CsvType,
   DEFAULT_DAYS,
   KEEPA_NO_DATA_SENTINEL,
   KeepaClient,
@@ -332,6 +428,7 @@ var VERSION = "0.1.0";
   isFoundProduct,
   isValidAsin,
   normalizeAsins,
+  parsePriceHistory,
   resolveDomainId
 });
 //# sourceMappingURL=index.cjs.map