ygoapi/dist/index.d.ts

TypeScript client for the YGOPRODeck API v7 - Yu-Gi-Oh! card database access

type CardType = "Effect Monster" | "Flip Effect Monster" | "Flip Tuner Effect Monster" | "Gemini Monster" | "Normal Monster" | "Normal Tuner Monster" | "Pendulum Effect Monster" | "Pendulum Effect Ritual Monster" | "Pendulum Flip Effect Monster" | "Pendulum Normal Monster" | "Pendulum Tuner Effect Monster" | "Ritual Effect Monster" | "Ritual Monster" | "Spell Card" | "Spirit Monster" | "Toon Monster" | "Trap Card" | "Tuner Monster" | "Union Effect Monster" | "Fusion Monster" | "Link Monster" | "Pendulum Effect Fusion Monster" | "Synchro Monster" | "Synchro Pendulum Effect Monster" | "Synchro Tuner Monster" | "XYZ Monster" | "XYZ Pendulum Effect Monster" | "Skill Card" | "Token";
type FrameType = "normal" | "effect" | "ritual" | "fusion" | "synchro" | "xyz" | "link" | "normal_pendulum" | "effect_pendulum" | "ritual_pendulum" | "fusion_pendulum" | "synchro_pendulum" | "xyz_pendulum" | "spell" | "trap" | "token" | "skill";
type MonsterRace = "Aqua" | "Beast" | "Beast-Warrior" | "Creator-God" | "Cyberse" | "Dinosaur" | "Divine-Beast" | "Dragon" | "Fairy" | "Fiend" | "Fish" | "Insect" | "Machine" | "Plant" | "Psychic" | "Pyro" | "Reptile" | "Rock" | "Sea Serpent" | "Spellcaster" | "Thunder" | "Warrior" | "Winged Beast" | "Wyrm" | "Zombie";
type SpellRace = "Normal" | "Field" | "Equip" | "Continuous" | "Quick-Play" | "Ritual";
type TrapRace = "Normal" | "Continuous" | "Counter";
type CardRace = MonsterRace | SpellRace | TrapRace;
type Attribute = "DARK" | "DIVINE" | "EARTH" | "FIRE" | "LIGHT" | "WATER" | "WIND";
type LinkMarker = "Top" | "Bottom" | "Left" | "Right" | "Bottom-Left" | "Bottom-Right" | "Top-Left" | "Top-Right";
type Format = "tcg" | "goat" | "ocg goat" | "speed duel" | "master duel" | "rush duel" | "duel links" | "genesys";
type BanlistType = "TCG" | "OCG" | "Goat";
type SortOption = "atk" | "def" | "name" | "type" | "level" | "id" | "new";
type ComparisonOperator = "lt" | "lte" | "gt" | "gte";
type Language = "fr" | "de" | "it" | "pt";
type DateRegion = "tcg" | "ocg";
interface CardSet {
	set_name: string;
	set_code: string;
	set_rarity: string;
	set_rarity_code: string;
	set_price: string;
	set_edition?: string;
	set_url?: string;
}
interface CardImage {
	id: number;
	image_url: string;
	image_url_small: string;
	image_url_cropped: string;
}
interface CardPrice {
	cardmarket_price: string;
	tcgplayer_price: string;
	ebay_price: string;
	amazon_price: string;
	coolstuffinc_price: string;
}
interface BanlistInfo {
	ban_tcg?: string;
	ban_ocg?: string;
	ban_goat?: string;
}
interface Card {
	id: number;
	name: string;
	type: CardType;
	frameType: FrameType;
	desc: string;
	ygoprodeck_url: string;
	atk?: number;
	def?: number;
	level?: number;
	race: CardRace;
	attribute?: Attribute;
	scale?: number;
	linkval?: number;
	linkmarkers?: LinkMarker[];
	card_sets?: CardSet[];
	card_images: CardImage[];
	card_prices: CardPrice[];
	banlist_info?: BanlistInfo;
	archetype?: string;
	misc_info?: Array<{
		beta_name?: string
		views?: number
		viewsweek?: number
		upvotes?: number
		downvotes?: number
		formats?: Format[]
		treated_as?: string
		tcg_date?: string
		ocg_date?: string
		konami_id?: string
		md_rarity?: string
		has_effect?: 0 | 1
		genesys_points?: number
	}>;
}
interface CardInfoResponse {
	data: Card[];
	meta?: PaginationMeta;
}
interface PaginationMeta {
	current_rows: number;
	total_rows: number;
	rows_remaining: number;
	total_pages: number;
	pages_remaining: number;
	next_page: string;
	next_page_offset: number;
}
interface CardSetInfo {
	set_name: string;
	set_code: string;
	num_of_cards: number;
	tcg_date?: string;
}
interface CardSetDetails {
	id: number;
	name: string;
	set_name: string;
	set_code: string;
	set_rarity: string;
	set_price: string;
}
interface Archetype {
	archetype_name: string;
}
interface DatabaseVersion {
	database_version: string;
	last_update: string;
}
interface CardInfoParams {
	name?: string;
	fname?: string;
	id?: string | number;
	konami_id?: string | number;
	type?: CardType;
	atk?: number | `${ComparisonOperator}${number}`;
	def?: number | `${ComparisonOperator}${number}`;
	level?: number | `${ComparisonOperator}${number}`;
	race?: CardRace | CardRace[];
	attribute?: Attribute | Attribute[];
	link?: number;
	linkmarker?: LinkMarker | LinkMarker[];
	scale?: number;
	cardset?: string;
	archetype?: string;
	banlist?: BanlistType;
	format?: Format;
	staple?: "yes";
	has_effect?: boolean;
	startdate?: string;
	enddate?: string;
	dateregion?: DateRegion;
	sort?: SortOption;
	num?: number;
	offset?: number;
	misc?: "yes";
	tcgplayer_data?: boolean;
	language?: Language;
}
interface KVStore {
	get(key: string): Promise<string | null> | string | null;
	set(key: string, value: string, ttl?: number): Promise<void> | void;
	delete?(key: string): Promise<void> | void;
}
interface RetryConfig {
	maxAttempts?: number;
	baseDelay?: number;
	maxDelay?: number;
	backoffFactor?: number;
}
interface FallbackConfig {
	urls?: string[];
	timeout?: number;
}
interface YgoApiOptions {
	headers?: HeadersInit;
	cache?: KVStore;
	cacheTtl?: number;
	retry?: RetryConfig;
	fallback?: FallbackConfig;
}
declare class YgoApiError extends Error {
	statusCode: number;
	constructor(statusCode: number, message: string);
}
declare class YgoApi {
	private readonly baseURL;
	private readonly headers;
	private readonly cache?;
	private readonly cacheTtl;
	private readonly retryConfig;
	private readonly fallbackConfig;
	constructor(options?: YgoApiOptions);
	/**
	* Build query string from parameters
	*/
	private buildQueryString;
	/**
	* Sleep utility for retry delays
	*/
	private sleep;
	/**
	* Generate cache key from endpoint and parameters
	*/
	private getCacheKey;
	/**
	* Try to get data from cache
	*/
	private getCached;
	/**
	* Store data in cache
	*/
	private setCached;
	/**
	* Perform API request with retry and caching
	*/
	private request;
	/**
	* Get card information
	* @param params - Query parameters
	* @returns Card information response
	*/
	getCardInfo(params?: CardInfoParams): Promise<CardInfoResponse>;
	/**
	* Get a single card by name
	* @param name - Exact card name
	* @returns Single card or null if not found
	*/
	getCardByName(name: string): Promise<Card | null>;
	/**
	* Get a single card by ID
	* @param id - Card ID (passcode)
	* @returns Single card or null if not found
	*/
	getCardById(id: string | number): Promise<Card | null>;
	/**
	* Search cards by fuzzy name
	* @param fname - Fuzzy search string
	* @param params - Additional parameters
	* @returns Card information response
	*/
	searchCards(fname: string, params?: Omit<CardInfoParams, "fname">): Promise<CardInfoResponse>;
	/**
	* Get cards by archetype
	* @param archetype - Archetype name
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByArchetype(archetype: string, params?: Omit<CardInfoParams, "archetype">): Promise<CardInfoResponse>;
	/**
	* Get cards by set
	* @param cardset - Card set name
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsBySet(cardset: string, params?: Omit<CardInfoParams, "cardset">): Promise<CardInfoResponse>;
	/**
	* Get a random card
	* @returns Random card
	*/
	getRandomCard(): Promise<Card>;
	/**
	* Get all card sets
	* @returns Array of card sets
	*/
	getAllCardSets(): Promise<CardSetInfo[]>;
	/**
	* Get card set information
	* @param setcode - Set code
	* @returns Card set details
	*/
	getCardSetInfo(setcode: string): Promise<CardSetDetails>;
	/**
	* Get all archetypes
	* @returns Array of archetypes
	*/
	getAllArchetypes(): Promise<Archetype[]>;
	/**
	* Check database version
	* @returns Database version information
	*/
	checkDatabaseVersion(): Promise<DatabaseVersion>;
	/**
	* Get staple cards
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getStapleCards(params?: Omit<CardInfoParams, "staple">): Promise<CardInfoResponse>;
	/**
	* Get cards by format
	* @param format - Card format
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByFormat(format: Format, params?: Omit<CardInfoParams, "format">): Promise<CardInfoResponse>;
	/**
	* Get cards in Genesys format with their point values
	* @param params - Additional parameters
	* @returns Card information response with genesys_points included in misc_info
	*/
	getCardsByGenesysFormat(params?: Omit<CardInfoParams, "format" | "misc">): Promise<CardInfoResponse>;
	/**
	* Get banned/limited cards
	* @param banlist - Banlist type
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getBanlistCards(banlist: BanlistType, params?: Omit<CardInfoParams, "banlist">): Promise<CardInfoResponse>;
	/**
	* Get cards with pagination
	* @param num - Number of cards per page
	* @param offset - Offset for pagination
	* @param params - Additional parameters
	* @returns Card information response with pagination metadata
	*/
	getCardsWithPagination(num: number, offset: number, params?: Omit<CardInfoParams, "num" | "offset">): Promise<CardInfoResponse>;
	/**
	* Get cards by type
	* @param type - Card type
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByType(type: CardType, params?: Omit<CardInfoParams, "type">): Promise<CardInfoResponse>;
	/**
	* Get cards by attribute
	* @param attribute - Card attribute
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByAttribute(attribute: Attribute, params?: Omit<CardInfoParams, "attribute">): Promise<CardInfoResponse>;
	/**
	* Get cards by race
	* @param race - Card race
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByRace(race: CardRace, params?: Omit<CardInfoParams, "race">): Promise<CardInfoResponse>;
	/**
	* Get cards by level
	* @param level - Card level or comparison
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByLevel(level: number | `${ComparisonOperator}${number}`, params?: Omit<CardInfoParams, "level">): Promise<CardInfoResponse>;
	/**
	* Get cards by ATK value
	* @param atk - ATK value or comparison
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByATK(atk: number | `${ComparisonOperator}${number}`, params?: Omit<CardInfoParams, "atk">): Promise<CardInfoResponse>;
	/**
	* Get cards by DEF value
	* @param def - DEF value or comparison
	* @param params - Additional parameters
	* @returns Card information response
	*/
	getCardsByDEF(def: number | `${ComparisonOperator}${number}`, params?: Omit<CardInfoParams, "def">): Promise<CardInfoResponse>;
	/**
	* Get cards with misc info
	* @param params - Additional parameters
	* @returns Card information response with misc info
	*/
	getCardsWithMiscInfo(params?: Omit<CardInfoParams, "misc">): Promise<CardInfoResponse>;
}
/**
* Build a comparison query for ATK/DEF/Level
* @param operator - Comparison operator
* @param value - Value to compare
* @returns Formatted comparison string
*/
declare function buildComparison(operator: ComparisonOperator, value: number): `${ComparisonOperator}${number}`;
/**
* Parse card image URLs from a card
* @param card - Card object
* @returns Object with image URLs
*/
declare function getCardImages(card: Card): {
	default: CardImage
	alternates: CardImage[]
};
/**
* Check if a card is a monster
* @param card - Card object
* @returns True if the card is a monster
*/
declare function isMonsterCard(card: Card): boolean;
/**
* Check if a card is a spell
* @param card - Card object
* @returns True if the card is a spell
*/
declare function isSpellCard(card: Card): boolean;
/**
* Check if a card is a trap
* @param card - Card object
* @returns True if the card is a trap
*/
declare function isTrapCard(card: Card): boolean;
/**
* Check if a card is an extra deck monster
* @param card - Card object
* @returns True if the card is an extra deck monster
*/
declare function isExtraDeckMonster(card: Card): boolean;
export { isTrapCard, isSpellCard, isMonsterCard, isExtraDeckMonster, getCardImages, buildComparison, YgoApiOptions, YgoApiError, YgoApi, TrapRace, SpellRace, SortOption, RetryConfig, PaginationMeta, MonsterRace, LinkMarker, Language, KVStore, FrameType, Format, FallbackConfig, DateRegion, DatabaseVersion, ComparisonOperator, CardType, CardSetInfo, CardSetDetails, CardSet, CardRace, CardPrice, CardInfoResponse, CardInfoParams, CardImage, Card, BanlistType, BanlistInfo, Attribute, Archetype };