@torvion/rascador 0.1.0

package/dist/index.js

@@ -0,0 +1,355 @@
+// src/errors.ts
+var RascadorError = class extends Error {
+  name = "RascadorError";
+  code;
+  /** HTTP status, or 0 when no response arrived (network failure, timeout). */
+  status;
+  retryable;
+  retryAfterSeconds;
+  /** Quote this when contacting support. */
+  requestId;
+  /** This failure in your dashboard log. */
+  logUrl;
+  details;
+  constructor(init) {
+    super(init.message, init.cause === void 0 ? void 0 : { cause: init.cause });
+    this.code = init.code;
+    this.status = init.status;
+    this.retryable = init.retryable;
+    this.retryAfterSeconds = init.retryAfterSeconds;
+    this.requestId = init.requestId;
+    this.logUrl = init.logUrl;
+    this.details = init.details;
+  }
+};
+function isRascadorError(error) {
+  return error instanceof RascadorError;
+}
+
+// src/pagination.ts
+var PagePromise = class {
+  #fetchPage;
+  #startOffset;
+  #first;
+  constructor(fetchPage, startOffset) {
+    this.#fetchPage = fetchPage;
+    this.#startOffset = startOffset;
+  }
+  // Lazy, so a list you only iterate doesn't also fire a request for `then`.
+  #firstPage() {
+    this.#first ??= this.#fetchPage(this.#startOffset);
+    return this.#first;
+  }
+  then(onfulfilled, onrejected) {
+    return this.#firstPage().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.#firstPage().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.#firstPage().finally(onfinally);
+  }
+  /** Every page, in order. */
+  async *pages() {
+    let page = await this.#firstPage();
+    for (; ; ) {
+      yield page;
+      const p = page.meta.pagination;
+      if (!p?.has_more || p.limit <= 0) return;
+      page = await this.#fetchPage(p.offset + p.limit);
+    }
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.pages()) yield* page.data;
+  }
+};
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.rascador.store";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_LIVE_TIMEOUT_MS = 13e4;
+var DEFAULT_MAX_RETRIES = 2;
+var MAX_BACKOFF_MS = 8e3;
+function readEnvKey() {
+  const env = globalThis.process?.env;
+  return env?.RASCADOR_API_KEY;
+}
+var Rascador = class {
+  #apiKey;
+  #baseUrl;
+  #source;
+  #timeoutMs;
+  #liveTimeoutMs;
+  #maxRetries;
+  #fetch;
+  #headers;
+  products;
+  categories;
+  sources;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? readEnvKey();
+    if (!apiKey) {
+      throw new RascadorError({
+        code: "missing_credentials",
+        message: "No API key. Pass `apiKey` or set the RASCADOR_API_KEY environment variable.",
+        status: 0,
+        retryable: false
+      });
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError("No global fetch found. Pass `fetch` in the options (Node 18+ has one built in).");
+    }
+    this.#apiKey = apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#source = options.source;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#liveTimeoutMs = options.liveTimeoutMs ?? DEFAULT_LIVE_TIMEOUT_MS;
+    this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#fetch = fetchImpl.bind(globalThis);
+    this.#headers = options.headers ?? {};
+    this.products = new ProductsResource(this);
+    this.categories = new CategoriesResource(this);
+    this.sources = new SourcesResource(this);
+  }
+  /** The key's scopes, limits and remaining quota. Never spends quota. */
+  me(options) {
+    return this._get({ path: "/v1/me", options });
+  }
+  /**
+   * Live search on the source site. Slow (20–40s) and quota-heavy.
+   * Returns result cards; call `products.get` for full details.
+   */
+  search(params, options) {
+    const { source, ...query } = params;
+    return this._get({ path: "/v1/search", query: { ...query, source: this._source(source) }, live: true, options });
+  }
+  /** @internal */
+  _source(source) {
+    return source ?? this.#source;
+  }
+  /** @internal */
+  async _get(spec) {
+    const url = this.#url(spec.path, spec.query);
+    const maxRetries = spec.options?.maxRetries ?? this.#maxRetries;
+    const timeoutMs = spec.options?.timeoutMs ?? (spec.live ? this.#liveTimeoutMs : this.#timeoutMs);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.#once(url, timeoutMs, spec.options?.signal);
+      } catch (error) {
+        if (!(error instanceof RascadorError) || !error.retryable || attempt >= maxRetries) throw error;
+        await sleep(backoffMs(attempt, error.retryAfterSeconds), spec.options?.signal);
+      }
+    }
+  }
+  #url(path, query) {
+    const url = new URL(this.#baseUrl + path);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async #once(url, timeoutMs, signal) {
+    const { signal: combined, cleanup, timedOut } = withTimeout(timeoutMs, signal);
+    let res;
+    try {
+      res = await this.#fetch(url, {
+        method: "GET",
+        headers: {
+          ...this.#headers,
+          accept: "application/json",
+          authorization: `Bearer ${this.#apiKey}`
+        },
+        signal: combined
+      });
+    } catch (cause) {
+      cleanup();
+      if (timedOut()) {
+        throw new RascadorError({
+          code: "timeout",
+          message: `No response within ${timeoutMs}ms.`,
+          status: 0,
+          retryable: false,
+          cause
+        });
+      }
+      if (signal?.aborted) throw cause;
+      throw new RascadorError({
+        code: "network_error",
+        message: cause instanceof Error ? cause.message : "The request could not be sent.",
+        status: 0,
+        retryable: true,
+        cause
+      });
+    }
+    let body;
+    try {
+      const text = await res.text();
+      body = text ? JSON.parse(text) : null;
+    } catch (cause) {
+      if (timedOut()) {
+        throw new RascadorError({
+          code: "timeout",
+          message: `The response did not finish within ${timeoutMs}ms.`,
+          status: res.status,
+          retryable: false,
+          cause
+        });
+      }
+      if (signal?.aborted) throw cause;
+      throw new RascadorError({
+        code: "invalid_response",
+        message: `Expected JSON from the gateway (HTTP ${res.status}).`,
+        status: res.status,
+        retryable: res.status >= 500,
+        cause
+      });
+    } finally {
+      cleanup();
+    }
+    if (!res.ok) throw errorFrom(res, body);
+    if (!body || typeof body !== "object" || !("data" in body)) {
+      throw new RascadorError({
+        code: "invalid_response",
+        message: "The gateway response had no `data` field.",
+        status: res.status,
+        retryable: false
+      });
+    }
+    return body;
+  }
+  /** The SDK version. Include it in bug reports. */
+  static VERSION = VERSION;
+};
+var ProductsResource = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * One product. Instant when stored; otherwise (or with `refresh: true`) a
+   * live fetch, which needs the `search:live` scope.
+   */
+  get(id, params = {}, options) {
+    const { source, ...query } = params;
+    return this.#client._get({
+      path: `/v1/products/${encodeURIComponent(String(id))}`,
+      query: { ...query, source: this.#client._source(source) },
+      live: params.refresh === true,
+      options
+    });
+  }
+  /** Stored products. `await` for one page, `for await` for every product. */
+  list(params = {}, options) {
+    const { source, offset, ...query } = params;
+    return new PagePromise(
+      (next) => this.#client._get({
+        path: "/v1/products",
+        query: { ...query, offset: next, source: this.#client._source(source) },
+        options
+      }),
+      offset
+    );
+  }
+};
+var CategoriesResource = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /** The source's category tree. `await` for one page, `for await` for all. */
+  list(params = {}, options) {
+    const { source, offset, ...query } = params;
+    return new PagePromise(
+      (next) => this.#client._get({
+        path: "/v1/categories",
+        query: { ...query, offset: next, source: this.#client._source(source) },
+        options
+      }),
+      offset
+    );
+  }
+};
+var SourcesResource = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /** Every source and what it supports. Never spends quota. */
+  list(options) {
+    return this.#client._get({ path: "/v1/sources", options });
+  }
+};
+function errorFrom(res, body) {
+  const e = body?.error;
+  const headerRetry = Number(res.headers.get("retry-after"));
+  if (!e || typeof e.code !== "string") {
+    return new RascadorError({
+      code: res.status >= 500 ? "internal_error" : "invalid_response",
+      message: `The gateway returned HTTP ${res.status} without an error body.`,
+      status: res.status,
+      retryable: res.status >= 500 || res.status === 429,
+      retryAfterSeconds: Number.isFinite(headerRetry) && headerRetry > 0 ? headerRetry : void 0
+    });
+  }
+  const retryAfter = typeof e.retry_after_seconds === "number" ? e.retry_after_seconds : Number.isFinite(headerRetry) && headerRetry > 0 ? headerRetry : void 0;
+  return new RascadorError({
+    code: e.code,
+    message: typeof e.message === "string" ? e.message : e.code,
+    status: res.status,
+    retryable: e.retryable === true,
+    retryAfterSeconds: retryAfter,
+    requestId: typeof e.request_id === "string" ? e.request_id : void 0,
+    logUrl: typeof e.log_url === "string" ? e.log_url : void 0,
+    details: e.details ?? void 0
+  });
+}
+function backoffMs(attempt, retryAfterSeconds) {
+  const jittered = Math.random() * Math.min(MAX_BACKOFF_MS, 500 * 2 ** attempt);
+  return Math.max(jittered, (retryAfterSeconds ?? 0) * 1e3);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function withTimeout(ms, signal) {
+  const controller = new AbortController();
+  let fired = false;
+  const timer = setTimeout(() => {
+    fired = true;
+    controller.abort();
+  }, ms);
+  const onAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) controller.abort(signal.reason);
+  else signal?.addEventListener("abort", onAbort, { once: true });
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    },
+    timedOut: () => fired
+  };
+}
+export {
+  DEFAULT_BASE_URL,
+  PagePromise,
+  Rascador,
+  RascadorError,
+  VERSION,
+  isRascadorError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/pagination.ts","../src/version.ts","../src/client.ts"],"sourcesContent":["/**\n * Codes the gateway can return, plus three the SDK raises itself:\n * `network_error`, `timeout` and `invalid_response`.\n *\n * The `(string & {})` keeps autocomplete for the known codes while still\n * accepting any code a newer gateway adds.\n */\nexport type RascadorErrorCode =\n  | \"invalid_request\"\n  | \"unknown_source\"\n  | \"missing_credentials\"\n  | \"invalid_token\"\n  | \"quota_exceeded\"\n  | \"coverage_exceeded\"\n  | \"payment_required\"\n  | \"insufficient_scope\"\n  | \"client_suspended\"\n  | \"not_found\"\n  | \"product_not_found\"\n  | \"rate_limited\"\n  | \"platform_busy\"\n  | \"internal_error\"\n  | \"gateway_misconfigured\"\n  | \"upstream_error\"\n  | \"upstream_unavailable\"\n  | \"upstream_busy\"\n  | \"upstream_timeout\"\n  | \"network_error\"\n  | \"timeout\"\n  | \"invalid_response\"\n  | (string & {})\n\nexport interface RascadorErrorInit {\n  code: RascadorErrorCode\n  message: string\n  status: number\n  retryable: boolean\n  retryAfterSeconds?: number\n  requestId?: string\n  logUrl?: string\n  details?: Record<string, unknown>\n  cause?: unknown\n}\n\n/** Thrown for every failed call. Branch on `code`, not on `message`. */\nexport class RascadorError extends Error {\n  override readonly name = \"RascadorError\"\n  readonly code: RascadorErrorCode\n  /** HTTP status, or 0 when no response arrived (network failure, timeout). */\n  readonly status: number\n  readonly retryable: boolean\n  readonly retryAfterSeconds: number | undefined\n  /** Quote this when contacting support. */\n  readonly requestId: string | undefined\n  /** This failure in your dashboard log. */\n  readonly logUrl: string | undefined\n  readonly details: Record<string, unknown> | undefined\n\n  constructor(init: RascadorErrorInit) {\n    super(init.message, init.cause === undefined ? undefined : { cause: init.cause })\n    this.code = init.code\n    this.status = init.status\n    this.retryable = init.retryable\n    this.retryAfterSeconds = init.retryAfterSeconds\n    this.requestId = init.requestId\n    this.logUrl = init.logUrl\n    this.details = init.details\n  }\n}\n\nexport function isRascadorError(error: unknown): error is RascadorError {\n  return error instanceof RascadorError\n}\n","import type { Response } from \"./types.ts\"\n\ntype FetchPage<T> = (offset: number | undefined) => Promise<Response<T[]>>\n\n/**\n * A single page you can `await`, or every item you can `for await`.\n *\n * `await list(...)` makes exactly one request. Iterating makes as many as\n * `meta.pagination.has_more` calls for, starting from the offset you passed.\n */\nexport class PagePromise<T> implements PromiseLike<Response<T[]>>, AsyncIterable<T> {\n  readonly #fetchPage: FetchPage<T>\n  readonly #startOffset: number | undefined\n  #first: Promise<Response<T[]>> | undefined\n\n  constructor(fetchPage: FetchPage<T>, startOffset: number | undefined) {\n    this.#fetchPage = fetchPage\n    this.#startOffset = startOffset\n  }\n\n  // Lazy, so a list you only iterate doesn't also fire a request for `then`.\n  #firstPage(): Promise<Response<T[]>> {\n    this.#first ??= this.#fetchPage(this.#startOffset)\n    return this.#first\n  }\n\n  then<R1 = Response<T[]>, R2 = never>(\n    onfulfilled?: ((value: Response<T[]>) => R1 | PromiseLike<R1>) | null,\n    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null\n  ): Promise<R1 | R2> {\n    return this.#firstPage().then(onfulfilled, onrejected)\n  }\n\n  catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<Response<T[]> | R> {\n    return this.#firstPage().catch(onrejected)\n  }\n\n  finally(onfinally?: (() => void) | null): Promise<Response<T[]>> {\n    return this.#firstPage().finally(onfinally)\n  }\n\n  /** Every page, in order. */\n  async *pages(): AsyncGenerator<Response<T[]>, void, undefined> {\n    let page = await this.#firstPage()\n    for (;;) {\n      yield page\n      const p = page.meta.pagination\n      if (!p?.has_more || p.limit <= 0) return\n      // Advance by the page size, not by what came back: with `only_new` a page\n      // can be shorter than `limit` without the listing being exhausted.\n      page = await this.#fetchPage(p.offset + p.limit)\n    }\n  }\n\n  async *[Symbol.asyncIterator](): AsyncIterator<T> {\n    for await (const page of this.pages()) yield* page.data\n  }\n}\n","// Written by scripts/sync-version.mjs from package.json. Do not edit by hand.\nexport const VERSION = \"0.1.0\"\n","import { RascadorError } from \"./errors.ts\"\nimport { PagePromise } from \"./pagination.ts\"\nimport type {\n  Category,\n  GetProductParams,\n  ListCategoriesParams,\n  ListProductsParams,\n  Me,\n  Product,\n  RequestOptions,\n  Response,\n  SearchHit,\n  SearchParams,\n  Source,\n  SourceId,\n} from \"./types.ts\"\nimport { VERSION } from \"./version.ts\"\n\nexport const DEFAULT_BASE_URL = \"https://api.rascador.store\"\n\n/** Stored-data reads answer in well under a second. */\nconst DEFAULT_TIMEOUT_MS = 30_000\n/** Live scrapes drive a real browser: 20-40s typical, up to ~90s for a product refresh. */\nconst DEFAULT_LIVE_TIMEOUT_MS = 130_000\nconst DEFAULT_MAX_RETRIES = 2\nconst MAX_BACKOFF_MS = 8_000\n\nexport interface RascadorOptions {\n  /** Defaults to the `RASCADOR_API_KEY` environment variable where one exists. */\n  apiKey?: string\n  /** Defaults to the production gateway. */\n  baseUrl?: string\n  /** Source used when a call doesn't name one. The gateway's own default is `shein`. */\n  source?: SourceId\n  /** Timeout for stored-data calls. Default 30s. */\n  timeoutMs?: number\n  /** Timeout for live calls (`search`, `products.get` with `refresh`). Default 130s. */\n  liveTimeoutMs?: number\n  /** Retries for errors the gateway marks retryable. Default 2. */\n  maxRetries?: number\n  /** Custom fetch, e.g. for a proxy or tests. Defaults to the global `fetch`. */\n  fetch?: typeof fetch\n  /** Extra headers sent with every request. */\n  headers?: Record<string, string>\n}\n\ntype Query = Record<string, string | number | boolean | undefined>\n\ninterface CallSpec {\n  path: string\n  query?: Query\n  live?: boolean\n  options?: RequestOptions\n}\n\nfunction readEnvKey(): string | undefined {\n  // `process` doesn't exist in browsers or Deno without the node shim.\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env\n  return env?.RASCADOR_API_KEY\n}\n\nexport class Rascador {\n  readonly #apiKey: string\n  readonly #baseUrl: string\n  readonly #source: SourceId | undefined\n  readonly #timeoutMs: number\n  readonly #liveTimeoutMs: number\n  readonly #maxRetries: number\n  readonly #fetch: typeof fetch\n  readonly #headers: Record<string, string>\n\n  readonly products: ProductsResource\n  readonly categories: CategoriesResource\n  readonly sources: SourcesResource\n\n  constructor(options: RascadorOptions = {}) {\n    const apiKey = options.apiKey ?? readEnvKey()\n    if (!apiKey) {\n      throw new RascadorError({\n        code: \"missing_credentials\",\n        message: \"No API key. Pass `apiKey` or set the RASCADOR_API_KEY environment variable.\",\n        status: 0,\n        retryable: false,\n      })\n    }\n\n    const fetchImpl = options.fetch ?? globalThis.fetch\n    if (typeof fetchImpl !== \"function\") {\n      throw new TypeError(\"No global fetch found. Pass `fetch` in the options (Node 18+ has one built in).\")\n    }\n\n    this.#apiKey = apiKey\n    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\")\n    this.#source = options.source\n    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n    this.#liveTimeoutMs = options.liveTimeoutMs ?? DEFAULT_LIVE_TIMEOUT_MS\n    this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES\n    // Bound so a detached `fetch` (e.g. window.fetch) keeps its receiver.\n    this.#fetch = fetchImpl.bind(globalThis)\n    this.#headers = options.headers ?? {}\n\n    this.products = new ProductsResource(this)\n    this.categories = new CategoriesResource(this)\n    this.sources = new SourcesResource(this)\n  }\n\n  /** The key's scopes, limits and remaining quota. Never spends quota. */\n  me(options?: RequestOptions): Promise<Response<Me>> {\n    return this._get({ path: \"/v1/me\", options })\n  }\n\n  /**\n   * Live search on the source site. Slow (20–40s) and quota-heavy.\n   * Returns result cards; call `products.get` for full details.\n   */\n  search(params: SearchParams, options?: RequestOptions): Promise<Response<SearchHit[]>> {\n    const { source, ...query } = params\n    return this._get({ path: \"/v1/search\", query: { ...query, source: this._source(source) }, live: true, options })\n  }\n\n  /** @internal */\n  _source(source: SourceId | undefined): SourceId | undefined {\n    return source ?? this.#source\n  }\n\n  /** @internal */\n  async _get<T>(spec: CallSpec): Promise<Response<T>> {\n    const url = this.#url(spec.path, spec.query)\n    const maxRetries = spec.options?.maxRetries ?? this.#maxRetries\n    const timeoutMs = spec.options?.timeoutMs ?? (spec.live ? this.#liveTimeoutMs : this.#timeoutMs)\n\n    for (let attempt = 0; ; attempt++) {\n      try {\n        return await this.#once<T>(url, timeoutMs, spec.options?.signal)\n      } catch (error) {\n        if (!(error instanceof RascadorError) || !error.retryable || attempt >= maxRetries) throw error\n        await sleep(backoffMs(attempt, error.retryAfterSeconds), spec.options?.signal)\n      }\n    }\n  }\n\n  #url(path: string, query: Query | undefined): string {\n    const url = new URL(this.#baseUrl + path)\n    for (const [key, value] of Object.entries(query ?? {})) {\n      if (value !== undefined) url.searchParams.set(key, String(value))\n    }\n    return url.toString()\n  }\n\n  async #once<T>(url: string, timeoutMs: number, signal: AbortSignal | undefined): Promise<Response<T>> {\n    const { signal: combined, cleanup, timedOut } = withTimeout(timeoutMs, signal)\n\n    let res: globalThis.Response\n    try {\n      res = await this.#fetch(url, {\n        method: \"GET\",\n        headers: {\n          ...this.#headers,\n          accept: \"application/json\",\n          authorization: `Bearer ${this.#apiKey}`,\n        },\n        signal: combined,\n      })\n    } catch (cause) {\n      cleanup()\n      if (timedOut()) {\n        // Not retried: a live scrape that outran us may still be running\n        // upstream, and firing another would only stack a second one on it.\n        throw new RascadorError({\n          code: \"timeout\",\n          message: `No response within ${timeoutMs}ms.`,\n          status: 0,\n          retryable: false,\n          cause,\n        })\n      }\n      if (signal?.aborted) throw cause\n      throw new RascadorError({\n        code: \"network_error\",\n        message: cause instanceof Error ? cause.message : \"The request could not be sent.\",\n        status: 0,\n        retryable: true,\n        cause,\n      })\n    }\n\n    let body: unknown\n    try {\n      const text = await res.text()\n      body = text ? JSON.parse(text) : null\n    } catch (cause) {\n      if (timedOut()) {\n        throw new RascadorError({\n          code: \"timeout\",\n          message: `The response did not finish within ${timeoutMs}ms.`,\n          status: res.status,\n          retryable: false,\n          cause,\n        })\n      }\n      if (signal?.aborted) throw cause\n      throw new RascadorError({\n        code: \"invalid_response\",\n        message: `Expected JSON from the gateway (HTTP ${res.status}).`,\n        status: res.status,\n        retryable: res.status >= 500,\n        cause,\n      })\n    } finally {\n      cleanup()\n    }\n\n    if (!res.ok) throw errorFrom(res, body)\n\n    if (!body || typeof body !== \"object\" || !(\"data\" in body)) {\n      throw new RascadorError({\n        code: \"invalid_response\",\n        message: \"The gateway response had no `data` field.\",\n        status: res.status,\n        retryable: false,\n      })\n    }\n    return body as Response<T>\n  }\n\n  /** The SDK version. Include it in bug reports. */\n  static readonly VERSION: string = VERSION\n}\n\nexport class ProductsResource {\n  readonly #client: Rascador\n  constructor(client: Rascador) {\n    this.#client = client\n  }\n\n  /**\n   * One product. Instant when stored; otherwise (or with `refresh: true`) a\n   * live fetch, which needs the `search:live` scope.\n   */\n  get(id: string | number, params: GetProductParams = {}, options?: RequestOptions): Promise<Response<Product>> {\n    const { source, ...query } = params\n    return this.#client._get({\n      path: `/v1/products/${encodeURIComponent(String(id))}`,\n      query: { ...query, source: this.#client._source(source) },\n      live: params.refresh === true,\n      options,\n    })\n  }\n\n  /** Stored products. `await` for one page, `for await` for every product. */\n  list(params: ListProductsParams = {}, options?: RequestOptions): PagePromise<Product> {\n    const { source, offset, ...query } = params\n    return new PagePromise<Product>(\n      (next) =>\n        this.#client._get({\n          path: \"/v1/products\",\n          query: { ...query, offset: next, source: this.#client._source(source) },\n          options,\n        }),\n      offset\n    )\n  }\n}\n\nexport class CategoriesResource {\n  readonly #client: Rascador\n  constructor(client: Rascador) {\n    this.#client = client\n  }\n\n  /** The source's category tree. `await` for one page, `for await` for all. */\n  list(params: ListCategoriesParams = {}, options?: RequestOptions): PagePromise<Category> {\n    const { source, offset, ...query } = params\n    return new PagePromise<Category>(\n      (next) =>\n        this.#client._get({\n          path: \"/v1/categories\",\n          query: { ...query, offset: next, source: this.#client._source(source) },\n          options,\n        }),\n      offset\n    )\n  }\n}\n\nexport class SourcesResource {\n  readonly #client: Rascador\n  constructor(client: Rascador) {\n    this.#client = client\n  }\n\n  /** Every source and what it supports. Never spends quota. */\n  list(options?: RequestOptions): Promise<Response<Source[]>> {\n    return this.#client._get({ path: \"/v1/sources\", options })\n  }\n}\n\nfunction errorFrom(res: globalThis.Response, body: unknown): RascadorError {\n  const e = (body as { error?: Record<string, unknown> } | null)?.error\n  const headerRetry = Number(res.headers.get(\"retry-after\"))\n\n  if (!e || typeof e.code !== \"string\") {\n    return new RascadorError({\n      code: res.status >= 500 ? \"internal_error\" : \"invalid_response\",\n      message: `The gateway returned HTTP ${res.status} without an error body.`,\n      status: res.status,\n      retryable: res.status >= 500 || res.status === 429,\n      retryAfterSeconds: Number.isFinite(headerRetry) && headerRetry > 0 ? headerRetry : undefined,\n    })\n  }\n\n  const retryAfter =\n    typeof e.retry_after_seconds === \"number\"\n      ? e.retry_after_seconds\n      : Number.isFinite(headerRetry) && headerRetry > 0\n        ? headerRetry\n        : undefined\n\n  return new RascadorError({\n    code: e.code,\n    message: typeof e.message === \"string\" ? e.message : e.code,\n    status: res.status,\n    retryable: e.retryable === true,\n    retryAfterSeconds: retryAfter,\n    requestId: typeof e.request_id === \"string\" ? e.request_id : undefined,\n    logUrl: typeof e.log_url === \"string\" ? e.log_url : undefined,\n    details: (e.details as Record<string, unknown> | undefined) ?? undefined,\n  })\n}\n\n/** Exponential backoff with full jitter, never shorter than what the gateway asked for. */\nfunction backoffMs(attempt: number, retryAfterSeconds: number | undefined): number {\n  const jittered = Math.random() * Math.min(MAX_BACKOFF_MS, 500 * 2 ** attempt)\n  return Math.max(jittered, (retryAfterSeconds ?? 0) * 1000)\n}\n\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) return reject(signal.reason)\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort)\n      resolve()\n    }, ms)\n    const onAbort = () => {\n      clearTimeout(timer)\n      reject(signal?.reason)\n    }\n    signal?.addEventListener(\"abort\", onAbort, { once: true })\n  })\n}\n\n/** AbortSignal.any isn't in Node 18, so combine the caller's signal and the timeout by hand. */\nfunction withTimeout(\n  ms: number,\n  signal: AbortSignal | undefined\n): { signal: AbortSignal; cleanup: () => void; timedOut: () => boolean } {\n  const controller = new AbortController()\n  let fired = false\n  const timer = setTimeout(() => {\n    fired = true\n    controller.abort()\n  }, ms)\n  const onAbort = () => controller.abort(signal?.reason)\n  if (signal?.aborted) controller.abort(signal.reason)\n  else signal?.addEventListener(\"abort\", onAbort, { once: true })\n\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      clearTimeout(timer)\n      signal?.removeEventListener(\"abort\", onAbort)\n    },\n    timedOut: () => fired,\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@torvion/rascador",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Rascador product data API: SHEIN, AliExpress, Amazon and Back Market.",
+  "license": "MIT",
+  "author": "Torvion",
+  "homepage": "https://rascador.store/developers/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Torvion-Labs/rascador-js.git"
+  },
+  "bugs": "https://github.com/Torvion-Labs/rascador-js/issues",
+  "keywords": ["rascador", "scraping", "shein", "aliexpress", "amazon", "backmarket", "product-data", "sdk"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:package": "publint && attw --pack .",
+    "changeset": "changeset",
+    "version": "changeset version && node scripts/sync-version.mjs",
+    "release": "npm run build && changeset publish",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^2.27.0",
+    "@types/node": "^22.0.0",
+    "publint": "^0.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}