@pinta365/blizzard_api 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Pinta <https://github.com/Pinta365>
+
+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,61 @@
+# BLIZZARD_API
+
+[![JSR Version](https://jsr.io/badges/@pinta365/blizzard-api)](https://jsr.io/@pinta365/blizzard-api)
+
+Start of what will cover the whole Blizzard Battle.net API when its done.
+
+Link to the module on [JSR](https://jsr.io/@pinta365/blizzard-api)
+
+## WORK IN PROGRESS
+
+Let me know if you want certain APIs to be prioritized. Currently only supports client credentials flow but the plan is
+to implement authorization code flow also.
+
+### APIs implemented
+
+| APIs                                          | Status | Note                      |
+| --------------------------------------------- | ------ | ------------------------- |
+| **World of Warcraft:** Game Data APIs         | ✅     |                           |
+| **World of Warcraft:** Profile APIs           | ✅     |                           |
+|                                               |        |                           |
+| **World of Warcraft Classic:** Game Data APIs |        |                           |
+|                                               |        |                           |
+| **Diablo III:** Community APIs                | ✅     | Missing profile endpoints |
+| **Diablo III:** Game Data APIs                | ✅     |                           |
+|                                               |        |                           |
+| **Hearthstone:** Game Data APIs               | ✅     |                           |
+|                                               |        |                           |
+| **StarCraft II:** Community APIs              |        |                           |
+| **StarCraft II:** Game Data APIs              | ✅     |                           |
+
+## Example
+
+```javascript
+import * as blizzardAPI from "@pinta365/blizzard-api";
+
+const clientId = "<YOUR CLIENT ID>";
+const clientSecret = "<YOUR SECRET>";
+
+blizzardAPI.setup({
+    clientId,
+    clientSecret,
+    region: "eu",
+    locale: "en_GB",
+});
+
+try {
+    const sword = await blizzardAPI.wow.item(33791);
+    console.log(sword);
+} catch (error) {
+    console.log(error);
+}
+```
+
+## Issues
+
+Issues or questions concerning the library can be raised at the
+[github repository](https://github.com/Pinta365/blizzard_api/issues) page.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/esm/mod.d.ts

@@ -0,0 +1,5 @@
+import { authenticate, setup } from "./src/shared/index.js";
+import * as wow from "./src/wow/index.js";
+import * as hearthstone from "./src/hearthstone/index.js";
+import * as sc2 from "./src/starcraft2/index.js";
+export { authenticate, hearthstone, sc2, setup, wow };

package/esm/mod.js

@@ -0,0 +1,5 @@
+import { authenticate, setup } from "./src/shared/index.js";
+import * as wow from "./src/wow/index.js";
+import * as hearthstone from "./src/hearthstone/index.js";
+import * as sc2 from "./src/starcraft2/index.js";
+export { authenticate, hearthstone, sc2, setup, wow };

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/hearthstone/game_data/card_backs.d.ts

@@ -0,0 +1,22 @@
+import type { LocalizedString } from "../../shared/index.js";
+import type { Search, SearchParameters } from "../search.js";
+export interface Cardback {
+    id: number;
+    sortCategory: number;
+    text: LocalizedString;
+    name: LocalizedString;
+}
+/**
+ * Returns an up-to-date list of all card backs matching the search criteria.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing an up-to-date list of all card backs matching the search criteria.
+ */
+export declare function searchCardbacks(searchParameters: SearchParameters): Promise<Search>;
+/**
+ * Returns the card back with an ID or slug that matches the one you specify.
+ *
+ * @param idorslug - The unique identifier for the card back by slug.
+ * @returns A promise that resolves to an object representing details about a card back.
+ */
+export declare function fetchCardback(idorslug: string): Promise<Cardback>;

package/esm/src/hearthstone/game_data/card_backs.js

@@ -0,0 +1,23 @@
+import { request } from "../../shared/index.js";
+import { search } from "../search.js";
+/**
+ * Returns an up-to-date list of all card backs matching the search criteria.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing an up-to-date list of all card backs matching the search criteria.
+ */
+export async function searchCardbacks(searchParameters) {
+    return await search("/cardback", searchParameters);
+}
+/**
+ * Returns the card back with an ID or slug that matches the one you specify.
+ *
+ * @param idorslug - The unique identifier for the card back by slug.
+ * @returns A promise that resolves to an object representing details about a card back.
+ */
+export async function fetchCardback(idorslug) {
+    return await request({
+        method: "GET",
+        url: `/hearthstone/cardback/${idorslug}`,
+    });
+}

package/esm/src/hearthstone/game_data/cards.d.ts

@@ -0,0 +1,37 @@
+import type { LocalizedString } from "../../shared/index.js";
+import type { Search, SearchParameters } from "../search.js";
+export interface Card {
+    id: number;
+    collectible: number;
+    slug: string;
+    classId: number;
+    multiClassIds: number[];
+    cardTypeId: number;
+    cardSetId: number;
+    rarityId: number;
+    artistName: string;
+    health: number;
+    attack: number;
+    manaCost: number;
+    name: LocalizedString;
+    text: LocalizedString;
+    image: string;
+    imageGold: string;
+    flavorText: LocalizedString;
+    cropImage: string;
+    keywordIds: number[];
+}
+/**
+ * Returns an up-to-date list of all cards matching the search criteria.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing an up-to-date list of all cards matching the search criteria.
+ */
+export declare function searchCards(searchParameters: SearchParameters): Promise<Search>;
+/**
+ * Returns the card with an ID or slug that matches the one you specify.
+ *
+ * @param idorslug - The unique identifier for the card by slug.
+ * @returns A promise that resolves to an object representing details about a card.
+ */
+export declare function fetchCard(idorslug: string, gameMode?: string): Promise<Card>;

package/esm/src/hearthstone/game_data/cards.js

@@ -0,0 +1,27 @@
+import { request } from "../../shared/index.js";
+import { search } from "../search.js";
+/**
+ * Returns an up-to-date list of all cards matching the search criteria.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing an up-to-date list of all cards matching the search criteria.
+ */
+export async function searchCards(searchParameters) {
+    return await search("/cards", searchParameters);
+}
+/**
+ * Returns the card with an ID or slug that matches the one you specify.
+ *
+ * @param idorslug - The unique identifier for the card by slug.
+ * @returns A promise that resolves to an object representing details about a card.
+ */
+export async function fetchCard(idorslug, gameMode) {
+    const reqOptions = {
+        method: "GET",
+        url: `/hearthstone/cards/${idorslug}`,
+    };
+    if (gameMode) {
+        reqOptions["qs"] = { gameMode };
+    }
+    return await request(reqOptions);
+}

package/esm/src/hearthstone/game_data/decks.d.ts

@@ -0,0 +1,88 @@
+import type { LocalizedString } from "../../shared/index.js";
+export interface Options {
+    code?: string;
+    ids?: string;
+    hero?: string;
+}
+export interface Deck {
+    deckCode: string;
+    version: number;
+    format: string;
+    hero: {
+        id: number;
+        collectible: number;
+        slug: string;
+        classId: number;
+        multiClassIds: number[];
+        cardTypeId: number;
+        cardSetId: number;
+        rarityId: number;
+        artistName: string;
+        health: number;
+        manaCost: number;
+        name: LocalizedString;
+        text: LocalizedString;
+        image: string;
+        imageGold: string;
+        flavorText: LocalizedString;
+        cropImage: string;
+        childIds: number[];
+    };
+    heroPower: {
+        id: number;
+        collectible: number;
+        slug: string;
+        classId: number;
+        multiClassIds: number[];
+        cardTypeId: number;
+        cardSetId: number;
+        rarityId: number;
+        artistName: null;
+        manaCost: number;
+        name: LocalizedString;
+        text: LocalizedString;
+        image: string;
+        imageGold: string;
+        flavorText: LocalizedString;
+        cropImage: string;
+        parentId: number;
+    };
+    class: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    };
+    cards: {
+        id: number;
+        collectible: number;
+        slug: string;
+        classId: number;
+        multiClassIds: number[];
+        cardTypeId: number;
+        cardSetId: number;
+        rarityId: number;
+        artistName: string;
+        health: number;
+        attack: number;
+        manaCost: number;
+        name: LocalizedString;
+        text: LocalizedString;
+        image: string;
+        imageGold: string;
+        flavorText: LocalizedString;
+        cropImage: string;
+        copyOfCardId: number;
+        duels: {
+            relevant: boolean;
+            constructed: boolean;
+        };
+    }[];
+    cardCount: number;
+}
+/**
+ * Returns the card with an ID or slug that matches the one you specify.
+ *
+ * @param options - find parameters fort the search.
+ * @returns A promise that resolves to an object representing details about a card.
+ */
+export declare function fetchDeck(options?: Options): Promise<Deck>;

package/esm/src/hearthstone/game_data/decks.js

@@ -0,0 +1,14 @@
+import { request } from "../../shared/index.js";
+/**
+ * Returns the card with an ID or slug that matches the one you specify.
+ *
+ * @param options - find parameters fort the search.
+ * @returns A promise that resolves to an object representing details about a card.
+ */
+export async function fetchDeck(options) {
+    return await request({
+        method: "GET",
+        url: `/hearthstone/deck`,
+        qs: options,
+    });
+}

package/esm/src/hearthstone/game_data/metadata.d.ts

@@ -0,0 +1,95 @@
+import type { LocalizedString } from "../../shared/index.js";
+export interface Metadata {
+    sets: {
+        id: number;
+        name: LocalizedString;
+        slug: string;
+        aliasSetIds?: number[];
+        type: string;
+        collectibleCount: number;
+        collectibleRevealedCount: number;
+        nonCollectibleCount: number;
+        nonCollectibleRevealedCount: number;
+    }[];
+    setGroups: {
+        slug: string;
+        year?: number;
+        svg?: string;
+        cardSets: string[];
+        name: LocalizedString;
+        standard?: boolean;
+        yearRange?: string;
+        icon?: string;
+    }[];
+    gameModes: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    }[];
+    arenaIds: number[];
+    types: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+        gameModes: number[];
+    }[];
+    rarities: {
+        slug: string;
+        id: number;
+        craftingCost: number[];
+        dustValue: number[];
+        name: LocalizedString;
+    }[];
+    classes: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+        cardId?: number;
+        heroPowerCardId?: number;
+        alternateHeroCardIds?: number[];
+    }[];
+    minionTypes: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+        gameModes: number[];
+    }[];
+    spellSchools: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    }[];
+    mercenaryRoles: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    }[];
+    mercenaryFactions: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    }[];
+    keywords: {
+        id: number;
+        slug: string;
+        name: LocalizedString;
+        refText: LocalizedString;
+        text: LocalizedString;
+        gameModes: number[];
+    }[];
+    filterableFields: string[];
+    numericFields: string[];
+    cardBackCategories: {
+        slug: string;
+        id: number;
+        name: LocalizedString;
+    }[];
+}
+type MetaTypes = "sets" | "setGroups" | "types" | "rarities" | "classes" | "minionTypes" | "keywords";
+/**
+ * Returns information about the categorization of cards. Metadata includes the card set, set group (for example, Standard or Year of the Dragon), rarity, class, card type, minion type, and keywords.
+ *
+ * @returns A promise that resolves to an object representing the Metadata.
+ */
+export declare function metadata(type: MetaTypes): Promise<Partial<Metadata>>;
+export {};

package/esm/src/hearthstone/game_data/metadata.js

@@ -0,0 +1,12 @@
+import { request } from "../../shared/index.js";
+/**
+ * Returns information about the categorization of cards. Metadata includes the card set, set group (for example, Standard or Year of the Dragon), rarity, class, card type, minion type, and keywords.
+ *
+ * @returns A promise that resolves to an object representing the Metadata.
+ */
+export async function metadata(type) {
+    return await request({
+        method: "GET",
+        url: `/hearthstone/metadata/${type}`,
+    });
+}

package/esm/src/hearthstone/index.d.ts

@@ -0,0 +1,4 @@
+export { fetchCard, searchCards } from "./game_data/cards.js";
+export { fetchCardback, searchCardbacks } from "./game_data/card_backs.js";
+export { fetchDeck } from "./game_data/decks.js";
+export { metadata } from "./game_data/metadata.js";

package/esm/src/hearthstone/index.js

@@ -0,0 +1,4 @@
+export { fetchCard, searchCards } from "./game_data/cards.js";
+export { fetchCardback, searchCardbacks } from "./game_data/card_backs.js";
+export { fetchDeck } from "./game_data/decks.js";
+export { metadata } from "./game_data/metadata.js";

package/esm/src/hearthstone/search.d.ts

@@ -0,0 +1,20 @@
+export interface SearchParameters {
+    searchFields?: Record<string | symbol, string | number>;
+    page?: number;
+    pageSize?: number;
+    sort?: string;
+}
+export interface Search {
+    page: number;
+    pageSize: number;
+    maxPageSize: number;
+    pageCount: number;
+    results: unknown[];
+}
+/**
+ * Performs a search.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing details about the search.
+ */
+export declare function search(url: string, searchParameters: SearchParameters): Promise<Search>;

package/esm/src/hearthstone/search.js

@@ -0,0 +1,29 @@
+import { request } from "../shared/index.js";
+/**
+ * Performs a search.
+ *
+ * @param SearchParameters - Object containing search parameters.
+ * @returns A promise that resolves to an object representing details about the search.
+ */
+export async function search(url, searchParameters) {
+    const searchFields = searchParameters.searchFields
+        ? Object.fromEntries(Object.entries(searchParameters.searchFields).map(([key, value]) => [key, value.toString()]))
+        : undefined;
+    const qs = {
+        ...searchFields,
+    };
+    if (searchParameters.sort) {
+        qs.sort = searchParameters.sort;
+    }
+    if (searchParameters.page !== undefined) {
+        qs.page = searchParameters.page;
+    }
+    if (searchParameters.pageSize !== undefined) {
+        qs.pageSize = searchParameters.pageSize;
+    }
+    return await request({
+        method: "GET",
+        url: `/hearthstone${url}`,
+        qs,
+    });
+}

package/esm/src/shared/auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents the configuration data for authentication.
+ * @property {string} accessToken - The current access token.
+ * @property {number} tokenExpiration - The expiration timestamp of the access token (in milliseconds).
+ */
+export interface AuthConfig {
+    accessToken: string;
+    tokenExpiration: number;
+}
+/**
+ * Retrieves the global authentication configuration.
+ * @returns {AuthConfig} The authentication configuration object.
+ */
+export declare function getauthConfig(): AuthConfig;
+/**
+ * Handles authentication and obtains an access token if needed.
+ * @param {boolean} forceNewToken - If true, forces the retrieval of a new token, ignoring any existing one.
+ * @returns {Promise<string>} Returns the access token (string).
+ * @throws {MissingRegionError} If the region is not configured.
+ * @throws {MissingClientIdError} If the client ID is not configured.
+ * @throws {MissingClientSecretError} If the client secret is not configured.
+ * @throws {AuthenticationError} If there is a problem during the authentication process.
+ */
+export declare function authenticate(forceNewToken?: boolean): Promise<string>;

package/esm/src/shared/auth.js

@@ -0,0 +1,58 @@
+//auth.ts
+import { getSetup, tokenUrl } from "./config.js";
+import { AuthenticationError, MissingClientIdError, MissingClientSecretError, MissingRegionError } from "./errors.js";
+/**
+ * Global storage for authentication configuration data.
+ */
+const authConfig = {
+    accessToken: "",
+    tokenExpiration: 0,
+};
+/**
+ * Retrieves the global authentication configuration.
+ * @returns {AuthConfig} The authentication configuration object.
+ */
+export function getauthConfig() {
+    return authConfig;
+}
+/**
+ * Handles authentication and obtains an access token if needed.
+ * @param {boolean} forceNewToken - If true, forces the retrieval of a new token, ignoring any existing one.
+ * @returns {Promise<string>} Returns the access token (string).
+ * @throws {MissingRegionError} If the region is not configured.
+ * @throws {MissingClientIdError} If the client ID is not configured.
+ * @throws {MissingClientSecretError} If the client secret is not configured.
+ * @throws {AuthenticationError} If there is a problem during the authentication process.
+ */
+export async function authenticate(forceNewToken = false) {
+    if (!getSetup().region) {
+        throw new MissingRegionError();
+    }
+    if (!getSetup().clientId) {
+        throw new MissingClientIdError();
+    }
+    if (!getSetup().clientSecret) {
+        throw new MissingClientSecretError();
+    }
+    if (!forceNewToken && authConfig.accessToken && authConfig.tokenExpiration &&
+        new Date() < new Date(authConfig.tokenExpiration)) {
+        return authConfig.accessToken;
+    }
+    const response = await fetch(tokenUrl(getSetup().region), {
+        method: "POST",
+        headers: {
+            "Authorization": "Basic " + btoa(`${getSetup().clientId}:${getSetup().clientSecret}`),
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: "grant_type=client_credentials",
+    });
+    if (response.ok) {
+        const data = await response.json();
+        authConfig.accessToken = data.access_token;
+        authConfig.tokenExpiration = Date.now() + data.expires_in * 1000;
+        return authConfig.accessToken;
+    }
+    else {
+        throw new AuthenticationError("Problem with Authentication", response.status, response.statusText);
+    }
+}

package/esm/src/shared/config.d.ts

@@ -0,0 +1,40 @@
+import type { Locales, Regions } from "./types.js";
+/**
+ * Represents the required application configuration.
+ * @property {Regions} region - The target Battle.net region for API requests.
+ * @property {Locales} locale - The desired locale for data.
+ * @property {string} clientId - The OAuth client ID.
+ * @property {string} clientSecret - The OAuth client secret.
+ */
+export interface Config {
+    region: Regions;
+    locale: Locales;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Generates the OAuth token URL based on the specified region.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {string} The constructed token URL.
+ */
+export declare function tokenUrl(region: Regions): string;
+/**
+ * Generates the base API URL based on the specified region.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {string} The constructed base API URL.
+ */
+export declare function apiBaseUrl(region: Regions): string;
+/**
+ * Updates the application configuration and performs basic validation.
+ * @param {Partial<Config>} userConfig - An object containing configuration properties to update.
+ * @throws {MissingRegionError} If the region is not provided in the update.
+ * @throws {MissingClientIdError} If the client ID is not provided in the update.
+ * @throws {MissingClientSecretError} If the client secret is not provided in the update.
+ */
+export declare function setup(userConfig: Partial<Config>): void;
+/**
+ * Retrieves the current application configuration.
+ * Note: The configuration may be partial if not fully setup.
+ * @returns {Config | Partial<Config>} The full or partially loaded configuration object.
+ */
+export declare function getSetup(): Config | Partial<Config>;

package/esm/src/shared/config.js

@@ -0,0 +1,48 @@
+import { MissingClientIdError, MissingClientSecretError, MissingRegionError } from "./errors.js";
+/**
+ * Holds the partially loaded application configuration.
+ */
+let config = {};
+/**
+ * Generates the OAuth token URL based on the specified region.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {string} The constructed token URL.
+ */
+export function tokenUrl(region) {
+    return region === "cn" ? "https://www.battlenet.com.cn/oauth/token" : `https://${region}.battle.net/oauth/token`;
+}
+/**
+ * Generates the base API URL based on the specified region.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {string} The constructed base API URL.
+ */
+export function apiBaseUrl(region) {
+    return region === "cn" ? "https://gateway.battlenet.com.cn" : `https://${region}.api.blizzard.com`;
+}
+/**
+ * Updates the application configuration and performs basic validation.
+ * @param {Partial<Config>} userConfig - An object containing configuration properties to update.
+ * @throws {MissingRegionError} If the region is not provided in the update.
+ * @throws {MissingClientIdError} If the client ID is not provided in the update.
+ * @throws {MissingClientSecretError} If the client secret is not provided in the update.
+ */
+export function setup(userConfig) {
+    config = { ...config, ...userConfig };
+    if (!config.region) {
+        throw new MissingRegionError();
+    }
+    if (!config.clientId) {
+        throw new MissingClientIdError();
+    }
+    if (!config.clientSecret) {
+        throw new MissingClientSecretError();
+    }
+}
+/**
+ * Retrieves the current application configuration.
+ * Note: The configuration may be partial if not fully setup.
+ * @returns {Config | Partial<Config>} The full or partially loaded configuration object.
+ */
+export function getSetup() {
+    return config;
+}