@pinta365/blizzard_api 0.3.5

package/script/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/script/src/hearthstone/search.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = void 0;
+const index_js_1 = require("../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.
+ */
+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 (0, index_js_1.request)({
+        method: "GET",
+        url: `/hearthstone${url}`,
+        qs,
+    });
+}
+exports.search = search;

package/script/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/script/src/shared/auth.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authenticate = exports.getauthConfig = void 0;
+//auth.ts
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Global storage for authentication configuration data.
+ */
+const authConfig = {
+    accessToken: "",
+    tokenExpiration: 0,
+};
+/**
+ * Retrieves the global authentication configuration.
+ * @returns {AuthConfig} The authentication configuration object.
+ */
+function getauthConfig() {
+    return authConfig;
+}
+exports.getauthConfig = getauthConfig;
+/**
+ * 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.
+ */
+async function authenticate(forceNewToken = false) {
+    if (!(0, config_js_1.getSetup)().region) {
+        throw new errors_js_1.MissingRegionError();
+    }
+    if (!(0, config_js_1.getSetup)().clientId) {
+        throw new errors_js_1.MissingClientIdError();
+    }
+    if (!(0, config_js_1.getSetup)().clientSecret) {
+        throw new errors_js_1.MissingClientSecretError();
+    }
+    if (!forceNewToken && authConfig.accessToken && authConfig.tokenExpiration &&
+        new Date() < new Date(authConfig.tokenExpiration)) {
+        return authConfig.accessToken;
+    }
+    const response = await fetch((0, config_js_1.tokenUrl)((0, config_js_1.getSetup)().region), {
+        method: "POST",
+        headers: {
+            "Authorization": "Basic " + btoa(`${(0, config_js_1.getSetup)().clientId}:${(0, config_js_1.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 errors_js_1.AuthenticationError("Problem with Authentication", response.status, response.statusText);
+    }
+}
+exports.authenticate = authenticate;

package/script/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/script/src/shared/config.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSetup = exports.setup = exports.apiBaseUrl = exports.tokenUrl = void 0;
+const errors_js_1 = require("./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.
+ */
+function tokenUrl(region) {
+    return region === "cn" ? "https://www.battlenet.com.cn/oauth/token" : `https://${region}.battle.net/oauth/token`;
+}
+exports.tokenUrl = tokenUrl;
+/**
+ * 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.
+ */
+function apiBaseUrl(region) {
+    return region === "cn" ? "https://gateway.battlenet.com.cn" : `https://${region}.api.blizzard.com`;
+}
+exports.apiBaseUrl = apiBaseUrl;
+/**
+ * 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.
+ */
+function setup(userConfig) {
+    config = { ...config, ...userConfig };
+    if (!config.region) {
+        throw new errors_js_1.MissingRegionError();
+    }
+    if (!config.clientId) {
+        throw new errors_js_1.MissingClientIdError();
+    }
+    if (!config.clientSecret) {
+        throw new errors_js_1.MissingClientSecretError();
+    }
+}
+exports.setup = setup;
+/**
+ * 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.
+ */
+function getSetup() {
+    return config;
+}
+exports.getSetup = getSetup;

package/script/src/shared/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Custom error class representing an API error.
+ * @class
+ * @extends {Error}
+ */
+export declare class APIError extends Error {
+    statusCode: number;
+    responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+/**
+ * Custom error class representing an Authentication error.
+ * @class
+ * @extends {Error}
+ */
+export declare class AuthenticationError extends Error {
+    statusCode: number;
+    responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+/**
+ * Custom error class representing a missing client id error.
+ * @class
+ * @extends {Error}
+ */
+export declare class MissingClientIdError extends Error {
+    constructor();
+}
+/**
+ * Custom error class representing a missing client secret error.
+ * @class
+ * @extends {Error}
+ */
+export declare class MissingClientSecretError extends Error {
+    constructor();
+}
+/**
+ * Custom error class representing a missing api region error.
+ * @class
+ * @extends {Error}
+ */
+export declare class MissingRegionError extends Error {
+    constructor();
+}

package/script/src/shared/errors.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingRegionError = exports.MissingClientSecretError = exports.MissingClientIdError = exports.AuthenticationError = exports.APIError = void 0;
+/**
+ * Custom error class representing an API error.
+ * @class
+ * @extends {Error}
+ */
+class APIError extends Error {
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        Object.defineProperty(this, "statusCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "responseBody", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "APIError";
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+exports.APIError = APIError;
+/**
+ * Custom error class representing an Authentication error.
+ * @class
+ * @extends {Error}
+ */
+class AuthenticationError extends Error {
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        Object.defineProperty(this, "statusCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "responseBody", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "AuthenticationError";
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Custom error class representing a missing client id error.
+ * @class
+ * @extends {Error}
+ */
+class MissingClientIdError extends Error {
+    constructor() {
+        super("Client Id must be setup. Check documentation");
+        this.name = "MissingClientIdError";
+    }
+}
+exports.MissingClientIdError = MissingClientIdError;
+/**
+ * Custom error class representing a missing client secret error.
+ * @class
+ * @extends {Error}
+ */
+class MissingClientSecretError extends Error {
+    constructor() {
+        super("Client Secret must be setup. Check documentation");
+        this.name = "MissingClientSecretError";
+    }
+}
+exports.MissingClientSecretError = MissingClientSecretError;
+/**
+ * Custom error class representing a missing api region error.
+ * @class
+ * @extends {Error}
+ */
+class MissingRegionError extends Error {
+    constructor() {
+        super("Api region must be setup. Check documentation");
+        this.name = "MissingRegionError";
+    }
+}
+exports.MissingRegionError = MissingRegionError;

package/script/src/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { setup } from "./config.js";
+export { authenticate } from "./auth.js";
+export { request } from "./request.js";
+export type { Asset, Character, Href, KeyId, KeyName, KeyNameId, LinkSelfHref, LocalizedString, NameId, Namespaces, RequestOptions, TypeName, } from "./types.js";

package/script/src/shared/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = exports.authenticate = exports.setup = void 0;
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "setup", { enumerable: true, get: function () { return config_js_1.setup; } });
+var auth_js_1 = require("./auth.js");
+Object.defineProperty(exports, "authenticate", { enumerable: true, get: function () { return auth_js_1.authenticate; } });
+var request_js_1 = require("./request.js");
+Object.defineProperty(exports, "request", { enumerable: true, get: function () { return request_js_1.request; } });

package/script/src/shared/request.d.ts

@@ -0,0 +1,13 @@
+import type { RequestOptions } from "./types.js";
+/**
+ * Makes an authenticated request to the API and handles potential errors.
+ * @param {RequestOptions} requestOptions - An object containing the following:
+ *      * method: The HTTP method (e.g., "GET", "POST")
+ *      * url:  The API endpoint path.
+ *      * namespace (optional):  The Battlenet namespace for the request.
+ *      * qs (optional): An object representing query string parameters.
+ * @returns {Promise<any>} The parsed JSON response from the API.
+ * @throws {APIError} If there is a problem fetching or the response is not successful.
+ * @throws {AuthenticationError} (Potentially) If authentication fails during the process.
+ */
+export declare function request(requestOptions: RequestOptions): Promise<unknown>;

package/script/src/shared/request.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = void 0;
+const config_js_1 = require("./config.js");
+const auth_js_1 = require("./auth.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Makes an authenticated request to the API and handles potential errors.
+ * @param {RequestOptions} requestOptions - An object containing the following:
+ *      * method: The HTTP method (e.g., "GET", "POST")
+ *      * url:  The API endpoint path.
+ *      * namespace (optional):  The Battlenet namespace for the request.
+ *      * qs (optional): An object representing query string parameters.
+ * @returns {Promise<any>} The parsed JSON response from the API.
+ * @throws {APIError} If there is a problem fetching or the response is not successful.
+ * @throws {AuthenticationError} (Potentially) If authentication fails during the process.
+ */
+async function request(requestOptions) {
+    if (!(0, auth_js_1.getauthConfig)().accessToken || ((0, auth_js_1.getauthConfig)().accessToken && (0, auth_js_1.getauthConfig)().tokenExpiration &&
+        new Date() < new Date((0, auth_js_1.getauthConfig)().tokenExpiration))) {
+        await (0, auth_js_1.authenticate)(true);
+    }
+    const { method, url, namespace } = requestOptions;
+    let { qs } = requestOptions;
+    if ((0, config_js_1.getSetup)().locale) {
+        qs = { ...{ locale: (0, config_js_1.getSetup)().locale }, ...qs };
+    }
+    const qsString = qs
+        ? Object.fromEntries(Object.entries(qs).filter(([, value]) => value !== undefined).map(([key, value]) => [key, value.toString()]))
+        : {};
+    const params = new URLSearchParams(qsString);
+    const headers = {
+        "Authorization": "Bearer " + (0, auth_js_1.getauthConfig)().accessToken,
+    };
+    if (namespace) {
+        headers["Battlenet-Namespace"] = `${namespace}-${(0, config_js_1.getSetup)().region}`;
+    }
+    const response = await fetch((0, config_js_1.apiBaseUrl)((0, config_js_1.getSetup)().region) + encodeURI(url) + (qsString ? "?" + params.toString() : ""), {
+        method: method,
+        headers: headers,
+    });
+    if (response.ok) {
+        return await response.json();
+    }
+    throw new errors_js_1.APIError("Problem fetching data from API", response.status, response.statusText);
+}
+exports.request = request;

package/script/src/shared/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Represents the configuration options for an API request.
+ * @property {string} method - The HTTP method to use (currently restricted to "GET").
+ * @property {string} url - The API endpoint path.
+ * @property {Namespaces} [namespace] - The optional Battle.net namespace for the request.
+ * @property {Record<string, string | number>} [qs] - An optional object for query string parameters.
+ */
+export interface RequestOptions {
+    method: "GET";
+    url: string;
+    namespace?: Namespaces;
+    qs?: Record<string, string | number>;
+}
+/**
+ * Supported Battle.net regions.
+ */
+export type Regions = "us" | "eu" | "kr" | "tw" | "cn";
+/**
+ * Supported locales for data.
+ */
+export type Locales = "en_US" | "es_MX" | "pt_BR" | "en_GB" | "es_ES" | "fr_FR" | "ru_RU" | "de_DE" | "pt_PT" | "it_IT" | "ko_KR" | "zh_TW" | "zh_CN";
+/**
+ * Available Battle.net namespaces.
+ */
+export type Namespaces = "static" | "dynamic" | "profile";
+/**
+ * Represents a reference (link) with a URL.
+ */
+export interface Href {
+    /**
+     * The URL or address of the reference.
+     */
+    href: string;
+}
+/**
+ * Represents a self-referential link structure commonly found in API responses.
+ */
+export interface LinkSelfHref {
+    self: Href;
+}
+/**
+ * Represents localized text. It can be either a string (if no locale was used) or a key-value object for multiple locales.
+ */
+export interface LocalizedString {
+    name: string | Record<Locales, string>;
+}
+/**
+ * Represents an object with a key (link), ID and LocalizedString name.
+ */
+export interface KeyNameId {
+    key: {
+        href: string;
+    };
+    name: LocalizedString;
+    id: number;
+}
+/**
+ * Represents an object with a key (link) and LocalizedString name.
+ */
+export interface KeyName {
+    key: {
+        href: string;
+    };
+    name: LocalizedString;
+}
+/**
+ * Represents an object with a key (link) and ID.
+ */
+export interface KeyId {
+    key: {
+        href: string;
+    };
+    id: number;
+}
+/**
+ * Represents an object with LocalizedString name and ID.
+ */
+export interface NameId {
+    name: LocalizedString;
+    id: number;
+}
+/**
+ * Represents an object with a type and a LocalizedString name.
+ */
+export interface TypeName {
+    type: string;
+    name: LocalizedString;
+}
+/**
+ * Represents a character profile.
+ */
+export interface Character {
+    key?: {
+        href: string;
+    };
+    name: string;
+    id: number;
+    realm: {
+        key: {
+            href: string;
+        };
+        name: LocalizedString;
+        id: number;
+        slug: string;
+    };
+    level?: number;
+    playable_class?: KeyId;
+    playable_race?: KeyId;
+}
+/**
+ * Represents a generic asset within a system.
+ * @property {string} key - A unique identifier for the asset.
+ * @property {string} value - The value associated with the asset.
+ * @property {number} [file_data_id] - (Optional) The ID of the file data associated with the asset (if any).
+ */
+export interface Asset {
+    key: string;
+    value: string;
+    file_data_id?: number;
+}

package/script/src/shared/types.js

@@ -0,0 +1,3 @@
+"use strict";
+//types.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/src/starcraft2/game_data/league.d.ts

@@ -0,0 +1,32 @@
+import type { LinkSelfHref } from "../../shared/index.js";
+export interface League extends LinkSelfHref {
+    key: {
+        league_id: number;
+        season_id: number;
+        queue_id: number;
+        team_type: number;
+    };
+    tier: {
+        id: number;
+        division: {
+            id: number;
+            ladder_id: number;
+            member_count: number;
+        }[];
+    }[];
+}
+/**
+ * Returns data for the specified season, queue, team, and league.
+ *
+ * Notes from the battle.net docs:
+ * queueId: the standard available queueIds are: 1=WoL 1v1, 2=WoL 2v2, 3=WoL 3v3, 4=WoL 4v4, 101=HotS 1v1, 102=HotS 2v2, 103=HotS 3v3, 104=HotS 4v4, 201=LotV 1v1, 202=LotV 2v2, 203=LotV 3v3, 204=LotV 4v4, 206=LotV Archon. Note that other available queues may not be listed here.
+ * teamType: there are two available teamTypes: 0=arranged, 1=random.
+ * leagueId: available leagueIds are: 0=Bronze, 1=Silver, 2=Gold, 3=Platinum, 4=Diamond, 5=Master, 6=Grandmaster.
+ *
+ * @param seasonId - The season ID of the data to retrieve.
+ * @param queueId - The queue ID of the data to retrieve.
+ * @param teamType - The team type of the data to retrieve.
+ * @param leagueId - The league ID of the data to retrieve.
+ * @returns A promise that resolves to an object representing the data for a league.
+ */
+export declare function leagueData(seasonId: number, queueId: number, teamType: number, leagueId: number): Promise<League>;

package/script/src/starcraft2/game_data/league.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.leagueData = void 0;
+const index_js_1 = require("../../shared/index.js");
+/**
+ * Returns data for the specified season, queue, team, and league.
+ *
+ * Notes from the battle.net docs:
+ * queueId: the standard available queueIds are: 1=WoL 1v1, 2=WoL 2v2, 3=WoL 3v3, 4=WoL 4v4, 101=HotS 1v1, 102=HotS 2v2, 103=HotS 3v3, 104=HotS 4v4, 201=LotV 1v1, 202=LotV 2v2, 203=LotV 3v3, 204=LotV 4v4, 206=LotV Archon. Note that other available queues may not be listed here.
+ * teamType: there are two available teamTypes: 0=arranged, 1=random.
+ * leagueId: available leagueIds are: 0=Bronze, 1=Silver, 2=Gold, 3=Platinum, 4=Diamond, 5=Master, 6=Grandmaster.
+ *
+ * @param seasonId - The season ID of the data to retrieve.
+ * @param queueId - The queue ID of the data to retrieve.
+ * @param teamType - The team type of the data to retrieve.
+ * @param leagueId - The league ID of the data to retrieve.
+ * @returns A promise that resolves to an object representing the data for a league.
+ */
+async function leagueData(seasonId, queueId, teamType, leagueId) {
+    return await (0, index_js_1.request)({
+        method: "GET",
+        url: `/data/sc2/league/${seasonId}/${queueId}/${teamType}/${leagueId}`,
+    });
+}
+exports.leagueData = leagueData;

package/script/src/starcraft2/index.d.ts

@@ -0,0 +1 @@
+export { leagueData } from "./game_data/league.js";

package/script/src/starcraft2/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.leagueData = void 0;
+var league_js_1 = require("./game_data/league.js");
+Object.defineProperty(exports, "leagueData", { enumerable: true, get: function () { return league_js_1.leagueData; } });