@pinta365/blizzard_api 0.3.9 → 0.5.0

package/script/src/shared/context.js

@@ -0,0 +1,312 @@
+"use strict";
+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;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiContext = void 0;
+exports.defaultLocale = defaultLocale;
+exports.oauthBaseUrl = oauthBaseUrl;
+exports.apiBaseUrl = apiBaseUrl;
+exports.assertConfig = assertConfig;
+const errors_js_1 = require("./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.
+ */
+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.
+ */
+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.
+ */
+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}
+ */
+function assertConfig(config) {
+    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();
+}
+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.
+ */
+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/"));
+    }
+}
+exports.ApiContext = ApiContext;
+_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 errors_js_1.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 errors_js_1.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 errors_js_1.AuthenticationError("Problem with Authentication", response.status, await response.text());
+    }
+    return await response.json();
+};

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

@@ -0,0 +1,53 @@
+/**
+ * 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();
+}
+/**
+ * Custom error class representing a missing user access token, needed for user-scoped endpoints
+ * such as the WoW account profile. Obtain one with the authorization code flow and use client.forUser(token).
+ * @class
+ * @extends {Error}
+ */
+export declare class MissingUserTokenError extends Error {
+    constructor();
+}

package/script/src/shared/errors.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingUserTokenError = 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;
+/**
+ * Custom error class representing a missing user access token, needed for user-scoped endpoints
+ * such as the WoW account profile. Obtain one with the authorization code flow and use client.forUser(token).
+ * @class
+ * @extends {Error}
+ */
+class MissingUserTokenError extends Error {
+    constructor() {
+        super("This endpoint requires a user access token. Use client.forUser(token). Check documentation");
+        this.name = "MissingUserTokenError";
+    }
+}
+exports.MissingUserTokenError = MissingUserTokenError;

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

@@ -0,0 +1,4 @@
+export { apiBaseUrl, ApiContext, assertConfig, oauthBaseUrl } from "./context.js";
+export type { AuthConfig, AuthorizeUrlOptions, ClientConfig, ExchangeCodeOptions, TokenResponse } from "./context.js";
+export { bindAll, type Bound } from "./bind.js";
+export type { Asset, Character, Href, KeyId, KeyName, KeyNameId, LinkSelfHref, Locales, LocalizedString, NamedRef, NameId, Namespaces, Regions, RequestOptions, TypeName, } from "./types.js";

package/script/src/shared/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindAll = exports.oauthBaseUrl = exports.assertConfig = exports.ApiContext = exports.apiBaseUrl = void 0;
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "apiBaseUrl", { enumerable: true, get: function () { return context_js_1.apiBaseUrl; } });
+Object.defineProperty(exports, "ApiContext", { enumerable: true, get: function () { return context_js_1.ApiContext; } });
+Object.defineProperty(exports, "assertConfig", { enumerable: true, get: function () { return context_js_1.assertConfig; } });
+Object.defineProperty(exports, "oauthBaseUrl", { enumerable: true, get: function () { return context_js_1.oauthBaseUrl; } });
+var bind_js_1 = require("./bind.js");
+Object.defineProperty(exports, "bindAll", { enumerable: true, get: function () { return bind_js_1.bindAll; } });

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

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ * @property {"user"} [auth] - Set to "user" for endpoints that require a user access token (authorization code flow).
+ */
+export interface RequestOptions {
+    method: "GET";
+    url: string;
+    namespace?: Namespaces;
+    qs?: Record<string, string | number>;
+    auth?: "user";
+}
+/**
+ * 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" | //Retail
+"static-classic1x" | "dynamic-classic1x" | "profile-classic1x" | //Classic
+"static-classic" | "dynamic-classic" | "profile-classic";
+/**
+ * Represents a reference (link) with a URL.
+ */
+export interface Href {
+    /**
+     * The URL or address of the reference.
+     */
+    href: string;
+}
+/**
+ * Represents the self link found at the top of most API responses.
+ */
+export interface LinkSelfHref {
+    _links: {
+        self: Href;
+    };
+}
+/**
+ * Represents localized text. The client always sends a locale (the configured one, or the region's default), so
+ * localized fields are plain strings.
+ */
+export type LocalizedString = string;
+/**
+ * Represents an object with a key (link), ID and LocalizedString name.
+ */
+export interface KeyNameId {
+    key: {
+        href: string;
+    };
+    name: LocalizedString;
+    id: number;
+}
+/**
+ * Represents a reference to another resource: a key (link), a name and an ID.
+ */
+export interface NamedRef {
+    key: Href;
+    name: string;
+    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/community/account.d.ts

@@ -0,0 +1,19 @@
+/**
+ * This module provides the StarCraft II account endpoint (player) using the Blizzard API.
+ */
+import type { ApiContext } from "../../shared/index.js";
+export interface Sc2Player {
+    name: string;
+    profileUrl: string;
+    avatarUrl: string;
+    profileId: string;
+    regionId: number;
+    realmId: number;
+}
+/**
+ * Returns the StarCraft II players linked to an account.
+ *
+ * @param accountId - The unique identifier for the account.
+ * @returns A promise that resolves to an array of players linked to the account.
+ */
+export declare function player(ctx: ApiContext, accountId: number): Promise<Sc2Player[]>;

package/script/src/starcraft2/community/account.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * This module provides the StarCraft II account endpoint (player) using the Blizzard API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.player = player;
+/**
+ * Returns the StarCraft II players linked to an account.
+ *
+ * @param accountId - The unique identifier for the account.
+ * @returns A promise that resolves to an array of players linked to the account.
+ */
+async function player(ctx, accountId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/player/${accountId}`,
+    });
+}