justtcg-js/dist/index.d.ts

The official JavaScript/TypeScript SDK for the JustTCG API.

/**
 * Represents a single Trading Card Game.
 */
interface Game {
    /** The id of this game. */
    id: string;
    /** The name of this game. */
    name: string;
    /** The total number of cards in this game. */
    cards_count: number;
    /** The total number of sets in this game. */
    sets_count: number;
    /** The last updated timestamp for this game in Unix timestamp format (seconds since epoch). */
    last_updated: number;
}
/**
 * Represents a single Card Set within a Game.
 */
interface Set {
    /** The id of this set. */
    id: string;
    /** The name of this set. */
    name: string;
    /** The number of cards in this set. */
    count: number;
    /** The id of the game this set belongs to. */
    gameId: string;
    /** The release date of this set in ISO 8601 format. */
    release_date: string;
}
type StatisticTimeFrame = '7d' | '30d' | '90d' | '1y' | 'allTime';
type Condition = 'Sealed' | 'Near Mint' | 'Lightly Played' | 'Moderately Played' | 'Heavily Played' | 'Damaged';
type ConditionAbv = 'S' | 'NM' | 'LP' | 'MP' | 'HP' | 'DMG';
/**
 * Parameters for the GET /cards endpoint.
 */
interface GetCardsParams extends QueryParams {
    /** A TCGplayer product ID. */
    tcgplayerId?: string;
    /** The TCGPlayer SKU of the specific variant. */
    tcgplayerSkuId?: string;
    /** A JustTCG card ID. */
    cardId?: string;
    /** A JustTCG variant ID. */
    variantId?: string;
    /** The Scryfall ID of the card. */
    scryfallId?: string;
    /** The MTGJSON ID of the card. */
    mtgjsonId?: string;
    /** A general search query for the card's name. */
    query?: string;
    /** The name of the game (e.g., 'Pokemon'). */
    game?: string;
    /** The id of the set (e.g., 'base-set-pokemon'). */
    set?: string;
    /** The name of the set (e.g., 'Base Set'). */
    set_name?: string;
    /** Updated after a specific date in Unix timestamp format (seconds since epoch). */
    updated_after?: number;
    /** An array of card conditions to filter by (e.g., ['Near Mint', 'Lightly Played']). */
    condition?: (Condition | ConditionAbv)[];
    /** An array of card print types to filter by (e.g., ['Foil', '1st Edition']). */
    printing?: string[];
    /** The maximum number of results to return. Default is 20. */
    limit?: number;
    /** The number of results to skip for pagination. */
    offset?: number;
    /** The order to sort the results by. Can be 'asc' or 'desc'. Default is 'desc'. */
    order?: 'asc' | 'desc';
    /** The field to order the results by. Default is 'price'. */
    orderBy?: 'price' | '24h' | '7d' | '30d' | '90d';
    /** Option to include price history in the response. */
    include_price_history?: boolean;
    /** Option to include specific timeframes for the price statistics. */
    include_statistics?: StatisticTimeFrame[];
}
/**
 * Describes a single item for a batch lookup request.
 */
interface BatchLookupItem {
    /** A TCGplayer product ID. */
    tcgplayerId?: string;
    /** The TCGPlayer SKU of the specific variant. */
    tcgplayerSkuId?: string;
    /** A JustTCG card ID. */
    cardId?: string;
    /** A JustTCG variant ID. */
    variantId?: string;
    /** The Scryfall ID of the card. */
    scryfallId?: string;
    /** The MTGJSON ID of the card. */
    mtgjsonId?: string;
    /** Updated after a specific date in Unix timestamp format (seconds since epoch). */
    updated_after?: number;
    /** An array of card print types to filter by. */
    printing?: string[];
    /** An array of card conditions to filter by. */
    condition?: (Condition | ConditionAbv)[];
    /** Option to include price history in the response. */
    include_price_history?: boolean;
    /** Option to include specific timeframes for the price statistics. */
    include_statistics?: StatisticTimeFrame[];
}
/**
 * Optional parameters for the `search` method.
 */
interface SearchCardsOptions {
    /** The name of the game to filter by (e.g., 'Pokemon'). */
    game?: string;
    /** The id of the set to filter by (e.g., 'base-set-pokemon'). */
    set?: string;
    /** The maximum number of results to return. Default is 20. */
    limit?: number;
    /** The number of results to skip for pagination. */
    offset?: number;
    /** An array of card print types to filter by. */
    printing?: string[];
    /** An array of card conditions to filter by. */
    condition?: (Condition | ConditionAbv)[];
    /** Option to include price history in the response. */
    include_price_history?: boolean;
    /** Option to include specific timeframes for the price statistics. */
    include_statistics?: StatisticTimeFrame[];
}
/**
 * Pagination metadata included in paginated API responses.
 */
interface PaginationMeta {
    /** The total number of items available for this query. */
    total: number;
    /** The maximum number of items returned per page. */
    limit: number;
    /** The number of items skipped before starting to collect the result set. */
    offset: number;
    /** Indicates if there are more items to fetch beyond the current page. */
    hasMore: boolean;
}
/**
 * API usage metadata returned in every successful API response.
 */
interface UsageMeta {
    /** The maximum number of API requests allowed per billing cycle. */
    apiRequestLimit: number;
    /** The maximum number of API requests allowed per day. */
    apiDailyLimit: number;
    /** The maximum number of API requests allowed per minute. */
    apiRateLimit: number;
    /** The number of API requests used in the current billing cycle. */
    apiRequestsUsed: number;
    /** The number of API requests used today. */
    apiDailyRequestsUsed: number;
    /** The number of API requests remaining in the current billing cycle. */
    apiRequestsRemaining: number;
    /** The number of API requests remaining today. */
    apiDailyRequestsRemaining: number;
    /** The API plan name. */
    apiPlan: string;
}
/**
 * The structured, clean response object our SDK provides.
 */
interface JustTCGApiResponse<T> {
    /** The main data payload from the API. */
    data: T;
    /** Pagination metadata, if the response is paginated. */
    pagination?: PaginationMeta;
    /** API usage metadata. */
    usage: UsageMeta;
    /** Error message, if the request failed. */
    error?: string;
    /** Error code, if the request failed. */
    code?: string;
}
/**
 * A single entry in a variant's price history.
 */
interface PriceHistoryEntry {
    /** Epoch timestamp in seconds. */
    t: number;
    /** Price in dollars. */
    p: number;
}
/**
 * Represents a specific version of a card (e.g., Near Mint, 1st Edition Foil).
 * Contains detailed pricing and statistical data.
 */
interface Variant {
    /** The unique identifier for this variant. */
    id: string;
    /** The condition of the card variant (e.g., Near Mint). */
    condition: Condition;
    /** The printing type of the card variant (e.g., Foil, 1st Edition). */
    printing: string;
    /** The language of the card variant, if applicable. */
    language: string | null;
    /** The TCGPlayer SKU of the specific variant. */
    tcgplayerSkuId?: string;
    /** The current price of the card variant in dollars. */
    price: number;
    /** The last time the price was updated, as an epoch timestamp in seconds. */
    lastUpdated: number;
    /** The percentage change in price over the last 24 hours. */
    priceChange24hr?: number | null;
    /** The percentage change in price over the last 7 days. */
    priceChange7d?: number | null;
    /** The average price over the last 7 days. */
    avgPrice?: number | null;
    /** The price history entries over the last 7 days. */
    priceHistory?: PriceHistoryEntry[] | null;
    minPrice7d?: number | null;
    maxPrice7d?: number | null;
    stddevPopPrice7d?: number | null;
    covPrice7d?: number | null;
    iqrPrice7d?: number | null;
    trendSlope7d?: number | null;
    priceChangesCount7d?: number | null;
    priceChange30d?: number | null;
    avgPrice30d?: number | null;
    minPrice30d?: number | null;
    maxPrice30d?: number | null;
    priceHistory30d?: PriceHistoryEntry[] | null;
    stddevPopPrice30d?: number | null;
    covPrice30d?: number | null;
    iqrPrice30d?: number | null;
    trendSlope30d?: number | null;
    priceChangesCount30d?: number | null;
    priceRelativeTo30dRange?: number | null;
    priceChange90d?: number | null;
    avgPrice90d?: number | null;
    minPrice90d?: number | null;
    maxPrice90d?: number | null;
    stddevPopPrice90d?: number | null;
    covPrice90d?: number | null;
    iqrPrice90d?: number | null;
    trendSlope90d?: number | null;
    priceChangesCount90d?: number | null;
    priceRelativeTo90dRange?: number | null;
    minPrice1y?: number | null;
    maxPrice1y?: number | null;
    minPriceAllTime?: number | null;
    minPriceAllTimeDate?: string | null;
    maxPriceAllTime?: number | null;
    maxPriceAllTimeDate?: string | null;
}
/**
 * Represents a single trading card, which contains one or more variants.
 */
interface Card {
    /** The unique identifier for the card. */
    id: string;
    /** The name of the card. */
    name: string;
    /** The game this card belongs to. */
    game: string;
    /** The set ID this card belongs to. */
    set: string;
    /** The set name this card belongs to. */
    set_name?: string;
    /** The card number within the set. */
    number: string | null;
    /** The rarity of the card. */
    rarity: string | null;
    /** The TCGPlayer ID for the card. */
    tcgplayerId: string | null;
    /** The Scryfall ID for the card. */
    scryfallId: string | null;
    /** The MTGJSON ID for the card. */
    mtgjsonId: string | null;
    /** Additional details about the card. */
    details?: string | null;
    /** The different variants of the card. */
    variants: Variant[];
}

interface HttpClientConfig {
    apiKey: string;
    baseUrl: string;
}
interface QueryParams {
    [key: string]: string | string[] | number | boolean | undefined | null;
}
declare class HttpClient {
    private readonly apiKey;
    private readonly baseUrl;
    constructor(config: HttpClientConfig);
    /**
     * Performs a GET request to a given path.
     * @param path The endpoint path (e.g., '/games').
     * @param params Optional query parameters.
     * @returns The JSON response from the API.
     */
    get<T>(path: string, params?: QueryParams): Promise<T>;
    /**
     * Performs a POST request to a given path.
     * @param path The endpoint path (e.g., '/cards').
     * @param body The JSON body for the request.
     * @returns The JSON response from the API.
     */
    post<T>(path: string, body: BatchLookupItem[]): Promise<T>;
    private getHeaders;
}

declare class BaseResource {
    protected httpClient: HttpClient;
    private pathPrefix;
    constructor(httpClient: HttpClient, pathPrefix: string);
    protected _get<T>(path: string, params?: QueryParams): Promise<T>;
    protected _post<T>(path: string, body: BatchLookupItem[]): Promise<T>;
}

/**
 * Provides access to the /cards API resource.
 */
declare class CardsResource extends BaseResource {
    /**
     * Retrieves a paginated list of cards based on a flexible set of query parameters.
     * @param params Parameters for searching, filtering, and paginating cards.
     * @returns A Promise resolving to the JustTCG API response containing an array of Card objects.
     */
    get(params: GetCardsParams): Promise<JustTCGApiResponse<Card[]>>;
    /**
     * Retrieves a list of cards based on a batch of specific identifiers.
     * @param items An array of objects, each identifying a card to look up.
     * @returns A Promise resolving to the JustTCG API response containing an array of the requested Card objects.
     */
    getByBatch(items: BatchLookupItem[]): Promise<JustTCGApiResponse<Card[]>>;
    /**
     * A convenience method to search for cards by a query string.
     * This is a wrapper around the more flexible `get` method.
     * @param query A search query for the card's name.
     * @param options Optional parameters to filter or paginate the search results.
     * @returns A Promise resolving to the JustTCG API response containing an array of Card objects.
     */
    search(query: string, options?: SearchCardsOptions): Promise<JustTCGApiResponse<Card[]>>;
}

declare class GamesResource extends BaseResource {
    /**
     * Retrieves a list of all supported games.
     * @returns A JustTCG API response containing an array of Game objects.
     */
    list(): Promise<JustTCGApiResponse<Game[]>>;
}

declare class SetsResource extends BaseResource {
    /**
     * Retrieves a paginated list of sets, optionally filtered by game.
     * @param params Optional parameters to filter the list of sets.
     * @returns A JustTCG API response containing an array of Set objects.
     */
    list(params?: {
        /** The name of the game to filter sets by (e.g., 'Pokemon'). */
        game?: string;
        /** The maximum number of results to return. Default is 20. */
        limit?: number;
        /** The number of results to skip for pagination. */
        offset?: number;
    }): Promise<JustTCGApiResponse<Set[]>>;
}

declare class V1Client {
    readonly games: GamesResource;
    readonly sets: SetsResource;
    readonly cards: CardsResource;
    constructor(httpClient: HttpClient);
}

interface JustTCGConfig {
    /**
     * Your JustTCG API key.
     * If not provided, the client will look for the `JUSTTCG_API_KEY` environment variable.
     */
    apiKey?: string;
}
declare class JustTCG {
    /** Provides access to the v1 version of the JustTCG API. */
    readonly v1: V1Client;
    private readonly httpClient;
    /**
     * Creates an instance of the JustTCG client.
     * @param config Configuration options for the client.
     */
    constructor(config?: JustTCGConfig);
}

export { type BatchLookupItem, type Card, type Condition, type ConditionAbv, type Game, type GetCardsParams, JustTCG, type JustTCGApiResponse, type JustTCGConfig, type PaginationMeta, type PriceHistoryEntry, type SearchCardsOptions, type Set, type StatisticTimeFrame, type UsageMeta, type Variant };