scryfall-api/dist/scryfall-api.d.ts

A Javascript library for https://scryfall.com/docs/api written in Typescript.

/**
 * Type definition for Nullable.
 * @type {T | null | undefined} The type can be T, null, or undefined.
 * @template T The type of the value that can be null or undefined.
 */
type Nullable<T> = null | T | undefined;

type QueryValue = boolean | number | string | undefined;
interface PageQuery {
    [key: string]: QueryValue;
    page: number;
}
declare class MagicPageResult<T> {
    #private;
    private readonly apiPath;
    private readonly query;
    constructor(apiPath: string, query: PageQuery);
    get count(): number;
    get hasMore(): boolean;
    all(): Promise<T[]>;
    get(limit: number): Promise<T[]>;
    next(): Promise<T[]>;
    page(page: number): Promise<T[]>;
    private setNextPage;
}

interface CardIdentifierId {
    id: string;
}
interface CardIdentifierIllustrationId {
    illustration_id: string;
}
interface CardIdentifierMtgGoId {
    mtgo_id: number;
}
interface CardIdentifierMultiverseId {
    multiverse_id: number;
}
interface CardIdentifierNameSet {
    name: string;
    set?: string;
}
interface CardIdentifierOracleId {
    oracle_id: string;
}
interface CardIdentifierCollectorSet {
    collector_number: string;
    set: string;
}
type CardIdentifier = CardIdentifierCollectorSet | CardIdentifierId | CardIdentifierIllustrationId | CardIdentifierMtgGoId | CardIdentifierMultiverseId | CardIdentifierNameSet | CardIdentifierOracleId;

declare class CardIdentifierApi {
    static byId(id: string): CardIdentifier;
    static byIllustrationId(id: string): CardIdentifier;
    static byMtgoId(id: number): CardIdentifier;
    static byMultiverseId(id: number): CardIdentifier;
    static byName(name: string, set?: string): CardIdentifier;
    static byOracleId(id: string): CardIdentifier;
    static bySet(set: string, collectorNumber: number | string): CardIdentifier;
}

type CardLanguage = 'ar' | 'de' | 'en' | 'es' | 'fr' | 'grc' | 'he' | 'it' | 'ja' | 'ko' | 'la' | 'ph' | 'pt' | 'ru' | 'sa' | 'zhs' | 'zht';
type CardLayout = 'adventure' | 'art_series' | 'augment' | 'battle' | 'case' | 'class' | 'double_faced_token' | 'emblem' | 'flip' | 'host' | 'leveler' | 'meld' | 'modal_dfc' | 'mutate' | 'normal' | 'planar' | 'prototype' | 'reversible_card' | 'saga' | 'scheme' | 'split' | 'token' | 'transform' | 'vanguard';
interface CardCore {
    arena_id?: Nullable<string>;
    cardmarket_id?: Nullable<number>;
    id: string;
    lang: CardLanguage;
    layout: CardLayout;
    mtgo_foil_id?: Nullable<number>;
    mtgo_id?: Nullable<number>;
    multiverse_ids?: Nullable<number[]>;
    object: 'card';
    oracle_id?: Nullable<string>;
    prints_search_uri: string;
    rulings_uri: string;
    scryfall_uri: string;
    tcgplayer_etched_id?: Nullable<number>;
    tcgplayer_id?: Nullable<number>;
    uri: string;
}

type Color = 'B' | 'G' | 'R' | 'U' | 'W';
interface ManaCost {
    cmc: number;
    colorless: boolean;
    colors: Color[];
    cost: string;
    monocolored: boolean;
    multicolored: boolean;
    object: 'mana_cost';
}
interface Symbology {
    appears_in_mana_costs: boolean;
    colors: Color[];
    english: string;
    funny: boolean;
    gatherer_alternates?: Nullable<string[]>;
    hybrid: boolean;
    loose_variant?: Nullable<string>;
    mana_value?: Nullable<number>;
    object: 'card_symbol';
    phyrexian: boolean;
    represents_mana: boolean;
    svg_uri?: Nullable<string>;
    symbol: string;
    transposable: boolean;
}

declare class SymbologyApi {
    all(): Promise<Symbology[]>;
    parseMana(shorthand: string): Promise<ManaCost>;
}
declare const symbology: SymbologyApi;

interface ImageUris {
    art_crop: string;
    border_crop: string;
    large: string;
    normal: string;
    png: string;
    small: string;
}

type CardComponent = 'combo_piece' | 'meld_part' | 'meld_result' | 'token';
type Legality = 'banned' | 'legal' | 'not_legal' | 'restricted';
interface CardFace {
    artist?: Nullable<string>;
    artist_id?: Nullable<string>;
    cmc?: Nullable<number>;
    color_indicator?: Nullable<Color[]>;
    colors?: Nullable<Color[]>;
    defense?: Nullable<string>;
    flavor_text?: Nullable<string>;
    illustration_id?: Nullable<string>;
    image_uris?: Nullable<ImageUris>;
    layout?: Nullable<string>;
    loyalty?: Nullable<string>;
    mana_cost: string;
    name: string;
    object: 'card_face';
    oracle_id?: Nullable<string>;
    oracle_text?: Nullable<string>;
    power?: Nullable<string>;
    printed_name?: Nullable<string>;
    printed_text?: Nullable<string>;
    printed_type_line?: Nullable<string>;
    toughness?: Nullable<string>;
    type_line?: Nullable<string>;
    watermark?: Nullable<string>;
}
interface RelatedCard {
    component: CardComponent;
    id: string;
    name: string;
    object: 'related_card';
    type_line: string;
    uri: string;
}
interface Legalities {
    alchemy: Legality;
    brawl: Legality;
    commander: Legality;
    duel: Legality;
    explorer: Legality;
    future: Legality;
    gladiator: Legality;
    historic: Legality;
    legacy: Legality;
    modern: Legality;
    oathbreaker: Legality;
    oldschool: Legality;
    pauper: Legality;
    paupercommander: Legality;
    penny: Legality;
    pioneer: Legality;
    predh: Legality;
    premodern: Legality;
    standard: Legality;
    standardbrawl: Legality;
    timeless: Legality;
    vintage: Legality;
}
interface GameplayCard {
    all_parts?: Nullable<RelatedCard[]>;
    card_faces?: Nullable<CardFace[]>;
    cmc: number;
    color_identity: Color[];
    color_indicator?: Nullable<Color[]>;
    colors?: Nullable<Color[]>;
    defense?: Nullable<string>;
    edhrec_rank?: Nullable<number>;
    hand_modifier?: Nullable<string>;
    keywords: string[];
    legalities: Legalities;
    life_modifier?: Nullable<string>;
    loyalty?: Nullable<string>;
    mana_cost?: Nullable<string>;
    name: string;
    oracle_text?: Nullable<string>;
    penny_rank?: Nullable<number>;
    power?: Nullable<string>;
    produced_mana?: Nullable<Color[]>;
    reserved: boolean;
    toughness?: Nullable<string>;
    type_line: string;
}

type SetType = 'alchemy' | 'archenemy' | 'arsenal' | 'box' | 'commander' | 'core' | 'draft_innovation' | 'duel_deck' | 'expansion' | 'from_the_vault' | 'funny' | 'masterpiece' | 'masters' | 'memorabilia' | 'minigame' | 'planechase' | 'premium_deck' | 'promo' | 'spellbook' | 'starter' | 'token' | 'treasure_chest' | 'vanguard';
interface Set {
    arena_code?: Nullable<string>;
    block?: Nullable<string>;
    block_code?: Nullable<string>;
    card_count: number;
    code: string;
    digital: boolean;
    foil_only: boolean;
    icon_svg_uri: string;
    id: string;
    mtgo_code?: Nullable<string>;
    name: string;
    nonfoil_only: boolean;
    object: 'set';
    parent_set_code?: Nullable<string>;
    printed_size?: Nullable<number>;
    released_at?: Nullable<Date>;
    scryfall_uri: string;
    search_uri: string;
    set_type: SetType;
    tcgplayer_id?: Nullable<number>;
    uri: string;
}

declare class SetApi {
    all(): Promise<Set[]>;
    byCode(code: string): Promise<Set | undefined>;
    byId(id: string): Promise<Set | undefined>;
    byTcgPlayerId(id: number): Promise<Set | undefined>;
}
declare const set: SetApi;

type BorderColor = 'black' | 'borderless' | 'gold' | 'silver' | 'white';
type Finish = 'etched' | 'foil' | 'nonfoil';
type Frame = '1993' | '1997' | '2003' | '2015' | 'future';
type FrameEffect = 'colorshifted' | 'companion' | 'compasslanddfc' | 'convertdfc' | 'devoid' | 'draft' | 'etched' | 'extendedart' | 'fandfc' | 'inverted' | 'legendary' | 'lesson' | 'miracle' | 'mooneldrazidfc' | 'nyxtouched' | 'originpwdfc' | 'shatteredglass' | 'showcase' | 'snow' | 'sunmoondfc' | 'tombstone' | 'upsidedowndfc' | 'waxingandwaningmoondfc';
type Game = 'arena' | 'mtgo' | 'paper';
type ImageStatus = 'highres_scan' | 'lowres' | 'missing' | 'placeholder';
interface Preview {
    previewed_at: Date;
    source: string;
    source_uri: string;
}
interface Prices {
    eur?: Nullable<string>;
    eur_foil?: Nullable<string>;
    tix?: Nullable<string>;
    usd?: Nullable<string>;
    usd_etched?: Nullable<string>;
    usd_foil?: Nullable<string>;
}
type PromoType = 'arenaleague' | 'buyabox' | 'convention' | 'datestamped' | 'draftweekend' | 'duels' | 'event' | 'fnm' | 'gameday' | 'gateway' | 'giftbox' | 'instore' | 'intropack' | 'judgegift' | 'league' | 'openhouse' | 'ourney' | 'planeswalkerdeck' | 'playerrewards' | 'premiereshop' | 'prerelease' | 'release' | 'setpromo' | 'starterdeck' | 'wizardsplaynetwork';
interface PurchaseUris {
    [key: string]: Nullable<string>;
    cardhoarder?: Nullable<string>;
    cardmarket?: Nullable<string>;
    tcgplayer?: Nullable<string>;
}
type Rarity = 'bonus' | 'common' | 'mythic' | 'rare' | 'special' | 'uncommon';
interface RelatedUris {
    [key: string]: Nullable<string>;
    edhrec?: Nullable<string>;
    gatherer?: Nullable<string>;
    mtgtop8?: Nullable<string>;
    tcgplayer_decks?: Nullable<string>;
    tcgplayer_infinite_articles?: Nullable<string>;
    tcgplayer_infinite_decks?: Nullable<string>;
}
type SecurityStamp = 'acorn' | 'arena' | 'circle' | 'heart' | 'oval' | 'triangle';
interface CardPrint {
    artist?: Nullable<string>;
    artist_ids?: Nullable<string[]>;
    attraction_lights?: Nullable<number[]>;
    booster: boolean;
    border_color: BorderColor;
    card_back_id: string;
    collector_number: string;
    content_warning?: Nullable<boolean>;
    digital: boolean;
    finishes: Finish[];
    flavor_name?: Nullable<string>;
    flavor_text?: Nullable<string>;
    frame: Frame;
    frame_effects?: Nullable<FrameEffect[]>;
    full_art: boolean;
    games: Game[];
    highres_image: boolean;
    illustration_id?: Nullable<string>;
    image_status: ImageStatus;
    image_uris?: Nullable<ImageUris>;
    oversized: boolean;
    preview: Preview;
    prices: Prices;
    printed_name?: Nullable<string>;
    printed_text?: Nullable<string>;
    printed_type_line?: Nullable<string>;
    promo: boolean;
    promo_types?: Nullable<PromoType[]>;
    purchase_uris?: Nullable<PurchaseUris>;
    rarity: Rarity;
    related_uris: RelatedUris;
    released_at: Date;
    reprint: boolean;
    scryfall_set_uri: string;
    security_stamp?: Nullable<SecurityStamp>;
    set: string;
    set_id: string;
    set_name: string;
    set_search_uri: string;
    set_type: SetType;
    set_uri: string;
    story_spotlight: boolean;
    textless: boolean;
    variation: boolean;
    variation_of?: Nullable<string>;
    watermark?: Nullable<string>;
}

type Card = CardCore & CardPrint & GameplayCard;

type CardSearchUnique = 'art' | 'cards' | 'prints';
type CardSearchOrder = 'artist' | 'cmc' | 'color' | 'edhrec' | 'eur' | 'name' | 'penny' | 'power' | 'rarity' | 'released' | 'review' | 'set' | 'tix' | 'toughness' | 'usd';
type CardSearchDirection = 'asc' | 'auto' | 'desc';
type CardSearchFormat = 'csv' | 'json';
interface CardSearch {
    dir?: CardSearchDirection;
    format?: CardSearchFormat;
    include_extras?: boolean;
    include_multilingual?: boolean;
    include_variations?: boolean;
    order?: CardSearchOrder;
    page?: number;
    pretty?: boolean;
    unique?: CardSearchUnique;
}

declare class CardApi {
    autoCompleteName(name: string): Promise<string[]>;
    byArenaId(id: number): Promise<Card | undefined>;
    byId(id: string): Promise<Card | undefined>;
    byMtgoId(id: number): Promise<Card | undefined>;
    byMultiverseId(id: number): Promise<Card | undefined>;
    byName(name: string, fuzzy?: boolean): Promise<Card | undefined>;
    byName(name: string, set?: string, fuzzy?: boolean): Promise<Card | undefined>;
    bySet(setCode: string, collectorNumber: number, lang?: string): Promise<Card | undefined>;
    byTcgPlayerId(id: number): Promise<Card | undefined>;
    collection(...identifiers: CardIdentifier[]): Promise<Card[]>;
    random(): Promise<Card>;
    search(query: string, options?: CardSearch | number): MagicPageResult<Card>;
}
declare const cards: CardApi;

declare class CatalogApi {
    artifactTypes(): Promise<string[]>;
    artistNames(): Promise<string[]>;
    cardNames(): Promise<string[]>;
    creatureTypes(): Promise<string[]>;
    enchantmentTypes(): Promise<string[]>;
    landTypes(): Promise<string[]>;
    loyalties(): Promise<string[]>;
    planeswalkerTypes(): Promise<string[]>;
    powers(): Promise<string[]>;
    spellTypes(): Promise<string[]>;
    toughnesses(): Promise<string[]>;
    watermarks(): Promise<string[]>;
    wordBank(): Promise<string[]>;
}
declare const catalog: CatalogApi;

interface Catalog {
    data: string[];
    object: 'catalog';
    total_values: number;
    uri: string;
}

interface Ruling {
    comment: string;
    object: 'ruling';
    oracle_id: string;
    published_at: Date;
    source: string;
}

declare class RulingApi {
    byArenaId(id: number): Promise<Ruling[]>;
    byId(id: string): Promise<Ruling[]>;
    byMtgoId(id: number): Promise<Ruling[]>;
    byMultiverseId(id: number): Promise<Ruling[]>;
    bySet(setCode: string, collectorNumber: number | string): Promise<Ruling[]>;
}
declare const rulings: RulingApi;

declare class InvalidScryfallArgumentError extends Error {
}

declare class ScryfallError extends Error {
    readonly code: string;
    readonly status: number;
    readonly type?: null | string | undefined;
    readonly warnings?: null | string[] | undefined;
    constructor(code: string, details: string, status: number, type?: null | string | undefined, warnings?: null | string[] | undefined);
}

declare class UnknownScryfallError extends Error {
}

export { type BorderColor, type Card, type CardComponent, type CardFace, type CardIdentifier, CardIdentifierApi as CardIdentifierBuilder, type CardIdentifierCollectorSet, type CardIdentifierId, type CardIdentifierIllustrationId, type CardIdentifierMtgGoId, type CardIdentifierMultiverseId, type CardIdentifierNameSet, type CardIdentifierOracleId, type CardLanguage, type CardLayout, type CardSearch, type CardSearchDirection, type CardSearchFormat, type CardSearchOrder, type CardSearchUnique, cards as Cards, type Catalog, catalog as Catalogs, type Color, type Finish, type Frame, type FrameEffect, type Game, type ImageStatus, type ImageUris, InvalidScryfallArgumentError, type Legalities, type Legality, MagicPageResult, type ManaCost, type Preview, type Prices, type PromoType, type PurchaseUris, type Rarity, type RelatedCard, type RelatedUris, type Ruling, rulings as Rulings, ScryfallError, type SecurityStamp, type Set, type SetType, set as Sets, type Symbology, symbology as SymbologyApi, UnknownScryfallError };