scryfall-api 3.0.0 → 3.0.3

package/README.md

@@ -0,0 +1,40 @@
+# scryfall-api
+
+[![npm](https://img.shields.io/npm/v/scryfall-api?style=flat-square)](https://www.npmjs.com/package/scryfall-api)
+[![GitHub issues](https://img.shields.io/github/issues/mariomh8/scryfall-api?style=flat-square)](https://github.com/MarioMH8/scryfall-api)
+
+A Javascript library for [Scryfall](https://scryfall.com/docs/api) written in Typescript.
+
+As of [January 29th, 2022](./CHANGELOG.md), almost all features described in the [Scryfall documentation](https://scryfall.com/docs/api) are supported. If you see something that isn't supported, make an issue! See [support readme](./SUPPORT.md).
+
+## Installation
+
+```bat
+npm install scryfall-api
+```
+
+## Documentation
+
+Link to [documentation.](./DOCUMENTATION.md)
+
+## Contributing
+
+Thanks for wanting to help out! Here's the setup you'll have to do:
+
+```bat
+git clone git@github.com:MarioMH8/scryfall-api.git
+cd scryfall-api
+yarn install
+```
+
+You can now make changes to the repository.
+
+To compile:
+
+```bat
+yarn build
+```
+
+## MIT License
+
+[Copyright 2021-2022 Mario Menéndez](./LICENSE)

package/dist/declarations/src/api/CardIdentifierBuilder.d.ts

@@ -0,0 +1,10 @@
+import { CardIdentifier } from '../types';
+export declare class CardIdentifierBuilder {
+    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: string | number): CardIdentifier;
+}

package/dist/declarations/src/api/Cards.d.ts

@@ -0,0 +1,19 @@
+import MagicPageResult from '../query/MagicPageResult';
+import MagicQuery from '../query/MagicQuery';
+import { Card, CardIdentifier, SearchOptions } from '../types';
+declare class Cards extends MagicQuery {
+    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 | undefined>;
+    search(query: string, options?: SearchOptions | number): MagicPageResult<Card, Cards>;
+}
+declare const _default: Cards;
+export default _default;

package/dist/declarations/src/api/Catalog.d.ts

@@ -0,0 +1,18 @@
+import MagicQuery from '../query/MagicQuery';
+declare class Catalog extends MagicQuery {
+    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 _default: Catalog;
+export default _default;

package/dist/declarations/src/api/Misc.d.ts

@@ -0,0 +1,7 @@
+import MagicQuery from '../query/MagicQuery';
+import { HomepageLink } from '../types';
+declare class Misc extends MagicQuery {
+    homepageLinks(): Promise<HomepageLink[]>;
+}
+declare const _default: Misc;
+export default _default;

package/dist/declarations/src/api/Rulings.d.ts

@@ -0,0 +1,11 @@
+import MagicQuery from '../query/MagicQuery';
+import { Ruling } from '../types';
+declare class Rulings extends MagicQuery {
+    byArenaId(id: number): Promise<Ruling[]>;
+    byId(id: string): Promise<Ruling[]>;
+    byMtgoId(id: number): Promise<Ruling[]>;
+    byMultiverseId(id: number): Promise<Ruling[]>;
+    bySet(setCode: string, collectorNumber: string | number): Promise<Ruling[]>;
+}
+declare const _default: Rulings;
+export default _default;

package/dist/declarations/src/api/Sets.d.ts

@@ -0,0 +1,10 @@
+import MagicQuery from '../query/MagicQuery';
+import { Set } from '../types';
+declare class Sets extends MagicQuery {
+    all(): Promise<Set[]>;
+    byCode(code: string): Promise<Set | undefined>;
+    byId(id: string): Promise<Set | undefined>;
+    byTcgPlayerId(id: number): Promise<Set | undefined>;
+}
+declare const _default: Sets;
+export default _default;

package/dist/declarations/src/api/Symbology.d.ts

@@ -0,0 +1,8 @@
+import MagicQuery from '../query/MagicQuery';
+import { CardSymbol, ManaCost } from '../types';
+declare class Symbology extends MagicQuery {
+    all(): Promise<CardSymbol[]>;
+    parseMana(shorthand: string): Promise<ManaCost | undefined>;
+}
+declare const _default: Symbology;
+export default _default;

package/dist/declarations/src/error/MagicQueryError.d.ts

@@ -0,0 +1,5 @@
+import { SearchError } from '../types/SearchError';
+export declare class MagicQueryError extends Error {
+    readonly data?: SearchError | undefined;
+    constructor(data?: SearchError | undefined);
+}

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,11 @@
+export { default as Cards } from './api/Cards';
+export { default as Catalog } from './api/Catalog';
+export { default as Misc } from './api/Misc';
+export { default as Rulings } from './api/Rulings';
+export { default as Sets } from './api/Sets';
+export { default as Symbology } from './api/Symbology';
+export * from './api/CardIdentifierBuilder';
+export * from './error/MagicQueryError';
+export * from './query/MagicQuery';
+export * from './query/MagicPageResult';
+export * from './types';

package/dist/declarations/src/query/MagicPageResult.d.ts

@@ -0,0 +1,18 @@
+import { PageQuery } from '../types';
+import MagicQuery from './MagicQuery';
+export default class MagicPageResult<T, Q extends MagicQuery, P = unknown> {
+    private readonly q;
+    private readonly apiPath;
+    private readonly query;
+    private readonly post?;
+    private _hasMore;
+    private _count;
+    constructor(q: Q, apiPath: string, query: PageQuery, post?: P | undefined);
+    get count(): number;
+    get hasMore(): boolean;
+    all(): Promise<T[]>;
+    get(limit: number): Promise<T[]>;
+    next(): Promise<T[]>;
+    page(page: number): Promise<T[]>;
+    private setNextPage;
+}

package/dist/declarations/src/query/MagicQuery.d.ts

@@ -0,0 +1,13 @@
+import { AxiosRequestConfig } from 'axios';
+import { Query, RetryStrategy, TOrArrayOfT } from '../types';
+export default class MagicQuery {
+    static retry: RetryStrategy;
+    private static readonly endpoint;
+    private static lastQuery;
+    private static readonly rateLimit;
+    private static canRetry;
+    private static debounce;
+    private static sleep;
+    private static tryQuery;
+    query<T = unknown, Y = unknown>(apiPath: TOrArrayOfT<string | number | undefined>, query?: Query, post?: Y, requestOptions?: AxiosRequestConfig): Promise<T | undefined>;
+}

package/dist/declarations/src/types/Border.d.ts

@@ -0,0 +1,7 @@
+export declare enum Border {
+    black = 0,
+    borderless = 1,
+    gold = 2,
+    silver = 3,
+    white = 4
+}

package/dist/declarations/src/types/BulkDataDefinition.d.ts

@@ -0,0 +1,14 @@
+import { BulkDataType } from './BulkDataType';
+export interface BulkDataDefinition {
+    compressed_size: number;
+    content_encoding: string;
+    content_type: string;
+    description: string;
+    download_uri: string;
+    id: string;
+    name: string;
+    object: 'bulk_data';
+    type: BulkDataType;
+    updated_at: string;
+    uri: string;
+}

package/dist/declarations/src/types/BulkDataType.d.ts

@@ -0,0 +1,2 @@
+import { BulkDataTypes } from './BulkDataTypes';
+export declare type BulkDataType = keyof typeof BulkDataTypes;

package/dist/declarations/src/types/BulkDataTypes.d.ts

@@ -0,0 +1,7 @@
+export declare enum BulkDataTypes {
+    oracle_cards = 0,
+    unique_artwork = 1,
+    default_cards = 2,
+    all_cards = 3,
+    rulings = 4
+}

package/dist/declarations/src/types/Card.d.ts

@@ -0,0 +1,91 @@
+import { Border } from './Border';
+import { CardFace } from './CardFace';
+import { Color } from './Color';
+import { FrameEffect } from './FrameEffect';
+import { Game } from './Game';
+import { ImageUris } from './ImageUris';
+import { Layout } from './Layout';
+import { Legalities } from './Legalties';
+import { Preview } from './Preview';
+import { Prices } from './Prices';
+import { PromoType } from './PromoType';
+import { PurchaseUris } from './PurchaseUris';
+import { Rarity } from './Rarity';
+import { RelatedCard } from './RelatedCard';
+import { RelatedUris } from './RelatedUris';
+import { Set as ScryfallSet } from './Set';
+export interface Card {
+    object: 'card';
+    arena_id?: number;
+    id: string;
+    lang: string;
+    mtgo_id?: number;
+    mtgo_foil_id?: number;
+    multiverse_ids?: number[];
+    tcgplayer_id?: number;
+    oracle_id: string;
+    prints_search_uri: string;
+    rulings_uri: string;
+    scryfall_uri: string;
+    uri: string;
+    all_parts?: RelatedCard[];
+    card_faces?: CardFace[];
+    cmc: number;
+    colors?: Color[];
+    color_identity: Color[];
+    color_indicator?: Color[];
+    edhrec_rank?: number;
+    foil: boolean;
+    hand_modifier?: string;
+    layout: keyof typeof Layout;
+    legalities: Legalities;
+    life_modifier?: string;
+    loyalty?: string;
+    mana_cost?: string;
+    name: string;
+    nonfoil: boolean;
+    oracle_text?: string;
+    oversized: boolean;
+    power?: string;
+    reserved: boolean;
+    toughness?: string;
+    type_line: string;
+    artist?: string;
+    artist_ids?: string[];
+    booster: boolean;
+    border_color: keyof typeof Border;
+    card_back_id: string;
+    collector_number: string;
+    digital: boolean;
+    flavor_text?: string;
+    frame_effects?: (keyof typeof FrameEffect)[];
+    frame: '1993' | '1997' | '2003' | '2015' | 'Future';
+    full_art: boolean;
+    games: (keyof typeof Game)[];
+    highres_image: boolean;
+    illustration_id?: string;
+    image_uris?: ImageUris;
+    prices: Prices;
+    printed_name?: string;
+    printed_text?: string;
+    printed_type_line?: string;
+    promo: boolean;
+    promo_types?: (keyof typeof PromoType)[];
+    purchase_uris: PurchaseUris;
+    rarity: keyof typeof Rarity;
+    related_uris: RelatedUris;
+    released_at: string;
+    reprint: boolean;
+    scryfall_set_uri: string;
+    set_name: string;
+    set_search_uri: string;
+    set_type: ScryfallSet['set_type'];
+    set_uri: string;
+    set: string;
+    story_spotlight: boolean;
+    textless: boolean;
+    variation: boolean;
+    variation_of?: string;
+    watermark?: string;
+    preview?: Preview;
+}

package/dist/declarations/src/types/CardFace.d.ts

@@ -0,0 +1,22 @@
+import { Color } from './Color';
+import { ImageUris } from './ImageUris';
+export interface CardFace {
+    object: 'card_face';
+    artist?: string;
+    color_indicator?: Color[];
+    colors: Color[];
+    flavor_text?: string;
+    illustration_id?: string;
+    image_uris?: ImageUris;
+    loyalty?: string;
+    mana_cost: string;
+    name: string;
+    oracle_text?: string;
+    power?: string;
+    printed_name?: string;
+    printed_text?: string;
+    printed_type_line?: string;
+    toughness?: string;
+    type_line: string;
+    watermark?: string;
+}

package/dist/declarations/src/types/CardIdentifier.d.ts

@@ -0,0 +1,10 @@
+export interface CardIdentifier {
+    id?: string;
+    mtgo_id?: number;
+    multiverse_id?: number;
+    oracle_id?: string;
+    illustration_id?: string;
+    name?: string;
+    set?: string;
+    collector_number?: string;
+}

package/dist/declarations/src/types/CardSymbol.d.ts

@@ -0,0 +1,13 @@
+import { Color } from './Color';
+export interface CardSymbol {
+    symbol: string;
+    loose_variant?: string;
+    english: string;
+    transposable: boolean;
+    represents_mana: boolean;
+    converted_mana_cost?: number;
+    colors: Color[];
+    appears_in_mana_costs: boolean;
+    funny: boolean;
+    gatherer_alternates?: string[];
+}

package/dist/declarations/src/types/Color.d.ts

@@ -0,0 +1,9 @@
+declare enum Colors {
+    W = 0,
+    B = 1,
+    R = 2,
+    U = 3,
+    G = 4
+}
+export declare type Color = keyof typeof Colors;
+export {};

package/dist/declarations/src/types/Format.d.ts

@@ -0,0 +1,15 @@
+export declare enum Format {
+    standard = 0,
+    future = 1,
+    historic = 2,
+    pioneer = 3,
+    modern = 4,
+    legacy = 5,
+    pauper = 6,
+    vintage = 7,
+    penny = 8,
+    commander = 9,
+    brawl = 10,
+    duel = 11,
+    oldschool = 12
+}

package/dist/declarations/src/types/FrameEffect.d.ts

@@ -0,0 +1,17 @@
+export declare enum FrameEffect {
+    legendary = 0,
+    miracle = 1,
+    nyxtouched = 2,
+    draft = 3,
+    devoid = 4,
+    tombstone = 5,
+    colorshifted = 6,
+    inverted = 7,
+    sunmoondfc = 8,
+    compasslanddfc = 9,
+    originpwdfc = 10,
+    mooneldrazidfc = 11,
+    moonreversemoondfc = 12,
+    showcase = 13,
+    extendedart = 14
+}

package/dist/declarations/src/types/Game.d.ts

@@ -0,0 +1,5 @@
+export declare enum Game {
+    paper = 0,
+    arena = 1,
+    mtgo = 2
+}

package/dist/declarations/src/types/HomepageLink.d.ts

@@ -0,0 +1,9 @@
+export interface HomepageLink {
+    id: number;
+    created_at: string;
+    updated_at: string;
+    priority: number;
+    text: string;
+    uri: string;
+    badge?: string;
+}

package/dist/declarations/src/types/ImageUris.d.ts

@@ -0,0 +1,8 @@
+export interface ImageUris {
+    small: string;
+    normal: string;
+    large: string;
+    png: string;
+    art_crop: string;
+    border_crop: string;
+}

package/dist/declarations/src/types/Layout.d.ts

@@ -0,0 +1,20 @@
+export declare enum Layout {
+    normal = 0,
+    split = 1,
+    flip = 2,
+    transform = 3,
+    meld = 4,
+    leveler = 5,
+    saga = 6,
+    adventure = 7,
+    planar = 8,
+    scheme = 9,
+    vanguard = 10,
+    token = 11,
+    double_faced_token = 12,
+    emblem = 13,
+    augment = 14,
+    host = 15,
+    art_series = 16,
+    double_sided = 17
+}

package/dist/declarations/src/types/Legalties.d.ts

@@ -0,0 +1,5 @@
+import { Format } from './Format';
+import { Legality } from './Legalty';
+export declare type Legalities = {
+    [key in keyof typeof Format]: keyof typeof Legality;
+};

package/dist/declarations/src/types/Legalty.d.ts

@@ -0,0 +1,6 @@
+export declare enum Legality {
+    legal = 0,
+    not_legal = 1,
+    restricted = 2,
+    banned = 3
+}

package/dist/declarations/src/types/ManaCost.d.ts

@@ -0,0 +1,9 @@
+import { Color } from './Color';
+export interface ManaCost {
+    cost: string;
+    cmc: number;
+    colors: Color[];
+    colorless: boolean;
+    monocolored: boolean;
+    multicolored: boolean;
+}

package/dist/declarations/src/types/PageQuery.d.ts

@@ -0,0 +1,5 @@
+import { QueryValue } from './PageQueryValue';
+export declare type PageQuery = {
+    [key: string]: QueryValue;
+    page: number;
+};

package/dist/declarations/src/types/PageQueryValue.d.ts

@@ -0,0 +1 @@
+export declare type QueryValue = string | number | boolean | undefined;

package/dist/declarations/src/types/Preview.d.ts

@@ -0,0 +1,5 @@
+export interface Preview {
+    previewed_at?: string;
+    source_uri?: string;
+    source?: string;
+}

package/dist/declarations/src/types/Prices.d.ts

@@ -0,0 +1,6 @@
+export interface Prices {
+    usd?: string;
+    usd_foil?: string;
+    eur?: string;
+    tix?: string;
+}

package/dist/declarations/src/types/PromoType.d.ts

@@ -0,0 +1,27 @@
+export declare enum PromoType {
+    tourney = 0,
+    prerelease = 1,
+    datestamped = 2,
+    planeswalkerdeck = 3,
+    buyabox = 4,
+    judgegift = 5,
+    event = 6,
+    convention = 7,
+    starterdeck = 8,
+    instore = 9,
+    setpromo = 10,
+    fnm = 11,
+    openhouse = 12,
+    league = 13,
+    draftweekend = 14,
+    gameday = 15,
+    release = 16,
+    intropack = 17,
+    giftbox = 18,
+    duels = 19,
+    wizardsplaynetwork = 20,
+    premiereshop = 21,
+    playerrewards = 22,
+    gateway = 23,
+    arenaleague = 24
+}

package/dist/declarations/src/types/PurchaseUris.d.ts

@@ -0,0 +1,6 @@
+export interface PurchaseUris {
+    tcgplayer?: string;
+    cardmarket?: string;
+    cardhoarder?: string;
+    [key: string]: string | undefined;
+}

package/dist/declarations/src/types/Query.d.ts

@@ -0,0 +1,4 @@
+import { QueryValue } from './PageQueryValue';
+export declare type Query = {
+    [key: string]: QueryValue;
+};

package/dist/declarations/src/types/Rarity.d.ts

@@ -0,0 +1,6 @@
+export declare enum Rarity {
+    common = 0,
+    uncommon = 1,
+    rare = 2,
+    mythic = 3
+}

package/dist/declarations/src/types/RelatedCard.d.ts

@@ -0,0 +1,9 @@
+import { RelatedCardComponent } from './RelatedCardComponent';
+export interface RelatedCard {
+    component: keyof typeof RelatedCardComponent;
+    id: string;
+    name: string;
+    object: 'related_card';
+    type_line: string;
+    uri: string;
+}

package/dist/declarations/src/types/RelatedCardComponent.d.ts

@@ -0,0 +1,6 @@
+export declare enum RelatedCardComponent {
+    token = 0,
+    meld_part = 1,
+    meld_result = 2,
+    combo_piece = 3
+}

package/dist/declarations/src/types/RelatedUris.d.ts

@@ -0,0 +1,7 @@
+export interface RelatedUris {
+    gatherer?: string;
+    tcgplayer_decks?: string;
+    edhrec?: string;
+    mtgtop8?: string;
+    [key: string]: string | undefined;
+}

package/dist/declarations/src/types/ResultCatalog.d.ts

@@ -0,0 +1,2 @@
+import { ResultData } from './ResultData';
+export declare type ResultCatalog = ResultData<string>;

package/dist/declarations/src/types/ResultData.d.ts

@@ -0,0 +1,4 @@
+export interface ResultData<T, NOT_FOUND = never> {
+    data: T[];
+    not_found?: NOT_FOUND[];
+}

package/dist/declarations/src/types/ResultList.d.ts

@@ -0,0 +1,7 @@
+import { ResultData } from './ResultData';
+export interface ResultList<T, NOT_FOUND = never> extends ResultData<T, NOT_FOUND> {
+    has_more: boolean;
+    next_page: string;
+    total_cards: string;
+    warnings: string[];
+}

package/dist/declarations/src/types/RetryStrategy.d.ts

@@ -0,0 +1,11 @@
+import { SearchError } from './SearchError';
+export interface RetryStrategy {
+    attempts: number;
+    timeout?: number;
+    /**
+     * Whether even `not_found` and `bad_request` errors should be retried.
+     * @deprecated Don't use this, this is for unit tests
+     */
+    forced?: boolean;
+    canRetry?(error?: SearchError): boolean;
+}

package/dist/declarations/src/types/Ruling.d.ts

@@ -0,0 +1,5 @@
+export interface Ruling {
+    source: string;
+    published_at: string;
+    comment: string;
+}

package/dist/declarations/src/types/SearchError.d.ts

@@ -0,0 +1,7 @@
+export interface SearchError {
+    object: 'error';
+    code: string;
+    status: number;
+    details: string;
+    warnings?: string[];
+}

package/dist/declarations/src/types/SearchOptions.d.ts

@@ -0,0 +1,15 @@
+import { Sort } from './Sort';
+import { SortDirection } from './SortDirection';
+import { UniqueStrategy } from './UniqueStrategy';
+export interface SearchOptions {
+    unique?: keyof typeof UniqueStrategy;
+    order?: keyof typeof Sort;
+    dir?: keyof typeof SortDirection;
+    include_extras?: boolean;
+    include_multilingual?: boolean;
+    include_variations?: boolean;
+    /**
+     * The page to start on. Defaults to `1`, for first page. A page is 175 cards.
+     */
+    page?: number;
+}