@pinta365/blizzard_api 0.4.0 → 0.5.0

package/esm/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/esm/src/hearthstone/game_data/metadata.js

@@ -0,0 +1,11 @@
+/**
+ * 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(ctx, type) {
+    return await ctx.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,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/esm/src/hearthstone/search.js

@@ -0,0 +1,28 @@
+/**
+ * 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(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/esm/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/esm/src/hearthstone/types.js

@@ -0,0 +1 @@
+export {};

package/esm/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/esm/src/shared/bind.js

@@ -0,0 +1,15 @@
+/**
+ * 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 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/esm/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 {};

package/esm/src/shared/context.js

@@ -0,0 +1,304 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ApiContext_instances, _ApiContext_config, _ApiContext_token, _ApiContext_userToken, _ApiContext_namespaceVariant, _ApiContext_namespaceHeader, _ApiContext_send, _ApiContext_requestToken;
+import { APIError, AuthenticationError, MissingClientIdError, MissingClientSecretError, MissingRegionError, MissingUserTokenError, } from "./errors.js";
+/**
+ * Renew the token this long before it actually expires, so in-flight requests don't race the expiry.
+ */
+const TOKEN_EXPIRY_MARGIN_MS = 60_000;
+/**
+ * How often a request is retried after a 429 (Too Many Requests) response, and the base backoff between tries.
+ */
+const MAX_RATE_LIMIT_RETRIES = 3;
+const RATE_LIMIT_BACKOFF_MS = 1_000;
+/**
+ * Server errors that are retried once, after a short delay.
+ */
+const SERVER_ERROR_STATUSES = new Set([500, 502, 503, 504]);
+const SERVER_ERROR_RETRY_DELAY_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function retryAfterMs(header) {
+    const seconds = header === null ? NaN : Number(header);
+    return Number.isFinite(seconds) && seconds >= 0 ? Math.min(seconds, 60) * 1000 : undefined;
+}
+const DEFAULT_LOCALES = {
+    us: "en_US",
+    eu: "en_GB",
+    kr: "ko_KR",
+    tw: "zh_TW",
+    cn: "zh_CN",
+};
+/**
+ * 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 function defaultLocale(region) {
+    return DEFAULT_LOCALES[region];
+}
+/**
+ * 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 function oauthBaseUrl(region) {
+    return region === "cn" ? "https://oauth.battlenet.com.cn" : "https://oauth.battle.net";
+}
+/**
+ * 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`;
+}
+/**
+ * Validates that a configuration has everything needed to make requests.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError}
+ */
+export function assertConfig(config) {
+    if (!config.region)
+        throw new MissingRegionError();
+    if (!config.clientId)
+        throw new MissingClientIdError();
+    if (!config.clientSecret)
+        throw new MissingClientSecretError();
+}
+function toQueryParams(qs) {
+    return qs
+        ? Object.fromEntries(Object.entries(qs).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))
+        : {};
+}
+/**
+ * Holds the configuration and token state of one client and performs its requests.
+ * Every endpoint function takes an ApiContext as its first argument.
+ */
+export class ApiContext {
+    /**
+     * @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 = {}, token, options = {}) {
+        _ApiContext_instances.add(this);
+        _ApiContext_config.set(this, void 0);
+        _ApiContext_token.set(this, void 0);
+        _ApiContext_userToken.set(this, void 0);
+        _ApiContext_namespaceVariant.set(this, void 0);
+        __classPrivateFieldSet(this, _ApiContext_config, config, "f");
+        __classPrivateFieldSet(this, _ApiContext_token, token ?? { accessToken: "", tokenExpiration: 0 }, "f");
+        __classPrivateFieldSet(this, _ApiContext_userToken, options.userToken, "f");
+        __classPrivateFieldSet(this, _ApiContext_namespaceVariant, options.namespaceVariant, "f");
+    }
+    /**
+     * The current configuration (may be partial if not fully set up).
+     */
+    get config() {
+        return __classPrivateFieldGet(this, _ApiContext_config, "f");
+    }
+    /**
+     * 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) {
+        const invalidatesToken = ["region", "clientId", "clientSecret"].some((key) => key in config && config[key] !== __classPrivateFieldGet(this, _ApiContext_config, "f")[key]);
+        Object.assign(__classPrivateFieldGet(this, _ApiContext_config, "f"), config);
+        if (invalidatesToken) {
+            __classPrivateFieldGet(this, _ApiContext_token, "f").accessToken = "";
+            __classPrivateFieldGet(this, _ApiContext_token, "f").tokenExpiration = 0;
+        }
+    }
+    /**
+     * Returns a copy of the client credentials token state.
+     */
+    getAuthConfig() {
+        return { accessToken: __classPrivateFieldGet(this, _ApiContext_token, "f").accessToken, tokenExpiration: __classPrivateFieldGet(this, _ApiContext_token, "f").tokenExpiration };
+    }
+    /**
+     * 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) {
+        return new ApiContext(__classPrivateFieldGet(this, _ApiContext_config, "f"), __classPrivateFieldGet(this, _ApiContext_token, "f"), { userToken, namespaceVariant: __classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f") });
+    }
+    /**
+     * 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) {
+        return new ApiContext(__classPrivateFieldGet(this, _ApiContext_config, "f"), __classPrivateFieldGet(this, _ApiContext_token, "f"), { userToken: __classPrivateFieldGet(this, _ApiContext_userToken, "f"), namespaceVariant });
+    }
+    /**
+     * 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 = false) {
+        const config = __classPrivateFieldGet(this, _ApiContext_config, "f");
+        assertConfig(config);
+        const token = __classPrivateFieldGet(this, _ApiContext_token, "f");
+        if (!forceNewToken && token.accessToken && Date.now() < token.tokenExpiration - TOKEN_EXPIRY_MARGIN_MS) {
+            return Promise.resolve(token.accessToken);
+        }
+        if (token.pending) {
+            return token.pending;
+        }
+        token.pending = __classPrivateFieldGet(this, _ApiContext_instances, "m", _ApiContext_requestToken).call(this, config, "grant_type=client_credentials")
+            .then((data) => {
+            token.accessToken = data.access_token;
+            token.tokenExpiration = Date.now() + data.expires_in * 1000;
+            return token.accessToken;
+        })
+            .finally(() => {
+            token.pending = undefined;
+        });
+        return token.pending;
+    }
+    /**
+     * 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) {
+        const config = __classPrivateFieldGet(this, _ApiContext_config, "f");
+        assertConfig(config);
+        const scope = new Set(["openid", ...(options.scope ?? [])]);
+        const params = new URLSearchParams({
+            response_type: "code",
+            client_id: config.clientId,
+            redirect_uri: options.redirectUri,
+            scope: [...scope].join(" "),
+            state: options.state,
+        });
+        return `${oauthBaseUrl(config.region)}/authorize?${params}`;
+    }
+    /**
+     * 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) {
+        const config = __classPrivateFieldGet(this, _ApiContext_config, "f");
+        assertConfig(config);
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: options.code,
+            redirect_uri: options.redirectUri,
+        });
+        return __classPrivateFieldGet(this, _ApiContext_instances, "m", _ApiContext_requestToken).call(this, config, body.toString());
+    }
+    /**
+     * 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) {
+        const config = __classPrivateFieldGet(this, _ApiContext_config, "f");
+        assertConfig(config);
+        const { url, namespace, qs, auth } = requestOptions;
+        const params = new URLSearchParams(toQueryParams({ locale: config.locale ?? defaultLocale(config.region), ...qs }));
+        const query = params.size ? `?${params}` : "";
+        const fullUrl = apiBaseUrl(config.region) + encodeURI(url) + query;
+        return __classPrivateFieldGet(this, _ApiContext_instances, "m", _ApiContext_send).call(this, fullUrl, namespace ? __classPrivateFieldGet(this, _ApiContext_instances, "m", _ApiContext_namespaceHeader).call(this, namespace, config.region) : undefined, auth === "user");
+    }
+    /**
+     * 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, qs) {
+        const config = __classPrivateFieldGet(this, _ApiContext_config, "f");
+        assertConfig(config);
+        const url = new URL(href);
+        for (const [key, value] of Object.entries(toQueryParams({ locale: config.locale ?? defaultLocale(config.region), ...qs }))) {
+            if (!url.searchParams.has(key))
+                url.searchParams.set(key, value);
+        }
+        // Hrefs from the API already carry their full namespace in the query string.
+        return __classPrivateFieldGet(this, _ApiContext_instances, "m", _ApiContext_send).call(this, url.toString(), undefined, url.pathname.startsWith("/profile/user/"));
+    }
+}
+_ApiContext_config = new WeakMap(), _ApiContext_token = new WeakMap(), _ApiContext_userToken = new WeakMap(), _ApiContext_namespaceVariant = new WeakMap(), _ApiContext_instances = new WeakSet(), _ApiContext_namespaceHeader = function _ApiContext_namespaceHeader(namespace, region) {
+    const isBase = namespace === "static" || namespace === "dynamic" || namespace === "profile";
+    return isBase && __classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f")
+        ? `${namespace}-${__classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f")}-${region}`
+        : `${namespace}-${region}`;
+}, _ApiContext_send = async function _ApiContext_send(url, namespaceHeader, userScoped) {
+    if (userScoped && !__classPrivateFieldGet(this, _ApiContext_userToken, "f")) {
+        throw new MissingUserTokenError();
+    }
+    const doFetch = async (forceNewToken) => {
+        const token = userScoped ? __classPrivateFieldGet(this, _ApiContext_userToken, "f") : await this.authenticate(forceNewToken);
+        const headers = { "Authorization": `Bearer ${token}` };
+        if (namespaceHeader)
+            headers["Battlenet-Namespace"] = namespaceHeader;
+        return await fetch(url, { method: "GET", headers });
+    };
+    let response = await doFetch(false);
+    if (response.status === 401 && !userScoped) {
+        // The cached token may have been revoked or expired early; retry once with a fresh one.
+        await response.body?.cancel();
+        response = await doFetch(true);
+    }
+    if (SERVER_ERROR_STATUSES.has(response.status)) {
+        // Transient gateway/server errors: requests are GETs, so retrying once is safe.
+        await response.body?.cancel();
+        await sleep(SERVER_ERROR_RETRY_DELAY_MS);
+        response = await doFetch(false);
+    }
+    for (let attempt = 1; response.status === 429 && attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {
+        // Rate limited: wait for Retry-After (seconds) if given, otherwise back off exponentially.
+        await response.body?.cancel();
+        await sleep(retryAfterMs(response.headers.get("Retry-After")) ?? RATE_LIMIT_BACKOFF_MS * 2 ** (attempt - 1));
+        response = await doFetch(false);
+    }
+    if (response.ok) {
+        return await response.json();
+    }
+    const text = await response.text();
+    let errorData = null;
+    try {
+        errorData = text ? JSON.parse(text) : null;
+    }
+    catch {
+        // Empty or non-JSON body (e.g. 404 with no body)
+    }
+    const statusCode = errorData?.code ?? response.status;
+    const errorMessage = errorData
+        ? JSON.stringify(errorData)
+        : response.statusText || "Problem fetching data from API";
+    throw new APIError(errorMessage, statusCode, response.statusText);
+}, _ApiContext_requestToken = async function _ApiContext_requestToken(config, body) {
+    const response = await fetch(`${oauthBaseUrl(config.region)}/token`, {
+        method: "POST",
+        headers: {
+            "Authorization": "Basic " + btoa(`${config.clientId}:${config.clientSecret}`),
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body,
+    });
+    if (!response.ok) {
+        throw new AuthenticationError("Problem with Authentication", response.status, await response.text());
+    }
+    return await response.json();
+};