v5.0.0, add support for Scryfall's new agent restriction

Won't know if this actually works until Scryfall starts rejecting requests, though

Author: ChiriVulpes

CHANGELOG.md

@@ -1,3 +1,6 @@
+# v5.0.0 (August 8th, 2024)
+- Added support for setting the agent name due to [Scryfall's new requirements](https://scryfall.com/blog/user-agent-and-accept-header-now-required-on-the-api-225) via `Scry.setAgent(name, version)`(./DOCUMENTATION.md#scrysetagent-agent-string-version-string-void-). All applications using scryfall-sdk that are not running on clientside in the browser must provide an agent name & version.
+
 # v4.2.1 (December 9th, 2023)
 - Fixed `MagicEmitters` (IE, what's returned by `Cards.search()`) erroring if not every possible event has a listener registered, thanks to [#69](https://github.com/ChiriVulpes/scryfall-sdk/pull/69) by [lordnox](https://github.com/lordnox).
 

DOCUMENTATION.md

@@ -1,9 +1,10 @@
 ## Table of Contents
 - [Usage](#usage-)
+  - [`Scry.setAgent (agent: string, version: string): void;`](#scrysetagent-agent-string-version-string-void-)
 - [Cards](#cards-)
   - [`Cards.byId (id: string): Promise<Card>;`](#cardsbyid-id-string-promisecard-)
   - [`Cards.byName (name: string, set?: string, fuzzy = false): Promise<Card>;`](#cardsbyname-name-string-set-string-fuzzy--false-promisecard-)
-  - [`Cards.bySet (code: string, collectorNumber: string | number, lang?: string): Promise<Card>;`](#cardsbyset-setcode-string-collectornumber-string--number-lang-string-promisecard-)
+  - [`Cards.bySet (setCode: string, collectorNumber: string | number, lang?: string): Promise<Card>;`](#cardsbyset-setcode-string-collectornumber-string--number-lang-string-promisecard-)
   - [`Cards.byMultiverseId (id: number): Promise<Card>;` ](#cardsbymultiverseid-id-number-promisecard-)
   - [`Cards.byMtgoId (id: number): Promise<Card>;` ](#cardsbymtgoid-id-number-promisecard-)
   - [`Cards.byArenaId (id: number): Promise<Card>;` ](#cardsbyarenaid-id-number-promisecard-)
@@ -86,7 +87,12 @@ import Scry = require("scryfall-sdk");
 ### Using a node.js version older than v18?
 Install the [`axios`](https://www.npmjs.com/package/axios) dependency alongside scryfall-sdk and it will automatically use it.
 
-
+### `Scry.setAgent (agent: string, version: string): void;` [🡅](#table-of-contents)
+> [!IMPORTANT]  
+> Scryfall *requires* that all applications provide an agent, except if they are executing on clientside in a browser.
+```ts
+Scry.setAgent("MyAmazingAppName", "1.0.0");
+```
 
 ## Cards [🡅](#table-of-contents)
 

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2017-2023 Chiri Vulpes
+Copyright 2017-2024 Chiri Vulpes
 
 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:
 

README.md

@@ -5,7 +5,7 @@
 
 A Node.js SDK for [Scryfall](https://scryfall.com/docs/api) written in Typescript.
 
-As of [October 23rd, 2023](./CHANGELOG.md), 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!
+As of [August 8th, 2024](./CHANGELOG.md), all features described in the [Scryfall documentation](https://scryfall.com/docs/api) should be supported. If you see something that isn't, make an issue!
 
 
 ## Installation
@@ -30,11 +30,18 @@ const prints = await chalice.getPrints();
 console.log(prints.length); // 7
 ```
 
-This module supports all features of Scryfall, along with automatically paginating through results, downloading bulk data streams, etc. There's also documentation on every single part of the SDK:
-
+> [!IMPORTANT]  
+> Scryfall [requires](https://scryfall.com/docs/api#required-headers) that all applications provide an agent, except if they are executing from web browser JavaScript.
+>
+> If this is true for your application, you must set your agent before making any requests:
+> ```ts
+> Scry.setAgent("MyAmazingAppName", "1.0.0");
+> ```
 
 ## [Full Documentation](./DOCUMENTATION.md)
-### [Scryfall-SDK Equivalents for Scryfall Routes](./ROUTES.md)
+scryfall-sdk supports all features of Scryfall, along with automatically paginating through results, downloading bulk data streams, and more. See the [documentation](./DOCUMENTATION.md) for information on everything you can do.
+
+Know the endpoint you want, but not sure what it looks like in scryfall-sdk? Well, you're in luck: [Scryfall-SDK Equivalents for Scryfall Routes](./ROUTES.md)
 
 
 ## Contributing
@@ -59,4 +66,4 @@ gulp watch
 
 ## MIT License
 
-[Copyright 2017-2022 Chiri Vulpes](./LICENSE)
+[Copyright 2017-2024 Chiri Vulpes](./LICENSE)

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scryfall-sdk",
-	"version": "4.2.2",
+	"version": "5.0.0",
 	"main": "./out/Scry.js",
 	"types": "./out/Scry.d.ts",
 	"description": "A Node.js SDK for https://scryfall.com/docs/api written in Typescript.",

src/Scry.ts

@@ -25,6 +25,13 @@ Cards["Scry"] = exports;
 Sets["Scry"] = exports;
 
 
+/**
+ * Sets the name and version of this agent. This is required for all non-browser applications.
+ */
+export function setAgent (agent: string, version: string) {
+	MagicQuerier.agent = `${agent}/${version}`;
+}
+
 /**
  * Sets the API calls to retry if they fail, for any reason.
  * @param attempts The number of attempts that can be made (includes the initial call).

src/api/BulkData.ts

@@ -94,6 +94,12 @@ class BulkData extends MagicQuerier {
 		} else {
 			const result = await fetch(definition.download_uri, {
 				method: "GET",
+				headers: {
+					...!MagicQuerier.agent ? undefined : {
+						'User-Agent': MagicQuerier.agent,
+					},
+					Accept: "*/*",
+				},
 			});
 
 			return result.body;

src/tests/Main.ts

@@ -9,6 +9,8 @@ import { Card, ENDPOINT_FILE_1, RESOURCE_GENERIC_CARD_BACK, SymbologyTransformer
 import Cached from "../util/Cached";
 import MagicQuerier from "../util/MagicQuerier";
 
+Scry.setAgent("ScryfallSDKTests", "1.0");
+
 const expect = chai.expect;
 chai.use(chaiAsPromised);
 

src/util/MagicQuerier.ts

@@ -63,6 +63,7 @@ export default class MagicQuerier {
 
 	public static lastQuery = 0;
 	public static retry: RetryStrategy = { attempts: 1 };
+	public static agent?: string;
 	public static timeout = defaultRequestTimeout;
 	public static requestCount = 0;
 
@@ -149,6 +150,10 @@ export default class MagicQuerier {
 			body: JSON.stringify(post),
 			headers: {
 				'Content-Type': 'application/json',
+				...!MagicQuerier.agent ? undefined : {
+					'User-Agent': MagicQuerier.agent,
+				},
+				Accept: "*/*",
 			},
 			method: post ? "POST" : "GET",
 		});