@pinta365/blizzard_api 0.3.9 → 0.5.0

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

@@ -0,0 +1,95 @@
+/**
+ * Custom error class representing an API error.
+ * @class
+ * @extends {Error}
+ */
+export 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;
+    }
+}
+/**
+ * Custom error class representing an Authentication error.
+ * @class
+ * @extends {Error}
+ */
+export 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;
+    }
+}
+/**
+ * Custom error class representing a missing client id error.
+ * @class
+ * @extends {Error}
+ */
+export class MissingClientIdError extends Error {
+    constructor() {
+        super("Client Id must be setup. Check documentation");
+        this.name = "MissingClientIdError";
+    }
+}
+/**
+ * Custom error class representing a missing client secret error.
+ * @class
+ * @extends {Error}
+ */
+export class MissingClientSecretError extends Error {
+    constructor() {
+        super("Client Secret must be setup. Check documentation");
+        this.name = "MissingClientSecretError";
+    }
+}
+/**
+ * Custom error class representing a missing api region error.
+ * @class
+ * @extends {Error}
+ */
+export class MissingRegionError extends Error {
+    constructor() {
+        super("Api region must be setup. Check documentation");
+        this.name = "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}
+ */
+export class MissingUserTokenError extends Error {
+    constructor() {
+        super("This endpoint requires a user access token. Use client.forUser(token). Check documentation");
+        this.name = "MissingUserTokenError";
+    }
+}

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

@@ -0,0 +1,2 @@
+export { apiBaseUrl, ApiContext, assertConfig, oauthBaseUrl } from "./context.js";
+export { bindAll } from "./bind.js";

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

@@ -0,0 +1,2 @@
+//types.ts
+export {};

package/esm/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/esm/src/starcraft2/community/account.js

@@ -0,0 +1,15 @@
+/**
+ * This module provides the StarCraft II account endpoint (player) using the Blizzard API.
+ */
+/**
+ * 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 async function player(ctx, accountId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/player/${accountId}`,
+    });
+}

package/esm/src/starcraft2/community/ladder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This module provides the StarCraft II ladder endpoints (grandmaster leaderboard and season) using the Blizzard API.
+ */
+import type { ApiContext } from "../../shared/index.js";
+import type { Sc2LadderTeam } from "./profile.js";
+export interface Sc2GrandmasterLeaderboard {
+    ladderTeams: Sc2LadderTeam[];
+}
+export interface Sc2Season {
+    seasonId: number;
+    number: number;
+    year: number;
+    startDate: string;
+    endDate: string;
+}
+/**
+ * Returns the grandmaster leaderboard for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the grandmaster leaderboard.
+ */
+export declare function grandmasterLeaderboard(ctx: ApiContext, regionId: number): Promise<Sc2GrandmasterLeaderboard>;
+/**
+ * Returns the current season for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the season.
+ */
+export declare function season(ctx: ApiContext, regionId: number): Promise<Sc2Season>;

package/esm/src/starcraft2/community/ladder.js

@@ -0,0 +1,27 @@
+/**
+ * This module provides the StarCraft II ladder endpoints (grandmaster leaderboard and season) using the Blizzard API.
+ */
+/**
+ * Returns the grandmaster leaderboard for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the grandmaster leaderboard.
+ */
+export async function grandmasterLeaderboard(ctx, regionId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/ladder/grandmaster/${regionId}`,
+    });
+}
+/**
+ * Returns the current season for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the season.
+ */
+export async function season(ctx, regionId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/ladder/season/${regionId}`,
+    });
+}

package/esm/src/starcraft2/community/legacy.d.ts

@@ -0,0 +1,206 @@
+/**
+ * This module provides the legacy StarCraft II community endpoints (profile, ladders, matches, ladder, achievements and
+ * rewards) using the Blizzard API.
+ */
+import type { ApiContext } from "../../shared/index.js";
+export interface Sc2LegacyIcon {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    offset: number;
+    url: string;
+}
+export interface Sc2LegacyCharacter {
+    id: string;
+    realm: number;
+    region: number;
+    displayName: string;
+    clanName: string;
+    clanTag: string;
+    profilePath: string;
+}
+export interface Sc2LegacyCareer {
+    primaryRace: string;
+    terranWins: number;
+    protossWins: number;
+    zergWins: number;
+    highest1v1Rank: string | null;
+    highestTeamRank: string | null;
+    seasonTotalGames: number;
+    careerTotalGames: number;
+}
+export interface Sc2LegacySwarmLevel {
+    level: number;
+    totalLevelXP: number;
+    currentLevelXP: number;
+}
+export interface Sc2LegacySwarmLevels {
+    level: number;
+    terran: Sc2LegacySwarmLevel;
+    zerg: Sc2LegacySwarmLevel;
+    protoss: Sc2LegacySwarmLevel;
+}
+export interface Sc2LegacySeason {
+    seasonId: number;
+    seasonNumber: number;
+    seasonYear: number;
+    totalGamesThisSeason: number;
+    stats: {
+        type: string;
+        wins: number;
+        games: number;
+    }[];
+}
+export interface Sc2LegacyAchievementsSummary {
+    points: {
+        totalPoints: number;
+        categoryPoints: Record<string, number>;
+    };
+    achievements: {
+        achievementId: string;
+        completionDate: number;
+    }[];
+}
+export interface Sc2LegacyProfile {
+    id: string;
+    realm: number;
+    displayName: string;
+    clanName: string;
+    clanTag: string;
+    profilePath: string;
+    portrait: Sc2LegacyIcon;
+    career: Sc2LegacyCareer;
+    swarmLevels: Sc2LegacySwarmLevels;
+    campaign: Record<string, unknown>;
+    season: Sc2LegacySeason;
+    rewards: {
+        selected: string[];
+        earned: string[];
+    };
+    achievements: Sc2LegacyAchievementsSummary;
+}
+export interface Sc2LegacyLadderGroup {
+    ladder: unknown[];
+    characters: Sc2LegacyCharacter[];
+    nonRanked: {
+        mmq: string;
+        gamesPlayed: number;
+    }[];
+}
+export interface Sc2LegacyLadders {
+    currentSeason: Sc2LegacyLadderGroup[];
+    previousSeason: Sc2LegacyLadderGroup[];
+    showcasePlacement: Sc2LegacyLadderGroup[];
+}
+export interface Sc2LegacyMatch {
+    map: string;
+    type: string;
+    decision: string;
+    speed: string;
+    date: number;
+}
+export interface Sc2LegacyMatches {
+    matches: Sc2LegacyMatch[];
+}
+export interface Sc2LegacyLadder {
+    ladderMembers: {
+        character: Sc2LegacyCharacter;
+        joinTimestamp: number;
+        points: number;
+        wins: number;
+        losses: number;
+        highestRank: number;
+        previousRank: number;
+        favoriteRaceP1: string;
+    }[];
+}
+export interface Sc2LegacyAchievement {
+    title: string;
+    description: string;
+    achievementId: string;
+    categoryId: string;
+    points: number;
+    icon: Sc2LegacyIcon;
+}
+export interface Sc2LegacyAchievementCategory {
+    title: string;
+    categoryId: string;
+    featuredAchievementId: string;
+    children?: {
+        title: string;
+        categoryId: string;
+        featuredAchievementId: string;
+    }[];
+}
+export interface Sc2LegacyAchievements {
+    achievements: Sc2LegacyAchievement[];
+    categories: Sc2LegacyAchievementCategory[];
+}
+export interface Sc2LegacyReward {
+    title: string;
+    id: string;
+    icon: Sc2LegacyIcon;
+    achievementId: string;
+}
+export interface Sc2LegacyRewards {
+    portraits: Sc2LegacyReward[];
+    terranDecals: Sc2LegacyReward[];
+    zergDecals: Sc2LegacyReward[];
+    protossDecals: Sc2LegacyReward[];
+    skins: (Sc2LegacyReward & {
+        name: string;
+    })[];
+    animations: (Sc2LegacyReward & {
+        command: string;
+    })[];
+}
+/**
+ * Returns the legacy StarCraft II profile of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy profile.
+ */
+export declare function legacyProfile(ctx: ApiContext, regionId: number, realmId: number, profileId: number): Promise<Sc2LegacyProfile>;
+/**
+ * Returns the legacy StarCraft II ladders of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy ladders.
+ */
+export declare function legacyLadders(ctx: ApiContext, regionId: number, realmId: number, profileId: number): Promise<Sc2LegacyLadders>;
+/**
+ * Returns the legacy StarCraft II matches of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy matches.
+ */
+export declare function legacyMatches(ctx: ApiContext, regionId: number, realmId: number, profileId: number): Promise<Sc2LegacyMatches>;
+/**
+ * Returns a legacy StarCraft II ladder.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param ladderId - The unique identifier for the ladder.
+ * @returns A promise that resolves to an object representing the legacy ladder.
+ */
+export declare function legacyLadder(ctx: ApiContext, regionId: number, ladderId: string): Promise<Sc2LegacyLadder>;
+/**
+ * Returns the legacy StarCraft II achievements for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the legacy achievements.
+ */
+export declare function legacyAchievements(ctx: ApiContext, regionId: number): Promise<Sc2LegacyAchievements>;
+/**
+ * Returns the legacy StarCraft II rewards for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the legacy rewards.
+ */
+export declare function legacyRewards(ctx: ApiContext, regionId: number): Promise<Sc2LegacyRewards>;

package/esm/src/starcraft2/community/legacy.js

@@ -0,0 +1,83 @@
+/**
+ * This module provides the legacy StarCraft II community endpoints (profile, ladders, matches, ladder, achievements and
+ * rewards) using the Blizzard API.
+ */
+/**
+ * Returns the legacy StarCraft II profile of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy profile.
+ */
+export async function legacyProfile(ctx, regionId, realmId, profileId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/profile/${regionId}/${realmId}/${profileId}`,
+    });
+}
+/**
+ * Returns the legacy StarCraft II ladders of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy ladders.
+ */
+export async function legacyLadders(ctx, regionId, realmId, profileId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/profile/${regionId}/${realmId}/${profileId}/ladders`,
+    });
+}
+/**
+ * Returns the legacy StarCraft II matches of a player.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param realmId - The realm: 1 or 2.
+ * @param profileId - The unique identifier for the profile.
+ * @returns A promise that resolves to an object representing the legacy matches.
+ */
+export async function legacyMatches(ctx, regionId, realmId, profileId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/profile/${regionId}/${realmId}/${profileId}/matches`,
+    });
+}
+/**
+ * Returns a legacy StarCraft II ladder.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @param ladderId - The unique identifier for the ladder.
+ * @returns A promise that resolves to an object representing the legacy ladder.
+ */
+export async function legacyLadder(ctx, regionId, ladderId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/ladder/${regionId}/${ladderId}`,
+    });
+}
+/**
+ * Returns the legacy StarCraft II achievements for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the legacy achievements.
+ */
+export async function legacyAchievements(ctx, regionId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/data/achievements/${regionId}`,
+    });
+}
+/**
+ * Returns the legacy StarCraft II rewards for a region.
+ *
+ * @param regionId - The region: 1=US, 2=EU, 3=KR/TW, 5=CN.
+ * @returns A promise that resolves to an object representing the legacy rewards.
+ */
+export async function legacyRewards(ctx, regionId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/sc2/legacy/data/rewards/${regionId}`,
+    });
+}