scruffy

A Gleam client for the Scryfall Magic: The Gathering API.

Status

scruffy provides Gleam types for the objects the Scryfall API returns (cards, sets, rulings, symbols, and more) under scruffy/*, along with a Glon *_schema() decoder for each one – e.g. card.card_schema() turns a card JSON string into a Card via glon.decode(card.card_schema(), from: json).

On top of that, scruffy/client/* gives you a pair of plain functions for every Scryfall endpoint: a *_request that builds the Request(String) to send, and a *_response that decodes the Response(String) you got back into the object you asked for, or a scruffy/client.ClientError describing what went wrong.

Installation

gleam add scruffy@1

Usage

scruffy never picks an HTTP client for you. Build a request with a *_request function, send it with whatever HTTP client suits your project, and decode the response with the matching *_response function. On Erlang, that HTTP client can be gleam_httpc’s send:

import gleam/httpc
import gleam/io
import gleam/result
import scruffy/client
import scruffy/client/cards

pub fn main() -> Nil {
  let result = {
    use resp <- result.try(
      cards.get_card_by_id_request("bd8fa327-dd41-4737-8f19-2cf5eb1f7cdd")
      |> httpc.send,
    )
    cards.card_response(resp)
  }

  case result {
    Ok(card) -> io.println(card.name)
    Error(client.ApiError(err)) -> io.println("Scryfall said: " <> err.details)
    Error(_) -> io.println("Something else went wrong")
  }
}

The same two functions work with a Promise-based client too (e.g. gleam_fetch on the JavaScript target) – just await the response between them:

use resp <- promise.try_await(fetch.send(cards.get_card_by_id_request(id)))
use resp <- promise.try_await(fetch.read_text_body(resp))
promise.resolve(cards.card_response(resp))

Further documentation can be found at https://hexdocs.pm/scruffy.

Development

gleam test    # Run the tests. The integration suite (test/scruffy_integration_test.gleam)
              # calls the live Scryfall API via gleam_httpc, so it needs network access and
              # only runs on the Erlang target -- `gleam test --target javascript` skips it.
gleam format  # Format the source