keepa-api 0.2.3 → 0.3.1

package/dist/index.d.cts

@@ -0,0 +1,206 @@
+type QueryValue = string | number | string[] | number[] | undefined;
+type QueryParams = Record<string, QueryValue>;
+interface RequestArgs {
+    path: string;
+    query?: QueryParams;
+    context: string;
+}
+
+declare abstract class APIResource {
+    protected _client: KeepaClient;
+    constructor(client: KeepaClient);
+}
+
+declare const MARKETPLACE_DOMAINS: {
+    readonly US: 1;
+    readonly GB: 2;
+    readonly DE: 3;
+    readonly FR: 4;
+    readonly JP: 5;
+    readonly CA: 6;
+    readonly IT: 8;
+    readonly ES: 9;
+    readonly IN: 10;
+    readonly MX: 11;
+    readonly BR: 12;
+};
+type Marketplace = keyof typeof MARKETPLACE_DOMAINS;
+type DomainId = (typeof MARKETPLACE_DOMAINS)[Marketplace];
+declare function resolveDomainId(marketplace: string | undefined): DomainId;
+
+interface ProductRequestOptions {
+    /** Case-insensitive at runtime. Defaults to 'US'. */
+    marketplace?: Marketplace;
+    /** Defaults to 1. */
+    days?: number;
+    /** When true, populates `history.price.*` and the scalar `price` / `listPrice`
+     *  fields on each returned product. Increases token cost. */
+    history?: boolean;
+}
+interface ProductListParams extends ProductRequestOptions {
+    asins: string[];
+}
+interface ProductRetrieveParams extends ProductRequestOptions {
+    asin: string;
+}
+interface KeepaCategoryNode {
+    catId: number;
+    name: string;
+}
+interface KeepaVariationAttribute {
+    dimension: string;
+    value: string;
+}
+interface KeepaVariation {
+    asin: string;
+    attributes?: KeepaVariationAttribute[];
+}
+interface PriceHistoryEntry {
+    timestamp: Date;
+    /** Marketplace's major unit — dollars for US, pounds for GB, yen for JP, etc. */
+    price: number;
+}
+/** Flag-gated fields (`price`, `listPrice`, `history.price.*`) are always present
+ *  on the type and default to empty/null when the corresponding request flag
+ *  wasn't set. */
+interface KeepaProduct {
+    asin: string;
+    title?: string;
+    description?: string;
+    parentAsin?: string;
+    categoryTree?: KeepaCategoryNode[];
+    rootCategory?: number;
+    salesRanks?: Record<string, number[]>;
+    variations?: KeepaVariation[];
+    features?: string[];
+    images: string[];
+    /** Null when missing or every history entry is Keepa's `-1` no-data sentinel. */
+    bsr: number | null;
+    /** Latest entry from `history.price.amazon`; null when history wasn't
+     *  requested or Keepa has no data. Marketplace's major unit. */
+    price: number | null;
+    /** Latest entry from `history.price.list`; null when unavailable.
+     *  Marketplace's major unit. */
+    listPrice: number | null;
+    history: {
+        price: {
+            /** Empty when `history: false`. Sentinel-filtered. */
+            amazon: PriceHistoryEntry[];
+            /** Empty when `history: false`. Sentinel-filtered. */
+            list: PriceHistoryEntry[];
+        };
+    };
+}
+
+declare class Products extends APIResource {
+    list(params: ProductListParams): Promise<KeepaProduct[]>;
+    /** Throws `ProductNotFoundError` when Keepa returns no product or a stub. */
+    retrieve(params: ProductRetrieveParams): Promise<KeepaProduct>;
+}
+
+interface ClientOptions {
+    /** Falls back to `process.env.KEEPA_API_KEY` when omitted. */
+    apiKey?: string;
+    baseURL?: string;
+    fetch?: typeof globalThis.fetch;
+}
+declare class KeepaClient {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly fetch: typeof globalThis.fetch;
+    readonly products: Products;
+    constructor(options?: ClientOptions);
+    _request<T>(args: RequestArgs): Promise<T>;
+}
+
+declare class KeepaError extends Error {
+    constructor(message: string);
+}
+declare class APIError extends KeepaError {
+    readonly status: number;
+    readonly context: string;
+    readonly body: string;
+    constructor(status: number, context: string, body: string, message?: string);
+    static from(response: Response, context: string): Promise<APIError>;
+}
+declare class RateLimitError extends APIError {
+    constructor(context: string, body: string);
+}
+declare class AuthenticationError extends APIError {
+    constructor(context: string, body: string);
+}
+declare class NetworkError extends KeepaError {
+    readonly context: string;
+    readonly cause: unknown;
+    constructor(context: string, cause: unknown);
+}
+
+declare const ASIN_LENGTH = 10;
+declare const ASIN_REGEX: RegExp;
+/** Structural check only — a passing ASIN may still not exist in Keepa's
+ *  database; use `isFoundProduct` for that. */
+declare function isValidAsin(value: string): boolean;
+declare function normalizeAsins(asins: string[]): string[];
+
+declare function parsePriceHistory(series: number[] | undefined): PriceHistoryEntry[];
+/** Stubs for unknown ASINs come back with `title: null`. */
+declare function isFoundProduct(product: KeepaProduct): boolean;
+/** Latest non-sentinel rank from Keepa's `[ts, rank, ts, rank, ...]` salesRanks
+ *  series for the product's rootCategory. */
+declare function extractBsr(salesRanks: Record<string, number[]> | undefined, rootCategory: number | undefined): number | null;
+
+/** Thrown when Keepa returns no product, or returns a stub (title === null).
+ *  `asin` carries the caller's original input unchanged. */
+declare class ProductNotFoundError extends KeepaError {
+    readonly asin: string;
+    constructor(asin: string);
+}
+
+declare const PRODUCT_PATH = "/product";
+declare const PRODUCT_LIST_CONTEXT = "products.list";
+declare const DEFAULT_DAYS = 1;
+declare const AMAZON_IMAGE_BASE = "https://m.media-amazon.com/images/I";
+declare const KEEPA_NO_DATA_SENTINEL = -1;
+declare const CsvType: {
+    readonly AMAZON: 0;
+    readonly NEW: 1;
+    readonly USED: 2;
+    readonly SALES: 3;
+    readonly LISTPRICE: 4;
+    readonly COLLECTIBLE: 5;
+    readonly REFURBISHED: 6;
+    readonly NEW_FBM_SHIPPING: 7;
+    readonly LIGHTNING_DEAL: 8;
+    readonly WAREHOUSE: 9;
+    readonly NEW_FBA: 10;
+    readonly COUNT_NEW: 11;
+    readonly COUNT_USED: 12;
+    readonly COUNT_REFURBISHED: 13;
+    readonly COUNT_COLLECTIBLE: 14;
+    readonly EXTRA_INFO_UPDATES: 15;
+    readonly RATING: 16;
+    readonly COUNT_REVIEWS: 17;
+    readonly BUY_BOX_SHIPPING: 18;
+    readonly USED_NEW_SHIPPING: 19;
+    readonly USED_VERY_GOOD_SHIPPING: 20;
+    readonly USED_GOOD_SHIPPING: 21;
+    readonly USED_ACCEPTABLE_SHIPPING: 22;
+    readonly COLLECTIBLE_NEW_SHIPPING: 23;
+    readonly COLLECTIBLE_VERY_GOOD_SHIPPING: 24;
+    readonly COLLECTIBLE_GOOD_SHIPPING: 25;
+    readonly COLLECTIBLE_ACCEPTABLE_SHIPPING: 26;
+    readonly REFURBISHED_SHIPPING: 27;
+    readonly EBAY_NEW_SHIPPING: 28;
+    readonly EBAY_USED_SHIPPING: 29;
+    readonly TRADE_IN: 30;
+    readonly RENTAL: 31;
+    readonly BUY_BOX_USED_SHIPPING: 32;
+    readonly PRIME_EXCL: 33;
+    readonly COUNT_NEW_FBA: 34;
+    readonly COUNT_NEW_FBM: 35;
+};
+type CsvType = (typeof CsvType)[keyof typeof CsvType];
+
+declare const VERSION = "0.1.0";
+
+export { AMAZON_IMAGE_BASE, APIError, APIResource, ASIN_LENGTH, ASIN_REGEX, AuthenticationError, type ClientOptions, CsvType, DEFAULT_DAYS, type DomainId, KEEPA_NO_DATA_SENTINEL, type KeepaCategoryNode, KeepaClient, KeepaError, type KeepaProduct, type KeepaVariation, type KeepaVariationAttribute, MARKETPLACE_DOMAINS, type Marketplace, NetworkError, PRODUCT_LIST_CONTEXT, PRODUCT_PATH, type PriceHistoryEntry, type ProductListParams, ProductNotFoundError, type ProductRequestOptions, type ProductRetrieveParams, Products, RateLimitError, VERSION, KeepaClient as default, extractBsr, isFoundProduct, isValidAsin, normalizeAsins, parsePriceHistory, resolveDomainId };

package/dist/index.d.ts

@@ -1,8 +1,206 @@
-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';
-export { ASIN_LENGTH, ASIN_REGEX, isValidAsin, normalizeAsins, } from './lib/asin.js';
-export * from './resources/index.js';
-export { VERSION } from './version.js';
-//# sourceMappingURL=index.d.ts.map
+type QueryValue = string | number | string[] | number[] | undefined;
+type QueryParams = Record<string, QueryValue>;
+interface RequestArgs {
+    path: string;
+    query?: QueryParams;
+    context: string;
+}
+
+declare abstract class APIResource {
+    protected _client: KeepaClient;
+    constructor(client: KeepaClient);
+}
+
+declare const MARKETPLACE_DOMAINS: {
+    readonly US: 1;
+    readonly GB: 2;
+    readonly DE: 3;
+    readonly FR: 4;
+    readonly JP: 5;
+    readonly CA: 6;
+    readonly IT: 8;
+    readonly ES: 9;
+    readonly IN: 10;
+    readonly MX: 11;
+    readonly BR: 12;
+};
+type Marketplace = keyof typeof MARKETPLACE_DOMAINS;
+type DomainId = (typeof MARKETPLACE_DOMAINS)[Marketplace];
+declare function resolveDomainId(marketplace: string | undefined): DomainId;
+
+interface ProductRequestOptions {
+    /** Case-insensitive at runtime. Defaults to 'US'. */
+    marketplace?: Marketplace;
+    /** Defaults to 1. */
+    days?: number;
+    /** When true, populates `history.price.*` and the scalar `price` / `listPrice`
+     *  fields on each returned product. Increases token cost. */
+    history?: boolean;
+}
+interface ProductListParams extends ProductRequestOptions {
+    asins: string[];
+}
+interface ProductRetrieveParams extends ProductRequestOptions {
+    asin: string;
+}
+interface KeepaCategoryNode {
+    catId: number;
+    name: string;
+}
+interface KeepaVariationAttribute {
+    dimension: string;
+    value: string;
+}
+interface KeepaVariation {
+    asin: string;
+    attributes?: KeepaVariationAttribute[];
+}
+interface PriceHistoryEntry {
+    timestamp: Date;
+    /** Marketplace's major unit — dollars for US, pounds for GB, yen for JP, etc. */
+    price: number;
+}
+/** Flag-gated fields (`price`, `listPrice`, `history.price.*`) are always present
+ *  on the type and default to empty/null when the corresponding request flag
+ *  wasn't set. */
+interface KeepaProduct {
+    asin: string;
+    title?: string;
+    description?: string;
+    parentAsin?: string;
+    categoryTree?: KeepaCategoryNode[];
+    rootCategory?: number;
+    salesRanks?: Record<string, number[]>;
+    variations?: KeepaVariation[];
+    features?: string[];
+    images: string[];
+    /** Null when missing or every history entry is Keepa's `-1` no-data sentinel. */
+    bsr: number | null;
+    /** Latest entry from `history.price.amazon`; null when history wasn't
+     *  requested or Keepa has no data. Marketplace's major unit. */
+    price: number | null;
+    /** Latest entry from `history.price.list`; null when unavailable.
+     *  Marketplace's major unit. */
+    listPrice: number | null;
+    history: {
+        price: {
+            /** Empty when `history: false`. Sentinel-filtered. */
+            amazon: PriceHistoryEntry[];
+            /** Empty when `history: false`. Sentinel-filtered. */
+            list: PriceHistoryEntry[];
+        };
+    };
+}
+
+declare class Products extends APIResource {
+    list(params: ProductListParams): Promise<KeepaProduct[]>;
+    /** Throws `ProductNotFoundError` when Keepa returns no product or a stub. */
+    retrieve(params: ProductRetrieveParams): Promise<KeepaProduct>;
+}
+
+interface ClientOptions {
+    /** Falls back to `process.env.KEEPA_API_KEY` when omitted. */
+    apiKey?: string;
+    baseURL?: string;
+    fetch?: typeof globalThis.fetch;
+}
+declare class KeepaClient {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly fetch: typeof globalThis.fetch;
+    readonly products: Products;
+    constructor(options?: ClientOptions);
+    _request<T>(args: RequestArgs): Promise<T>;
+}
+
+declare class KeepaError extends Error {
+    constructor(message: string);
+}
+declare class APIError extends KeepaError {
+    readonly status: number;
+    readonly context: string;
+    readonly body: string;
+    constructor(status: number, context: string, body: string, message?: string);
+    static from(response: Response, context: string): Promise<APIError>;
+}
+declare class RateLimitError extends APIError {
+    constructor(context: string, body: string);
+}
+declare class AuthenticationError extends APIError {
+    constructor(context: string, body: string);
+}
+declare class NetworkError extends KeepaError {
+    readonly context: string;
+    readonly cause: unknown;
+    constructor(context: string, cause: unknown);
+}
+
+declare const ASIN_LENGTH = 10;
+declare const ASIN_REGEX: RegExp;
+/** Structural check only — a passing ASIN may still not exist in Keepa's
+ *  database; use `isFoundProduct` for that. */
+declare function isValidAsin(value: string): boolean;
+declare function normalizeAsins(asins: string[]): string[];
+
+declare function parsePriceHistory(series: number[] | undefined): PriceHistoryEntry[];
+/** Stubs for unknown ASINs come back with `title: null`. */
+declare function isFoundProduct(product: KeepaProduct): boolean;
+/** Latest non-sentinel rank from Keepa's `[ts, rank, ts, rank, ...]` salesRanks
+ *  series for the product's rootCategory. */
+declare function extractBsr(salesRanks: Record<string, number[]> | undefined, rootCategory: number | undefined): number | null;
+
+/** Thrown when Keepa returns no product, or returns a stub (title === null).
+ *  `asin` carries the caller's original input unchanged. */
+declare class ProductNotFoundError extends KeepaError {
+    readonly asin: string;
+    constructor(asin: string);
+}
+
+declare const PRODUCT_PATH = "/product";
+declare const PRODUCT_LIST_CONTEXT = "products.list";
+declare const DEFAULT_DAYS = 1;
+declare const AMAZON_IMAGE_BASE = "https://m.media-amazon.com/images/I";
+declare const KEEPA_NO_DATA_SENTINEL = -1;
+declare const CsvType: {
+    readonly AMAZON: 0;
+    readonly NEW: 1;
+    readonly USED: 2;
+    readonly SALES: 3;
+    readonly LISTPRICE: 4;
+    readonly COLLECTIBLE: 5;
+    readonly REFURBISHED: 6;
+    readonly NEW_FBM_SHIPPING: 7;
+    readonly LIGHTNING_DEAL: 8;
+    readonly WAREHOUSE: 9;
+    readonly NEW_FBA: 10;
+    readonly COUNT_NEW: 11;
+    readonly COUNT_USED: 12;
+    readonly COUNT_REFURBISHED: 13;
+    readonly COUNT_COLLECTIBLE: 14;
+    readonly EXTRA_INFO_UPDATES: 15;
+    readonly RATING: 16;
+    readonly COUNT_REVIEWS: 17;
+    readonly BUY_BOX_SHIPPING: 18;
+    readonly USED_NEW_SHIPPING: 19;
+    readonly USED_VERY_GOOD_SHIPPING: 20;
+    readonly USED_GOOD_SHIPPING: 21;
+    readonly USED_ACCEPTABLE_SHIPPING: 22;
+    readonly COLLECTIBLE_NEW_SHIPPING: 23;
+    readonly COLLECTIBLE_VERY_GOOD_SHIPPING: 24;
+    readonly COLLECTIBLE_GOOD_SHIPPING: 25;
+    readonly COLLECTIBLE_ACCEPTABLE_SHIPPING: 26;
+    readonly REFURBISHED_SHIPPING: 27;
+    readonly EBAY_NEW_SHIPPING: 28;
+    readonly EBAY_USED_SHIPPING: 29;
+    readonly TRADE_IN: 30;
+    readonly RENTAL: 31;
+    readonly BUY_BOX_USED_SHIPPING: 32;
+    readonly PRIME_EXCL: 33;
+    readonly COUNT_NEW_FBA: 34;
+    readonly COUNT_NEW_FBM: 35;
+};
+type CsvType = (typeof CsvType)[keyof typeof CsvType];
+
+declare const VERSION = "0.1.0";
+
+export { AMAZON_IMAGE_BASE, APIError, APIResource, ASIN_LENGTH, ASIN_REGEX, AuthenticationError, type ClientOptions, CsvType, DEFAULT_DAYS, type DomainId, KEEPA_NO_DATA_SENTINEL, type KeepaCategoryNode, KeepaClient, KeepaError, type KeepaProduct, type KeepaVariation, type KeepaVariationAttribute, MARKETPLACE_DOMAINS, type Marketplace, NetworkError, PRODUCT_LIST_CONTEXT, PRODUCT_PATH, type PriceHistoryEntry, type ProductListParams, ProductNotFoundError, type ProductRequestOptions, type ProductRetrieveParams, Products, RateLimitError, VERSION, KeepaClient as default, extractBsr, isFoundProduct, isValidAsin, normalizeAsins, parsePriceHistory, resolveDomainId };