@carddex/sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Furgalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @carddex/sdk
+
+Official TypeScript/JavaScript client for the [CardDex](https://carddex.dev) Pokémon TCG API — cards, sets, print variants, sealed products, and price history from Cardmarket (EUR) and TCGplayer (USD).
+
+- Zero runtime dependencies — uses global `fetch`, so it runs unmodified in Node 18+, browsers, Cloudflare Workers, Deno and Bun.
+- Fully typed, ESM + CJS builds, with a shipped `.d.ts`.
+- No codegen step for consumers: types are generated at build time from the CardDex OpenAPI spec and committed.
+
+## Install
+
+```bash
+npm install @carddex/sdk
+# or
+pnpm add @carddex/sdk
+# or
+yarn add @carddex/sdk
+```
+
+## Quickstart
+
+```ts
+import { CardDex } from '@carddex/sdk';
+
+const client = new CardDex({ apiKey: process.env.CARDDEX_API_KEY });
+
+const { data: cards } = await client.cards.list({ name: 'Charizard', sort: 'release_date', order: 'desc' });
+
+const card = await client.cards.get('sv06-001', { include: ['prices', 'images'] });
+
+const prices = await client.cards.prices('sv06-001');
+
+const history = await client.cards.priceHistory('sv06-001', { days: 180, source: ['cardmarket', 'tcgplayer'] });
+```
+
+An API key is optional. Omit it to call the API anonymously. The SDK sends the key in the `X-API-Key` header.
+
+You can also sign in with an email link at [carddex.dev/account](https://carddex.dev/account) to see your keys, create up to 2 active keys, and rotate or revoke them.
+### Get a free API key
+
+```ts
+import { CardDex } from '@carddex/sdk';
+
+const client = new CardDex();
+const { api_key } = await client.auth.register('you@example.com', 'My App');
+// Save api_key now — it is shown only once. If you lose it, sign in at https://carddex.dev/account to create a new one or rotate/revoke keys.
+```
+
+## Calling from a browser
+
+Public read endpoints accept requests from any origin. **Never ship a real API key in public frontend code** — anyone who opens dev tools can read it, and it would be shared by every visitor to your site. Instead:
+
+- Call anonymously from the browser. CardDex allows this at a lower but real rate limit (30 req/min, 5,000 req/day per visitor IP) specifically so a frontend can call it directly, with no key:
+
+  ```ts
+  const client = new CardDex(); // no apiKey — anonymous browser mode
+  ```
+
+- Or proxy through your own backend and attach the key there, server-side.
+
+If you construct `new CardDex({ apiKey })` in what looks like a browser environment, the SDK logs a one-time `console.warn` as a safety net — it does not block the request.
+
+## Pagination
+
+Every list endpoint returns `{ data, meta: { total, page, pageSize, totalPages } }`. Each resource that lists something also exposes an `*All` method that returns an async iterator, fetching pages lazily as you consume them:
+
+```ts
+for await (const card of client.cards.listAll({ set: 'sv06' })) {
+  console.log(card.name);
+}
+
+for await (const product of client.sealed.listAll({ set_id: 'sv06' })) { ... }
+
+for await (const card of client.sets.cardsAll('sv06')) { ... }
+```
+
+You can also use the lower-level `paginate()` helper directly against any page-shaped fetcher:
+
+```ts
+import { paginate } from '@carddex/sdk';
+
+for await (const card of paginate((page) => client.cards.list({ set: 'sv06', page }))) { ... }
+```
+
+## Errors
+
+Every non-2xx response throws a `CardDexError`:
+
+```ts
+import { CardDex, CardDexError } from '@carddex/sdk';
+
+try {
+  await client.cards.get('does-not-exist');
+} catch (err) {
+  if (err instanceof CardDexError) {
+    err.status;      // HTTP status, e.g. 404
+    err.code;         // the API's error.code (a number for a real API response; 'NETWORK_ERROR' for a transport failure)
+    err.message;      // the API's error.message
+    err.retryAfter;   // seconds to wait, parsed from Retry-After on a 429 — null otherwise
+    err.rateLimit;    // { limit, dailyLimit, dailyRemaining } parsed from response headers, or null
+    err.isRateLimited; // true for a 429 (either the per-minute or the daily cap)
+  }
+}
+```
+
+## Rate limits & retries
+
+Every response carries `X-RateLimit-Limit` (per minute), `X-RateLimit-Daily-Limit` and `X-RateLimit-Daily-Remaining` (per UTC day, approximate). A 429 carries `Retry-After` in seconds: `60` for the per-minute limit, or the seconds until 00:00 UTC for the daily one.
+
+Automatic retry on 429 is **off by default** — the SDK never silently blocks your code. Turn it on when you want it:
+
+```ts
+const client = new CardDex({ retry: true }); // up to 2 retries, never waiting more than 60s
+
+const client2 = new CardDex({ retry: { maxRetries: 3, maxWaitSeconds: 30 } });
+```
+
+A `Retry-After` longer than `maxWaitSeconds` is never honoured — the call fails immediately instead of sleeping. This is deliberate: the daily-quota 429's `Retry-After` can be most of a day, and a small SDK default should never block a request for hours. The per-minute 429's `Retry-After: 60` fits comfortably under the default 60s cap, so that case retries; a daily-cap 429 does not, by design.
+
+## Migrating from pokemontcg.io
+
+The pokemontcg.io v2 compatibility layer is live: an app built on pokemontcg.io v2 can keep its code and stored ids and change its base URL to `https://api.carddex.dev/compat/pokemontcg/v2`. The guide at [carddex.dev/migrate/pokemontcg](https://carddex.dev/migrate/pokemontcg) covers what the layer supports, which official pokemontcg.io SDKs work with it, and the fields that differ.
+
+This SDK talks to the native `/v1` API, which uses CardDex ids (`sv02-062`) but accepts pokemontcg.io ids as well: `client.cards.get('sv2-62')` returns the same card. The API also returns a `ptcgio_id` field on every card and accepts a `ptcgio_id` filter on the card list; this SDK's types don't include either yet.
+
+## API surface
+
+| Resource | Methods |
+| --- | --- |
+| `client.cards` | `list`, `listAll`, `get`, `random`, `prices`, `priceHistory` |
+| `client.sets` | `list`, `get`, `cards`, `cardsAll`, `neighbors`, `sealed` |
+| `client.sealed` | `list`, `listAll`, `get`, `prices` |
+| `client.prices` | `bulk`, `top`, `trends`, `bargains`, `history` |
+| `client.auth` | `register`, `usage` |
+| `client` | `usage()` (shorthand for `client.auth.usage()`), `health()` |
+
+Full parameter and response types are exported from the package root — see `src/params.ts` and `src/types.ts`, or your editor's autocomplete.
+
+## Development (this monorepo)
+
+```bash
+pnpm install
+pnpm --filter @carddex/sdk generate   # refresh src/generated/openapi.d.ts from the live OpenAPI spec
+pnpm --filter @carddex/sdk build
+pnpm --filter @carddex/sdk test
+pnpm --filter @carddex/sdk typecheck
+pnpm --filter @carddex/sdk lint
+```
+
+`openapi.json` in this package's root is a committed snapshot of `https://api.carddex.dev/openapi.json`. `pnpm generate` refreshes it and regenerates `src/generated/openapi.d.ts` from it; if the fetch fails (offline, no network egress in CI), it regenerates from whatever snapshot is already committed instead of failing outright.
+
+The OpenAPI spec now documents response body schemas too (`components.schemas`, validated against live API responses by `carddex-api`'s `tests/integration/openapi-contract.test.ts`), so `src/generated/openapi.d.ts` types response bodies precisely rather than as `unknown`. The hand-written interfaces in `src/types.ts` predate that and can stay — they're what this SDK's public API is built on — but new code can also reach into `components["schemas"]` from the generated file directly.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,444 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CardDex: () => CardDex,
+  CardDexError: () => CardDexError,
+  paginate: () => paginate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+function parseRateLimitHeaders(headers) {
+  const num = (name) => {
+    const raw = headers.get(name);
+    if (raw == null) return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  };
+  return {
+    limit: num("X-RateLimit-Limit"),
+    dailyLimit: num("X-RateLimit-Daily-Limit"),
+    dailyRemaining: num("X-RateLimit-Daily-Remaining")
+  };
+}
+var CardDexError = class _CardDexError extends Error {
+  /** HTTP status code. `0` for a request that never got a response (network failure, abort). */
+  status;
+  /**
+   * The API's own `error.code`. For a response the API actually produced,
+   * this is the same number as `status` (see the note on `ApiErrorBody` in
+   * `types.ts`) — kept as its own field because a transport-level failure
+   * (no response at all) sets it to a string like `NETWORK_ERROR` instead.
+   */
+  code;
+  /** Seconds to wait before retrying, parsed from `Retry-After` on a 429. `null` otherwise. */
+  retryAfter;
+  /** Rate-limit headers on the response, when there was one. */
+  rateLimit;
+  constructor(message, options) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "CardDexError";
+    this.status = options.status;
+    this.code = options.code;
+    this.retryAfter = options.retryAfter ?? null;
+    this.rateLimit = options.rateLimit ?? null;
+    Object.setPrototypeOf(this, _CardDexError.prototype);
+  }
+  /** Whether this is a 429 (either the per-minute or the daily cap). */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  static async fromResponse(response) {
+    const rateLimit = parseRateLimitHeaders(response.headers);
+    const retryAfterHeader = response.headers.get("Retry-After");
+    const retryAfter = retryAfterHeader != null ? Number(retryAfterHeader) : null;
+    let message = `CardDex API error (${response.status})`;
+    let code = response.status;
+    try {
+      const body = await response.clone().json();
+      if (body?.error) {
+        if (typeof body.error.message === "string") message = body.error.message;
+        if (typeof body.error.code === "number" || typeof body.error.code === "string") {
+          code = body.error.code;
+        }
+      }
+    } catch {
+    }
+    return new _CardDexError(message, {
+      status: response.status,
+      code,
+      retryAfter: Number.isFinite(retryAfter) ? retryAfter : null,
+      rateLimit
+    });
+  }
+  static network(cause) {
+    const message = cause instanceof Error ? cause.message : "Network request failed";
+    return new _CardDexError(message, { status: 0, code: "NETWORK_ERROR", cause });
+  }
+};
+
+// src/http.ts
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_MAX_WAIT_SECONDS = 60;
+function buildQueryString(params) {
+  if (!params) return "";
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      search.set(key, value.join(","));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  const qs = search.toString();
+  return qs ? `?${qs}` : "";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var HttpClient = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  retryConfig;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch;
+    if (options.retry === true) {
+      this.retryConfig = {
+        maxRetries: DEFAULT_MAX_RETRIES,
+        maxWaitSeconds: DEFAULT_MAX_WAIT_SECONDS
+      };
+    } else if (options.retry && typeof options.retry === "object") {
+      this.retryConfig = {
+        maxRetries: options.retry.maxRetries ?? DEFAULT_MAX_RETRIES,
+        maxWaitSeconds: options.retry.maxWaitSeconds ?? DEFAULT_MAX_WAIT_SECONDS
+      };
+    } else {
+      this.retryConfig = null;
+    }
+  }
+  async get(path, query, signal) {
+    return this.request("GET", path, { query, signal });
+  }
+  async post(path, body, signal) {
+    return this.request("POST", path, { body, signal });
+  }
+  async request(method, path, opts) {
+    const url = `${this.baseUrl}${path}${buildQueryString(opts.query)}`;
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+          signal: opts.signal
+        });
+      } catch (cause) {
+        throw CardDexError.network(cause);
+      }
+      if (response.status === 429 && this.retryConfig && attempt < this.retryConfig.maxRetries) {
+        const retryAfterHeader = response.headers.get("Retry-After");
+        const retryAfterSeconds = retryAfterHeader != null ? Number(retryAfterHeader) : Number.NaN;
+        if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds <= this.retryConfig.maxWaitSeconds) {
+          attempt++;
+          await sleep(retryAfterSeconds * 1e3);
+          continue;
+        }
+      }
+      if (!response.ok) {
+        throw await CardDexError.fromResponse(response);
+      }
+      if (response.status === 204) return void 0;
+      return await response.json();
+    }
+  }
+};
+
+// src/resources/auth.ts
+var AuthResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * `POST /v1/auth/register` — claim a free API key. The key is returned
+   * exactly once, so store it immediately. A lost key can be replaced by signing
+   * in at https://carddex.dev/account (create, rotate or revoke keys there).
+   */
+  async register(email, name) {
+    const res = await this.http.post("/v1/auth/register", {
+      email,
+      name
+    });
+    return res.data;
+  }
+  /** `GET /v1/auth/usage` — usage stats for the API key this client was constructed with. Requires an `apiKey`. */
+  async usage() {
+    const res = await this.http.get("/v1/auth/usage");
+    return res.data;
+  }
+};
+
+// src/pagination.ts
+async function* paginate(fetchPage, startPage = 1) {
+  let page = startPage;
+  for (; ; ) {
+    const response = await fetchPage(page);
+    if (response.data.length === 0) return;
+    yield* response.data;
+    if (page >= response.meta.totalPages) return;
+    page++;
+  }
+}
+
+// src/resources/cards.ts
+var CardsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** `GET /v1/cards` — list, search, filter and sort cards. */
+  list(params) {
+    return this.http.get("/v1/cards", params);
+  }
+  /**
+   * Iterates every card matching `params` across all pages, fetching pages
+   * lazily as you consume them.
+   *
+   * @example
+   * ```ts
+   * for await (const card of client.cards.listAll({ set: 'sv06' })) { ... }
+   * ```
+   */
+  listAll(params) {
+    return paginate((page) => this.list({ ...params, page }));
+  }
+  /** `GET /v1/cards/random` */
+  async random() {
+    const res = await this.http.get("/v1/cards/random");
+    return res.data;
+  }
+  /** `GET /v1/cards/{id}` */
+  async get(id, params) {
+    const res = await this.http.get(
+      `/v1/cards/${encodeURIComponent(id)}`,
+      params
+    );
+    return res.data;
+  }
+  /** `GET /v1/cards/{id}/prices` — the latest price row(s) for a card. */
+  async prices(id, params) {
+    const res = await this.http.get(
+      `/v1/cards/${encodeURIComponent(id)}/prices`,
+      params
+    );
+    return res.data;
+  }
+  /** `GET /v1/cards/{id}/prices/history` — one row per day per price guide, oldest first. */
+  async priceHistory(id, params) {
+    const res = await this.http.get(
+      `/v1/cards/${encodeURIComponent(id)}/prices/history`,
+      params
+    );
+    return res.data;
+  }
+};
+
+// src/resources/prices.ts
+var PricesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * `GET /v1/prices` — latest price rows for up to 100 card ids (and/or up
+   * to 100 print/variant ids) in one request. Keyed by the id you asked for;
+   * an id with no price data maps to `[]`.
+   */
+  async bulk(params) {
+    const res = await this.http.get(
+      "/v1/prices",
+      params
+    );
+    return res.data;
+  }
+  /** `GET /v1/prices/top` — highest-valued cards. */
+  async top(params) {
+    const res = await this.http.get("/v1/prices/top", params);
+    return res.data;
+  }
+  /** `GET /v1/prices/trends` — biggest movers against the card's own rolling average. */
+  async trends(params) {
+    const res = await this.http.get("/v1/prices/trends", params);
+    return res.data;
+  }
+  /** `GET /v1/prices/bargains` — cards trading below a reference price, best discount first. */
+  async bargains(params) {
+    const res = await this.http.get(
+      "/v1/prices/bargains",
+      params
+    );
+    return res.data;
+  }
+  /** `GET /v1/prices/{cardId}/history` — one row per day per guide, oldest first. */
+  async history(cardId, params) {
+    const res = await this.http.get(
+      `/v1/prices/${encodeURIComponent(cardId)}/history`,
+      params
+    );
+    return res.data;
+  }
+};
+
+// src/resources/sealed.ts
+var SealedResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** `GET /v1/sealed` — list sealed products with their latest price. */
+  list(params) {
+    return this.http.get("/v1/sealed", params);
+  }
+  /** Iterates every sealed product matching `params` across all pages. */
+  listAll(params) {
+    return paginate((page) => this.list({ ...params, page }));
+  }
+  /** `GET /v1/sealed/{id}` */
+  async get(id, params) {
+    const res = await this.http.get(
+      `/v1/sealed/${encodeURIComponent(id)}`,
+      params
+    );
+    return res.data;
+  }
+  /** `GET /v1/sealed/{id}/prices` — one row per synced day, oldest first. */
+  async prices(id, params) {
+    const res = await this.http.get(
+      `/v1/sealed/${encodeURIComponent(id)}/prices`,
+      params
+    );
+    return res.data;
+  }
+};
+
+// src/resources/sets.ts
+var SetsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** `GET /v1/sets` — every set. */
+  async list() {
+    const res = await this.http.get("/v1/sets");
+    return res.data;
+  }
+  /** `GET /v1/sets/{id}` */
+  async get(id) {
+    const res = await this.http.get(
+      `/v1/sets/${encodeURIComponent(id)}`
+    );
+    return res.data;
+  }
+  /** `GET /v1/sets/{id}/cards` */
+  cards(id, params) {
+    return this.http.get(
+      `/v1/sets/${encodeURIComponent(id)}/cards`,
+      params
+    );
+  }
+  /** Iterates every card in a set across all pages. */
+  cardsAll(id, params) {
+    return paginate((page) => this.cards(id, { ...params, page }));
+  }
+  /** `GET /v1/sets/{id}/cards/{cardId}/neighbors` — the 2 previous / 2 next card ids. */
+  async neighbors(setId, cardId) {
+    const res = await this.http.get(
+      `/v1/sets/${encodeURIComponent(setId)}/cards/${encodeURIComponent(cardId)}/neighbors`
+    );
+    return res.data;
+  }
+  /** `GET /v1/sets/{id}/sealed` — sealed products attached to a set, each with its latest price. */
+  async sealed(id, params) {
+    const res = await this.http.get(
+      `/v1/sets/${encodeURIComponent(id)}/sealed`,
+      params
+    );
+    return res.data;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.carddex.dev";
+function isBrowserLike() {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+var CardDex = class {
+  cards;
+  sets;
+  sealed;
+  prices;
+  auth;
+  http;
+  constructor(options = {}) {
+    if (options.apiKey && isBrowserLike()) {
+      console.warn(
+        "[@carddex/sdk] An apiKey was passed in what looks like a browser environment. API keys shipped in frontend code are visible to every visitor. Omit apiKey for CardDex's anonymous browser mode, or proxy authenticated requests through your own backend."
+      );
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error(
+        "@carddex/sdk requires a global fetch implementation. On Node < 18, pass one via `fetch` in the options."
+      );
+    }
+    this.http = new HttpClient({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      fetch: fetchImpl.bind(globalThis),
+      retry: options.retry
+    });
+    this.cards = new CardsResource(this.http);
+    this.sets = new SetsResource(this.http);
+    this.sealed = new SealedResource(this.http);
+    this.prices = new PricesResource(this.http);
+    this.auth = new AuthResource(this.http);
+  }
+  /** `GET /v1/auth/usage` — shorthand for `client.auth.usage()`. Requires an `apiKey`. */
+  usage() {
+    return this.auth.usage();
+  }
+  /** `GET /v1/health` — API health, price freshness, and cron status. */
+  async health() {
+    return this.http.get("/v1/health");
+  }
+};
+//# sourceMappingURL=index.cjs.map