cards

Functions for calling Scryfall’s Cards endpoints.

Each function builds its request with scruffy/client/request and sends it with the client.Requester you provide, so what comes back is already the decoded object – or a client.ClientError describing what went wrong. Call new once with your Requester to get a Client back with all of them already wired up, if you’d rather not pass one at every call site.

See https://scryfall.com/docs/api/cards for the upstream reference.

Types

CardCollection

</>

The response to a get_card_collection request: the cards that were found, plus any identifiers that couldn’t be matched to a card.

pub type CardCollection {
  CardCollection(
    data: List(card.Card),
    not_found: List(CardIdentifier),
  )
}

Constructors

CardCollection(
  data: List(card.Card),
  not_found: List(CardIdentifier),
)

CardIdentifier

</>

A way of identifying a single card within a get_card_collection request.

pub type CardIdentifier {
  IdentifierById(String)
  IdentifierByMtgoId(Int)
  IdentifierByMultiverseId(Int)
  IdentifierByOracleId(String)
  IdentifierByIllustrationId(String)
  IdentifierByName(String)
  IdentifierByNameAndSet(name: String, set: String)
  IdentifierByCollectorNumber(
    set: String,
    collector_number: String,
  )
}

Constructors

```
IdentifierById(String)
```
```
IdentifierByMtgoId(Int)
```
```
IdentifierByMultiverseId(Int)
```
```
IdentifierByOracleId(String)
```
```
IdentifierByIllustrationId(String)
```
```
IdentifierByName(String)
```

IdentifierByNameAndSet(name: String, set: String)

IdentifierByCollectorNumber(
  set: String,
  collector_number: String,
)

Client

</>

Every function above, already wired up to a Requester – see new.

pub type Client(e) {
  Client(
    get_cards_manifest: fn() -> Result(
      scryfall_list.ScryfallList(card.Card),
      client.ClientError(e),
    ),
    search_cards: fn(String, SearchOptions) -> Result(
      scryfall_list.ScryfallList(card.Card),
      client.ClientError(e),
    ),
    get_card_by_name: fn(NameQuery, option.Option(String)) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    autocomplete_card_name: fn(String, option.Option(Bool)) -> Result(
      catalog.Catalog(String),
      client.ClientError(e),
    ),
    get_random_card: fn(option.Option(String)) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_collection: fn(List(CardIdentifier)) -> Result(
      CardCollection,
      client.ClientError(e),
    ),
    get_card_by_set_and_number: fn(
      String,
      String,
      option.Option(language.Language),
    ) -> Result(card.Card, client.ClientError(e)),
    get_card_by_multiverse_id: fn(Int) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_by_mtgo_id: fn(Int) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_by_arena_id: fn(Int) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_by_tcgplayer_id: fn(Int) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_by_cardmarket_id: fn(Int) -> Result(
      card.Card,
      client.ClientError(e),
    ),
    get_card_by_id: fn(String) -> Result(
      card.Card,
      client.ClientError(e),
    ),
  )
}

Constructors

Client(
  get_cards_manifest: fn() -> Result(
    scryfall_list.ScryfallList(card.Card),
    client.ClientError(e),
  ),
  search_cards: fn(String, SearchOptions) -> Result(
    scryfall_list.ScryfallList(card.Card),
    client.ClientError(e),
  ),
  get_card_by_name: fn(NameQuery, option.Option(String)) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  autocomplete_card_name: fn(String, option.Option(Bool)) -> Result(
    catalog.Catalog(String),
    client.ClientError(e),
  ),
  get_random_card: fn(option.Option(String)) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_collection: fn(List(CardIdentifier)) -> Result(
    CardCollection,
    client.ClientError(e),
  ),
  get_card_by_set_and_number: fn(
    String,
    String,
    option.Option(language.Language),
  ) -> Result(card.Card, client.ClientError(e)),
  get_card_by_multiverse_id: fn(Int) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_by_mtgo_id: fn(Int) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_by_arena_id: fn(Int) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_by_tcgplayer_id: fn(Int) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_by_cardmarket_id: fn(Int) -> Result(
    card.Card,
    client.ClientError(e),
  ),
  get_card_by_id: fn(String) -> Result(
    card.Card,
    client.ClientError(e),
  ),
)

NameQuery

</>

A way of identifying a card by name, either exactly or through Scryfall’s fuzzy-matching algorithm.

pub type NameQuery {
  Exact(String)
  Fuzzy(String)
}

Constructors

```
Exact(String)
```
```
Fuzzy(String)
```

SearchOptions

</>

Optional parameters accepted by search_cards.

pub type SearchOptions {
  SearchOptions(
    unique: option.Option(UniqueMode),
    order: option.Option(SortOrder),
    dir: option.Option(SortDirection),
    include_extras: option.Option(Bool),
    include_multilingual: option.Option(Bool),
    include_variations: option.Option(Bool),
    page: option.Option(Int),
  )
}

Constructors

SearchOptions(
  unique: option.Option(UniqueMode),
  order: option.Option(SortOrder),
  dir: option.Option(SortDirection),
  include_extras: option.Option(Bool),
  include_multilingual: option.Option(Bool),
  include_variations: option.Option(Bool),
  page: option.Option(Int),
)

SortDirection

</>

The direction search_cards results are sorted in.

pub type SortDirection {
  Auto
  Ascending
  Descending
}

Constructors

```
Auto
```
```
Ascending
```
```
Descending
```

SortOrder

</>

The field search_cards results are sorted by.

pub type SortOrder {
  ByName
  BySet
  ByReleased
  ByRarity
  ByColor
  ByUsd
  ByTix
  ByEur
  ByCmc
  ByPower
  ByToughness
  ByEdhrec
  ByPenny
  ByArtist
  ByReview
}

Constructors

```
ByName
```
```
BySet
```
```
ByReleased
```
```
ByRarity
```
```
ByColor
```
```
ByUsd
```
```
ByTix
```
```
ByEur
```
```
ByCmc
```
```
ByPower
```
```
ByToughness
```
```
ByEdhrec
```
```
ByPenny
```
```
ByArtist
```
```
ByReview
```

UniqueMode

</>

How cards with multiple versions should be collapsed by search_cards.

pub type UniqueMode {
  UniqueCards
  UniqueArt
  UniquePrints
}

Constructors

```
UniqueCards
```
```
UniqueArt
```
```
UniquePrints
```

Values

autocomplete_card_name

</>

pub fn autocomplete_card_name(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  q: String,
  include_extras: option.Option(Bool),
) -> Result(catalog.Catalog(String), client.ClientError(e))

Get a Catalog of Magic-related word fragments that can be used as the start of a full card name, for use in a typeahead search bar.

card_collection_schema

</>

pub fn card_collection_schema() -> glon.JsonSchema(CardCollection)

get_card_by_arena_id

</>

pub fn get_card_by_arena_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: Int,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its MTG Arena ID.

get_card_by_cardmarket_id

</>

pub fn get_card_by_cardmarket_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: Int,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its Cardmarket product ID.

get_card_by_id

</>

pub fn get_card_by_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: String,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its Scryfall ID.

get_card_by_mtgo_id

</>

pub fn get_card_by_mtgo_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: Int,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its Magic Online ID.

get_card_by_multiverse_id

</>

pub fn get_card_by_multiverse_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: Int,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its multiverse ID, as assigned by Wizards’ Gatherer.

get_card_by_name

</>

pub fn get_card_by_name(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  query: NameQuery,
  set: option.Option(String),
) -> Result(card.Card, client.ClientError(e))

Get a single card by name, optionally scoped to a particular set.

get_card_by_set_and_number

</>

pub fn get_card_by_set_and_number(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  set: String,
  collector_number: String,
  lang: option.Option(language.Language),
) -> Result(card.Card, client.ClientError(e))

Get a single card by its set code, collector number, and (optionally) a specific language.

get_card_by_tcgplayer_id

</>

pub fn get_card_by_tcgplayer_id(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  id: Int,
) -> Result(card.Card, client.ClientError(e))

Get a single card by its TCGplayer product ID.

get_card_collection

</>

pub fn get_card_collection(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  identifiers: List(CardIdentifier),
) -> Result(CardCollection, client.ClientError(e))

Get a list of up to 75 cards at once, identified in bulk by ID, name, or set/collector number.

get_cards_manifest

</>

pub fn get_cards_manifest(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
) -> Result(
  scryfall_list.ScryfallList(card.Card),
  client.ClientError(e),
)

Get a lightweight manifest of every card Scryfall has on file.

get_random_card

</>

pub fn get_random_card(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  q: option.Option(String),
) -> Result(card.Card, client.ClientError(e))

Get a random card, optionally scoped to cards matching a search query.

new

</>

pub fn new(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
) -> Client(e)

Build a Client bound to the given Requester, so you don’t have to pass one to every call: let cards = cards.new(httpc.send) then cards.get_card_by_id(id).

search_cards

</>

pub fn search_cards(
  requester: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  q: String,
  options: SearchOptions,
) -> Result(
  scryfall_list.ScryfallList(card.Card),
  client.ClientError(e),
)

Search for cards using Scryfall’s full-text search syntax.