npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tutor

v0.8.0

Published

Interface for Gatherer, the Magic: The Gathering card database

Downloads

13

Readme

Build Status

Gatherer is the canonical source for Magic: The Gathering card details. While useful, it lacks an interface for retrieving this data programmatically. The lack of an API makes creating Magic-related applications unnecessarily difficult.

Tutor is a simple JavaScript interface for Gatherer.

API

tutor.card

tutor.card(id, callback(err, card))
tutor.card(name, callback(err, card))
tutor.card(details, callback(err, card))

The first and second forms are shorthand for tutor.card({id: id}, ...) and tutor.card({name: name}, ...) respectively. The callback is passed an object representing the specified card. Version-specific metadata such as flavor text and rarity are included for cards specified by id. Attributes not applicable to the card type (e.g. lands have no mana cost) or not present (e.g. certain creatures have no rules text) are omitted.

tutor.card 'Demonic Tutor', (err, card) ->
  console.log card.name
  # => "Demonic Tutor"
  console.log card.mana_cost
  # => "{1}{B}"
  console.log card.text
  # => "Search your library for a card and put that card into your hand. Then shuffle your library."

Split cards

Because the two sides of a split card share a Gatherer id, it's necessary to provide the name of the desired side:

tutor.card id: 27165, name: 'Fire', (err, card) ->
  console.log card.name
  # => "Fire"

tutor.card id: 27165, name: 'Ice', (err, card) ->
  console.log card.name
  # => "Ice"

Retrieving either side of a split card by name is straightforward:

tutor.card 'Fire', (err, card) ->
  console.log card.name
  # => "Fire"

tutor.card 'Ice', (err, card) ->
  console.log card.name
  # => "Ice"

Flip cards

Retrieving the top half of a flip card by id is straightforward:

tutor.card 247175, (err, card) ->
  console.log card.name
  # => "Nezumi Graverobber"

Either half of a flip card can be retrieved explicitly by setting which to "a" (for the upper half) or "b" (for the lower half):

tutor.card id: 247175, which: 'b', (err, card) ->
  console.log card.name
  # => "Nighteyes the Desecrator"

When retrieving a flip card by name rather than id, one may simply provide the name of the desired half:

tutor.card 'Nighteyes the Desecrator', (err, card) ->
  console.log card.name
  # => "Nighteyes the Desecrator"

Double-faced cards

Either face of a double-faced card can be retrieved by id:

tutor.card 262675, (err, card) ->
  console.log card.name
  # => "Afflicted Deserter"

tutor.card 262698, (err, card) ->
  console.log card.name
  # => "Werewolf Ransacker"

Or by name:

tutor.card 'Afflicted Deserter', (err, card) ->
  console.log card.name
  # => "Afflicted Deserter"

tutor.card 'Werewolf Ransacker', (err, card) ->
  console.log card.name
  # => "Werewolf Ransacker"

tutor.set

tutor.set(name, callback(err, set))

Scrape cards from the set specified by name. For example:

tutor.set 'Homelands', (err, cards) ->
  console.log cards.length
  # => 115
  console.log Object.keys(cards[0]).sort()
  # => [
  #   "converted_mana_cost",
  #   "expansion",
  #   "gatherer_url",
  #   "image_url",
  #   "mana_cost",
  #   "name",
  #   "power",
  #   "rarity",
  #   "subtypes",
  #   "supertypes",
  #   "text",
  #   "toughness",
  #   "types",
  #   "versions"
  # ]

tutor.formats

tutor.formats(callback(err, formatNames))

Provides the names of all the game's formats:

tutor.formats (err, formatNames) ->
  console.log formatNames
  # => [
  #   "Classic",
  #   "Commander",
  #   ...
  #   "Vintage",
  #   "Zendikar Block"
  # ]

tutor.sets

tutor.sets(callback(err, setNames))

Provides the names of all the game's sets:

tutor.sets (err, setNames) ->
  console.log setNames
  # => [
  #   "Alara Reborn",
  #   "Alliances",
  #   ...
  #   "Worldwake",
  #   "Zendikar"
  # ]

tutor.types

tutor.types(callback(err, types))

Provides the names of all the game's types:

tutor.types (err, types) ->
  console.log types
  # => [
  #   "Artifact",
  #   "Basic",
  #   ...
  #   "Vanguard",
  #   "World"
  # ]

CLI

npm install tutor --global will make the tutor command available globally.

$ tutor card 'Demonic Tutor'
Demonic Tutor {1}{B} Search your library for a card and put that card into your hand. Then shuffle your library.

$ tutor card 'Demonic Tutor' --format json | python -mjson.tool | head -n 10
{
    "community_rating": {
        "rating": 4.714,
        "votes": 229
    },
    "converted_mana_cost": 2,
    "languages": {},
    "legality": {
        "Commander": "Legal",
        "Legacy": "Banned",

$ tutor card 60 --format json | python -mjson.tool | head -n 10
{
    "artist": "Douglas Schuler",
    "community_rating": {
        "rating": 4.917,
        "votes": 109
    },
    "converted_mana_cost": 2,
    "expansion": "Limited Edition Alpha",
    "languages": {},
    "legality": {

$ tutor set Alliances | head -n 2
Aesthir Glider {3} 2/1 Flying Aesthir Glider can't block.
Agent of Stromgald {R} 1/1 {R}: Add {B} to your mana pool.

Example of using the CLI from other applications:

Link to Wiki

Running the tests

make fixtures
make test
make testcli