/** * 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 total number of sealed products in this game. */ sealed_count: number; /** The last updated timestamp for this game in Unix timestamp format (seconds since epoch). */ last_updated: number; /** Total value of all cards in the game, in USD. Takes the highest price of any variant for each card. */ game_value_usd: number; /** Percentage change in game value over the last 7 days. */ game_value_change_7d_pct: number; /** Percentage change in game value over the last 30 days. */ game_value_change_30d_pct: number; /** Percentage change in game value over the last 90 days. */ game_value_change_90d_pct: number; /** Number of cards with positive price change in the last 7 days. */ cards_pos_7d_count: number; /** Number of cards with negative price change in the last 7 days. */ cards_neg_7d_count: number; /** Number of sealed products with positive price change in the last 7 days. */ sealed_cards_pos_7d_count: number; /** Number of sealed products with negative price change in the last 7 days. */ sealed_cards_neg_7d_count: number; /** Number of cards with positive price change in the last 30 days. */ cards_pos_30d_count: number; /** Number of cards with negative price change in the last 30 days. */ cards_neg_30d_count: number; /** Number of sealed products with positive price change in the last 30 days. */ sealed_cards_pos_30d_count: number; /** Number of sealed products with negative price change in the last 30 days. */ sealed_cards_neg_30d_count: number; /** Number of cards with positive price change in the last 90 days. */ cards_pos_90d_count: number; /** Number of cards with negative price change in the last 90 days. */ cards_neg_90d_count: number; /** Number of sealed products with positive price change in the last 90 days. */ sealed_cards_pos_90d_count: number; /** Number of sealed products with negative price change in the last 90 days. */ sealed_cards_neg_90d_count: 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 id of the game this set belongs to. */ game_id: string; /** The name of the game this set belongs to. */ game: string; /** The total number of cards in this set. */ count: number; /** The total number of variants in this set. */ variants_count: number; /** The total number of sealed products in this set. */ sealed_count: number; /** The release date of this set in ISO 8601 format. */ release_date: string; /** Total value of all cards in the set, in USD. Takes the highest price of any variant for each card. */ set_value_usd: number; /** Percentage change in set value over the last 7 days. */ set_value_change_7d_pct: number; /** Percentage change in set value over the last 30 days. */ set_value_change_30d_pct: number; /** Percentage change in set value over the last 90 days. */ set_value_change_90d_pct: number; } 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'; type Order = 'asc' | 'desc'; type OrderBy = 'price' | '24h' | '7d' | '30d' | '90d'; type PriceHistoryDuration = '7d' | '30d' | '90d' | '180d' | '1y'; /** * 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 or UUID. */ cardId?: string; /** A JustTCG variant ID or UUID. */ 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 number of the card (e.g. 015'). */ number?: 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?: Order; /** The field to order the results by. Default is 'price'. */ orderBy?: OrderBy; /** Option to include price history in the response. */ include_price_history?: boolean; /** Specify the duration of price history to include. Options are 7d, 30d, 90d, 180d, or 1y. This is ignored if include_price_history is set to false.*/ priceHistoryDuration?: PriceHistoryDuration; /** Option to include specific timeframes for the price statistics. */ include_statistics?: StatisticTimeFrame[]; /** Option to include cards who have null prices. */ include_null_prices?: boolean; /** Filters results to include only cards where the current market price is greater than or equal to the provided value. */ min_price?: number; } /** * 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 or UUID. */ cardId?: string; /** A JustTCG variant ID or UUID. */ 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 card number to filter by (e.g., '015'). */ number?: 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; /** Specify the duration of price history to include. Options are 7d, 30d, 90d, 180d, or 1y. This is ignored if include_price_history is set to false. */ priceHistoryDuration?: PriceHistoryDuration; /** Option to include specific timeframes for the price statistics. */ include_statistics?: StatisticTimeFrame[]; /** Option to include cards who have null prices. */ include_null_prices?: boolean; /** Filters results to include only cards where the current market price is greater than or equal to the provided value. */ min_price?: number; } /** * 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 { /** 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 slug identifier for this variant. Will be renamed to `slug` in v2. */ id: string; /** The uuid of this variant. Recommended for stable identification of the variant. */ uuid: 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; 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 slug identifier for the card. Will be renamed to `slug` in v2. */ id: string; /** The uuid of the card. Recommended for stable identification of the card. */ uuid: 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; debug?: boolean; } interface QueryParams { [key: string]: string | string[] | number | boolean | undefined | null; } declare class HttpClient { private readonly apiKey; private readonly baseUrl; private readonly debug; 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(path: string, params?: QueryParams): Promise; /** * 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(path: string, body: BatchLookupItem[]): Promise; private getHeaders; } declare class BaseResource { protected httpClient: HttpClient; private pathPrefix; constructor(httpClient: HttpClient, pathPrefix: string); protected _get(path: string, params?: QueryParams): Promise; protected _post(path: string, body: BatchLookupItem[]): Promise; } /** * 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>; /** * 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>; /** * 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>; } 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>; } 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; /** Query string to search for sets by name. */ q?: string; /** Order by a specific field. */ orderBy?: 'name' | 'release_date'; /** Order direction: ascending ('asc') or descending ('desc'). */ order?: 'asc' | 'desc'; /** The maximum number of results to return. Default is 20. */ limit?: number; /** The number of results to skip for pagination. */ offset?: number; }): Promise>; } 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; /** * Enable debug mode to log request details. */ debug?: boolean; } 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 Order, type OrderBy, type PaginationMeta, type PriceHistoryDuration, type PriceHistoryEntry, type SearchCardsOptions, type Set, type StatisticTimeFrame, type UsageMeta, type Variant };