scryfall-scry

scry

Single function client for the Scryfall API, adhering to the usage guidelines for request spacing and caching.

Usage

import * as redis from 'redis'
import scry from 'scry'
 
scry.configure({ redisClient: redis.createClient() })
 
scry('/cards/named?exact=grizzly+bears') // Promise<https://scryfall.com/docs/api/cards>
  .then((bears) => {
    console.log(`${bears.name} is a ${bears.power}/${bears.toughness} ${bears.type_line}.`)
  })
  .catch((err) => {
    console.error(err)
  })

You must call scry.configure(...) providing either a Redis client object (for default cache implementation) or your own cache implementation. configure only needs to be called once, at the entry point of your application, since the scry function is a shared singleton by design (in order to enforce global cache usage + rate limits).

For successful searches the promise will resolve with a JS object as documented in the Scryfall API docs. Responses with HTTP error codes (including searches that don't match any results) will reject the promise with an AxiosError.

Typescript types for Scryfall API objects are not provided^yet. If you want to specify a type for your expected response, you can do so using scry<MyType>(...), or verify responses with something like io-ts.

The full selection of configuration options is shown below:

scry.configure({
  redisClient,
  // OR
  cache,
 
  requestSpaceMilliseconds: 50 // Number of millis to leave between requests. The Scryfall API usage guidelines request at least 50ms.
  cachePrefix: '' // Prefix to apply to all cache keys. Useful if the redis instance is shared .
  cacheDurationSeconds: 24 * 60 * 60 // How long objects should be cached in seconds. The Scryfall API usage guidelines request at least a day.
})

Custom cache implementations must match the following type (which is exported):

export type Cache = {
  get: (key: string) => Promise<string | null>
  set: (key: string, value: string, cacheDurationSeconds: number) => Promise<void>
}

The default cache implementation simply wraps the provided Redis client's get/set methods, using Redis's built-in cache expiry (i.e. SET key value EX duration).