scryfall-api 0.0.0-beta-20261103181737

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2026 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+![banner.png](.idea%2Fbanner.png)
+
+<h1 align="center">
+  scryfall-api
+</h1>
+
+<p align="center">
+  A Javascript library for <a href='https://scryfall.com/docs/api' target='_blank'>scryfall.com</a> written in Typescript.
+</p>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/scryfall-api" rel="nofollow">
+        <img src="https://img.shields.io/npm/v/scryfall-api?style=flat-square" alt="npm" style="max-width: 100%;">
+    </a>
+    <a href="https://github.com/MarioMH8/scryfall-api">
+        <img src="https://img.shields.io/github/issues/mariomh8/scryfall-api?style=flat-square" alt="GitHub issues" style="max-width: 100%;">
+    </a>
+</p>
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+
+## Installation
+
+```bash
+npm install --save scryfall-api
+```
+
+**Using bun**
+
+```bash
+bun add scryfall-api
+```
+
+## Documentation
+
+In the documentation below, requiring the package is assumed.
+
+```ts
+import scryfall from 'scryfall-api';
+
+scryfall.Cards.byName('Black Lotus').then(console.log);
+```
+
+**With CommonJS**
+
+```js
+const scryfall = require('scryfall-api');
+
+scryfall.Cards.byName('Black Lotus').then(console.log);
+```
+
+**If you only need Cards**
+
+```ts
+import { Cards } from 'scryfall-api';
+
+Cards.byName('Black Lotus').then(console.log);
+```
+
+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:
+
+Clone the project
+
+```bash
+git clone git@github.com:MarioMH8/scryfall-api.git
+```
+
+Go to the project directory
+
+```bash
+cd scryfall-api
+```
+
+Install dependencies
+
+```bash
+bun install
+```
+
+Compile the project
+
+```bash
+bun run build
+```
+
+You can read the full [contribution](./CONTRIBUTING.md) guidelines.
+
+## MIT License
+
+[Copyright 2021-2026 MarioMH](./LICENSE)

package/dist/scryfall-api.d.mts

@@ -0,0 +1,447 @@
+type TOrArrayOfT<T> = T | T[];
+/**
+ * Type definition for Nullable.
+ * @type {T | null | undefined} The type can be T, null, or undefined.
+ * @template T The type of the value that can be null or undefined.
+ */
+type Nullable<T> = null | T | undefined;
+type ParameterValue = boolean | number | string | undefined;
+type FetcherParameters = Record<string, ParameterValue>;
+type TFetcher = <TData>(apiPath: TOrArrayOfT<number | string | undefined>, parameters?: FetcherParameters, body?: object) => Promise<TData | undefined>;
+type QueryValue = boolean | number | string | undefined;
+interface PageQuery {
+  [key: string]: QueryValue;
+  page: number;
+}
+declare class MagicPageResult<T> {
+  #private;
+  private readonly apiPath;
+  private readonly query;
+  private readonly fetcher;
+  constructor(apiPath: string, query: PageQuery, fetcher?: TFetcher);
+  get count(): number;
+  get hasMore(): boolean;
+  all(): Promise<T[]>;
+  get(limit: number): Promise<T[]>;
+  next(): Promise<T[]>;
+  page(page: number): Promise<T[]>;
+  private setNextPage;
+}
+interface CardIdentifierId {
+  id: string;
+}
+interface CardIdentifierIllustrationId {
+  illustration_id: string;
+}
+interface CardIdentifierMtgGoId {
+  mtgo_id: number;
+}
+interface CardIdentifierMultiverseId {
+  multiverse_id: number;
+}
+interface CardIdentifierNameSet {
+  name: string;
+  set?: string;
+}
+interface CardIdentifierOracleId {
+  oracle_id: string;
+}
+interface CardIdentifierCollectorSet {
+  collector_number: string;
+  set: string;
+}
+type CardIdentifier = CardIdentifierCollectorSet | CardIdentifierId | CardIdentifierIllustrationId | CardIdentifierMtgGoId | CardIdentifierMultiverseId | CardIdentifierNameSet | CardIdentifierOracleId;
+declare class CardIdentifierApi {
+  static byId(id: string): CardIdentifier;
+  static byIllustrationId(id: string): CardIdentifier;
+  static byMtgoId(id: number): CardIdentifier;
+  static byMultiverseId(id: number): CardIdentifier;
+  static byName(name: string, set?: string): CardIdentifier;
+  static byOracleId(id: string): CardIdentifier;
+  static bySet(set: string, collectorNumber: number | string): CardIdentifier;
+}
+type CardLanguage = 'ar' | 'de' | 'en' | 'es' | 'fr' | 'grc' | 'he' | 'it' | 'ja' | 'ko' | 'la' | 'ph' | 'pt' | 'ru' | 'sa' | 'zhs' | 'zht';
+type CardLayout = 'adventure' | 'art_series' | 'augment' | 'battle' | 'case' | 'class' | 'double_faced_token' | 'emblem' | 'flip' | 'host' | 'leveler' | 'meld' | 'modal_dfc' | 'mutate' | 'normal' | 'planar' | 'prototype' | 'reversible_card' | 'saga' | 'scheme' | 'split' | 'token' | 'transform' | 'vanguard';
+interface CardCore {
+  arena_id?: Nullable<string>;
+  cardmarket_id?: Nullable<number>;
+  id: string;
+  lang: CardLanguage;
+  layout: CardLayout;
+  mtgo_foil_id?: Nullable<number>;
+  mtgo_id?: Nullable<number>;
+  multiverse_ids?: Nullable<number[]>;
+  object: 'card';
+  oracle_id?: Nullable<string>;
+  prints_search_uri: string;
+  rulings_uri: string;
+  scryfall_uri: string;
+  tcgplayer_etched_id?: Nullable<number>;
+  tcgplayer_id?: Nullable<number>;
+  uri: string;
+}
+type Color = 'B' | 'G' | 'R' | 'U' | 'W';
+interface ManaCost {
+  cmc: number;
+  colorless: boolean;
+  colors: Color[];
+  cost: string;
+  monocolored: boolean;
+  multicolored: boolean;
+  object: 'mana_cost';
+}
+interface Symbology {
+  appears_in_mana_costs: boolean;
+  cmc: number;
+  colors: Color[];
+  english: string;
+  funny: boolean;
+  gatherer_alternates?: Nullable<string[]>;
+  hybrid: boolean;
+  loose_variant?: Nullable<string>;
+  mana_value?: Nullable<number>;
+  object: 'card_symbol';
+  phyrexian: boolean;
+  represents_mana: boolean;
+  svg_uri?: Nullable<string>;
+  symbol: string;
+  transposable: boolean;
+}
+declare class SymbologyApi {
+  all(): Promise<Symbology[]>;
+  parseMana(shorthand: string): Promise<ManaCost>;
+}
+declare const symbology: SymbologyApi;
+interface ImageUris {
+  /**
+   *Size varies by card.
+   */
+  art: string;
+  /**
+   * @deprecated Use `art` instead. Removed on 2027-01-01.
+   * @see https://scryfall.com/blog/new-webp-images-jpeg-deprecations-237
+   */
+  art_crop: string;
+  /**
+   * @deprecated Use `crop` instead. Removed on 2027-01-01.
+   * @see https://scryfall.com/blog/new-webp-images-jpeg-deprecations-237
+   */
+  border_crop: string;
+  /**
+   *480 × 680.
+   */
+  crop: string;
+  /**
+   *672 × 936.
+   */
+  display: string;
+  /**
+   *488 × 680.
+   */
+  grid: string;
+  /**
+   *The only remaining JPEG size (488 × 680).
+   */
+  jpeg: string;
+  /**
+   * @deprecated Use `display` instead. Removed on 2027-01-01.
+   * @see https://scryfall.com/blog/new-webp-images-jpeg-deprecations-237
+   */
+  large: string;
+  /**
+   * @deprecated Use `grid` for WebP or `jpeg` for JPEG.
+   * @see https://scryfall.com/blog/new-webp-images-jpeg-deprecations-237
+   */
+  normal: string;
+  /**
+   *Still available, but hotlinking is not allowed after 2027-01-01.
+   */
+  png: string;
+  /**
+   * @deprecated Use `thumb` instead. Removed on 2027-01-01.
+   * @see https://scryfall.com/blog/new-webp-images-jpeg-deprecations-237
+   */
+  small: string;
+  /**
+   *146 × 204.
+   */
+  thumb: string;
+}
+type CardComponent = 'combo_piece' | 'meld_part' | 'meld_result' | 'token';
+type Legality = 'banned' | 'legal' | 'not_legal' | 'restricted';
+interface CardFace {
+  artist?: Nullable<string>;
+  artist_id?: Nullable<string>;
+  cmc?: Nullable<number>;
+  color_indicator?: Nullable<Color[]>;
+  colors?: Nullable<Color[]>;
+  defense?: Nullable<string>;
+  flavor_text?: Nullable<string>;
+  illustration_id?: Nullable<string>;
+  image_uris?: Nullable<ImageUris>;
+  layout?: Nullable<string>;
+  loyalty?: Nullable<string>;
+  mana_cost: string;
+  name: string;
+  object: 'card_face';
+  oracle_id?: Nullable<string>;
+  oracle_text?: Nullable<string>;
+  power?: Nullable<string>;
+  printed_name?: Nullable<string>;
+  printed_text?: Nullable<string>;
+  printed_type_line?: Nullable<string>;
+  toughness?: Nullable<string>;
+  type_line?: Nullable<string>;
+  watermark?: Nullable<string>;
+}
+interface RelatedCard {
+  component: CardComponent;
+  id: string;
+  name: string;
+  object: 'related_card';
+  type_line: string;
+  uri: string;
+}
+interface Legalities {
+  alchemy: Legality;
+  brawl: Legality;
+  commander: Legality;
+  duel: Legality;
+  explorer: Legality;
+  future: Legality;
+  gladiator: Legality;
+  historic: Legality;
+  legacy: Legality;
+  modern: Legality;
+  oathbreaker: Legality;
+  oldschool: Legality;
+  pauper: Legality;
+  paupercommander: Legality;
+  penny: Legality;
+  pioneer: Legality;
+  predh: Legality;
+  premodern: Legality;
+  standard: Legality;
+  standardbrawl: Legality;
+  timeless: Legality;
+  vintage: Legality;
+}
+interface GameplayCard {
+  all_parts?: Nullable<RelatedCard[]>;
+  card_faces?: Nullable<CardFace[]>;
+  cmc: number;
+  color_identity: Color[];
+  color_indicator?: Nullable<Color[]>;
+  colors?: Nullable<Color[]>;
+  defense?: Nullable<string>;
+  edhrec_rank?: Nullable<number>;
+  game_changer?: Nullable<boolean>;
+  hand_modifier?: Nullable<string>;
+  keywords: string[];
+  legalities: Legalities;
+  life_modifier?: Nullable<string>;
+  loyalty?: Nullable<string>;
+  mana_cost?: Nullable<string>;
+  name: string;
+  oracle_text?: Nullable<string>;
+  penny_rank?: Nullable<number>;
+  power?: Nullable<string>;
+  produced_mana?: Nullable<Color[]>;
+  reserved: boolean;
+  toughness?: Nullable<string>;
+  type_line: string;
+}
+type SetType = 'alchemy' | 'archenemy' | 'arsenal' | 'box' | 'commander' | 'core' | 'draft_innovation' | 'duel_deck' | 'expansion' | 'from_the_vault' | 'funny' | 'masterpiece' | 'masters' | 'memorabilia' | 'minigame' | 'planechase' | 'premium_deck' | 'promo' | 'spellbook' | 'starter' | 'token' | 'treasure_chest' | 'vanguard';
+interface Set {
+  arena_code?: Nullable<string>;
+  block?: Nullable<string>;
+  block_code?: Nullable<string>;
+  card_count: number;
+  code: string;
+  digital: boolean;
+  foil_only: boolean;
+  icon_svg_uri: string;
+  id: string;
+  mtgo_code?: Nullable<string>;
+  name: string;
+  nonfoil_only: boolean;
+  object: 'set';
+  parent_set_code?: Nullable<string>;
+  printed_size?: Nullable<number>;
+  released_at?: Nullable<Date>;
+  scryfall_uri: string;
+  search_uri: string;
+  set_type: SetType;
+  tcgplayer_id?: Nullable<number>;
+  uri: string;
+}
+declare class SetApi {
+  all(): Promise<Set[]>;
+  byCode(code: string): Promise<Set | undefined>;
+  byId(id: string): Promise<Set | undefined>;
+  byTcgPlayerId(id: number): Promise<Set | undefined>;
+}
+declare const set: SetApi;
+type BorderColor = 'black' | 'borderless' | 'gold' | 'silver' | 'white';
+type Finish = 'etched' | 'foil' | 'nonfoil';
+type Frame = '1993' | '1997' | '2003' | '2015' | 'future';
+type FrameEffect = 'colorshifted' | 'companion' | 'compasslanddfc' | 'convertdfc' | 'devoid' | 'draft' | 'etched' | 'extendedart' | 'fandfc' | 'inverted' | 'legendary' | 'lesson' | 'miracle' | 'mooneldrazidfc' | 'nyxtouched' | 'originpwdfc' | 'shatteredglass' | 'showcase' | 'snow' | 'sunmoondfc' | 'tombstone' | 'upsidedowndfc' | 'waxingandwaningmoondfc';
+type Game = 'arena' | 'mtgo' | 'paper';
+type ImageStatus = 'highres_scan' | 'lowres' | 'missing' | 'placeholder';
+interface Preview {
+  previewed_at: Date;
+  source: string;
+  source_uri: string;
+}
+interface Prices {
+  eur?: Nullable<string>;
+  eur_foil?: Nullable<string>;
+  tix?: Nullable<string>;
+  usd?: Nullable<string>;
+  usd_etched?: Nullable<string>;
+  usd_foil?: Nullable<string>;
+}
+type PromoType = 'arenaleague' | 'buyabox' | 'convention' | 'datestamped' | 'draftweekend' | 'duels' | 'event' | 'fnm' | 'gameday' | 'gateway' | 'giftbox' | 'instore' | 'intropack' | 'judgegift' | 'league' | 'openhouse' | 'ourney' | 'planeswalkerdeck' | 'playerrewards' | 'premiereshop' | 'prerelease' | 'release' | 'setpromo' | 'starterdeck' | 'wizardsplaynetwork';
+interface PurchaseUris {
+  [key: string]: Nullable<string>;
+  cardhoarder?: Nullable<string>;
+  cardmarket?: Nullable<string>;
+  tcgplayer?: Nullable<string>;
+}
+type Rarity = 'bonus' | 'common' | 'mythic' | 'rare' | 'special' | 'uncommon';
+interface RelatedUris {
+  [key: string]: Nullable<string>;
+  edhrec?: Nullable<string>;
+  gatherer?: Nullable<string>;
+  mtgtop8?: Nullable<string>;
+  tcgplayer_decks?: Nullable<string>;
+  tcgplayer_infinite_articles?: Nullable<string>;
+  tcgplayer_infinite_decks?: Nullable<string>;
+}
+type SecurityStamp = 'acorn' | 'arena' | 'circle' | 'heart' | 'oval' | 'triangle';
+interface CardPrint {
+  artist?: Nullable<string>;
+  artist_ids?: Nullable<string[]>;
+  attraction_lights?: Nullable<number[]>;
+  booster: boolean;
+  border_color: BorderColor;
+  card_back_id: string;
+  collector_number: string;
+  content_warning?: Nullable<boolean>;
+  digital: boolean;
+  finishes: Finish[];
+  flavor_name?: Nullable<string>;
+  flavor_text?: Nullable<string>;
+  frame: Frame;
+  frame_effects?: Nullable<FrameEffect[]>;
+  full_art: boolean;
+  games: Game[];
+  highres_image: boolean;
+  illustration_id?: Nullable<string>;
+  image_status: ImageStatus;
+  image_uris?: Nullable<ImageUris>;
+  oversized: boolean;
+  preview: Preview;
+  prices: Prices;
+  printed_name?: Nullable<string>;
+  printed_text?: Nullable<string>;
+  printed_type_line?: Nullable<string>;
+  promo: boolean;
+  promo_types?: Nullable<PromoType[]>;
+  purchase_uris?: Nullable<PurchaseUris>;
+  rarity: Rarity;
+  related_uris: RelatedUris;
+  released_at: Date;
+  reprint: boolean;
+  scryfall_set_uri: string;
+  security_stamp?: Nullable<SecurityStamp>;
+  set: string;
+  set_id: string;
+  set_name: string;
+  set_search_uri: string;
+  set_type: SetType;
+  set_uri: string;
+  story_spotlight: boolean;
+  textless: boolean;
+  variation: boolean;
+  variation_of?: Nullable<string>;
+  watermark?: Nullable<string>;
+}
+type Card = CardCore & CardPrint & GameplayCard;
+type CardSearchUnique = 'art' | 'cards' | 'prints';
+type CardSearchOrder = 'artist' | 'cmc' | 'color' | 'edhrec' | 'eur' | 'name' | 'penny' | 'power' | 'rarity' | 'released' | 'review' | 'set' | 'tix' | 'toughness' | 'usd';
+type CardSearchDirection = 'asc' | 'auto' | 'desc';
+type CardSearchFormat = 'csv' | 'json';
+interface CardSearch {
+  dir?: CardSearchDirection;
+  format?: CardSearchFormat;
+  include_extras?: boolean;
+  include_multilingual?: boolean;
+  include_variations?: boolean;
+  order?: CardSearchOrder;
+  page?: number;
+  pretty?: boolean;
+  unique?: CardSearchUnique;
+}
+declare class CardApi {
+  autoCompleteName(name: string): Promise<string[]>;
+  byArenaId(id: number): Promise<Card | undefined>;
+  byId(id: string): Promise<Card | undefined>;
+  byMtgoId(id: number): Promise<Card | undefined>;
+  byMultiverseId(id: number): Promise<Card | undefined>;
+  byName(name: string, isFuzzySearch?: boolean): Promise<Card | undefined>;
+  byName(name: string, set?: string, isFuzzySearch?: boolean): Promise<Card | undefined>;
+  bySet(set: string, collectorNumber: number, lang?: string): Promise<Card | undefined>;
+  byTcgPlayerId(id: number): Promise<Card | undefined>;
+  collection(...identifiers: CardIdentifier[]): Promise<Card[]>;
+  random(): Promise<Card>;
+  search(query: string, options?: CardSearch | number): MagicPageResult<Card>;
+}
+declare const cards: CardApi;
+declare class CatalogApi {
+  artifactTypes(): Promise<string[]>;
+  artistNames(): Promise<string[]>;
+  cardNames(): Promise<string[]>;
+  creatureTypes(): Promise<string[]>;
+  enchantmentTypes(): Promise<string[]>;
+  landTypes(): Promise<string[]>;
+  loyalties(): Promise<string[]>;
+  planeswalkerTypes(): Promise<string[]>;
+  powers(): Promise<string[]>;
+  spellTypes(): Promise<string[]>;
+  toughnesses(): Promise<string[]>;
+  watermarks(): Promise<string[]>;
+  wordBank(): Promise<string[]>;
+}
+declare const catalog: CatalogApi;
+export interface Catalog {
+  data: string[];
+  object: 'catalog';
+  total_values: number;
+  uri: string;
+}
+export interface Ruling {
+  comment: string;
+  object: 'ruling';
+  oracle_id: string;
+  published_at: Date;
+  source: string;
+}
+declare class RulingApi {
+  byArenaId(id: number): Promise<Ruling[]>;
+  byId(id: string): Promise<Ruling[]>;
+  byMtgoId(id: number): Promise<Ruling[]>;
+  byMultiverseId(id: number): Promise<Ruling[]>;
+  bySet(set: string, collectorNumber: number | string): Promise<Ruling[]>;
+}
+declare const rulings: RulingApi;
+declare class InvalidScryfallArgumentError extends Error {}
+declare class ScryfallError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly type?: null | string | undefined;
+  readonly warnings?: null | string[] | undefined;
+  constructor(code: string, details: string, status: number, type?: null | string | undefined, warnings?: null | string[] | undefined);
+}
+declare class UnknownScryfallError extends Error {}
+export { type BorderColor, type Card, type CardComponent, type CardFace, type CardIdentifier, CardIdentifierApi as CardIdentifierBuilder, type CardIdentifierCollectorSet, type CardIdentifierId, type CardIdentifierIllustrationId, type CardIdentifierMtgGoId, type CardIdentifierMultiverseId, type CardIdentifierNameSet, type CardIdentifierOracleId, type CardLanguage, type CardLayout, type CardSearch, type CardSearchDirection, type CardSearchFormat, type CardSearchOrder, type CardSearchUnique, cards as Cards, catalog as Catalogs, type Color, type Finish, type Frame, type FrameEffect, type Game, type ImageStatus, type ImageUris, InvalidScryfallArgumentError, type Legalities, type Legality, MagicPageResult, type ManaCost, type Preview, type Prices, type PromoType, type PurchaseUris, type Rarity, type RelatedCard, type RelatedUris, rulings as Rulings, ScryfallError, type SecurityStamp, type Set, type SetType, set as Sets, type Symbology, symbology as SymbologyApi, UnknownScryfallError };

package/dist/scryfall-api.mjs

@@ -0,0 +1,401 @@
+// src/error/invalid.error.ts
+var InvalidScryfallArgumentError = class extends Error {};
+
+// src/error/scryfall.error.ts
+var ScryfallError = class extends Error {
+	code;
+	status;
+	type;
+	warnings;
+	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
+const defaultNow = () => Date.now();
+async function sleep(milliseconds) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, milliseconds);
+	});
+}
+function createDebounceFetcher(fetcher, { maxRequestsPerSecond, now, sleep: sleepFunction }) {
+	const interval = 1e3 / maxRequestsPerSecond;
+	const clock = now ?? defaultNow;
+	const wait = sleepFunction ?? sleep;
+	let lastRequestAt = -Infinity;
+	return async function debounceFetcher(...arguments_) {
+		for (;;) {
+			const currentTime = clock();
+			const timeUntilNextRequest = lastRequestAt + interval - currentTime;
+			if (timeUntilNextRequest <= 0) {
+				lastRequestAt = currentTime;
+				break;
+			}
+			await wait(timeUntilNextRequest);
+		}
+		return fetcher(...arguments_);
+	};
+}
+
+// src/fetcher/retry.fetcher.ts
+const defaultCanRetry = (object) => {
+	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(fetcher = fetch, { canRetry = defaultCanRetry, maxAttempts = 3 } = {}) {
+	let retries = 0;
+	return async function retryFetcher(...arguments_) {
+		retries++;
+		const response = await fetcher(...arguments_);
+		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.toFixed(0)}`);
+		}
+		if (canRetry(object)) return retryFetcher(...arguments_);
+		if (code && details && status) throw new ScryfallError(code, details, status, type, warnings);
+		throw new UnknownScryfallError(`Request failed with status ${response.status.toFixed(0)}`);
+	};
+}
+
+// src/fetcher/fetcher.ts
+const scryfallEndpoint = "https://api.scryfall.com";
+const defaultRequestsPerSecond = 10;
+const DATE_REGEXP = /^\d{4}-\d{2}-\d{2}?$/;
+const dateParser = (_key, value) => {
+	if (typeof value === "string" && DATE_REGEXP.test(value)) return new Date(value);
+	return value;
+};
+const globallyLimitedFetch = createDebounceFetcher(fetch, { maxRequestsPerSecond: defaultRequestsPerSecond });
+function createFetcher({ fetch: fetchFunction, maxRequestsPerSecond = defaultRequestsPerSecond, now, sleep } = {}) {
+	const globalFetch = fetchFunction ? createDebounceFetcher(fetchFunction, {
+		maxRequestsPerSecond: defaultRequestsPerSecond,
+		now,
+		sleep
+	}) : globallyLimitedFetch;
+	const retryingFetch = createRetryFetcher(globalFetch);
+	const simpleFetcher = maxRequestsPerSecond === defaultRequestsPerSecond ? retryingFetch : createDebounceFetcher(retryingFetch, {
+		maxRequestsPerSecond,
+		now,
+		sleep
+	});
+	return async function fetcher(apiPath, parameters, body) {
+		let path = "";
+		if (typeof apiPath === "number" || typeof apiPath === "string") path = apiPath;
+		else if (apiPath) path = apiPath.join("/");
+		const url = new URL(`${scryfallEndpoint}/${String(path)}`);
+		if (parameters) {
+			for (const [key, value] of Object.entries(parameters)) if (value !== void 0) url.searchParams.append(key, value.toString());
+		}
+		try {
+			const init = { method: body ? "POST" : "GET" };
+			if (body) {
+				init.body = JSON.stringify(body);
+				init.headers = { "Content-Type": "application/json" };
+			}
+			const content = await (await simpleFetcher(url, init)).text();
+			return JSON.parse(content, dateParser);
+		} catch (error) {
+			if (error instanceof ScryfallError) {
+				if (error.warnings) console.warn(error.warnings);
+				if (error.code === "not_found" || error.code === "bad_request") return;
+			}
+			throw error;
+		}
+	};
+}
+const fetcher = createFetcher();
+
+// src/fetcher/page.result.ts
+var MagicPageResult = class {
+	apiPath;
+	query;
+	fetcher;
+	#count = 0;
+	#hasMore = true;
+	constructor(apiPath, query, fetcher$1 = fetcher) {
+		this.apiPath = apiPath;
+		this.query = query;
+		this.fetcher = fetcher$1;
+	}
+	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 this.fetcher(this.apiPath, this.query);
+		this.#hasMore = results?.has_more ?? false;
+		this.#count = Number.parseInt(results?.total_cards?.toFixed(0) ?? "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/api/card/card.api.ts
+const cardsPerSecond = 2;
+const collectionFetcher = createFetcher({ maxRequestsPerSecond: cardsPerSecond });
+const namedFetcher = createFetcher({ maxRequestsPerSecond: cardsPerSecond });
+const randomFetcher = createFetcher({ maxRequestsPerSecond: cardsPerSecond });
+const searchFetcher = createFetcher({ maxRequestsPerSecond: cardsPerSecond });
+var CardApi = class {
+	async autoCompleteName(name) {
+		return (await fetcher("cards/autocomplete", { q: name }))?.data ?? [];
+	}
+	async byArenaId(id) {
+		return fetcher(["cards/arena", id]);
+	}
+	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, set, isFuzzySearch = false) {
+		let isF = isFuzzySearch;
+		let s = set;
+		if (typeof set === "boolean") {
+			isF = set;
+			s = void 0;
+		}
+		return namedFetcher("cards/named", {
+			[isF ? "fuzzy" : "exact"]: name,
+			set: s
+		});
+	}
+	async bySet(set, collectorNumber, lang) {
+		const path = [
+			"cards",
+			set,
+			collectorNumber
+		];
+		if (lang) path.push(lang);
+		return fetcher(path);
+	}
+	async byTcgPlayerId(id) {
+		return fetcher(["cards/tcgplayer", id]);
+	}
+	async collection(...identifiers) {
+		const cards = [];
+		for (let index = 0; index < identifiers.length; index += 75) {
+			const collectionSection = { identifiers: identifiers.slice(index, index + 75) };
+			const result = await collectionFetcher("cards/collection", void 0, collectionSection);
+			cards.push(...result?.data ?? []);
+		}
+		return cards;
+	}
+	async random() {
+		return randomFetcher("cards/random");
+	}
+	search(query, options) {
+		return new MagicPageResult("cards/search", {
+			q: query,
+			...typeof options === "number" ? { page: options } : {
+				...options,
+				page: options?.page ?? 1
+			}
+		}, searchFetcher);
+	}
+};
+const cards = new CardApi();
+
+// 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, set) {
+		if (set) return {
+			name,
+			set
+		};
+		return { name };
+	}
+	static byOracleId(id) {
+		return { oracle_id: id };
+	}
+	static bySet(set, collectorNumber) {
+		return {
+			collector_number: String(collectorNumber),
+			set
+		};
+	}
+};
+
+// 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 ?? [];
+	}
+};
+const catalog = new CatalogApi();
+
+// 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(set, collectorNumber) {
+		return (await fetcher([
+			"cards",
+			set,
+			String(collectorNumber),
+			"rulings"
+		]))?.data ?? [];
+	}
+};
+const rulings = new RulingApi();
+
+// src/api/set/set.api.ts
+var SetApi = class {
+	async all() {
+		return (await fetcher("sets"))?.data ?? [];
+	}
+	async byCode(code) {
+		return await fetcher(["sets", code]);
+	}
+	async byId(id) {
+		return fetcher(["sets", id]);
+	}
+	async byTcgPlayerId(id) {
+		return fetcher(["sets/tcgplayer", id]);
+	}
+};
+const set = new SetApi();
+
+// src/api/symbology/symbology.api.ts
+var SymbologyApi = class {
+	async all() {
+		return (await fetcher("symbology"))?.data ?? [];
+	}
+	async parseMana(shorthand) {
+		if (!shorthand || typeof shorthand !== "string") throw new InvalidScryfallArgumentError("shorthand must be a string");
+		return await fetcher("symbology/parse-mana", { cost: shorthand }) ?? {
+			cmc: 0,
+			colorless: false,
+			colors: [],
+			cost: "",
+			monocolored: false,
+			multicolored: false,
+			object: "mana_cost"
+		};
+	}
+};
+const symbology = new SymbologyApi();
+
+export { CardIdentifierApi as CardIdentifierBuilder, cards as Cards, catalog as Catalogs, InvalidScryfallArgumentError, MagicPageResult, rulings as Rulings, ScryfallError, set as Sets, symbology as SymbologyApi, UnknownScryfallError };

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "scryfall-api",
+	"version": "0.0.0-beta-20261103181737",
+	"description": "A Javascript library for https://scryfall.com/docs/api written in Typescript.",
+	"keywords": [
+		"magic",
+		"magic the gathering",
+		"magic-the-gathering",
+		"gathering",
+		"api",
+		"mtgsdk",
+		"typescript",
+		"card",
+		"cards",
+		"scryfall",
+		"scry"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/MarioMH8/scryfall-api.git"
+	},
+	"homepage": "https://github.com/MarioMH8/scryfall-api",
+	"bugs": {
+		"url": "https://github.com/MarioMH8/scryfall-api/issues"
+	},
+	"license": "MIT",
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/scryfall-api.d.mts",
+			"default": "./dist/scryfall-api.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"commitlint": "commitlint --edit",
+		"lint": "eslint --cache .",
+		"lint:ci": "eslint --cache --cache-strategy content .",
+		"lint:fix": "eslint --cache --fix .",
+		"lint:package": "bun run build && publint",
+		"prepare": "husky",
+		"prepublishOnly": "tsdown",
+		"test": "bun test --timeout 50000",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@changesets/cli": "3.0.3",
+		"@commitlint/cli": "21.2.4",
+		"@commitlint/config-conventional": "21.2.4",
+		"@hexadrop/eslint-config": "1.3.1",
+		"@hexadrop/tsconfig": "0.0.5",
+		"@types/bun": "1.4.4",
+		"eslint": "10.13.0",
+		"husky": "9.1.7",
+		"lint-staged": "17.6.0",
+		"publint": "0.3.25",
+		"tsdown": "0.23.4",
+		"typescript": "6.0.3"
+	}
+}