Skip to content

Latest commit

 

History

History
524 lines (353 loc) · 19.7 KB

DOCUMENTATION.md

File metadata and controls

524 lines (353 loc) · 19.7 KB

Table of Contents

Usage 🡅

In the documentation below, requiring the package is assumed.

import Scry = require("scryfall-sdk");

Cards 🡅

Cards.byId (id: string): Promise<Card>; 🡅

Gets a single card from its ID.

Scry.Cards.byId("9ea8179a-d3c9-4cdc-a5b5-68cc73279050").then(result => console.log(result.name)); // Blood Scrivener

Cards.byName (name: string, set?: string, fuzzy = false): Promise<Card>; 🡅

Gets a card based on its name. Supports fuzzy searching, by 1-2 replacements/translations.

Scry.Cards.byName("Blood Scrivener").then(result => console.log(result.name)); // Blood Scrivener
Scry.Cards.byName("Bliid Scrivener", true).then(result => console.log(result.name)); // Blood Scrivener
Scry.Cards.byName("Loxodon Warhammer", "MRD").then(result => console.log(result.name, result.set)); // Loxodon Warhammer, mrd
Scry.Cards.byName("Warhammer", "MRD", true).then(result => console.log(result.name, result.set)); // Loxodon Warhammer, mrd

Cards.bySet (setCode: string, collectorNumber: number, lang?: string): Promise<Card>; 🡅

Gets a card based on its set and collector id. You can use the optional lang argument to get cards in another language. See the Scryfall Documentation for a list of all languages.

Scry.Cards.bySet("dgm", 22).then(result => console.log(result.name + ", " + result.printed_name)); // Blood Scrivener, undefined
Scry.Cards.bySet("dgm", 22, "ja").then(result => console.log(result.name + ", " + result.printed_name)); // Blood Scrivener, 血の公証人

Cards.byMultiverseId (id: number): Promise<Card>; 🡅

Gets a card based on its multiverse id.

Scry.Cards.byMultiverseId(369030).then(result => console.log(result.name)); // Blood Scrivener

Cards.byMtgoId (id: number): Promise<Card>; 🡅

Gets a card based on its MTGO (sometimes called "Cat") id.

Scry.Cards.byMtgoId(48338).then(result => console.log(result.name)); // Blood Scrivener

Cards.byArenaId (id: number): Promise<Card>; 🡅

Gets a card based on its MTG Arena id.

Scry.Cards.byArenaId(67330).then(result => console.log(result.name)); // Yargle, Glutton of Urborg

Cards.byTcgPlayerId (id: number): Promise<Card>; 🡅

Gets a card based on its TCG Player id.

Scry.Cards.byTcgPlayerId(1030).then(result => console.log(result.name)); // Ankh of Mishra

Cards.search (query: string, options?: SearchOptions): MagicEmitter<Card>; 🡅

Queries for a card using the Scryfall Search API.

Scry.Cards.search("type:planeswalker").on("data", card => {
	console.log(card.name);
}).on("end", () => {
	console.log("done");
});

For information on how to provide extra options, see the /get/cards/search page on Scryfall. You can also reference the SearchOptions interface in IScry.ts

This query returns a MagicEmitter.

Cards.all (page = 1): MagicEmitter<Card>; 🡅

From the Scryfall documentation:

Scryfall currently has 191,325 cards, and this endpoint has 1094 pages. This represents more than 400 MB of JSON data: beware your memory and storage limits if you are downloading the entire database.

Every card type is returned, including planar cards, schemes, Vanguard cards, tokens, emblems, and funny cards.

Scry.Cards.all().on("data", card => {
	console.log(card.name);
}).on("end", () => {
	console.log("done");
});

This query returns a MagicEmitter.

The page parameter is the page of results that the query will begin at. A page is 175 cards, and cannot be changed. To get only the one page you requested, you can do the following:

const cardsFromPage15 = await Scry.Cards.all(15).cancelAfterPage().waitForAll();

Cards.random (id: number): Promise<Card>; 🡅

Gets a random card.

Scry.Cards.random().then(result => console.log(result.name));

Cards.autoCompleteName (name: string): Promise<string[]>; 🡅

From the Scryfall documentation:

Returns [an array] containing up to 25 full card names that could be autocompletions of the given string parameter q.

This method is designed for creating assistive UI elements that allow users to free-type card names. The names are sorted with the nearest match first.

Spaces, punctuation, and capitalization are ignored.

If q is less than 2 characters long, or if no names match, the Catalog will contain 0 items (instead of returning any errors).

Scry.Cards.autoCompleteName("bloodsc").then((results) => {
	for (const result of results) {
		console.log(result);
		// Bloodscent
		// Blood Scrivener
		// Bloodscale Prowler
		// Burning-Tree Bloodscale
		// Ghor-Clan Bloodscale
	}
});

Cards.collection (...collection: CardIdentifier[]): MagicEmitter<Card>; 🡅

Takes a list of "card identifiers", which describe a card, and returns their actual card objects.

This method is useful for decks and even entire collections. Scryfall has a limit of 75 cards, but this API will split your request into multiple API calls, allowing requests of as many cards as you want.

In order to assist with manual requests, this method comes with a new set of factories by the name CardIdentifier. These are:

  • Scry.CardIdentifier.byId(id: string): CardIdentifier;
  • Scry.CardIdentifier.byMultiverseId(id: number): CardIdentifier;
  • Scry.CardIdentifier.byMtgoId(id: number): CardIdentifier;
  • Scry.CardIdentifier.byOracleId(id: string): CardIdentifier;
  • Scry.CardIdentifier.byIllustrationId(id: string): CardIdentifier;
  • Scry.CardIdentifier.byName(string: string, set?: string): CardIdentifier;
  • Scry.CardIdentifier.byName(string: string, set?: string): CardIdentifier;
  • Scry.CardIdentifier.bySet(set: string, collectorNumber: string | number): CardIdentifier;

Example:

const collection = [
    Scry.CardIdentifier.byId("94c70f23-0ca9-425e-a53a-6c09921c0075"),
    Scry.CardIdentifier.byMultiverseId(462293),
    Scry.CardIdentifier.byMtgoId(71692),
    Scry.CardIdentifier.byOracleId("394c6de5-7957-4a0b-a6b9-ee0c707cd022"),
    Scry.CardIdentifier.byIllustrationId("99f43949-049e-41e2-bf4c-e22e11790012"),
    Scry.CardIdentifier.byName("Blood Scrivener"),
    Scry.CardIdentifier.byName("Lightning Bolt", "prm"),
    Scry.CardIdentifier.bySet("mrd", "150"),
];

const cards = await Scry.Cards.collection(...collection).waitForAll();
// every card identifier has been mapped to its real card object

for (const card of cards) {
    console.log(card.name);
}
// Crush Dissent
// Contentious Plan
// Bond of Insight
// Forgotten Cave
// GO TO JAIL
// Blood Scrivener
// Lightning Bolt
// Chalice of the Void

Sets 🡅

Sets.byCode (code: string): Promise<Set>; 🡅

Gets a set by its code.

Scry.Sets.byCode("hou").then(set => console.log(set.name)); // Hour of Devastation

Sets.byId (id: string): Promise<Set>; 🡅

Gets a set by its Scryfall ID.

Scry.Sets.byId("65ff168b-bb94-47a5-a8f9-4ec6c213e768").then(set => console.log(set.name)); // Hour of Devastation

Sets.byTcgPlayerId (id: number): Promise<Set>; 🡅

Gets a set by its TCG Player ID, also known as the groupId on TCGPlayer's API.

Scry.Sets.byTcgPlayerId(1934).then(set => console.log(set.name)); // Hour of Devastation

Sets.all (): Promise<Set[]>; 🡅

Gets all sets.

Scry.Sets.all().then(result => console.log(result.length)); // 394

Rulings 🡅

Rulings.byId (id: string): Promise<Ruling[]>; 🡅

Gets the rulings for a single card from its ID.

Scry.Rulings.byId("9ea8179a-d3c9-4cdc-a5b5-68cc73279050").then(result => console.log(result.length)); // 2

Rulings.bySet (code: string, collectorId: string | number): Promise<Ruling[]>; 🡅

Gets the rulings for a card based on its set and collector id.

Scry.Rulings.bySet("dgm", "22").then(result => console.log(result.length)); // 2

Rulings.byMultiverseId (id: number): Promise<Ruling[]>; 🡅

Gets the rulings for a card based on its multiverse id.

Scry.Rulings.byMultiverseId(369030).then(result => console.log(result.length)); // 2

Rulings.byMtgoId (id: number): Promise<Ruling[]>; 🡅

Gets the rulings for a card based on its MTGO (sometimes called "Cat") id.

Scry.Rulings.byMtgoId(48338).then(result => console.log(result.length)); // 2

Rulings.byArenaId (id: number): Promise<Ruling[]>; 🡅

Gets the rulings for a card based on its Arena id.

Scry.Rulings.byArenaId(67204).then(result => console.log(result.length)); // 3

Symbology 🡅

Symbology.all (): Promise<CardSymbol[]>; 🡅

Gets all card symbols.

Scry.Symbology.all().then(result => console.log(result.length)); // 63

Symbology.parseMana (mana: string): Promise<ManaCost>; 🡅

From the Scryfall documentation:

Parses the given mana cost parameter and returns Scryfall’s interpretation.

The server understands most community shorthand for mana costs (such as 2WW for {2}{W}{W}). Symbols can also be out of order, lowercase, or have multiple colorless costs (such as 2{g}2 for {4}{G}).

Scry.Symbology.parseMana("7wg").then(result => console.log(result.cost)); // {7}{W}{G}

Catalogs 🡅

Catalog.cardNames (): Promise<string[]>; 🡅

Scry.Catalog.cardNames().then(result => console.log(result.length)); // 18059

Catalog.artistNames (): Promise<string[]>; 🡅

Scry.Catalog.artistNames().then(result => console.log(result.length)); // 676

Catalog.wordBank (): Promise<string[]>; 🡅

Scry.Catalog.wordBank().then(result => console.log(result.length)); // 12892

Catalog.creatureTypes (): Promise<string[]>; 🡅

Scry.Catalog.creatureTypes().then(result => console.log(result.length)); // 242

Catalog.planeswalkerTypes (): Promise<string[]>; 🡅

Scry.Catalog.planeswalkerTypes().then(result => console.log(result.length)); // 42

Catalog.landTypes (): Promise<string[]>; 🡅

Scry.Catalog.landTypes().then(result => console.log(result.length)); // 13

Catalog.artifactTypes (): Promise<string[]>; 🡅

Scry.Catalog.artifactTypes().then(result => console.log(result.length)); // 6

Catalog.enchantmentTypes (): Promise<string[]>; 🡅

Scry.Catalog.enchantmentTypes().then(result => console.log(result.length)); // 5

Catalog.spellTypes (): Promise<string[]>; 🡅

Scry.Catalog.spellTypes().then(result => console.log(result.length)); // 2

Catalog.powers (): Promise<string[]>; 🡅

Scry.Catalog.powers().then(result => console.log(result.length)); // 33

Catalog.toughnesses (): Promise<string[]>; 🡅

Scry.Catalog.toughnesses().then(result => console.log(result.length)); // 35

Catalog.loyalties (): Promise<string[]>; 🡅

Scry.Catalog.loyalties().then(result => console.log(result.length)); // 9

Catalog.watermarks (): Promise<string[]>; 🡅

Scry.Catalog.watermarks().then(result => console.log(result.length)); // 50

Misc 🡅

homepageLinks (): Promise<string[]>; 🡅

Scry.homepageLinks().then(result => console.log(result.length)); // 4

bulkData (): Promise<BulkData[]>; 🡅

Scry.bulkData().then(result => console.log(result.length)); // 5

error (): SearchError | undefined; 🡅

Returns the error returned by the last API call, or undefined if there was no error.

Note: The "last error" is reset for every page in a multi-page call — this means that using .waitForAll() or similar may throw out errors from previous pages.

setRetry (attempts: number, timeout?: number, canRetry?: (error: SearchError) => boolean): void; 🡅

Sets the retry attempts & timeout for future API calls.

If a call errors because of a 404 or 400 (not found/bad request), then it will not retry.

Example usage:

// allow 3 attempts for each query, with a timeout of 1000 ms (1 sec) between each
Scry.setRetry(3, 1000);
// some api requests here

// allow 3 attempts, a timeout of 1000 ms, and only retry if the error code is "some_code"
Scry.setRetry(3, 1000, error => error.code == "some_code");
// some api requests here

MagicEmitter<T, NOT_FOUND> 🡅

MagicEmitter.on(event: "data", listener: (data: T) => any): MagicEmitter;

Adds a listener for when data has been received. This method returns the emitter object.

MagicEmitter.on(event: "not_found", listener: (notFound: NOT_FOUND) => any): MagicEmitter;

Adds a listener for when the API returned that it was unable to find something. This method returns the emitter object.

MagicEmitter.on(event: "end", listener: () => any): MagicEmitter;

Adds a listener for when all data has been received. This method returns the emitter object.

MagicEmitter.on(event: "cancel", listener: () => any): MagicEmitter;

Adds a listener for when emitting data has been cancelled. This method returns the emitter object.

MagicEmitter.on(event: "error", listener: (err: Error) => any): MagicEmitter;

Adds a listener for when the emitter errors. This method returns the emitter object.

MagicEmitter.on(event: "done", listener: () => any): MagicEmitter;

Adds a listener for when the emitter is done: either after finishing, erroring, or being cancelled. This method returns the emitter object.

MagicEmitter.cancel(): void;

Cancels emitting data. Only emits the "cancel" event, not the "end" event.

MagicEmitter.waitForAll(): Promise<T[] & { not_found: NOT_FOUND[] }>;

Returns a promise for an array of T, fulfilled after the end event is emitted. If the API returns that it was unable to find anything, it's returned in a not_found array property on the array of T. (Note that this property is excluded when using JSON.stringify on the array)

MagicEmitter.all(): AsyncGenerator<T, void, unknown>;

Returns an async iterator that will yield each T when it receives it.

Example usage:

for await (const card of Scry.Cards.search("type:planeswalker").all()) {
    console.log(card.name);
}

MagicEmitter.notFound(): AsyncGenerator<NOT_FOUND, void, unknown>;

Returns an async generator that will yield each "not found" value when it receives it.

Example usage:

for await (const identifier of Scry.Cards.collection({ id: "00000000-0000-0000-0000-000000000000" }).notFound()) {
    console.log(identifier);
}