scryfall-api 3.2.5 → 4.0.0-beta.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2022 Mario Menéndez
+Copyright (c) 2021-2024 MarioMH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,42 +1,93 @@
-# scryfall-api
+![banner.png](.idea%2Fbanner.png)
 
-[![npm](https://img.shields.io/npm/v/scryfall-api?style=flat-square)](https://www.npmjs.com/package/scryfall-api)
-[![GitHub issues](https://img.shields.io/github/issues/mariomh8/scryfall-api?style=flat-square)](https://github.com/MarioMH8/scryfall-api)
+<h1 align="center">
+  scryfall-api
+</h1>
 
-A Javascript library for [Scryfall](https://scryfall.com/docs/api) written in Typescript.
+<p align="center">
+  A Javascript library for <a href='https://scryfall.com/docs/api' target='_blank'>scryfall.com</a> written in Typescript.
+</p>
 
-As of [August 6th, 2022](./CHANGELOG.md), almost all features described in
-the [Scryfall documentation](https://scryfall.com/docs/api) are supported. If you see something that isn't supported,
-make an issue! See [support readme](./SUPPORT.md).
+<p align="center">
+    <a href="https://www.npmjs.com/package/scryfall-api" rel="nofollow">
+        <img src="https://camo.githubusercontent.com/a172c58fbefc7103cb230b872119a85914a463f32958ea9e4e1f3ad9d7e1a100/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f7363727966616c6c2d6170693f7374796c653d666c61742d737175617265" alt="npm" data-canonical-src="https://img.shields.io/npm/v/scryfall-api?style=flat-square" style="max-width: 100%;">
+    </a>
+    <a href="https://github.com/MarioMH8/scryfall-api">
+        <img src="https://camo.githubusercontent.com/93378eea577b6b00f04b1fbfa5dc6871778ff3f6b4de76833a6211d35770f6c4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6d6172696f6d68382f7363727966616c6c2d6170693f7374796c653d666c61742d737175617265" alt="GitHub issues" data-canonical-src="https://img.shields.io/github/issues/mariomh8/scryfall-api?style=flat-square" style="max-width: 100%;">
+    </a>
+</p>
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
 
 ## Installation
 
-```bat
-npm install scryfall-api
+```bash
+npm install --save scryfall-api
+```
+
+**Using bun**
+
+```bash
+bun add scryfall-api
 ```
 
 ## Documentation
 
-Link to [documentation.](./DOCUMENTATION.md)
+In the documentation below, requiring the package is assumed.
+
+```js
+import scryfall from 'scryfall-api';
+```
+
+
+**With CommonJS**
+
+```js
+const scryfall = require('scryfall-api');
+```
+
+**If you only need Cards**
+
+```js
+import { Cards } from 'scryfall-api';
+```
+
+Link to [full documentation.](./DOCUMENTATION.md)
 
 ## Contributing
 
+This project uses [Bun](https://bun.sh) as a runtime, test runner and bundler.
+
 Thanks for wanting to help out! Here's the setup you'll have to do:
 
-```bat
+Clone the project
+
+```bash
 git clone git@github.com:MarioMH8/scryfall-api.git
+```
+
+Go to the project directory
+
+```bash
 cd scryfall-api
-yarn install
 ```
 
-You can now make changes to the repository.
+Install dependencies
+
+```bash
+bun install
+```
 
-To compile:
+Compile the project
 
-```bat
-yarn build
+```bash
+bun run build
 ```
 
 ## MIT License
 
-[Copyright 2021-2022 Mario Menéndez](./LICENSE)
+[Copyright 2021-2024 MarioMH](./LICENSE)

package/dist/scryfall-api.cjs

@@ -0,0 +1,488 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/scryfall-api.ts
+var scryfall_api_exports = {};
+__export(scryfall_api_exports, {
+  CardIdentifierBuilder: () => card_identifier_default,
+  Cards: () => card_default,
+  Catalogs: () => catalog_default,
+  InvalidScryfallArgumentError: () => InvalidScryfallArgumentError,
+  MagicPageResult: () => MagicPageResult,
+  Rulings: () => ruling_default,
+  ScryfallError: () => ScryfallError,
+  Sets: () => set_default,
+  SymbologyApi: () => symbology_default,
+  UnknownScryfallError: () => UnknownScryfallError
+});
+module.exports = __toCommonJS(scryfall_api_exports);
+
+// src/error/invalid.error.ts
+var InvalidScryfallArgumentError = class extends Error {
+};
+
+// src/error/scryfall.error.ts
+var ScryfallError = class extends Error {
+  constructor(code, details, status, type, warnings) {
+    super(details);
+    this.code = code;
+    this.status = status;
+    this.type = type;
+    this.warnings = warnings;
+  }
+};
+
+// src/error/unknown.error.ts
+var UnknownScryfallError = class extends Error {
+};
+
+// src/fetcher/debounce.fetcher.ts
+var lastQuery = 100;
+var rateLimit = 100;
+async function sleep(ms = 0) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function debounce() {
+  const now = Date.now();
+  const timeSinceLastQuery = now - lastQuery;
+  if (timeSinceLastQuery >= rateLimit) {
+    lastQuery = now;
+  } else {
+    const timeUntilNextQuery = rateLimit - timeSinceLastQuery;
+    lastQuery += timeUntilNextQuery;
+    await sleep(timeUntilNextQuery);
+  }
+}
+function createDebounceFetcher(fetcher2 = fetch) {
+  return async function debounceFetcher(...args) {
+    await debounce();
+    return fetcher2(...args);
+  };
+}
+
+// src/fetcher/page.result.ts
+var MagicPageResult = class {
+  constructor(apiPath, query) {
+    this.apiPath = apiPath;
+    this.query = query;
+    this.#hasMore = true;
+    this.#count = 0;
+  }
+  #count;
+  #hasMore;
+  get count() {
+    return this.#count;
+  }
+  get hasMore() {
+    return this.#hasMore;
+  }
+  async all() {
+    const r = [];
+    while (this.#hasMore) {
+      const result = await this.next();
+      r.push(...result);
+    }
+    return r;
+  }
+  async get(limit) {
+    const r = [];
+    while (this.#hasMore) {
+      const result = await this.next();
+      r.push(...result);
+      if (r.length === limit) {
+        return r;
+      }
+      if (r.length > limit) {
+        return r.slice(0, limit);
+      }
+    }
+    return r;
+  }
+  async next() {
+    const results = await fetcher(this.apiPath, this.query);
+    this.#hasMore = results?.has_more ?? false;
+    this.#count = Number.parseInt(`${results?.total_cards ?? 0}`, 10);
+    if (this.#hasMore) {
+      this.setNextPage();
+    }
+    return results?.data ?? [];
+  }
+  async page(page) {
+    this.query.page = page;
+    return this.next();
+  }
+  setNextPage() {
+    this.query.page += 1;
+  }
+};
+
+// src/fetcher/retry.fetcher.ts
+var defaultCanRetry = async (response) => {
+  const object = await response.json();
+  const status = "status" in object ? Number(object.status) : void 0;
+  if (status && status >= 500) {
+    return true;
+  }
+  const code = "code" in object && typeof object.code === "string" ? object.code : void 0;
+  return code !== "not_found" && code !== "bad_request";
+};
+function createRetryFetcher({ maxAttempts = 3, canRetry = defaultCanRetry } = {}, fetcher2 = fetch) {
+  let retries = 0;
+  return async function retryFetcher(...args) {
+    retries++;
+    const response = await fetcher2(...args);
+    if (response.ok) {
+      return response;
+    }
+    const object = await response.json();
+    const code = "code" in object && typeof object.code === "string" ? object.code : void 0;
+    const status = "status" in object ? Number(object.status) : void 0;
+    const details = "details" in object && typeof object.details === "string" ? object.details : void 0;
+    const type = "type" in object && typeof object.type === "string" ? object.type : void 0;
+    const warnings = "warnings" in object && Array.isArray(object.warnings) ? object.warnings : void 0;
+    if (retries >= maxAttempts) {
+      if (code && details && status) {
+        throw new ScryfallError(code, details, status, type, warnings);
+      }
+      throw new UnknownScryfallError(`Request failed with status ${response.status}`);
+    }
+    if (canRetry(response)) {
+      return retryFetcher(...args);
+    }
+    if (code && details && status) {
+      throw new ScryfallError(code, details, status, type, warnings);
+    }
+    throw new UnknownScryfallError(`Request failed with status ${response.status}`);
+  };
+}
+
+// src/fetcher/index.ts
+var simpleFetcher = createDebounceFetcher(createRetryFetcher());
+var endpoint = "https://api.scryfall.com";
+var DATE_REGEXP = /^\d{4}-\d{2}-\d{2}?$/;
+var dateParser = (_key, value) => {
+  if (typeof value === "string") {
+    if (DATE_REGEXP.test(value)) {
+      return new Date(value);
+    }
+  }
+  return value;
+};
+async function fetcher(apiPath, params, body) {
+  let path = "";
+  if (typeof apiPath === "number" || typeof apiPath === "string") {
+    path = apiPath;
+  } else if (apiPath) {
+    path = apiPath.join("/");
+  }
+  const url = new URL(`${endpoint}/${path}`);
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== void 0) {
+        url.searchParams.append(key, `${value}`);
+      }
+    });
+  }
+  try {
+    const init = {
+      method: body ? "POST" : "GET"
+    };
+    if (body) {
+      init.body = JSON.stringify(body);
+      init.headers = {
+        "Content-Type": "application/json"
+      };
+    }
+    const response = await simpleFetcher(url, init);
+    const content = await response.text();
+    return JSON.parse(content, dateParser);
+  } catch (e) {
+    if (e instanceof ScryfallError) {
+      if (e.warnings) {
+        console.warn(e.warnings);
+      }
+      if (e.code === "not_found" || e.code === "bad_request") {
+        return void 0;
+      }
+    }
+    throw e;
+  }
+}
+
+// src/api/card/card.api.ts
+var CardApi = class {
+  /*
+   * Returns up to 20 full English card names that could be autocompletions of the given string parameter.
+   * @param {string} name
+   * 	The string to search for
+   * @returns {Promise<string[]>}
+   * 	A list of up to 20 full English card names.
+   */
+  async autoCompleteName(name) {
+    const result = await fetcher("cards/autocomplete", {
+      q: name
+    });
+    return result?.data ?? [];
+  }
+  /*
+   * Returns a single card with the given Magic: The Gathering Arena ID.
+   * @param {number} id
+   * 	The Magic: The Gathering Arena ID of the card to retrieve.
+   * @returns {Promise<Card | undefined>}
+   * 	Returns a single card or undefined if no card is found.
+   */
+  async byArenaId(id) {
+    return fetcher(["cards/arena", id]);
+  }
+  /*
+   * Returns a single card with the given Scryfall ID.
+   * @param {number} id
+   * 	The Scryfall ID.
+   * @returns {Promise<Card | undefined>}
+   * 	Returns a single card or undefined if no card is found.
+   */
+  async byId(id) {
+    return fetcher(["cards", id]);
+  }
+  async byMtgoId(id) {
+    return fetcher(["cards/mtgo", id]);
+  }
+  async byMultiverseId(id) {
+    return fetcher(["cards/multiverse", id]);
+  }
+  async byName(name, set2, fuzzy = false) {
+    let f = fuzzy;
+    let s = set2;
+    if (typeof set2 === "boolean") {
+      f = set2;
+      s = void 0;
+    }
+    return fetcher("cards/named", {
+      [f ? "fuzzy" : "exact"]: name,
+      set: s
+    });
+  }
+  async bySet(setCode, collectorNumber, lang) {
+    const path = ["cards", setCode, collectorNumber];
+    if (lang) {
+      path.push(lang);
+    }
+    return fetcher(path);
+  }
+  async byTcgPlayerId(id) {
+    return fetcher(["cards/tcgplayer", id]);
+  }
+  async collection(...identifiers) {
+    const cards2 = [];
+    for (let i = 0; i < identifiers.length; i += 75) {
+      const collectionSection = { identifiers: identifiers.slice(i, i + 75) };
+      const result = await fetcher(
+        "cards/collection",
+        void 0,
+        collectionSection
+      );
+      cards2.push(...result?.data ?? []);
+    }
+    return cards2;
+  }
+  async random() {
+    return fetcher("cards/random");
+  }
+  search(query, options) {
+    return new MagicPageResult("cards/search", {
+      q: query,
+      ...typeof options === "number" ? { page: options } : { ...options, page: options?.page ?? 1 }
+    });
+  }
+};
+var cards = new CardApi();
+var card_api_default = cards;
+
+// src/api/card/index.ts
+var card_default = card_api_default;
+
+// src/api/card-identifier/card-identifier.api.ts
+var CardIdentifierApi = class {
+  static byId(id) {
+    return { id };
+  }
+  static byIllustrationId(id) {
+    return { illustration_id: id };
+  }
+  static byMtgoId(id) {
+    return { mtgo_id: id };
+  }
+  static byMultiverseId(id) {
+    return { multiverse_id: id };
+  }
+  static byName(name, set2) {
+    if (set2) {
+      return { name, set: set2 };
+    }
+    return { name };
+  }
+  static byOracleId(id) {
+    return { oracle_id: id };
+  }
+  static bySet(set2, collectorNumber) {
+    return { collector_number: `${collectorNumber}`, set: set2 };
+  }
+};
+
+// src/api/card-identifier/index.ts
+var card_identifier_default = CardIdentifierApi;
+
+// src/api/catalog/catalog.api.ts
+var CatalogApi = class {
+  async artifactTypes() {
+    return (await fetcher("catalog/artifact-types"))?.data ?? [];
+  }
+  async artistNames() {
+    return (await fetcher("catalog/artist-names"))?.data ?? [];
+  }
+  async cardNames() {
+    return (await fetcher("catalog/card-names"))?.data ?? [];
+  }
+  async creatureTypes() {
+    return (await fetcher("catalog/creature-types"))?.data ?? [];
+  }
+  async enchantmentTypes() {
+    return (await fetcher("catalog/enchantment-types"))?.data ?? [];
+  }
+  async landTypes() {
+    return (await fetcher("catalog/land-types"))?.data ?? [];
+  }
+  async loyalties() {
+    return (await fetcher("catalog/loyalties"))?.data ?? [];
+  }
+  async planeswalkerTypes() {
+    return (await fetcher("catalog/planeswalker-types"))?.data ?? [];
+  }
+  async powers() {
+    return (await fetcher("catalog/powers"))?.data ?? [];
+  }
+  async spellTypes() {
+    return (await fetcher("catalog/spell-types"))?.data ?? [];
+  }
+  async toughnesses() {
+    return (await fetcher("catalog/toughnesses"))?.data ?? [];
+  }
+  async watermarks() {
+    return (await fetcher("catalog/watermarks"))?.data ?? [];
+  }
+  async wordBank() {
+    return (await fetcher("catalog/word-bank"))?.data ?? [];
+  }
+};
+var catalog = new CatalogApi();
+var catalog_api_default = catalog;
+
+// src/api/catalog/index.ts
+var catalog_default = catalog_api_default;
+
+// src/api/ruling/ruling.api.ts
+var RulingApi = class {
+  async byArenaId(id) {
+    return (await fetcher(["cards/arena", id, "rulings"]))?.data ?? [];
+  }
+  async byId(id) {
+    return (await fetcher(["cards", id, "rulings"]))?.data ?? [];
+  }
+  async byMtgoId(id) {
+    return (await fetcher(["cards/mtgo", id, "rulings"]))?.data ?? [];
+  }
+  async byMultiverseId(id) {
+    return (await fetcher(["cards/multiverse", id, "rulings"]))?.data ?? [];
+  }
+  async bySet(setCode, collectorNumber) {
+    return (await fetcher(["cards", setCode, `${collectorNumber}`, "rulings"]))?.data ?? [];
+  }
+};
+var rulings = new RulingApi();
+var ruling_api_default = rulings;
+
+// src/api/ruling/index.ts
+var ruling_default = ruling_api_default;
+
+// src/api/set/set.api.ts
+var SetApi = class {
+  async all() {
+    const result = await fetcher("sets");
+    return result?.data ?? [];
+  }
+  async byCode(code) {
+    return await fetcher(["sets", code]);
+  }
+  async byId(id) {
+    return fetcher(["sets", id]);
+  }
+  async byTcgPlayerId(id) {
+    return fetcher(["sets/tcgplayer", id]);
+  }
+};
+var set = new SetApi();
+var set_api_default = set;
+
+// src/api/set/index.ts
+var set_default = set_api_default;
+
+// src/api/symbology/symbology.api.ts
+var SymbologyApi = class {
+  async all() {
+    const list = await fetcher("symbology");
+    return list?.data ?? [];
+  }
+  async parseMana(shorthand) {
+    if (!shorthand || typeof shorthand !== "string") {
+      throw new InvalidScryfallArgumentError("shorthand must be a string");
+    }
+    const cost = await fetcher("symbology/parse-mana", {
+      cost: shorthand
+    });
+    return cost ?? {
+      cost: "",
+      colors: [],
+      cmc: 0,
+      colorless: false,
+      monocolored: false,
+      multicolored: false,
+      object: "mana_cost"
+    };
+  }
+};
+var symbology = new SymbologyApi();
+var symbology_api_default = symbology;
+
+// src/api/symbology/index.ts
+var symbology_default = symbology_api_default;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CardIdentifierBuilder,
+  Cards,
+  Catalogs,
+  InvalidScryfallArgumentError,
+  MagicPageResult,
+  Rulings,
+  ScryfallError,
+  Sets,
+  SymbologyApi,
+  UnknownScryfallError
+});