@carddex/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,583 @@
-export { CardDexClient } from './client.js';
-export type { Card, CardWithRelations, CardAttack, CardAbility, CardWeakness, CardResistance, CardImage, CardPrice, CardVariant, CardMeta, Set, PaginatedResponse, PaginationMeta, CardListParams, CardDexClientOptions, WebhookSubscription, } from './types.js';
-//# sourceMappingURL=index.d.ts.map
+type QueryValue = string | number | boolean | undefined | null | readonly (string | number)[];
+type QueryParams = Record<string, QueryValue>;
+interface RetryOptions {
+    /** Max retry attempts on 429. Default 2. */
+    maxRetries?: number;
+    /**
+     * A computed `Retry-After` above this many seconds is never honoured — the
+     * request fails immediately instead of sleeping (this is what keeps a
+     * daily-quota 429, whose `Retry-After` can be most of a day, from blocking
+     * for hours). Default 60, matching the per-minute limiter's own
+     * `Retry-After: 60`.
+     */
+    maxWaitSeconds?: number;
+}
+interface HttpClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    fetch: typeof fetch;
+    /** `false` (default) disables retries; `true` enables them with the defaults below. */
+    retry?: boolean | RetryOptions;
+}
+/**
+ * Minimal fetch wrapper: builds URLs, attaches auth, parses JSON, and turns
+ * non-2xx responses into `CardDexError`. No dependency beyond global `fetch`.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly retryConfig;
+    constructor(options: HttpClientOptions);
+    get<T>(path: string, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    private request;
+}
+
+/**
+ * Domain types for CardDex API responses.
+ *
+ * The OpenAPI spec (`openapi.json` in this package, generated from
+ * `https://api.carddex.dev/openapi.json`) currently documents paths,
+ * parameters and status codes but not response body schemas — every
+ * `responses[status]` is a bare `{ description }`. `src/generated/openapi.d.ts`
+ * is generated straight from that spec and is honest about the gap: response
+ * bodies come back typed as `unknown`.
+ *
+ * These interfaces fill that gap by hand, mirroring the API's own internal
+ * row shapes (`apps/carddex-api/src/types/index.ts` /
+ * `packages/shared/src/types/*.ts` in the monorepo this SDK ships from) as of
+ * 2026-09-27. They are the best available typing today; once the API adds
+ * `content.schema` to its OpenAPI responses, this file should be regenerated
+ * instead of maintained by hand.
+ */
+interface CardDexSet {
+    id: string;
+    name: string;
+    series: string | null;
+    release_date: string | null;
+    official_cards: number | null;
+    total_cards: number | null;
+    logo_url: string | null;
+    symbol_url: string | null;
+    set_code: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CardAttack {
+    id: number;
+    card_id: string;
+    name: string;
+    cost: string[] | null;
+    damage: string | null;
+    text: string | null;
+    sort_order: number | null;
+}
+interface CardAbility {
+    id: number;
+    card_id: string;
+    name: string;
+    text: string | null;
+    type: string | null;
+}
+interface CardWeakness {
+    id: number;
+    card_id: string;
+    type: string;
+    value: string;
+}
+interface CardResistance {
+    id: number;
+    card_id: string;
+    type: string;
+    value: string;
+}
+interface CardImage {
+    id: number;
+    card_id: string;
+    language: string;
+    small_url: string | null;
+    large_url: string | null;
+}
+/** One price guide's currency and figures. `source` is `'cardmarket' | 'tcgplayer'` in practice. */
+interface CardPrice {
+    id: number;
+    card_id: string;
+    card_name?: string | null;
+    number?: string | null;
+    set_id?: string | null;
+    rarity?: string | null;
+    supertype?: string | null;
+    variant_id: string | null;
+    source: string;
+    currency: string;
+    trend_price: number | null;
+    avg_price: number | null;
+    low_price: number | null;
+    avg_1d: number | null;
+    avg_7d: number | null;
+    avg_30d: number | null;
+    price_change_1d: number | null;
+    price_change_7d: number | null;
+    price_change_30d: number | null;
+    recorded_at: string;
+}
+/** A `/v1/prices/bargains` row: a `CardPrice` plus the discount used to rank it. */
+type BargainCardPrice = CardPrice & {
+    discount_pct: number;
+};
+interface CardVariant {
+    id: string;
+    card_id: string;
+    variant_type: string;
+    edition: string | null;
+    rarity: string | null;
+    image_url: string | null;
+    artist: string | null;
+    ball_type: string | null;
+    source: string;
+    cardmarket_id: number | null;
+    cardmarket_url: string | null;
+    tcgplayer_id: number | null;
+    created_at: string;
+    updated_at: string;
+    /** `1` on the card's base print, `0` on alternates. See variant-list endpoints. */
+    is_base?: number;
+}
+interface Card {
+    id: string;
+    set_id: string;
+    name: string;
+    number: string;
+    supertype: string;
+    subtypes: string[] | null;
+    hp: number | null;
+    types: string[] | null;
+    rarity: string | null;
+    artist: string | null;
+    regulation_mark: string | null;
+    flavor_text: string | null;
+    rules: string[] | null;
+    evolves_from: string | null;
+    evolves_to: string[] | null;
+    retreat_cost: number;
+    legalities: Record<string, string> | null;
+    cardmarket_id: number | null;
+    cardmarket_url: string | null;
+    tcgplayer_id: number | null;
+    version_code: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A `Card` with the relations requested via `include=`. Every field here is optional and only present when asked for. */
+interface CardWithRelations extends Card {
+    attacks?: CardAttack[];
+    abilities?: CardAbility[];
+    weaknesses?: CardWeakness[];
+    resistances?: CardResistance[];
+    images?: CardImage[];
+    prices?: CardPrice[];
+    variants?: CardVariant[];
+    set?: CardDexSet;
+}
+/** The 2 previous / 2 next card ids within a set, from `/v1/sets/{id}/cards/{cardId}/neighbors`. */
+interface CardNeighbors {
+    prev_prev: string | null;
+    prev: string | null;
+    next: string | null;
+    next_next: string | null;
+}
+/** Known `sealed_products.product_type` values. The column has no CHECK constraint, so treat this as open — expect strings not (yet) listed here. */
+type SealedProductType = 'booster_box' | 'booster_bundle' | 'elite_trainer_box' | 'case' | 'collection' | 'premium_collection' | 'tin' | 'mini_tin' | 'blister' | 'deck' | 'trainer_kit' | 'build_and_battle' | 'other';
+interface SealedLatestPrice {
+    source: string;
+    currency: string;
+    trend: number | null;
+    avg: number | null;
+    low: number | null;
+    avg_1d: number | null;
+    avg_7d: number | null;
+    avg_30d: number | null;
+    price_change_1d: number | null;
+    price_change_7d: number | null;
+    price_change_30d: number | null;
+    recorded_at: string;
+}
+interface SealedProduct {
+    id: string;
+    set_id: string | null;
+    name: string;
+    product_type: string;
+    cardmarket_id: number | null;
+    cardmarket_category_id: number | null;
+    cardmarket_expansion: string | null;
+    image_url: string | null;
+    source_image_url: string | null;
+    created_at: string;
+    updated_at: string;
+    /** The newest price row, or `null` if the product has never been priced. */
+    latest_price?: SealedLatestPrice | null;
+}
+/** A row of sealed price history. Mirrors `CardPrice` minus `variant_id`. */
+interface SealedPrice {
+    id: number;
+    sealed_product_id: string;
+    source: string;
+    currency: string;
+    trend_price: number | null;
+    avg_price: number | null;
+    low_price: number | null;
+    avg_1d: number | null;
+    avg_7d: number | null;
+    avg_30d: number | null;
+    price_change_1d: number | null;
+    price_change_7d: number | null;
+    price_change_30d: number | null;
+    recorded_at: string;
+}
+interface PaginationMeta {
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    meta: PaginationMeta;
+}
+interface SingleResponse<T> {
+    data: T;
+}
+/**
+ * The API's error body, present on every non-2xx JSON response.
+ *
+ * `docs.astro` shows `code: "NOT_FOUND"` as an example, but
+ * `apps/carddex-api/src/middleware/errorHandler.ts` actually writes the HTTP
+ * status number into `code` (`{ error: { code: err.status, message } }`), and
+ * `packages/shared`'s own `ErrorResponse` type agrees (`code: number`). This
+ * SDK follows the real runtime shape, not the docs example — see the "spec
+ * gaps" note in this package's README.
+ */
+interface ApiErrorBody {
+    error: {
+        code: number;
+        message: string;
+    };
+}
+interface UsageRecentRequest {
+    endpoint: string;
+    status_code: number | null;
+    response_time_ms: number | null;
+    created_at: string;
+}
+/** Response of `GET /v1/auth/usage` for the calling API key. */
+interface UsageResponse {
+    tier: string;
+    /** Requests per minute allowed for the tier; `null` for admin keys. */
+    rate_limit: number | null;
+    /** Requests per UTC day allowed for the tier; `null` when uncapped. */
+    daily_limit: number | null;
+    requests_today: number;
+    total_requests: number;
+    /** Last 100 requests, newest first. */
+    recent: UsageRecentRequest[];
+}
+/** Response of `POST /v1/auth/register`. */
+interface RegisterResponse {
+    api_key: string;
+    tier: string;
+    rate_limit: number;
+    message: string;
+}
+/** Response of `GET /v1/health`. */
+interface HealthResponse {
+    status: 'ok' | 'degraded';
+    [key: string]: unknown;
+}
+
+declare class AuthResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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).
+     */
+    register(email: string, name?: string): Promise<RegisterResponse>;
+    /** `GET /v1/auth/usage` — usage stats for the API key this client was constructed with. Requires an `apiKey`. */
+    usage(): Promise<UsageResponse>;
+}
+
+/**
+ * Request parameter types, mirroring the query parameters declared in
+ * `OPENAPI_SPEC` (`apps/carddex-api/src/routes/docs.ts`) in the monorepo.
+ */
+/** A single price guide, or several comma-joined to get each one's own labelled series (display endpoints only). */
+type CardPriceSource = 'cardmarket' | 'tcgplayer' | (string & {});
+/** Ranking endpoints (`/prices/top`, `/trends`, `/bargains`) sort by one guide's price, so only one is accepted. */
+type CardPriceSourceOne = 'cardmarket' | 'tcgplayer';
+/** Sealed products are priced by Cardmarket only. */
+type SealedPriceSource = 'cardmarket';
+type CardSortField = 'name' | 'hp' | 'number' | 'rarity' | 'set' | 'artist' | 'release_date';
+type CardInclude = 'attacks' | 'abilities' | 'weaknesses' | 'resistances' | 'images' | 'prices' | 'variants';
+type CardListParams = {
+    name?: string;
+    q?: string;
+    set?: string;
+    type?: string;
+    rarity?: string;
+    supertype?: string;
+    hp_gte?: number;
+    hp_lte?: number;
+    artist?: string;
+    /** The catalogue is English-only for now; anything else is a 400. Defaults to `en`. */
+    lang?: 'en';
+    page?: number;
+    /** Max 250. */
+    pageSize?: number;
+    sort?: CardSortField;
+    order?: 'asc' | 'desc';
+    /** One or more of `CardInclude`, comma-separated or as an array. */
+    include?: CardInclude | CardInclude[];
+    /** One or more price guides — an array asks for each guide's own row. */
+    source?: CardPriceSource | CardPriceSource[];
+};
+type CardGetParams = {
+    include?: CardInclude | CardInclude[];
+    source?: CardPriceSource | CardPriceSource[];
+};
+type CardPricesParams = {
+    /** Price this print instead of the base card. */
+    variant_id?: string;
+    source?: CardPriceSource | CardPriceSource[];
+};
+type CardPriceHistoryParams = CardPricesParams & {
+    /** Window length in days, counted back from today. Defaults to 90, capped at 365. */
+    days?: number;
+};
+type SetCardsParams = {
+    page?: number;
+    pageSize?: number;
+};
+type SealedListParams = {
+    set_id?: string;
+    type?: string;
+    q?: string;
+    page?: number;
+    /** Max 250. */
+    pageSize?: number;
+    source?: SealedPriceSource;
+};
+type SealedPriceHistoryParams = {
+    /** Window length in days. Defaults to 90, capped at 365. */
+    days?: number;
+    source?: SealedPriceSource;
+};
+type BulkPricesParams = {
+    /** Card ids, up to 100. */
+    ids?: string[];
+    /** Print (variant) ids, up to 100. At least one of `ids`/`variants` is required. */
+    variants?: string[];
+    source?: CardPriceSource | CardPriceSource[];
+};
+type RankingParams = {
+    limit?: number;
+    offset?: number;
+    /** Narrow to one CardDex set id. */
+    set?: string;
+    source?: CardPriceSourceOne;
+};
+type TrendsParams = RankingParams & {
+    direction?: 'up' | 'down';
+};
+type BargainsParams = RankingParams & {
+    mode?: 'below-average' | 'cheapest';
+    minPrice?: number;
+};
+type PriceHistoryParams = {
+    days?: number;
+    /** Print (variant) id; defaults to the base card. */
+    variant?: string;
+    source?: CardPriceSource | CardPriceSource[];
+};
+
+declare class CardsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/cards` — list, search, filter and sort cards. */
+    list(params?: CardListParams): Promise<PaginatedResponse<Card>>;
+    /**
+     * 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?: Omit<CardListParams, 'page'>): AsyncGenerator<Card, void, void>;
+    /** `GET /v1/cards/random` */
+    random(): Promise<CardWithRelations>;
+    /** `GET /v1/cards/{id}` */
+    get(id: string, params?: CardGetParams): Promise<CardWithRelations>;
+    /** `GET /v1/cards/{id}/prices` — the latest price row(s) for a card. */
+    prices(id: string, params?: CardPricesParams): Promise<CardPrice[]>;
+    /** `GET /v1/cards/{id}/prices/history` — one row per day per price guide, oldest first. */
+    priceHistory(id: string, params?: CardPriceHistoryParams): Promise<CardPrice[]>;
+}
+
+declare class PricesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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 `[]`.
+     */
+    bulk(params: BulkPricesParams): Promise<Record<string, CardPrice[]>>;
+    /** `GET /v1/prices/top` — highest-valued cards. */
+    top(params?: RankingParams): Promise<CardPrice[]>;
+    /** `GET /v1/prices/trends` — biggest movers against the card's own rolling average. */
+    trends(params?: TrendsParams): Promise<CardPrice[]>;
+    /** `GET /v1/prices/bargains` — cards trading below a reference price, best discount first. */
+    bargains(params?: BargainsParams): Promise<BargainCardPrice[]>;
+    /** `GET /v1/prices/{cardId}/history` — one row per day per guide, oldest first. */
+    history(cardId: string, params?: PriceHistoryParams): Promise<CardPrice[]>;
+}
+
+declare class SealedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/sealed` — list sealed products with their latest price. */
+    list(params?: SealedListParams): Promise<PaginatedResponse<SealedProduct>>;
+    /** Iterates every sealed product matching `params` across all pages. */
+    listAll(params?: Omit<SealedListParams, 'page'>): AsyncGenerator<SealedProduct, void, void>;
+    /** `GET /v1/sealed/{id}` */
+    get(id: string, params?: {
+        source?: SealedListParams['source'];
+    }): Promise<SealedProduct>;
+    /** `GET /v1/sealed/{id}/prices` — one row per synced day, oldest first. */
+    prices(id: string, params?: SealedPriceHistoryParams): Promise<SealedPrice[]>;
+}
+
+declare class SetsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/sets` — every set. */
+    list(): Promise<CardDexSet[]>;
+    /** `GET /v1/sets/{id}` */
+    get(id: string): Promise<CardDexSet>;
+    /** `GET /v1/sets/{id}/cards` */
+    cards(id: string, params?: SetCardsParams): Promise<PaginatedResponse<Card>>;
+    /** Iterates every card in a set across all pages. */
+    cardsAll(id: string, params?: Omit<SetCardsParams, 'page'>): AsyncGenerator<Card, void, void>;
+    /** `GET /v1/sets/{id}/cards/{cardId}/neighbors` — the 2 previous / 2 next card ids. */
+    neighbors(setId: string, cardId: string): Promise<CardNeighbors>;
+    /** `GET /v1/sets/{id}/sealed` — sealed products attached to a set, each with its latest price. */
+    sealed(id: string, params?: {
+        source?: SealedPriceSource;
+    }): Promise<SealedProduct[]>;
+}
+
+interface CardDexOptions {
+    /**
+     * A `pk_live_...` key from `POST /v1/auth/register`. Omit it to call the
+     * API anonymously — CardDex allows this at a lower rate (30 req/min,
+     * 5,000 req/day per IP), specifically so a browser can call it without a
+     * key. **Never ship a real API key in public frontend code**: it would be
+     * readable by anyone who opens dev tools and shared by every visitor to
+     * your site. Proxy through your own backend instead if you need the
+     * higher, keyed limits from a browser context.
+     */
+    apiKey?: string;
+    /** Defaults to `https://api.carddex.dev`. Override for a local/staging API or a CORS proxy. */
+    baseUrl?: string;
+    /** Defaults to the global `fetch`. Override to inject a custom implementation (proxies, logging, tests). */
+    fetch?: typeof fetch;
+    /**
+     * Automatic retry on `429`, honouring `Retry-After`. **Off by default.**
+     * Pass `true` for the defaults (up to 2 retries, never waiting more than
+     * 60s), or an object to tune them. A `Retry-After` longer than
+     * `maxWaitSeconds` — typically the daily-quota reset, which can be most of
+     * a day away — is never honoured; the request fails immediately instead.
+     */
+    retry?: boolean | RetryOptions;
+}
+/**
+ * CardDex API client.
+ *
+ * ```ts
+ * import { CardDex } from '@carddex/sdk';
+ *
+ * const client = new CardDex({ apiKey: process.env.CARDDEX_API_KEY });
+ * const { data } = await client.cards.list({ name: 'Charizard' });
+ * ```
+ */
+declare class CardDex {
+    readonly cards: CardsResource;
+    readonly sets: SetsResource;
+    readonly sealed: SealedResource;
+    readonly prices: PricesResource;
+    readonly auth: AuthResource;
+    private readonly http;
+    constructor(options?: CardDexOptions);
+    /** `GET /v1/auth/usage` — shorthand for `client.auth.usage()`. Requires an `apiKey`. */
+    usage(): Promise<UsageResponse>;
+    /** `GET /v1/health` — API health, price freshness, and cron status. */
+    health(): Promise<HealthResponse>;
+}
+
+/** Rate-limit info parsed from response headers, when present. */
+interface RateLimitInfo {
+    /** `X-RateLimit-Limit`: requests allowed per minute. */
+    limit: number | null;
+    /** `X-RateLimit-Daily-Limit`: requests allowed per UTC day, or `null` when the tier is uncapped. */
+    dailyLimit: number | null;
+    /** `X-RateLimit-Daily-Remaining`: approximate, can lag by about a minute. `null` when the API couldn't compute it. */
+    dailyRemaining: number | null;
+}
+/**
+ * Thrown for any non-2xx response, and for network/parse failures the fetch
+ * layer can't attribute to the API itself.
+ */
+declare class CardDexError extends Error {
+    /** HTTP status code. `0` for a request that never got a response (network failure, abort). */
+    readonly status: number;
+    /**
+     * 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.
+     */
+    readonly code: number | string;
+    /** Seconds to wait before retrying, parsed from `Retry-After` on a 429. `null` otherwise. */
+    readonly retryAfter: number | null;
+    /** Rate-limit headers on the response, when there was one. */
+    readonly rateLimit: RateLimitInfo | null;
+    constructor(message: string, options: {
+        status: number;
+        code: number | string;
+        retryAfter?: number | null;
+        rateLimit?: RateLimitInfo | null;
+        cause?: unknown;
+    });
+    /** Whether this is a 429 (either the per-minute or the daily cap). */
+    get isRateLimited(): boolean;
+    static fromResponse(response: Response): Promise<CardDexError>;
+    static network(cause: unknown): CardDexError;
+}
+
+/**
+ * Turns a page-fetching function into an async iterator over every item,
+ * fetching the next page lazily as the caller consumes items.
+ *
+ * @example
+ * ```ts
+ * for await (const card of paginate((page) => client.cards.list({ set: 'sv06', page }))) {
+ *   console.log(card.name);
+ * }
+ * ```
+ */
+declare function paginate<T>(fetchPage: (page: number) => Promise<PaginatedResponse<T>>, startPage?: number): AsyncGenerator<T, void, void>;
+
+export { type ApiErrorBody, type BargainCardPrice, type BargainsParams, type BulkPricesParams, type Card, type CardAbility, type CardAttack, CardDex, CardDexError, type CardDexOptions, type CardDexSet, type CardGetParams, type CardImage, type CardInclude, type CardListParams, type CardNeighbors, type CardPrice, type CardPriceHistoryParams, type CardPriceSource, type CardPriceSourceOne, type CardPricesParams, type CardResistance, type CardSortField, type CardVariant, type CardWeakness, type CardWithRelations, type HealthResponse, type PaginatedResponse, type PaginationMeta, type PriceHistoryParams, type RankingParams, type RateLimitInfo, type RegisterResponse, type RetryOptions, type SealedLatestPrice, type SealedListParams, type SealedPrice, type SealedPriceHistoryParams, type SealedPriceSource, type SealedProduct, type SealedProductType, type SetCardsParams, type SingleResponse, type TrendsParams, type UsageRecentRequest, type UsageResponse, paginate };