@pinta365/blizzard_api 0.4.0 → 0.5.0

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

@@ -0,0 +1,82 @@
+import type { ApiContext } from "../../shared/index.js";
+import type { LocalizedString } from "../../shared/index.js";
+export interface MetadataSet {
+    id: number;
+    name: LocalizedString;
+    slug: string;
+    hyped: boolean;
+    type: string;
+    collectibleCount: number;
+    collectibleRevealedCount: number;
+    nonCollectibleCount: number;
+    nonCollectibleRevealedCount: number;
+    aliasSetIds?: number[];
+}
+export interface MetadataSetGroup {
+    slug: string;
+    year?: number;
+    svg?: string;
+    cardSets: string[];
+    name: LocalizedString;
+    standard?: boolean;
+    yearRange?: string;
+    icon?: string;
+}
+export interface MetadataType {
+    slug: string;
+    id: number;
+    name: LocalizedString;
+    gameModes: number[];
+}
+export interface MetadataRarity {
+    slug: string;
+    id: number;
+    craftingCost: number[];
+    dustValue: number[];
+    name: LocalizedString;
+}
+export interface MetadataClass {
+    slug: string;
+    id: number;
+    name: LocalizedString;
+    cardId?: number;
+    heroPowerCardId?: number;
+    alternateHeroCardIds?: number[];
+}
+export interface MetadataMinionType {
+    slug: string;
+    id: number;
+    name: LocalizedString;
+    gameModes: number[];
+}
+export interface MetadataKeyword {
+    id: number;
+    slug: string;
+    name: LocalizedString;
+    refText: LocalizedString;
+    text: LocalizedString;
+    gameModes: number[];
+}
+/**
+ * The response of metadata(type) for each metadata type.
+ */
+export interface MetadataByType {
+    sets: MetadataSet[];
+    setGroups: MetadataSetGroup[];
+    types: MetadataType[];
+    rarities: MetadataRarity[];
+    classes: MetadataClass[];
+    minionTypes: MetadataMinionType[];
+    keywords: MetadataKeyword[];
+}
+/**
+ * Any metadata response.
+ */
+export type Metadata = MetadataByType[keyof MetadataByType];
+export type MetaTypes = keyof MetadataByType;
+/**
+ * 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<T extends MetaTypes>(ctx: ApiContext, type: T): Promise<MetadataByType[T]>;

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metadata = metadata;
+/**
+ * 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.
+ */
+async function metadata(ctx, type) {
+    return await ctx.request({
+        method: "GET",
+        url: `/hearthstone/metadata/${type}`,
+    });
+}

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metadata = exports.fetchDeck = exports.searchCardbacks = exports.fetchCardback = exports.searchCards = exports.fetchCard = void 0;
+var cards_js_1 = require("./game_data/cards.js");
+Object.defineProperty(exports, "fetchCard", { enumerable: true, get: function () { return cards_js_1.fetchCard; } });
+Object.defineProperty(exports, "searchCards", { enumerable: true, get: function () { return cards_js_1.searchCards; } });
+var card_backs_js_1 = require("./game_data/card_backs.js");
+Object.defineProperty(exports, "fetchCardback", { enumerable: true, get: function () { return card_backs_js_1.fetchCardback; } });
+Object.defineProperty(exports, "searchCardbacks", { enumerable: true, get: function () { return card_backs_js_1.searchCardbacks; } });
+var decks_js_1 = require("./game_data/decks.js");
+Object.defineProperty(exports, "fetchDeck", { enumerable: true, get: function () { return decks_js_1.fetchDeck; } });
+var metadata_js_1 = require("./game_data/metadata.js");
+Object.defineProperty(exports, "metadata", { enumerable: true, get: function () { return metadata_js_1.metadata; } });

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

@@ -0,0 +1,21 @@
+import type { ApiContext } from "../shared/index.js";
+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(ctx: ApiContext, url: string, searchParameters: SearchParameters): Promise<Search>;

package/script/src/hearthstone/search.js

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

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

@@ -0,0 +1,5 @@
+export type { Cardback, CardbackSearch } from "./game_data/card_backs.js";
+export type { Card, CardSearch } from "./game_data/cards.js";
+export type { Deck, Options } from "./game_data/decks.js";
+export type { Metadata, MetadataByType, MetadataClass, MetadataKeyword, MetadataMinionType, MetadataRarity, MetadataSet, MetadataSetGroup, MetadataType, MetaTypes, } from "./game_data/metadata.js";
+export type { Search, SearchParameters } from "./search.js";

package/script/src/hearthstone/types.js

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

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

@@ -0,0 +1,14 @@
+import type { ApiContext } from "./context.js";
+/**
+ * Turns a module of endpoint functions `(ctx, ...args) => R` into the same functions without the context argument.
+ */
+export type Bound<T> = {
+    [K in keyof T as T[K] extends (ctx: ApiContext, ...args: any[]) => unknown ? K : never]: T[K] extends (ctx: ApiContext, ...args: infer A) => infer R ? (...args: A) => R : never;
+};
+/**
+ * Binds every endpoint function of a module to a context.
+ * @param {ApiContext} ctx - The context the endpoints will use.
+ * @param {T} endpoints - A module namespace of endpoint functions.
+ * @returns {Bound<T>} The bound endpoints.
+ */
+export declare function bindAll<T extends object>(ctx: ApiContext, endpoints: T): Bound<T>;

package/script/src/shared/bind.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindAll = bindAll;
+/**
+ * Binds every endpoint function of a module to a context.
+ * @param {ApiContext} ctx - The context the endpoints will use.
+ * @param {T} endpoints - A module namespace of endpoint functions.
+ * @returns {Bound<T>} The bound endpoints.
+ */
+function bindAll(ctx, endpoints) {
+    const bound = {};
+    for (const [name, value] of Object.entries(endpoints)) {
+        if (typeof value === "function") {
+            bound[name] = value.bind(undefined, ctx);
+        }
+    }
+    return Object.freeze(bound);
+}

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

@@ -0,0 +1,163 @@
+import type { Locales, Regions, RequestOptions } from "./types.js";
+/**
+ * Represents the configuration of a client.
+ * @property {Regions} region - The target Battle.net region for API requests.
+ * @property {Locales} [locale] - The locale for localized fields. Defaults to the main locale of the region
+ *     (us: en_US, eu: en_GB, kr: ko_KR, tw: zh_TW, cn: zh_CN).
+ * @property {string} clientId - The OAuth client ID.
+ * @property {string} clientSecret - The OAuth client secret.
+ */
+export interface ClientConfig {
+    region: Regions;
+    locale?: Locales;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Represents the authentication state of the client credentials token.
+ * @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;
+}
+/**
+ * Options for building the authorization code flow URL.
+ * @property {string} redirectUri - The redirect URI registered for the client.
+ * @property {string[]} [scope] - The requested scopes, e.g. ["wow.profile"]. "openid" is always included.
+ * @property {string} state - An opaque, unguessable value to protect against CSRF. Verify it on the redirect.
+ */
+export interface AuthorizeUrlOptions {
+    redirectUri: string;
+    scope?: string[];
+    state: string;
+}
+/**
+ * Options for exchanging an authorization code for a user access token.
+ * @property {string} code - The code received on the redirect URI.
+ * @property {string} redirectUri - The same redirect URI used to build the authorize URL.
+ */
+export interface ExchangeCodeOptions {
+    code: string;
+    redirectUri: string;
+}
+/**
+ * Represents the token response of the OAuth token endpoint.
+ */
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    sub?: string;
+    id_token?: string;
+}
+interface ContextOptions {
+    userToken?: string;
+    namespaceVariant?: string;
+}
+interface TokenState extends AuthConfig {
+    pending?: Promise<string>;
+}
+/**
+ * Returns the locale used when none is configured. A locale is always sent, so localized fields are plain strings.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {Locales} The default locale of the region.
+ */
+export declare function defaultLocale(region: Regions): Locales;
+/**
+ * Generates the OAuth base URL based on the specified region.
+ * @param {Regions} region - The target Battle.net region.
+ * @returns {string} The OAuth base URL.
+ */
+export declare function oauthBaseUrl(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;
+/**
+ * Validates that a configuration has everything needed to make requests.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError}
+ */
+export declare function assertConfig(config: Partial<ClientConfig>): asserts config is ClientConfig;
+/**
+ * Holds the configuration and token state of one client and performs its requests.
+ * Every endpoint function takes an ApiContext as its first argument.
+ */
+export declare class ApiContext {
+    #private;
+    /**
+     * @param {Partial<ClientConfig>} config - The client configuration. Shared by reference with derived contexts.
+     * @param {TokenState} [token] - Token state to share (used by derived contexts).
+     * @param {ContextOptions} [options] - User token and namespace variant.
+     */
+    constructor(config?: Partial<ClientConfig>, token?: TokenState, options?: ContextOptions);
+    /**
+     * The current configuration (may be partial if not fully set up).
+     */
+    get config(): Readonly<Partial<ClientConfig>>;
+    /**
+     * Merges configuration into this context. Changing the region or credentials discards the cached token.
+     * @param {Partial<ClientConfig>} config - The configuration properties to update.
+     */
+    configure(config: Partial<ClientConfig>): void;
+    /**
+     * Returns a copy of the client credentials token state.
+     */
+    getAuthConfig(): AuthConfig;
+    /**
+     * Returns a context that uses the given user access token for user-scoped endpoints
+     * (e.g. the WoW account profile). It shares configuration and the client credentials token with this context.
+     * @param {string} userToken - A user access token from the authorization code flow.
+     */
+    forUser(userToken: string): ApiContext;
+    /**
+     * Returns a context for another game version: base namespaces ("static", "dynamic", "profile") get the variant
+     * inserted before the region, e.g. "classic1x" turns "static" into "static-classic1x-eu".
+     * It shares configuration, tokens and the user token with this context.
+     * @param {string} namespaceVariant - The namespace variant, e.g. "classic" or "classic1x".
+     */
+    withNamespaceVariant(namespaceVariant: string): ApiContext;
+    /**
+     * Obtains a client credentials access token, reusing the cached one while it is valid.
+     * Concurrent callers share a single token request.
+     * @param {boolean} forceNewToken - If true, fetches a new token even if the cached one is valid.
+     * @returns {Promise<string>} The access token.
+     * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError} If the client is not configured.
+     * @throws {AuthenticationError} If there is a problem during the authentication process.
+     */
+    authenticate(forceNewToken?: boolean): Promise<string>;
+    /**
+     * Builds the URL to send a user to for the authorization code flow.
+     * @param {AuthorizeUrlOptions} options - Redirect URI, scopes and state.
+     * @returns {string} The authorize URL.
+     */
+    authorizeUrl(options: AuthorizeUrlOptions): string;
+    /**
+     * Exchanges an authorization code for a user access token.
+     * @param {ExchangeCodeOptions} options - The code and the redirect URI used to obtain it.
+     * @returns {Promise<TokenResponse>} The token response; pass `access_token` to forUser().
+     * @throws {AuthenticationError} If the exchange fails.
+     */
+    exchangeCode(options: ExchangeCodeOptions): Promise<TokenResponse>;
+    /**
+     * Makes an authenticated request to the API.
+     * @param {RequestOptions} requestOptions - Method, path, namespace, query string and auth mode.
+     * @returns {Promise<unknown>} The parsed JSON response.
+     * @throws {APIError} If the response is not successful.
+     * @throws {MissingUserTokenError} If the endpoint needs a user token and this context has none.
+     */
+    request(requestOptions: RequestOptions): Promise<unknown>;
+    /**
+     * Makes an authenticated request to a full href returned in an API response.
+     * @param {string} href - The full href URL from a Blizzard API response.
+     * @param {Record<string, string | number>} [qs] - Optional query string parameters to append.
+     * @returns {Promise<unknown>} The parsed JSON response.
+     * @throws {APIError} If the response is not successful.
+     */
+    requestHref(href: string, qs?: Record<string, string | number>): Promise<unknown>;
+}
+export {};