# Magic: The Gathering Elixir SDK

Elixir SDK for using the [magicthegathering.io](http://magicthegathering.io) APIs.

Note that API use is free and does not require authentication or registration, but some rate limits apply. [Read the official API website for more information](https://docs.magicthegathering.io/#documentationrate_limits).

Add the dependency to your project and you're good to go!

## Installation

This package can be installed by adding `mtg_sdk_elixir` to your list of dependencies in
`mix.exs`:

```elixir
def deps do
  [{:mtg_sdk_elixir, "~> 1.0.0"}]
end
```

Now you are ready to start calling MTG API.

## Usage examples

### Cards

#### Get all cards with default values (pageSize = 100, page = 0)
```elixir
iex> Mtg.list(Card)
{:ok,
 %Mtg.Response.Collection{
   count: 100,
   data: [
     %Mtg.Card{
       ...
       rarity: "Rare",
       ...
       set_name: "Tenth Edition",
       name: "Abundance",
       ...
       foreign_names: [
         %Mtg.Card.ForeignName{
           flavor: nil,
           image_url: "http://gatherer.wizards.com/Handlers/Image.ashx?multiverseid=148402&type=card",
           language: "German",
           multiverseid: 148402,
           name: "Überfluss",
           text: "Falls du eine Karte ziehen würdest, kannst du stattdessen Land oder Nichtland bestimmen und Karten oben von deiner Bibliothek aufdecken, bis du eine Karte der bestimmten Art aufdeckst. Nimm diese Karte auf deine Hand und lege alle anderen auf diese Weise aufgedeckten Karten in beliebiger Reihenfolge unter deine Bibliothek."
         },
         ...
       },
       ...
       rulings: [
         %Mtg.Card.Ruling{
           date: "2004-10-04",
           text: "This replacement effect replaces the draw, so nothing that triggers on a draw will trigger."
         },
         ...
       ],
       id: "1669af17-d287-5094-b005-4b143441442f",
       legalities: [
         %Mtg.Card.Legality{format: "Commander", legality: "Legal"},
         ...
       ],
       watermark: nil
     },
     ...
   ],
   page_size: 100,
   total_count: 45846,
   type: "cards"
 }}
```

#### Get all cards with filters (name = "Abundance")
```elixir
iex> Mtg.list(Card)
{:ok,
 %Mtg.Response.Collection{
   count: 6,
   data: [
     %Mtg.Card{...},
     ...
   ],
   page_size: 100,
   total_count: 6,
   type: "cards"
 }}
```

#### Get all cards with OR filters (name = "Abundance" OR name = "Tarmogoyf")
```elixir
iex> Mtg.list(Card, [{:name, :or, ["Abundance", "Tarmogoyf"]}])
{:ok,
 %Mtg.Response.Collection{
   count: 12,
   data: [
     %Mtg.Card{...},
     ...
   ],
   page_size: 100,
   total_count: 12,
   type: "cards"
 }}
```

#### Get all cards with AND filters (name = "Abu" AND name = "dance")
```elixir
iex> Mtg.list(Card, [{:name, :and, ["Abu", "dance"]}])
{:ok,
 %Mtg.Response.Collection{
   count: 6,
   data: [
     %Mtg.Card{...},
     ...
   ],
   page_size: 100,
   total_count: 6,
   type: "cards"
 }}
```

For more query filters, visit [https://docs.magicthegathering.io/#api_v1cards_list](https://docs.magicthegathering.io/#api_v1cards_list).

#### Get card
```elixir
iex> Mtg.show(Card, 1)
{:ok,
 %Mtg.Card{
  ...
 }}
```

### Sets

#### Get all sets with default values (pageSize = 500, page = 0)
```elixir
iex> Mtg.list(Set)
{:ok,
 %Mtg.Response.Collection{
   count: 448,
   data: [
     %Mtg.Set{
       block: "Core Set",
       booster: ["rare", "uncommon", "uncommon", "uncommon", "common", "common",
        "common", "common", "common", "common", "common", "common", "common",
        "common", "land", "marketing"],
       border: nil,
       code: "10E",
       gatherer_code: nil,
       magic_cards_info_code: nil,
       mkm_id: nil,
       mkm_name: nil,
       name: "Tenth Edition",
       old_code: nil,
       online_only: false,
       release_date: ~D[2007-07-13],
       type: "core"
     },
     ...
   ],
   page_size: 500,
   total_count: 448,
   type: "sets"
 }}
```

#### Get all sets with filters (block = "com")
```elixir
iex> Mtg.list(Set)
{:ok,
 %Mtg.Response.Collection{
   count: 19,
   data: [
     %Mtg.Set{...},
     ...
   ],
   page_size: 500,
   total_count: 19,
   type: "sets"
 }}
```

#### Get all cards with OR filters (block = "com" OR block = "black")
```elixir
iex> Mtg.list(Set, [{:block, :or, ["com", "black"]}])
{:ok,
 %Mtg.Response.Collection{
   count: 40,
   data: [
     %Mtg.Set{...},
     ...
   ],
   page_size: 500,
   total_count: 40,
   type: "sets"
 }}
```

For more query filters, visit [https://docs.magicthegathering.io/#api_v1sets_list](https://docs.magicthegathering.io/#api_v1sets_list).

#### Get set
```elixir
iex> Mtg.show(Set, "ktk")
{:ok,
 %Mtg.Set{
  ...
 }}
```

#### Get set booster
```elixir
iex> Mtg.generate_set_booster("ktk")
{:ok,
 %Mtg.Collection{
  count: nil,
   data: [
     %Mtg.Card{...},
     ...
   ],
   page_size: nil,
   total_count: nil,
   type: "cards"
 }}
```

### Type

#### Get types

```elixir
iex> Mtg.list(Type)
{:ok,
 ["Artifact", "Card", "Conspiracy", "Creature", "Emblem", "Enchantment", "Hero",
  "instant", "Instant", "Land", "Phenomenon", "Plane", "Planeswalker", "Scheme",
  "Sorcery", "Summon", "Tribal", "Vanguard", "You’ll"]}
```

### Subtype

#### Get subtypes

```elixir
iex> Mtg.list(Subtype)
{:ok,
 ["Advisor", "Aetherborn", "Ajani", "Alara", "Ally", "Aminatou", "and/or",
  "Angel", "Angrath", "Antelope", "Ape", "Arcane", "Archer", "Archon", "Arkhos",
  "Arlinn", "Artificer", "Ashiok", "Assassin", "Assembly-Worker", "Atog",
  "Aura", "Aurochs", "Autobot", "Avatar", "Azgol", "Azra", "Baddest,", "Badger",
  "Barbarian", "Basilisk", "Bat", "Bear", "Beast", "Beaver", "Beeble",
  "Belenon", "Berserker", "Biggest,", "Bird", "Boar", "Bolas", "Bolas’s",
  "Brainiac", "Bringer", "Brushwagg", "Bureaucrat", "Camel", ...]}
```

### Supertype

#### Get supertypes

```elixir
iex> Mtg.list(Supertype)
{:ok,
 ["Basic", "Host", "Legendary", "Ongoing", "Snow", "World"]}
```

### Format

#### Get formats

```elixir
iex> Mtg.list(Format)
{:ok,
 ["Commander", "Duel", "Frontier", "Future", "Legacy", "Modern", "Oldschool",
  "Pauper", "Penny", "Standard", "Vintage"]}
```