The TypeScript SDK
Installation
Section titled “Installation”npm i @tcgdex/sdk
bun i @tcgdex/sdk
yarn add @tcgdex/sdk
pnpm add @tcgdex/sdk
Basic Usage
Section titled “Basic Usage”// Import the SDK in ESM/TypeScriptimport TCGdex from '@tcgdex/sdk'
// Instantiate the SDK with your preferred languageconst tcgdex = new TCGdex('en');
// Use in an async context(async () => { // Retrieve Furret from the Darkness Ablaze Set const card = await tcgdex.card.get('swsh3-136'); console.log(card.name); // "Furret"})();
Fetching Data
Section titled “Fetching Data”The SDK provides dedicated endpoints for common data types:
// Get a specific cardconst card = await tcgdex.card.get('swsh3-136');
// Get a specific setconst set = await tcgdex.set.get('swsh3');
// Get a specific serieconst serie = await tcgdex.serie.get('swsh');
// Get a list of all cardsconst allCards = await tcgdex.card.list();
Getting Random Data
Section titled “Getting Random Data”You can also retrieve random cards, sets, or series:
// Get a random cardconst randomCard = await tcgdex.random.card();
// Get a random setconst randomSet = await tcgdex.random.set();
// Get a random serieconst randomSerie = await tcgdex.random.serie();
Advanced Queries
Section titled “Advanced Queries”The SDK provides a powerful query system to filter data:
import TCGdex, { Query } from '@tcgdex/sdk';
const tcgdex = new TCGdex('en');
// Create a query to find Pikachu cards with HP between 60 and 70const pikachuCards = await tcgdex.card.list( Query.create() .equal('name', 'Pikachu') // Match exact name .greaterOrEqualThan('hp', 60) // HP >= 60 .lesserThan('hp', 70) // HP < 70 .sort('localId', 'ASC') // Sort by ID ascending);
// Find cards containing "5" in their ID but not "tg"const filteredCards = await tcgdex.card.list( Query.create() .contains('localId', '5') // ID contains "5" .not.contains('localId', 'tg') // ID doesn't contain "tg");
// Pagination example - get page 3 with 2 items per pageconst paginatedCards = await tcgdex.card.list( Query.create() .paginate(3, 2));
Object Relationships
Section titled “Object Relationships”The SDK makes it easy to navigate relationships between objects:
// Get a card then retrieve its setconst card = await tcgdex.card.get('swsh3-136');const set = await card.getSet();
// Get a set then retrieve its serieconst set = await tcgdex.set.get('swsh3');const serie = await set.getSerie();
// Get a card from a set's card listconst set = await tcgdex.set.get('swsh3');const firstCardResume = set.cards[0];const fullCard = await firstCardResume.getCard();
Filtering by Attributes
Section titled “Filtering by Attributes”Find cards by specific attributes:
// Get all fire type cardsconst fireType = await tcgdex.type.get('fire');
// Get all cards with specific HPconst hp90Cards = await tcgdex.hp.get('90');
// Get all cards by a specific illustratorconst illustratorCards = await tcgdex.illustrator.get('TOKIYA');
// Get all cards with a specific rarityconst rareCards = await tcgdex.rarity.get('rare');
Configuration Options
Section titled “Configuration Options”The SDK provides several configuration options:
// Create SDK with a specific languageconst tcgdex = new TCGdex('fr'); // French
// Change the language after initializationtcgdex.setLang('en'); // Switch to English
// Set a custom API endpointtcgdex.setEndpoint('https://custom-api.example.com/v2');
// Configure cachingtcgdex.setCacheTTL(3600); // Set cache duration to 1 hour
Card Images
Section titled “Card Images”Access card images easily:
const card = await tcgdex.card.get('swsh3-136');
// Get high-quality PNG image URLconst highQualityPng = card.getImageURL('high', 'png');
// Get low-quality WEBP image URL for performanceconst lowQualityWebp = card.getImageURL('low', 'webp');
Related Resources
Section titled “Related Resources”- Check the full REST API documentation for all available endpoints
- Source code on GitHub
- NPM package
- Discord Community