scryfall-api 4.0.5 → 5.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2025 MarioMH
+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

package/README.md

@@ -93,6 +93,8 @@ Compile the project
 bun run build
 ```
 
+You can read the full [contribution](./CONTRIBUTING.md) guidelines.
+
 ## MIT License
 
-[Copyright 2021-2025 MarioMH](./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 };