keepa-api 0.2.0 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # 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 `Keepa` client class exposes resources (`products`, etc.) that wrap each endpoint with typed inputs and responses.
+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.
 
@@ -49,9 +49,9 @@ npm install /absolute/path/to/keepa-api-0.1.0.tgz
 ## Quickstart
 
 ```ts
-import Keepa from 'keepa-api';
+import KeepaClient from 'keepa-api';
 
-const keepa = new Keepa({ apiKey: process.env.KEEPA_API_KEY });
+const keepa = new KeepaClient({ apiKey: process.env.KEEPA_API_KEY });
 
 const products = await keepa.products.list({
   asins: ['B00MNV8E0C'],
@@ -65,7 +65,7 @@ The client reads `process.env.KEEPA_API_KEY` if you don't pass `apiKey` explicit
 
 ## API
 
-### `new Keepa(options?)`
+### `new KeepaClient(options?)`
 
 | Option | Type | Default | Notes |
 |--------|------|---------|-------|
@@ -78,7 +78,7 @@ The client reads `process.env.KEEPA_API_KEY` if you don't pass `apiKey` explicit
 | Param | Type | Default | Notes |
 |-------|------|---------|-------|
 | `asins` | `string[]` | (required) | Validated + uppercased. Throws on malformed input. |
-| `marketplace` | `'US' \| 'UK' \| 'DE' \| 'FR' \| 'JP' \| 'CA' \| 'IT' \| 'ES' \| 'IN' \| 'MX' \| 'AU'` | `'US'` | Case-insensitive. Throws on unknown. |
+| `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). |
 
 The SDK maps Keepa's raw wire shape into a friendlier `KeepaProduct`:
@@ -88,7 +88,7 @@ The SDK maps Keepa's raw wire shape into a friendlier `KeepaProduct`:
 
 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.
 
-**Stub records:** Keepa returns one record per requested ASIN even when it has no data — these stubs have `title === undefined`. Filter with `isFoundProduct` (below).
+**Stub records:** Keepa returns one record per requested ASIN even when it has no data — these stubs have `title === null`. Filter with `isFoundProduct` (below).
 
 ### Helpers
 
@@ -105,7 +105,7 @@ for (const product of real) {
 
 | Helper | Signature | Returns |
 |--------|-----------|---------|
-| `isFoundProduct(product)` | `(product: KeepaProduct) => boolean` | `true` only if Keepa returned real data (`title` is non-empty). |
+| `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. |
@@ -133,17 +133,17 @@ normalizeAsins(['B07XYZ']);          // throws: Invalid ASIN(s): B07XYZ. ...
 import { MARKETPLACE_DOMAINS, resolveDomainId } from 'keepa-api';
 
 MARKETPLACE_DOMAINS.US;   // 1
-resolveDomainId('uk');    // 2 (case-insensitive)
+resolveDomainId('gb');    // 2 (case-insensitive)
 resolveDomainId(undefined); // 1 (defaults to US)
 ```
 
 | Code | Domain ID | Code | Domain ID |
 |------|-----------|------|-----------|
 | US   | 1         | IT   | 8         |
-| UK   | 2         | ES   | 9         |
+| GB   | 2         | ES   | 9         |
 | DE   | 3         | IN   | 10        |
 | FR   | 4         | MX   | 11        |
-| JP   | 5         | AU   | 13        |
+| JP   | 5         | BR   | 12        |
 | CA   | 6         |      |           |
 
 ### Errors

package/dist/client.d.ts

@@ -8,7 +8,7 @@ export interface ClientOptions {
     /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
     fetch?: typeof globalThis.fetch;
 }
-export declare class Keepa {
+export declare class KeepaClient {
     readonly apiKey: string;
     readonly baseURL: string;
     readonly fetch: typeof globalThis.fetch;
@@ -17,5 +17,5 @@ export declare class Keepa {
     /** Internal: used by APIResource subclasses to perform a request. */
     _request<T>(args: RequestArgs): Promise<T>;
 }
-export default Keepa;
+export default KeepaClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAID,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAExC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAEhB,OAAO,GAAE,aAAkB;IAuBvC,qEAAqE;IACrE,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAQ3C;AAED,eAAe,KAAK,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAID,qBAAa,WAAW;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAExC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAEhB,OAAO,GAAE,aAAkB;IAuBvC,qEAAqE;IACrE,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAQ3C;AAED,eAAe,WAAW,CAAC"}

package/dist/client.js

@@ -1,7 +1,7 @@
 import { request } from './core/request.js';
 import { Products } from './resources/products/products.js';
 const DEFAULT_BASE_URL = 'https://api.keepa.com';
-export class Keepa {
+export class KeepaClient {
     apiKey;
     baseURL;
     fetch;
@@ -13,7 +13,7 @@ export class Keepa {
         const envApiKey = typeof process !== 'undefined' ? process.env?.KEEPA_API_KEY : undefined;
         const apiKey = options.apiKey || envApiKey;
         if (!apiKey) {
-            throw new Error('Missing Keepa API key. Pass it as `new Keepa({ apiKey })` or set KEEPA_API_KEY in your environment.');
+            throw new Error('Missing Keepa API key. Pass it as `new KeepaClient({ apiKey })` or set KEEPA_API_KEY in your environment.');
         }
         this.apiKey = apiKey;
         // Strip a trailing slash so `${baseURL}${path}` never produces `//product`.
@@ -34,5 +34,5 @@ export class Keepa {
         return request(config, args);
     }
 }
-export default Keepa;
+export default KeepaClient;
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAW5D,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD,MAAM,OAAO,KAAK;IACP,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,KAAK,CAA0B;IAE/B,QAAQ,CAAW;IAE5B,YAAY,UAAyB,EAAE;QACrC,qFAAqF;QACrF,sFAAsF;QACtF,uCAAuC;QACvC,MAAM,SAAS,GACb,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,qGAAqG,CACtG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,4EAA4E;QAC5E,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,sEAAsE;QACtE,0EAA0E;QAC1E,sEAAsE;QACtE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEhE,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,qEAAqE;IACrE,QAAQ,CAAI,IAAiB;QAC3B,MAAM,MAAM,GAAkB;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;QACF,OAAO,OAAO,CAAI,MAAM,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;CACF;AAED,eAAe,KAAK,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAW5D,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD,MAAM,OAAO,WAAW;IACb,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,KAAK,CAA0B;IAE/B,QAAQ,CAAW;IAE5B,YAAY,UAAyB,EAAE;QACrC,qFAAqF;QACrF,sFAAsF;QACtF,uCAAuC;QACvC,MAAM,SAAS,GACb,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,2GAA2G,CAC5G,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,4EAA4E;QAC5E,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,sEAAsE;QACtE,0EAA0E;QAC1E,sEAAsE;QACtE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEhE,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,qEAAqE;IACrE,QAAQ,CAAI,IAAiB;QAC3B,MAAM,MAAM,GAAkB;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;QACF,OAAO,OAAO,CAAI,MAAM,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;CACF;AAED,eAAe,WAAW,CAAC"}

package/dist/core/resource.d.ts

@@ -1,6 +1,6 @@
-import type { Keepa } from '../client.js';
+import type { KeepaClient } from '../client.js';
 export declare abstract class APIResource {
-    protected _client: Keepa;
-    constructor(client: Keepa);
+    protected _client: KeepaClient;
+    constructor(client: KeepaClient);
 }
 //# sourceMappingURL=resource.d.ts.map

package/dist/core/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,8BAAsB,WAAW;IAC/B,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC;gBAEb,MAAM,EAAE,KAAK;CAG1B"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,8BAAsB,WAAW;IAC/B,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC;gBAEnB,MAAM,EAAE,WAAW;CAGhC"}

package/dist/core/resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAEA,MAAM,OAAgB,WAAW;IACrB,OAAO,CAAQ;IAEzB,YAAY,MAAa;QACvB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;CACF"}
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAEA,MAAM,OAAgB,WAAW;IACrB,OAAO,CAAc;IAE/B,YAAY,MAAmB;QAC7B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Keepa as default, Keepa, type ClientOptions } from './client.js';
+export { KeepaClient as default, KeepaClient, type ClientOptions } from './client.js';
 export { KeepaError, APIError, RateLimitError, AuthenticationError, NetworkError, } from './core/error.js';
 export { APIResource } from './core/resource.js';
 export { MARKETPLACE_DOMAINS, resolveDomainId, type Marketplace, type DomainId, } from './lib/marketplace.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,UAAU,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,QAAQ,GACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EACL,UAAU,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,QAAQ,GACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Keepa as default, Keepa } from './client.js';
+export { KeepaClient as default, KeepaClient } from './client.js';
 export { KeepaError, APIError, RateLimitError, AuthenticationError, NetworkError, } from './core/error.js';
 export { APIResource } from './core/resource.js';
 export { MARKETPLACE_DOMAINS, resolveDomainId, } from './lib/marketplace.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,KAAK,EAAsB,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,UAAU,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,mBAAmB,EACnB,eAAe,GAGhB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAEtF,OAAO,EACL,UAAU,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,mBAAmB,EACnB,eAAe,GAGhB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/lib/marketplace.d.ts

@@ -1,6 +1,6 @@
 export declare const MARKETPLACE_DOMAINS: {
     readonly US: 1;
-    readonly UK: 2;
+    readonly GB: 2;
     readonly DE: 3;
     readonly FR: 4;
     readonly JP: 5;
@@ -9,7 +9,7 @@ export declare const MARKETPLACE_DOMAINS: {
     readonly ES: 9;
     readonly IN: 10;
     readonly MX: 11;
-    readonly AU: 13;
+    readonly BR: 12;
 };
 export type Marketplace = keyof typeof MARKETPLACE_DOMAINS;
 export type DomainId = (typeof MARKETPLACE_DOMAINS)[Marketplace];

package/dist/lib/marketplace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marketplace.d.ts","sourceRoot":"","sources":["../../src/lib/marketplace.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;CAYtB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,WAAW,CAAC,CAAC;AAIjE,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CASzE"}
+{"version":3,"file":"marketplace.d.ts","sourceRoot":"","sources":["../../src/lib/marketplace.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;CAYtB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,WAAW,CAAC,CAAC;AAIjE,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CASzE"}

package/dist/lib/marketplace.js

@@ -1,9 +1,10 @@
-// The 11 marketplaces consumed by the existing internal projects. Keepa supports more
-// (AE, NL, PL, SE, BR, TR, …); extend this map and the README marketplace table when
-// a new region is needed. The numeric id is Keepa's `domain` query parameter value.
+// The full set of marketplaces Keepa currently supports. Codes are ISO 3166-1
+// alpha-2; the numeric id is Keepa's `domain` query parameter value. Domain 7
+// is reserved (formerly Amazon China, retired). Update the README marketplace
+// table alongside any change here.
 export const MARKETPLACE_DOMAINS = {
     US: 1,
-    UK: 2,
+    GB: 2,
     DE: 3,
     FR: 4,
     JP: 5,
@@ -12,7 +13,7 @@ export const MARKETPLACE_DOMAINS = {
     ES: 9,
     IN: 10,
     MX: 11,
-    AU: 13,
+    BR: 12,
 };
 const SUPPORTED_LIST = Object.keys(MARKETPLACE_DOMAINS).join(', ');
 export function resolveDomainId(marketplace) {

package/dist/lib/marketplace.js.map

@@ -1 +1 @@
-{"version":3,"file":"marketplace.js","sourceRoot":"","sources":["../../src/lib/marketplace.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,qFAAqF;AACrF,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;CACE,CAAC;AAKX,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEnE,MAAM,UAAU,eAAe,CAAC,WAA+B;IAC7D,MAAM,GAAG,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,WAAW,EAAiB,CAAC;IAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,wBAAwB,WAAW,iBAAiB,cAAc,EAAE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"marketplace.js","sourceRoot":"","sources":["../../src/lib/marketplace.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,mCAAmC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;CACE,CAAC;AAKX,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEnE,MAAM,UAAU,eAAe,CAAC,WAA+B;IAC7D,MAAM,GAAG,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,WAAW,EAAiB,CAAC;IAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,wBAAwB,WAAW,iBAAiB,cAAc,EAAE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/resources/products/error.d.ts

@@ -0,0 +1,10 @@
+import { KeepaError } from '../../core/error.js';
+/** Thrown by `Products.retrieve` when Keepa has no record for the requested ASIN
+ *  (either no product object returned, or a stub with no title). The `asin`
+ *  property carries the value the caller passed in, unchanged, so it can be
+ *  surfaced in user-facing messages without re-deriving it. */
+export declare class ProductNotFoundError extends KeepaError {
+    readonly asin: string;
+    constructor(asin: string);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/resources/products/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/resources/products/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;+DAG+D;AAC/D,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB"}

package/dist/resources/products/error.js

@@ -0,0 +1,14 @@
+import { KeepaError } from '../../core/error.js';
+/** Thrown by `Products.retrieve` when Keepa has no record for the requested ASIN
+ *  (either no product object returned, or a stub with no title). The `asin`
+ *  property carries the value the caller passed in, unchanged, so it can be
+ *  surfaced in user-facing messages without re-deriving it. */
+export class ProductNotFoundError extends KeepaError {
+    asin;
+    constructor(asin) {
+        super(`Keepa: no product found for ASIN ${asin}`);
+        this.name = 'ProductNotFoundError';
+        this.asin = asin;
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/resources/products/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/resources/products/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;+DAG+D;AAC/D,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IACzC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CAAC,oCAAoC,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/resources/products/index.d.ts

@@ -1,4 +1,6 @@
-export { Products, extractBsr, isFoundProduct } from './products.js';
-export type { ProductListParams, KeepaProduct, KeepaVariation, KeepaVariationAttribute, KeepaCategoryNode, } from './product.type.js';
+export { Products } from './products.js';
+export { extractBsr, isFoundProduct } from './product.util.js';
+export { ProductNotFoundError } from './error.js';
+export type { ProductListParams, ProductRetrieveParams, KeepaProduct, KeepaVariation, KeepaVariationAttribute, KeepaCategoryNode, } from './product.type.js';
 export { PRODUCT_PATH, PRODUCT_LIST_CONTEXT, DEFAULT_DAYS, AMAZON_IMAGE_BASE, KEEPA_NO_DATA_SENTINEL, } from './constant.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/resources/products/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resources/products/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resources/products/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,eAAe,CAAC"}

package/dist/resources/products/index.js

@@ -1,4 +1,6 @@
-export { Products, extractBsr, isFoundProduct } from './products.js';
+export { Products } from './products.js';
+export { extractBsr, isFoundProduct } from './product.util.js';
+export { ProductNotFoundError } from './error.js';
 // NOTE: raw Keepa wire types (KeepaProductRaw, KeepaProductResponseRaw) are
 // intentionally NOT re-exported. They are an implementation detail — Products.list
 // maps them to the consumer-friendly KeepaProduct shape before returning.

package/dist/resources/products/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/resources/products/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAUrE,4EAA4E;AAC5E,mFAAmF;AACnF,0EAA0E;AAE1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/resources/products/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAWlD,4EAA4E;AAC5E,mFAAmF;AACnF,0EAA0E;AAE1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,eAAe,CAAC"}

package/dist/resources/products/product.type.d.ts

@@ -6,6 +6,13 @@ export interface ProductListParams {
     /** Days of price history to include. Defaults to 1. */
     days?: number;
 }
+export interface ProductRetrieveParams {
+    asin: string;
+    /** Marketplace code (case-insensitive at runtime). Defaults to 'US'. */
+    marketplace?: Marketplace;
+    /** Days of price history to include. Defaults to 1. */
+    days?: number;
+}
 export interface KeepaCategoryNode {
     catId: number;
     name: string;

package/dist/resources/products/product.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product.type.d.ts","sourceRoot":"","sources":["../../../src/resources/products/product.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACxC;AAED;;;+DAG+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,gFAAgF;IAChF,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;oDACgD;IAChD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB"}
+{"version":3,"file":"product.type.d.ts","sourceRoot":"","sources":["../../../src/resources/products/product.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACxC;AAED;;;+DAG+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,gFAAgF;IAChF,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;oDACgD;IAChD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB"}

package/dist/resources/products/product.util.d.ts

@@ -0,0 +1,15 @@
+import type { KeepaProduct } from './product.type.js';
+import type { KeepaProductRaw } from './product.raw.type.js';
+/** Map Keepa's raw wire shape into the consumer-friendly KeepaProduct. */
+export declare function toKeepaProduct(raw: KeepaProductRaw): KeepaProduct;
+/** Returns true when Keepa returned an actual product record (not just a stub
+ *  for an unknown ASIN). Stubs come back with `title: null`; real listings
+ *  always have a string. Use as a `.filter()` predicate to drop empty matches. */
+export declare function isFoundProduct(product: KeepaProduct): boolean;
+/** Extract the most recent real BSR from Keepa's `[ts, rank, ts, rank, ...]` salesRanks array.
+ *  Walks backward through rank entries (odd indices) and skips Keepa's `-1` sentinel which
+ *  marks "no data captured at that timestamp". Returns `null` if every entry is sentinel.
+ *  Most consumers won't need this — `Products.list` already fills `bsr` on every returned
+ *  product. Useful when working with a raw Keepa response. */
+export declare function extractBsr(salesRanks: Record<string, number[]> | undefined, rootCategory: number | undefined): number | null;
+//# sourceMappingURL=product.util.d.ts.map

package/dist/resources/products/product.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product.util.d.ts","sourceRoot":"","sources":["../../../src/resources/products/product.util.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE5E,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CAcjE;AAYD;;kFAEkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAE7D;AAED;;;;8DAI8D;AAC9D,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,EAChD,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAaf"}

package/dist/resources/products/product.util.js

@@ -0,0 +1,56 @@
+import { AMAZON_IMAGE_BASE, KEEPA_NO_DATA_SENTINEL, VALID_IMAGE_FILENAME, } from './constant.js';
+/** Map Keepa's raw wire shape into the consumer-friendly KeepaProduct. */
+export function toKeepaProduct(raw) {
+    return {
+        asin: raw.asin,
+        title: raw.title,
+        description: raw.description,
+        parentAsin: raw.parentAsin,
+        categoryTree: raw.categoryTree,
+        rootCategory: raw.rootCategory,
+        salesRanks: raw.salesRanks,
+        variations: raw.variations,
+        features: raw.features,
+        images: rawImagesToUrls(raw.images),
+        bsr: extractBsr(raw.salesRanks, raw.rootCategory),
+    };
+}
+/** Convert Keepa's raw images array into full Amazon image URLs (the large
+ *  variant). Filters entries whose filename doesn't match the expected
+ *  alphanumeric image-name pattern as defense-in-depth. */
+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}`);
+}
+/** Returns true when Keepa returned an actual product record (not just a stub
+ *  for an unknown ASIN). Stubs come back with `title: null`; real listings
+ *  always have a string. Use as a `.filter()` predicate to drop empty matches. */
+export function isFoundProduct(product) {
+    return product.title != null;
+}
+/** Extract the most recent real BSR from Keepa's `[ts, rank, ts, rank, ...]` salesRanks array.
+ *  Walks backward through rank entries (odd indices) and skips Keepa's `-1` sentinel which
+ *  marks "no data captured at that timestamp". Returns `null` if every entry is sentinel.
+ *  Most consumers won't need this — `Products.list` already fills `bsr` on every returned
+ *  product. Useful when working with a raw Keepa response. */
+export function extractBsr(salesRanks, rootCategory) {
+    if (!salesRanks || rootCategory === undefined)
+        return null;
+    const ranks = salesRanks[String(rootCategory)];
+    if (!ranks || ranks.length < 2)
+        return null;
+    // Keepa pairs are [ts, rank, ts, rank, ...]. If length is even, the last index
+    // is a rank; if odd (truncated/schema drift), it's a dangling timestamp — skip
+    // back one slot so we always start on a rank.
+    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 !== undefined && rank !== KEEPA_NO_DATA_SENTINEL)
+            return rank;
+    }
+    return null;
+}
+//# sourceMappingURL=product.util.js.map

package/dist/resources/products/product.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product.util.js","sourceRoot":"","sources":["../../../src/resources/products/product.util.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAIvB,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,GAAoB;IACjD,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;QACnC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC;KAClD,CAAC;AACJ,CAAC;AAED;;2DAE2D;AAC3D,SAAS,eAAe,CAAC,MAAmC;IAC1D,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9C,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SAC9E,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,iBAAiB,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;kFAEkF;AAClF,MAAM,UAAU,cAAc,CAAC,OAAqB;IAClD,OAAO,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED;;;;8DAI8D;AAC9D,MAAM,UAAU,UAAU,CACxB,UAAgD,EAChD,YAAgC;IAEhC,IAAI,CAAC,UAAU,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,+EAA+E;IAC/E,+EAA+E;IAC/E,8CAA8C;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3E,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,sBAAsB;YAAE,OAAO,IAAI,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/resources/products/products.d.ts

@@ -1,21 +1,9 @@
 import { APIResource } from '../../core/resource.js';
-import type { KeepaProduct, ProductListParams } from './product.type.js';
+import type { KeepaProduct, ProductListParams, ProductRetrieveParams } from './product.type.js';
 export declare class Products extends APIResource {
     list(params: ProductListParams): Promise<KeepaProduct[]>;
+    /** 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). */
+    retrieve(params: ProductRetrieveParams): Promise<KeepaProduct>;
 }
-/** Returns true when Keepa returned an actual product record (not just a stub
- *  for an unknown ASIN). Use as a `.filter()` predicate to drop empty matches.
- *
- *  We use `title.length > 0` because it's the strongest single correlate of
- *  "Keepa has data" — stubs for unknown ASINs come back without a title, and
- *  every real listing has one. If Keepa's stub format changes (e.g. they start
- *  returning a placeholder title), tighten this predicate to also require
- *  `categoryTree` or another non-string field. */
-export declare function isFoundProduct(product: KeepaProduct): boolean;
-/** Extract the most recent real BSR from Keepa's `[ts, rank, ts, rank, ...]` salesRanks array.
- *  Walks backward through rank entries (odd indices) and skips Keepa's `-1` sentinel which
- *  marks "no data captured at that timestamp". Returns `null` if every entry is sentinel.
- *  Most consumers won't need this — `Products.list` already fills `bsr` on every returned
- *  product. Useful when working with a raw Keepa response. */
-export declare function extractBsr(salesRanks: Record<string, number[]> | undefined, rootCategory: number | undefined): number | null;
 //# sourceMappingURL=products.d.ts.map

package/dist/resources/products/products.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"products.d.ts","sourceRoot":"","sources":["../../../src/resources/products/products.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAWrD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAOzE,qBAAa,QAAS,SAAQ,WAAW;IACjC,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAuB/D;AA6BD;;;;;;;kDAOkD;AAClD,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAE7D;AAED;;;;8DAI8D;AAC9D,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,EAChD,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAaf"}
+{"version":3,"file":"products.d.ts","sourceRoot":"","sources":["../../../src/resources/products/products.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAQrD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAK3B,qBAAa,QAAS,SAAQ,WAAW;IACjC,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwB9D;qFACiF;IAC3E,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;CAQrE"}

package/dist/resources/products/products.js

@@ -1,7 +1,9 @@
 import { APIResource } from '../../core/resource.js';
 import { resolveDomainId } from '../../lib/marketplace.js';
 import { normalizeAsins } from '../../lib/asin.js';
-import { PRODUCT_PATH, PRODUCT_LIST_CONTEXT, DEFAULT_DAYS, AMAZON_IMAGE_BASE, KEEPA_NO_DATA_SENTINEL, VALID_IMAGE_FILENAME, } from './constant.js';
+import { PRODUCT_PATH, PRODUCT_LIST_CONTEXT, DEFAULT_DAYS, } from './constant.js';
+import { ProductNotFoundError } from './error.js';
+import { toKeepaProduct, isFoundProduct } from './product.util.js';
 export class Products extends APIResource {
     async list(params) {
         if (params.asins.length === 0) {
@@ -24,64 +26,15 @@ export class Products extends APIResource {
         });
         return (data.products ?? []).map(toKeepaProduct);
     }
-}
-/** Map Keepa's raw wire shape into the consumer-friendly KeepaProduct. */
-function toKeepaProduct(raw) {
-    return {
-        asin: raw.asin,
-        title: raw.title,
-        description: raw.description,
-        parentAsin: raw.parentAsin,
-        categoryTree: raw.categoryTree,
-        rootCategory: raw.rootCategory,
-        salesRanks: raw.salesRanks,
-        variations: raw.variations,
-        features: raw.features,
-        images: rawImagesToUrls(raw.images),
-        bsr: extractBsr(raw.salesRanks, raw.rootCategory),
-    };
-}
-/** Convert Keepa's raw images array into full Amazon image URLs (the large
- *  variant). Filters entries whose filename doesn't match the expected
- *  alphanumeric image-name pattern as defense-in-depth. */
-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}`);
-}
-/** Returns true when Keepa returned an actual product record (not just a stub
- *  for an unknown ASIN). Use as a `.filter()` predicate to drop empty matches.
- *
- *  We use `title.length > 0` because it's the strongest single correlate of
- *  "Keepa has data" — stubs for unknown ASINs come back without a title, and
- *  every real listing has one. If Keepa's stub format changes (e.g. they start
- *  returning a placeholder title), tighten this predicate to also require
- *  `categoryTree` or another non-string field. */
-export function isFoundProduct(product) {
-    return typeof product.title === 'string' && product.title.length > 0;
-}
-/** Extract the most recent real BSR from Keepa's `[ts, rank, ts, rank, ...]` salesRanks array.
- *  Walks backward through rank entries (odd indices) and skips Keepa's `-1` sentinel which
- *  marks "no data captured at that timestamp". Returns `null` if every entry is sentinel.
- *  Most consumers won't need this — `Products.list` already fills `bsr` on every returned
- *  product. Useful when working with a raw Keepa response. */
-export function extractBsr(salesRanks, rootCategory) {
-    if (!salesRanks || rootCategory === undefined)
-        return null;
-    const ranks = salesRanks[String(rootCategory)];
-    if (!ranks || ranks.length < 2)
-        return null;
-    // Keepa pairs are [ts, rank, ts, rank, ...]. If length is even, the last index
-    // is a rank; if odd (truncated/schema drift), it's a dangling timestamp — skip
-    // back one slot so we always start on a rank.
-    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 !== undefined && rank !== KEEPA_NO_DATA_SENTINEL)
-            return rank;
+    /** 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). */
+    async retrieve(params) {
+        const { asin, ...rest } = params;
+        const [product] = await this.list({ ...rest, asins: [asin] });
+        if (!product || !isFoundProduct(product)) {
+            throw new ProductNotFoundError(asin);
+        }
+        return product;
     }
-    return null;
 }
 //# sourceMappingURL=products.js.map

package/dist/resources/products/products.js.map

@@ -1 +1 @@
-{"version":3,"file":"products.js","sourceRoot":"","sources":["../../../src/resources/products/products.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"products.js","sourceRoot":"","sources":["../../../src/resources/products/products.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GACb,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnE,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC,KAAK,CAAC,IAAI,CAAC,MAAyB;QAClC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,IACE,MAAM,CAAC,IAAI,KAAK,SAAS;YACzB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,EACnD,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,IAAI,+BAA+B,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAA0B;YAChE,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE;gBACL,MAAM;gBACN,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,YAAY;aAClC;YACD,OAAO,EAAE,oBAAoB;SAC9B,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACnD,CAAC;IAED;qFACiF;IACjF,KAAK,CAAC,QAAQ,CAAC,MAA6B;QAC1C,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACjC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keepa-api",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "TypeScript SDK for the Keepa API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,6 +35,14 @@
     "asin"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bilalyasin1616/keepa-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bilalyasin1616/keepa-api/issues"
+  },
+  "homepage": "https://github.com/bilalyasin1616/keepa-api#readme",
   "devDependencies": {
     "@types/node": "^22.10.0",
     "dotenv": "^16.4.0",