@pinta365/blizzard_api 0.7.1 → 0.8.1

package/esm/src/generated/wow_forever_api.js

@@ -0,0 +1,2 @@
+// Generated by scripts/gen_api.ts from src/wow_forever/index.ts. Do not edit; run `deno task gen:api`.
+export {};

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

@@ -12,6 +12,12 @@ export interface ClientConfig {
     locale?: Locales;
     clientId: string;
     clientSecret: string;
+    /**
+     * Static namespace version for WoW: Forever, e.g. "1.60.1_70399". When set, `wowForever` static requests use
+     * `static-<version>-forever-<region>` instead of `static-forever-<region>` (which serves the current version). Use it
+     * to pin a version; the current one is in the `self` link of any static response.
+     */
+    foreverStaticVersion?: string;
 }
 /**
  * Represents the authentication state of the client credentials token.
@@ -56,7 +62,10 @@ export interface TokenResponse {
 interface ContextOptions {
     userToken?: string;
     namespaceVariant?: string;
+    staticVersion?: StaticVersion;
 }
+/** Returns the static namespace version to insert before the variant, or undefined for the plain namespace. */
+type StaticVersion = (config: Readonly<Partial<ClientConfig>>) => string | undefined;
 interface TokenState extends AuthConfig {
     pending?: Promise<string>;
 }
@@ -92,7 +101,7 @@ export declare 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.
+     * @param {ContextOptions} [options] - User token, namespace variant and static namespace version.
      */
     constructor(config?: Partial<ClientConfig>, token?: TokenState, options?: ContextOptions);
     /**
@@ -119,8 +128,10 @@ export declare class ApiContext {
      * 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".
+     * @param {StaticVersion} [staticVersion] - Reads a static namespace version from the configuration, e.g. "1.60.1_70399"
+     *   turns "static" into "static-1.60.1_70399-forever-eu". When it returns undefined, the plain namespace is used.
      */
-    withNamespaceVariant(namespaceVariant: string): ApiContext;
+    withNamespaceVariant(namespaceVariant: string, staticVersion?: StaticVersion): ApiContext;
     /**
      * Obtains a client credentials access token, reusing the cached one while it is valid.
      * Concurrent callers share a single token request.

package/esm/src/shared/context.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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;
+var _ApiContext_instances, _ApiContext_config, _ApiContext_token, _ApiContext_userToken, _ApiContext_namespaceVariant, _ApiContext_staticVersion, _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.
@@ -86,7 +86,7 @@ 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.
+     * @param {ContextOptions} [options] - User token, namespace variant and static namespace version.
      */
     constructor(config = {}, token, options = {}) {
         _ApiContext_instances.add(this);
@@ -94,10 +94,12 @@ export class ApiContext {
         _ApiContext_token.set(this, void 0);
         _ApiContext_userToken.set(this, void 0);
         _ApiContext_namespaceVariant.set(this, void 0);
+        _ApiContext_staticVersion.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");
+        __classPrivateFieldSet(this, _ApiContext_staticVersion, options.staticVersion, "f");
     }
     /**
      * The current configuration (may be partial if not fully set up).
@@ -129,16 +131,26 @@ export class ApiContext {
      * @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") });
+        return new ApiContext(__classPrivateFieldGet(this, _ApiContext_config, "f"), __classPrivateFieldGet(this, _ApiContext_token, "f"), {
+            userToken,
+            namespaceVariant: __classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f"),
+            staticVersion: __classPrivateFieldGet(this, _ApiContext_staticVersion, "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".
+     * @param {StaticVersion} [staticVersion] - Reads a static namespace version from the configuration, e.g. "1.60.1_70399"
+     *   turns "static" into "static-1.60.1_70399-forever-eu". When it returns undefined, the plain namespace is used.
      */
-    withNamespaceVariant(namespaceVariant) {
-        return new ApiContext(__classPrivateFieldGet(this, _ApiContext_config, "f"), __classPrivateFieldGet(this, _ApiContext_token, "f"), { userToken: __classPrivateFieldGet(this, _ApiContext_userToken, "f"), namespaceVariant });
+    withNamespaceVariant(namespaceVariant, staticVersion) {
+        return new ApiContext(__classPrivateFieldGet(this, _ApiContext_config, "f"), __classPrivateFieldGet(this, _ApiContext_token, "f"), {
+            userToken: __classPrivateFieldGet(this, _ApiContext_userToken, "f"),
+            namespaceVariant,
+            staticVersion,
+        });
     }
     /**
      * Obtains a client credentials access token, reusing the cached one while it is valid.
@@ -238,11 +250,14 @@ export class ApiContext {
         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) {
+_ApiContext_config = new WeakMap(), _ApiContext_token = new WeakMap(), _ApiContext_userToken = new WeakMap(), _ApiContext_namespaceVariant = new WeakMap(), _ApiContext_staticVersion = 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}`;
+    if (!isBase || !__classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f"))
+        return `${namespace}-${region}`;
+    const version = namespace === "static" ? __classPrivateFieldGet(this, _ApiContext_staticVersion, "f")?.call(this, __classPrivateFieldGet(this, _ApiContext_config, "f")) : undefined;
+    return version
+        ? `${namespace}-${version}-${__classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f")}-${region}`
+        : `${namespace}-${__classPrivateFieldGet(this, _ApiContext_namespaceVariant, "f")}-${region}`;
 }, _ApiContext_send = async function _ApiContext_send(url, namespaceHeader, userScoped) {
     if (userScoped && !__classPrivateFieldGet(this, _ApiContext_userToken, "f")) {
         throw new MissingUserTokenError();

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

@@ -26,7 +26,7 @@ export type Locales = "en_US" | "es_MX" | "pt_BR" | "en_GB" | "es_ES" | "fr_FR"
  */
 export type Namespaces = "static" | "dynamic" | "profile" | //Retail
 "static-classic1x" | "dynamic-classic1x" | "profile-classic1x" | //Classic
-"static-classic" | "dynamic-classic" | "profile-classic";
+"static-classic" | "dynamic-classic" | "profile-classic" | "static-forever" | "dynamic-forever" | "profile-forever";
 /**
  * Represents a reference (link) with a URL.
  */

package/esm/src/wow/game_data/achievement.d.ts

@@ -25,6 +25,8 @@ export interface AchievementCategory extends LinkSelfHref {
     name: LocalizedString;
     achievements?: KeyNameId[];
     parent_category?: KeyNameId;
+    /** Absent when the category has no subcategories. */
+    subcategories?: KeyNameId[];
     is_guild_category: boolean;
     aggregates_by_faction: AggregatesByFaction;
     display_order: number;
@@ -45,6 +47,8 @@ export interface Achievement extends LinkSelfHref {
         amount: number;
     };
     next_achievement?: KeyNameId;
+    /** Absent when the achievement grants no reward. */
+    reward_description?: LocalizedString;
     media: KeyId;
     display_order: number;
 }

package/esm/src/wow/game_data/item.d.ts

@@ -54,8 +54,10 @@ export interface Item extends LinkSelfHref {
         item_subclass: KeyNameId;
         inventory_type: TypeName;
         binding: TypeName;
-        unique_equipped: string;
-        weapon: {
+        /** Absent for items that are not unique-equipped. */
+        unique_equipped?: string;
+        /** Absent for non-weapon items. */
+        weapon?: {
             damage: {
                 min_value: number;
                 max_value: number;
@@ -77,10 +79,26 @@ export interface Item extends LinkSelfHref {
                 display_string: LocalizedString;
             };
         };
-        stats: {
+        /** Absent for non-armor items. */
+        armor?: {
+            value: number;
+            display: {
+                display_string: LocalizedString;
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                    a: number;
+                };
+            };
+        };
+        /** Absent for items without stats, such as non-equippable items. */
+        stats?: {
             type: TypeName;
             value: number;
             is_negated?: boolean;
+            /** Present on "Equip:" bonus stats, such as spell power. */
+            is_equip_bonus?: boolean;
             display: {
                 display_string: LocalizedString;
                 color: {
@@ -91,11 +109,13 @@ export interface Item extends LinkSelfHref {
                 };
             };
         }[];
-        spells: {
+        /** Absent for items without spells. */
+        spells?: {
             spell: KeyNameId;
             description: LocalizedString;
         }[];
-        requirements: {
+        /** Absent for items without requirements. */
+        requirements?: {
             level: {
                 value: number;
                 display_string: LocalizedString;
@@ -105,10 +125,13 @@ export interface Item extends LinkSelfHref {
             value: number;
             display_string: LocalizedString;
         };
-        durability: {
+        /** Absent for items without durability, such as non-equippable items. */
+        durability?: {
             value: number;
             display_string: LocalizedString;
         };
+        /** Present on some items, such as companion pets. */
+        is_subclass_hidden?: boolean;
         sell_price?: {
             value: number;
             display_strings: {

package/esm/src/wow/game_data/mount.d.ts

@@ -8,7 +8,8 @@ export interface Mount extends LinkSelfHref {
     id: number;
     name: LocalizedString;
     creature_displays: KeyId[];
-    description: LocalizedString;
+    /** null for mounts without a description. */
+    description: LocalizedString | null;
     source: TypeName;
     faction?: TypeName;
     should_exclude_if_uncollected?: boolean;

package/esm/src/wow/game_data/reputations.d.ts

@@ -1,5 +1,5 @@
 import type { ApiContext } from "../../shared/index.js";
-import type { KeyId, KeyNameId, LinkSelfHref, LocalizedString } from "../../shared/index.js";
+import type { KeyId, KeyNameId, LinkSelfHref, LocalizedString, TypeName } from "../../shared/index.js";
 export interface ReputationFactions extends LinkSelfHref {
     factions: KeyNameId[];
     root_factions: KeyNameId[];
@@ -9,6 +9,12 @@ export interface ReputationFaction extends LinkSelfHref {
     name: LocalizedString;
     description: LocalizedString;
     reputation_tiers: KeyId;
+    /** Present for header factions, which group the sub-factions in `factions`. */
+    is_header?: boolean;
+    /** The sub-factions; present for header factions. */
+    factions?: KeyNameId[];
+    /** The faction's player faction; present for header factions. */
+    player_faction?: TypeName;
 }
 export interface ReputationTiers extends LinkSelfHref {
     reputation_tiers: {

package/esm/src/wow/game_data/talent.d.ts

@@ -9,7 +9,8 @@ export interface SpellTooltip {
     spell: KeyNameId;
     description: string;
     cast_time: string;
-    power_cost?: string;
+    /** null for abilities without a power cost. */
+    power_cost?: string | null;
     range?: string;
     cooldown?: string;
 }
@@ -80,7 +81,10 @@ export interface Talent extends LinkSelfHref {
         description: LocalizedString | null;
     }[];
     spell: KeyNameId;
-    playable_class: KeyId;
+    playable_class: KeyId & {
+        /** Absent when the talent is not tied to a class (id 0). */
+        name?: string;
+    };
     playable_specialization?: KeyNameId;
 }
 export interface PvpTalents extends LinkSelfHref {

package/esm/src/wow/profile/character_statistics.d.ts

@@ -76,6 +76,10 @@ export interface CharacterStatistics extends LinkSelfHref {
         base: number;
         effective: number;
     };
+    frost_resistance?: {
+        base: number;
+        effective: number;
+    };
     fire_resistance?: {
         base: number;
         effective: number;

package/esm/src/wow_forever/account.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WoW: Forever versions of the Retail account profile endpoints whose Forever responses differ from Retail.
+ * Each one makes the same request as the Retail endpoint, but returns a Forever type.
+ * Verified against the live API (EU) on 2026-11-02, before launch.
+ */
+import type { ApiContext } from "../shared/index.js";
+import type { AccountCharacter, AccountProfileSummary, AccountTransmogsCollection } from "../wow/profile/account_profile.js";
+/**
+ * A Forever character in the account profile. Forever is realmless: characters have a two-part name (`name` and
+ * `surname`, unique per region) and no realm. The `character` link is realmless too
+ * (`/profile/wow/character/{name}-{surname}`). The hidden realm is the first part of the `protected_character` id.
+ */
+export interface ForeverAccountCharacter extends Omit<AccountCharacter, "realm"> {
+    /** The second part of the character's name. */
+    surname: string;
+}
+/** Account profile summary as returned for Forever. */
+export interface ForeverAccountProfileSummary extends Omit<AccountProfileSummary, "wow_accounts" | "houses"> {
+    wow_accounts: {
+        id: number;
+        characters: ForeverAccountCharacter[];
+    }[];
+}
+/** Account transmog collection as returned for Forever. */
+export interface ForeverAccountTransmogsCollection extends Omit<AccountTransmogsCollection, "appearance_sets"> {
+    /** Absent when the account has collected no appearance sets. */
+    appearance_sets?: AccountTransmogsCollection["appearance_sets"];
+}
+/**
+ * Returns a profile summary for an account, including its WoW accounts and Forever characters.
+ * Requires a user access token (client.forUser(token)).
+ *
+ * @returns A promise that resolves to an object representing the account profile summary.
+ */
+export declare function accountProfileSummary(ctx: ApiContext): Promise<ForeverAccountProfileSummary>;
+/**
+ * Returns the transmog appearances and sets collected by an account.
+ * Requires a user access token (client.forUser(token)).
+ *
+ * @returns A promise that resolves to an object representing the account's transmogs.
+ */
+export declare function accountTransmogsCollection(ctx: ApiContext): Promise<ForeverAccountTransmogsCollection>;

package/esm/src/wow_forever/account.js

@@ -0,0 +1,24 @@
+/**
+ * WoW: Forever versions of the Retail account profile endpoints whose Forever responses differ from Retail.
+ * Each one makes the same request as the Retail endpoint, but returns a Forever type.
+ * Verified against the live API (EU) on 2026-11-02, before launch.
+ */
+import { accountProfileSummary as retailAccountProfileSummary, accountTransmogsCollection as retailAccountTransmogsCollection, } from "../wow/profile/account_profile.js";
+/**
+ * Returns a profile summary for an account, including its WoW accounts and Forever characters.
+ * Requires a user access token (client.forUser(token)).
+ *
+ * @returns A promise that resolves to an object representing the account profile summary.
+ */
+export async function accountProfileSummary(ctx) {
+    return await retailAccountProfileSummary(ctx);
+}
+/**
+ * Returns the transmog appearances and sets collected by an account.
+ * Requires a user access token (client.forUser(token)).
+ *
+ * @returns A promise that resolves to an object representing the account's transmogs.
+ */
+export async function accountTransmogsCollection(ctx) {
+    return await retailAccountTransmogsCollection(ctx);
+}