scryfall-client

Lightweight Scryfall API client with batching and in-memory caching. Zero dependencies — uses native fetch and Map.

Installation

npm install scryfall-client

Requires Node.js >= 18.

Usage

Fetch by MTGA card ID → name mapping

Use this when you have an Arena deck list where the same card (e.g. a basic land) appears multiple times under different IDs.

import { fetchCardsByNames } from 'scryfall-client';

const cards = [
  { cardId: 12345, name: 'Lightning Bolt' },
  { cardId: 67890, name: 'Mountain' },
  { cardId: 11111, name: 'Mountain' }, // same name, different Arena ID
];

const result = await fetchCardsByNames(cards);
// Map<cardId, ScryfallCard>
// cardId 67890 and 11111 share the same ScryfallCard object

Fetch by name list

Use this when you just have a list of card names.

import { fetchCardsByNameList } from 'scryfall-client';

const result = await fetchCardsByNameList(['Black Lotus', 'Ancestral Recall']);
// Map<lowercase name, ScryfallCard>

const lotus = result.get('black lotus');

Get a card image URL

import { getCardImageUri } from 'scryfall-client';

const uri = getCardImageUri(card);              // 'normal' size
const small = getCardImageUri(card, 'small');   // 'small' size
// Works for double-faced cards — falls back to front face automatically

Available sizes: 'small' | 'normal' | 'large' | 'art_crop' | 'border_crop'

Clear the cache

import { clearCache } from 'scryfall-client';

clearCache(); // Primarily useful in tests

API

fetchCardsByNames(cards)

| Parameter | Type | |-----------|------| | cards | ReadonlyArray<{ cardId: number; name: string }> |

Returns Promise<Map<number, ScryfallCard>> keyed by cardId. Deduplicates by name before fetching — multiple IDs with the same name share one ScryfallCard object.

fetchCardsByNameList(names)

| Parameter | Type | |-----------|------| | names | string[] |

Returns Promise<Map<string, ScryfallCard>> keyed by lowercase card name. Deduplicates and ignores empty strings.

getCardImageUri(card, size?)

| Parameter | Type | Default | |-----------|------|---------| | card | ScryfallCard | — | | size | ScryfallImageSize | 'normal' |

Returns string | undefined. Falls back to card_faces[0] for double-faced cards.

clearCache()

Empties the module-level name → card cache.

Caching & rate limiting

All fetched cards are cached in memory by lowercase name for the lifetime of the Node.js process. Subsequent calls for the same names skip the network entirely.

Batches are capped at 75 cards (the Scryfall /cards/collection endpoint limit). A 500 ms delay is inserted between batches to respect Scryfall's 2 req/sec rate limit. Network errors are swallowed per batch — callers receive partial results rather than a thrown error.

Building from source

npm run build      # compiles TypeScript → dist/
npm run typecheck  # type-check without emitting

License

MIT