@torvion/rascador 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,315 @@
+/**
+ * Wire types for the Rascador `/v1` API.
+ *
+ * These mirror the gateway's zod schemas (`rascador-gateway/src/schemas/*.ts`)
+ * field for field, snake_case included, so what you read here is exactly what
+ * the API reference documents.
+ */
+type SourceId = "shein" | "aliexpress" | "amazon" | "backmarket";
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface Meta {
+    request_id: string;
+    source?: SourceId;
+    /** Where the data came from: our cache, the stored catalogue, a live scrape, or the source registry. */
+    origin?: "cache" | "store" | "live" | "registry";
+    cached?: boolean;
+    took_ms: number;
+    /** This exact request in your dashboard log. */
+    log_url?: string;
+    /** Non-fatal degradation, e.g. `category_names_unavailable`. The response is still a 200. */
+    warnings?: string[];
+    /** With `only_new: true`: how many products were dropped as already seen this period. */
+    filtered_seen?: number;
+    pagination?: Pagination;
+}
+/** What every method resolves to: the gateway's success envelope, unchanged. */
+interface Response<T> {
+    data: T;
+    meta: Meta;
+}
+interface Money {
+    /** On a multi-variant listing this is the cheapest variant; read it with `current_max`. */
+    current: number | null;
+    /** Top of the price range on a multi-variant listing. */
+    current_max?: number;
+    original: number | null;
+    /** ISO 4217 code as reported by the source. */
+    currency: string | null;
+    discount_percent: number | null;
+    on_sale: boolean;
+}
+interface CategoryRef {
+    id: number | null;
+    /** Null when the category catalogue is unavailable; see `meta.warnings`. */
+    name: string | null;
+    url: string | null;
+}
+interface Product {
+    /** Numeric on SHEIN/AliExpress, an ASIN string on Amazon. */
+    id: number | string | null;
+    source: SourceId;
+    url: string;
+    detail_url: string;
+    sku: string | null;
+    title: string | null;
+    brand: string | null;
+    description: string | null;
+    images: string[];
+    price: Money;
+    category: CategoryRef;
+    variants: {
+        colors: string[];
+        sizes: string[];
+    };
+    availability: "in_stock" | "out_of_stock" | "unknown";
+    availability_raw: string | null;
+    rating: {
+        value: number | null;
+        count: number | null;
+    };
+    /** ISO-8601 UTC instant this data was collected. */
+    scraped_at: string;
+}
+interface SearchHit {
+    product_id: number | string | null;
+    url: string;
+    /** Null when the id could not be determined. */
+    detail_url: string | null;
+    title: string | null;
+    image: string | null;
+    price: number | null;
+    original_price: number | null;
+    discount_percent: number | null;
+    currency: string | null;
+    rating: number | null;
+}
+interface Category {
+    /** On SHEIN, usable as `products.list({ category_id })`. */
+    id: number | null;
+    source_category_id: number | string | null;
+    name: string | null;
+    url: string;
+    /** Stable across sources, e.g. `Shoes/Boots`. */
+    path: string;
+    parent_path: string | null;
+    level: number;
+    /** Search term that lists this category, when it has no id-addressable listing. */
+    query: string | null;
+    first_seen_at: string | null;
+    last_seen_at: string | null;
+}
+interface Source {
+    id: string;
+    name: string;
+    capabilities: {
+        live_search: boolean;
+        live_product_fetch: boolean;
+        product_id_filter: boolean;
+        /** Filters `products.list` accepts for this source. */
+        filters: string[];
+        max_search_pages: number;
+        max_limit: number;
+    };
+}
+interface Me {
+    client_id: string;
+    token_id: string;
+    token_name: string;
+    environment: "live" | "test";
+    plan: string;
+    scopes: string[];
+    quota: {
+        /** Billing period, YYYYMM (UTC). */
+        period: string;
+        limit: number;
+        used: number;
+        remaining: number;
+        resets_at: string;
+        topup_balance: number;
+    };
+    rate_limits: {
+        cheap_per_minute: number;
+        expensive_per_minute: number;
+        expensive_per_day: number;
+        expensive_concurrent: number;
+    };
+    /** Units charged per call type. */
+    quota_costs: Record<string, number>;
+}
+interface SourceParam {
+    /** Overrides the client's default source for this call. */
+    source?: SourceId;
+}
+interface PageParams {
+    /** 1–1000, default 50. */
+    limit?: number;
+    offset?: number;
+}
+interface SearchParams extends SourceParam {
+    q: string;
+    /** 1–5 result pages, roughly 120 products each. Default 1. */
+    pages?: number;
+    /** Bypass the 20-day result cache. Costs more quota. */
+    refresh?: boolean;
+}
+interface GetProductParams extends SourceParam {
+    /** Force a live re-scrape (20–90s, needs `search:live`, costs more quota). */
+    refresh?: boolean;
+}
+interface ListProductsParams extends SourceParam, PageParams {
+    category_id?: number;
+    sku?: string;
+    q?: string;
+    brand?: string;
+    min_price?: number;
+    max_price?: number;
+    color?: string;
+    size?: string;
+    on_sale?: boolean;
+    /** Drop products this key has already been served this billing period. */
+    only_new?: boolean;
+}
+interface ListCategoriesParams extends SourceParam, PageParams {
+    q?: string;
+    level?: number;
+    parent_path?: string;
+}
+/** Per-call overrides. */
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+
+type FetchPage<T> = (offset: number | undefined) => Promise<Response<T[]>>;
+/**
+ * A single page you can `await`, or every item you can `for await`.
+ *
+ * `await list(...)` makes exactly one request. Iterating makes as many as
+ * `meta.pagination.has_more` calls for, starting from the offset you passed.
+ */
+declare class PagePromise<T> implements PromiseLike<Response<T[]>>, AsyncIterable<T> {
+    #private;
+    constructor(fetchPage: FetchPage<T>, startOffset: number | undefined);
+    then<R1 = Response<T[]>, R2 = never>(onfulfilled?: ((value: Response<T[]>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<Response<T[]> | R>;
+    finally(onfinally?: (() => void) | null): Promise<Response<T[]>>;
+    /** Every page, in order. */
+    pages(): AsyncGenerator<Response<T[]>, void, undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.rascador.store";
+interface RascadorOptions {
+    /** Defaults to the `RASCADOR_API_KEY` environment variable where one exists. */
+    apiKey?: string;
+    /** Defaults to the production gateway. */
+    baseUrl?: string;
+    /** Source used when a call doesn't name one. The gateway's own default is `shein`. */
+    source?: SourceId;
+    /** Timeout for stored-data calls. Default 30s. */
+    timeoutMs?: number;
+    /** Timeout for live calls (`search`, `products.get` with `refresh`). Default 130s. */
+    liveTimeoutMs?: number;
+    /** Retries for errors the gateway marks retryable. Default 2. */
+    maxRetries?: number;
+    /** Custom fetch, e.g. for a proxy or tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+}
+type Query = Record<string, string | number | boolean | undefined>;
+interface CallSpec {
+    path: string;
+    query?: Query;
+    live?: boolean;
+    options?: RequestOptions;
+}
+declare class Rascador {
+    #private;
+    readonly products: ProductsResource;
+    readonly categories: CategoriesResource;
+    readonly sources: SourcesResource;
+    constructor(options?: RascadorOptions);
+    /** The key's scopes, limits and remaining quota. Never spends quota. */
+    me(options?: RequestOptions): Promise<Response<Me>>;
+    /**
+     * Live search on the source site. Slow (20–40s) and quota-heavy.
+     * Returns result cards; call `products.get` for full details.
+     */
+    search(params: SearchParams, options?: RequestOptions): Promise<Response<SearchHit[]>>;
+    /** @internal */
+    _source(source: SourceId | undefined): SourceId | undefined;
+    /** @internal */
+    _get<T>(spec: CallSpec): Promise<Response<T>>;
+    /** The SDK version. Include it in bug reports. */
+    static readonly VERSION: string;
+}
+declare class ProductsResource {
+    #private;
+    constructor(client: Rascador);
+    /**
+     * One product. Instant when stored; otherwise (or with `refresh: true`) a
+     * live fetch, which needs the `search:live` scope.
+     */
+    get(id: string | number, params?: GetProductParams, options?: RequestOptions): Promise<Response<Product>>;
+    /** Stored products. `await` for one page, `for await` for every product. */
+    list(params?: ListProductsParams, options?: RequestOptions): PagePromise<Product>;
+}
+declare class CategoriesResource {
+    #private;
+    constructor(client: Rascador);
+    /** The source's category tree. `await` for one page, `for await` for all. */
+    list(params?: ListCategoriesParams, options?: RequestOptions): PagePromise<Category>;
+}
+declare class SourcesResource {
+    #private;
+    constructor(client: Rascador);
+    /** Every source and what it supports. Never spends quota. */
+    list(options?: RequestOptions): Promise<Response<Source[]>>;
+}
+
+/**
+ * Codes the gateway can return, plus three the SDK raises itself:
+ * `network_error`, `timeout` and `invalid_response`.
+ *
+ * The `(string & {})` keeps autocomplete for the known codes while still
+ * accepting any code a newer gateway adds.
+ */
+type RascadorErrorCode = "invalid_request" | "unknown_source" | "missing_credentials" | "invalid_token" | "quota_exceeded" | "coverage_exceeded" | "payment_required" | "insufficient_scope" | "client_suspended" | "not_found" | "product_not_found" | "rate_limited" | "platform_busy" | "internal_error" | "gateway_misconfigured" | "upstream_error" | "upstream_unavailable" | "upstream_busy" | "upstream_timeout" | "network_error" | "timeout" | "invalid_response" | (string & {});
+interface RascadorErrorInit {
+    code: RascadorErrorCode;
+    message: string;
+    status: number;
+    retryable: boolean;
+    retryAfterSeconds?: number;
+    requestId?: string;
+    logUrl?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/** Thrown for every failed call. Branch on `code`, not on `message`. */
+declare class RascadorError extends Error {
+    readonly name = "RascadorError";
+    readonly code: RascadorErrorCode;
+    /** HTTP status, or 0 when no response arrived (network failure, timeout). */
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | undefined;
+    /** Quote this when contacting support. */
+    readonly requestId: string | undefined;
+    /** This failure in your dashboard log. */
+    readonly logUrl: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(init: RascadorErrorInit);
+}
+declare function isRascadorError(error: unknown): error is RascadorError;
+
+declare const VERSION = "0.1.0";
+
+export { CategoriesResource, type Category, type CategoryRef, DEFAULT_BASE_URL, type GetProductParams, type ListCategoriesParams, type ListProductsParams, type Me, type Meta, type Money, type PageParams, PagePromise, type Pagination, type Product, ProductsResource, Rascador, RascadorError, type RascadorErrorCode, type RascadorErrorInit, type RascadorOptions, type RequestOptions, type Response, type SearchHit, type SearchParams, type Source, type SourceId, type SourceParam, SourcesResource, VERSION, isRascadorError };

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Wire types for the Rascador `/v1` API.
+ *
+ * These mirror the gateway's zod schemas (`rascador-gateway/src/schemas/*.ts`)
+ * field for field, snake_case included, so what you read here is exactly what
+ * the API reference documents.
+ */
+type SourceId = "shein" | "aliexpress" | "amazon" | "backmarket";
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface Meta {
+    request_id: string;
+    source?: SourceId;
+    /** Where the data came from: our cache, the stored catalogue, a live scrape, or the source registry. */
+    origin?: "cache" | "store" | "live" | "registry";
+    cached?: boolean;
+    took_ms: number;
+    /** This exact request in your dashboard log. */
+    log_url?: string;
+    /** Non-fatal degradation, e.g. `category_names_unavailable`. The response is still a 200. */
+    warnings?: string[];
+    /** With `only_new: true`: how many products were dropped as already seen this period. */
+    filtered_seen?: number;
+    pagination?: Pagination;
+}
+/** What every method resolves to: the gateway's success envelope, unchanged. */
+interface Response<T> {
+    data: T;
+    meta: Meta;
+}
+interface Money {
+    /** On a multi-variant listing this is the cheapest variant; read it with `current_max`. */
+    current: number | null;
+    /** Top of the price range on a multi-variant listing. */
+    current_max?: number;
+    original: number | null;
+    /** ISO 4217 code as reported by the source. */
+    currency: string | null;
+    discount_percent: number | null;
+    on_sale: boolean;
+}
+interface CategoryRef {
+    id: number | null;
+    /** Null when the category catalogue is unavailable; see `meta.warnings`. */
+    name: string | null;
+    url: string | null;
+}
+interface Product {
+    /** Numeric on SHEIN/AliExpress, an ASIN string on Amazon. */
+    id: number | string | null;
+    source: SourceId;
+    url: string;
+    detail_url: string;
+    sku: string | null;
+    title: string | null;
+    brand: string | null;
+    description: string | null;
+    images: string[];
+    price: Money;
+    category: CategoryRef;
+    variants: {
+        colors: string[];
+        sizes: string[];
+    };
+    availability: "in_stock" | "out_of_stock" | "unknown";
+    availability_raw: string | null;
+    rating: {
+        value: number | null;
+        count: number | null;
+    };
+    /** ISO-8601 UTC instant this data was collected. */
+    scraped_at: string;
+}
+interface SearchHit {
+    product_id: number | string | null;
+    url: string;
+    /** Null when the id could not be determined. */
+    detail_url: string | null;
+    title: string | null;
+    image: string | null;
+    price: number | null;
+    original_price: number | null;
+    discount_percent: number | null;
+    currency: string | null;
+    rating: number | null;
+}
+interface Category {
+    /** On SHEIN, usable as `products.list({ category_id })`. */
+    id: number | null;
+    source_category_id: number | string | null;
+    name: string | null;
+    url: string;
+    /** Stable across sources, e.g. `Shoes/Boots`. */
+    path: string;
+    parent_path: string | null;
+    level: number;
+    /** Search term that lists this category, when it has no id-addressable listing. */
+    query: string | null;
+    first_seen_at: string | null;
+    last_seen_at: string | null;
+}
+interface Source {
+    id: string;
+    name: string;
+    capabilities: {
+        live_search: boolean;
+        live_product_fetch: boolean;
+        product_id_filter: boolean;
+        /** Filters `products.list` accepts for this source. */
+        filters: string[];
+        max_search_pages: number;
+        max_limit: number;
+    };
+}
+interface Me {
+    client_id: string;
+    token_id: string;
+    token_name: string;
+    environment: "live" | "test";
+    plan: string;
+    scopes: string[];
+    quota: {
+        /** Billing period, YYYYMM (UTC). */
+        period: string;
+        limit: number;
+        used: number;
+        remaining: number;
+        resets_at: string;
+        topup_balance: number;
+    };
+    rate_limits: {
+        cheap_per_minute: number;
+        expensive_per_minute: number;
+        expensive_per_day: number;
+        expensive_concurrent: number;
+    };
+    /** Units charged per call type. */
+    quota_costs: Record<string, number>;
+}
+interface SourceParam {
+    /** Overrides the client's default source for this call. */
+    source?: SourceId;
+}
+interface PageParams {
+    /** 1–1000, default 50. */
+    limit?: number;
+    offset?: number;
+}
+interface SearchParams extends SourceParam {
+    q: string;
+    /** 1–5 result pages, roughly 120 products each. Default 1. */
+    pages?: number;
+    /** Bypass the 20-day result cache. Costs more quota. */
+    refresh?: boolean;
+}
+interface GetProductParams extends SourceParam {
+    /** Force a live re-scrape (20–90s, needs `search:live`, costs more quota). */
+    refresh?: boolean;
+}
+interface ListProductsParams extends SourceParam, PageParams {
+    category_id?: number;
+    sku?: string;
+    q?: string;
+    brand?: string;
+    min_price?: number;
+    max_price?: number;
+    color?: string;
+    size?: string;
+    on_sale?: boolean;
+    /** Drop products this key has already been served this billing period. */
+    only_new?: boolean;
+}
+interface ListCategoriesParams extends SourceParam, PageParams {
+    q?: string;
+    level?: number;
+    parent_path?: string;
+}
+/** Per-call overrides. */
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+
+type FetchPage<T> = (offset: number | undefined) => Promise<Response<T[]>>;
+/**
+ * A single page you can `await`, or every item you can `for await`.
+ *
+ * `await list(...)` makes exactly one request. Iterating makes as many as
+ * `meta.pagination.has_more` calls for, starting from the offset you passed.
+ */
+declare class PagePromise<T> implements PromiseLike<Response<T[]>>, AsyncIterable<T> {
+    #private;
+    constructor(fetchPage: FetchPage<T>, startOffset: number | undefined);
+    then<R1 = Response<T[]>, R2 = never>(onfulfilled?: ((value: Response<T[]>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<Response<T[]> | R>;
+    finally(onfinally?: (() => void) | null): Promise<Response<T[]>>;
+    /** Every page, in order. */
+    pages(): AsyncGenerator<Response<T[]>, void, undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.rascador.store";
+interface RascadorOptions {
+    /** Defaults to the `RASCADOR_API_KEY` environment variable where one exists. */
+    apiKey?: string;
+    /** Defaults to the production gateway. */
+    baseUrl?: string;
+    /** Source used when a call doesn't name one. The gateway's own default is `shein`. */
+    source?: SourceId;
+    /** Timeout for stored-data calls. Default 30s. */
+    timeoutMs?: number;
+    /** Timeout for live calls (`search`, `products.get` with `refresh`). Default 130s. */
+    liveTimeoutMs?: number;
+    /** Retries for errors the gateway marks retryable. Default 2. */
+    maxRetries?: number;
+    /** Custom fetch, e.g. for a proxy or tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+}
+type Query = Record<string, string | number | boolean | undefined>;
+interface CallSpec {
+    path: string;
+    query?: Query;
+    live?: boolean;
+    options?: RequestOptions;
+}
+declare class Rascador {
+    #private;
+    readonly products: ProductsResource;
+    readonly categories: CategoriesResource;
+    readonly sources: SourcesResource;
+    constructor(options?: RascadorOptions);
+    /** The key's scopes, limits and remaining quota. Never spends quota. */
+    me(options?: RequestOptions): Promise<Response<Me>>;
+    /**
+     * Live search on the source site. Slow (20–40s) and quota-heavy.
+     * Returns result cards; call `products.get` for full details.
+     */
+    search(params: SearchParams, options?: RequestOptions): Promise<Response<SearchHit[]>>;
+    /** @internal */
+    _source(source: SourceId | undefined): SourceId | undefined;
+    /** @internal */
+    _get<T>(spec: CallSpec): Promise<Response<T>>;
+    /** The SDK version. Include it in bug reports. */
+    static readonly VERSION: string;
+}
+declare class ProductsResource {
+    #private;
+    constructor(client: Rascador);
+    /**
+     * One product. Instant when stored; otherwise (or with `refresh: true`) a
+     * live fetch, which needs the `search:live` scope.
+     */
+    get(id: string | number, params?: GetProductParams, options?: RequestOptions): Promise<Response<Product>>;
+    /** Stored products. `await` for one page, `for await` for every product. */
+    list(params?: ListProductsParams, options?: RequestOptions): PagePromise<Product>;
+}
+declare class CategoriesResource {
+    #private;
+    constructor(client: Rascador);
+    /** The source's category tree. `await` for one page, `for await` for all. */
+    list(params?: ListCategoriesParams, options?: RequestOptions): PagePromise<Category>;
+}
+declare class SourcesResource {
+    #private;
+    constructor(client: Rascador);
+    /** Every source and what it supports. Never spends quota. */
+    list(options?: RequestOptions): Promise<Response<Source[]>>;
+}
+
+/**
+ * Codes the gateway can return, plus three the SDK raises itself:
+ * `network_error`, `timeout` and `invalid_response`.
+ *
+ * The `(string & {})` keeps autocomplete for the known codes while still
+ * accepting any code a newer gateway adds.
+ */
+type RascadorErrorCode = "invalid_request" | "unknown_source" | "missing_credentials" | "invalid_token" | "quota_exceeded" | "coverage_exceeded" | "payment_required" | "insufficient_scope" | "client_suspended" | "not_found" | "product_not_found" | "rate_limited" | "platform_busy" | "internal_error" | "gateway_misconfigured" | "upstream_error" | "upstream_unavailable" | "upstream_busy" | "upstream_timeout" | "network_error" | "timeout" | "invalid_response" | (string & {});
+interface RascadorErrorInit {
+    code: RascadorErrorCode;
+    message: string;
+    status: number;
+    retryable: boolean;
+    retryAfterSeconds?: number;
+    requestId?: string;
+    logUrl?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/** Thrown for every failed call. Branch on `code`, not on `message`. */
+declare class RascadorError extends Error {
+    readonly name = "RascadorError";
+    readonly code: RascadorErrorCode;
+    /** HTTP status, or 0 when no response arrived (network failure, timeout). */
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | undefined;
+    /** Quote this when contacting support. */
+    readonly requestId: string | undefined;
+    /** This failure in your dashboard log. */
+    readonly logUrl: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(init: RascadorErrorInit);
+}
+declare function isRascadorError(error: unknown): error is RascadorError;
+
+declare const VERSION = "0.1.0";
+
+export { CategoriesResource, type Category, type CategoryRef, DEFAULT_BASE_URL, type GetProductParams, type ListCategoriesParams, type ListProductsParams, type Me, type Meta, type Money, type PageParams, PagePromise, type Pagination, type Product, ProductsResource, Rascador, RascadorError, type RascadorErrorCode, type RascadorErrorInit, type RascadorOptions, type RequestOptions, type Response, type SearchHit, type SearchParams, type Source, type SourceId, type SourceParam, SourcesResource, VERSION, isRascadorError };