@pinta365/blizzard_api 0.3.9 → 0.5.0

package/README.md

@@ -2,35 +2,29 @@
 
 [![JSR Version](https://jsr.io/badges/@pinta365/blizzard-api)](https://jsr.io/@pinta365/blizzard-api)
 
-Start of what will cover the whole Blizzard Battle.net API when its done.
+TypeScript client for the Blizzard Battle.net APIs: World of Warcraft (Retail, Classic and Classic Era), Hearthstone,
+StarCraft II and Diablo III. Runs on Deno, Node.js, Bun and in the browser.
 
 Available as:
 
 - ESM module: [JSR](https://jsr.io/@pinta365/blizzard-api)
 - CommonJS module: [NPM](https://www.npmjs.com/package/@pinta365/blizzard_api)
 
-## WORK IN PROGRESS
-
-Let me know if you want certain APIs to be prioritized. Currently only supports client credentials flow but the plan is
-to implement authorization code flow also.
-
 ### APIs implemented
 
-| APIs                                          | Status | Note                      |
-| --------------------------------------------- | ------ | ------------------------- |
-| **World of Warcraft:** Game Data APIs         | ✅     |                           |
-| **World of Warcraft:** Profile APIs           | ✅     |                           |
-|                                               |        |                           |
-| **World of Warcraft Classic:** Game Data APIs |        |                           |
-| **World of Warcraft Classic:** Profile APIs   |        |                           |
-|                                               |        |                           |
-| **Diablo III:** Community APIs                | ✅     | Missing profile endpoints |
-| **Diablo III:** Game Data APIs                | ✅     |                           |
-|                                               |        |                           |
-| **Hearthstone:** Game Data APIs               | ✅     |                           |
-|                                               |        |                           |
-| **StarCraft II:** Community APIs              |        |                           |
-| **StarCraft II:** Game Data APIs              | ✅     |                           |
+| APIs                                        | Status | Note                                                 |
+| ------------------------------------------- | ------ | ---------------------------------------------------- |
+| **World of Warcraft:** Game Data APIs       | ✅     | Including housing, item appearances, hero talents    |
+| **World of Warcraft:** Profile APIs         | ✅     | Account profile endpoints need a user token          |
+| **World of Warcraft Classic:** Game Data    | ✅     | Progression (`wowClassic`) and Era (`wowClassicEra`) |
+| **World of Warcraft Classic:** Profile APIs | ✅     | Progression (`wowClassic`) and Era (`wowClassicEra`) |
+| **Diablo III:** Community APIs              | ✅     | Including account and hero profiles                  |
+| **Diablo III:** Game Data APIs              | ✅     |                                                      |
+| **Hearthstone:** Game Data APIs             | ✅     |                                                      |
+| **StarCraft II:** Community APIs            | ✅     | Including the legacy endpoints                       |
+| **StarCraft II:** Game Data APIs            | ✅     |                                                      |
+
+Every endpoint is checked against the live API by the project's smoke test.
 
 ## ⚡️ Quickstart
 
@@ -38,7 +32,7 @@ to implement authorization code flow also.
 
 ```bash
 # Deno
-deno add @pinta365/blizzard-api
+deno add jsr:@pinta365/blizzard-api
 
 # Bun
 bunx jsr add @pinta365/blizzard-api
@@ -50,31 +44,145 @@ npx jsr add @pinta365/blizzard-api
 npm install @pinta365/blizzard_api --save
 ```
 
-**Basic Usage (ESM)**
+**Usage**
 
-```javascript
-import * as blizzardAPI from "@pinta365/blizzard-api";
+Create an API client at <https://develop.battle.net/access/clients> to get a client ID and secret.
 
-const clientId = "<YOUR CLIENT ID>";
-const clientSecret = "<YOUR SECRET>";
+```ts
+import { createClient } from "@pinta365/blizzard-api";
 
-blizzardAPI.setup({
-    clientId,
-    clientSecret,
-    region: "eu",
-    locale: "en_GB",
+const client = createClient({
+    region: "eu", // "us" | "eu" | "kr" | "tw" | "cn"
+    locale: "en_GB", // optional: defaults to the main locale of the region (us: en_US, eu: en_GB, ...)
+    clientId: "<YOUR CLIENT ID>",
+    clientSecret: "<YOUR SECRET>",
 });
 
+const sword = await client.wow.item(33791);
+const realms = await client.wowClassicEra.realms();
+const card = await client.hearthstone.fetchCard("52119-arch-villain-rafaam");
+const season = await client.sc2.season(2);
+const hero = await client.diablo3.heroClass("barbarian");
+```
+
+The client fetches and caches the access token for you and renews it before it expires. Each client has its own
+configuration and token, so you can use several regions or credentials side by side.
+
+**CommonJS**
+
+```js
+const { createClient } = require("@pinta365/blizzard_api");
+```
+
+## Games and flavors
+
+| Client property        | Game                                                          |
+| ---------------------- | ------------------------------------------------------------- |
+| `client.wow`           | World of Warcraft (Retail)                                    |
+| `client.wowClassic`    | WoW Classic progression (currently Mists of Pandaria Classic) |
+| `client.wowClassicEra` | WoW Classic Era, Season of Discovery, Hardcore, Anniversary   |
+| `client.hearthstone`   | Hearthstone                                                   |
+| `client.sc2`           | StarCraft II                                                  |
+| `client.diablo3`       | Diablo III                                                    |
+
+The two Classic properties only include the endpoints Blizzard supports for that flavor.
+
+## Response types
+
+Every response has a TypeScript type. Import them from the entry point of the game:
+
+```ts
+import type { Mount } from "@pinta365/blizzard-api/wow";
+import type { Card } from "@pinta365/blizzard-api/hearthstone";
+```
+
+Entry points: `/wow`, `/wow-classic`, `/hearthstone`, `/sc2` and `/diablo3`. The Classic clients mostly return the same
+types as Retail (import those from `/wow`). `/wow-classic` holds the Classic-only ones, such as
+`ClassicCharacterProfile`, where fields that only Retail returns are optional.
+
+## Following links
+
+Responses contain `href` links to related resources. `requestHref` fetches them with the client's token:
+
+```ts
+const mount = await client.wow.mount(6);
+const display = await client.requestHref(mount.creature_displays[0].key.href);
+```
+
+## User tokens (account profile)
+
+The WoW account profile endpoints (`accountProfileSummary`, `protectedCharacterProfile` and the `account*Collection`
+endpoints) need a user access token from the OAuth authorization code flow:
+
+```ts
+// 1. Send the user to Battle.net to log in.
+const state = crypto.randomUUID(); // store it, and check it on the redirect
+const url = client.authorizeUrl({ redirectUri: "https://example.com/callback", scope: ["wow.profile"], state });
+
+// 2. On your redirect URI, exchange the code for a user token.
+const { access_token } = await client.exchangeCode({ code, redirectUri: "https://example.com/callback" });
+
+// 3. Use a user-scoped client. It is cheap to create, and it shares the app token with its parent.
+const user = client.forUser(access_token);
+const profile = await user.wow.accountProfileSummary();
+```
+
+The redirect URI must be registered on your API client. Calling a user-scoped endpoint without a user token throws
+`MissingUserTokenError`.
+
+## Errors and retries
+
+- Failed requests throw `errors.APIError`, with `statusCode` and the response body.
+- A `401` is retried once with a fresh token.
+- A `429 Too Many Requests` is retried up to three times, honouring `Retry-After`.
+- A server error (`500`, `502`, `503`, `504`) is retried once.
+
+```ts
+import { errors } from "@pinta365/blizzard-api";
+
+try {
+    await client.wow.characterProfile("silvermoon", "nosuchcharacter");
+} catch (error) {
+    if (error instanceof errors.APIError && error.statusCode === 404) {
+        // Not found
+    }
+}
+```
+
+## Module-level API
+
+The module-level API from earlier versions still works. It uses a built-in default client:
+
+```ts
+import * as blizzardAPI from "@pinta365/blizzard-api";
+
+blizzardAPI.setup({ region: "eu", locale: "en_GB", clientId, clientSecret });
 const sword = await blizzardAPI.wow.item(33791);
-console.log(sword);
 ```
 
-**Basic Usage (CommonJS)**
+## Upgrading from 0.4
 
-```javascript
-const blizzardAPI = require("@pinta365/blizzard_api");
+- `wowClassic` now targets Classic **progression**. For Classic Era realms, use `wowClassicEra`.
+- `mythicRaidLeaderboard(raid, faction)` takes a raid slug and `"alliance"` or `"horde"`, e.g. `("uldir", "alliance")`.
+- `pvpSeasonLeaderboard(seasonId, bracket)` takes a bracket name, e.g. `"3v3"` or `"shuffle-overall"`.
+- `wow`, `hearthstone` and the other namespaces are plain objects. Import types from the game entry points (see
+  [Response types](#response-types)).
+- A locale is always sent: when `locale` is not set, the region's main locale is used (`us`: `en_US`, `eu`: `en_GB`,
+  `kr`: `ko_KR`, `tw`: `zh_TW`, `cn`: `zh_CN`). Localized fields (`name`, `description`, ...) are therefore always
+  strings, and the types say so. Before, omitting `locale` returned an object with every locale.
+- Response types were checked against live responses and corrected. Fields that only some characters or flavors have are
+  now optional, so you may need to handle `undefined`.
+- Some types were renamed to remove duplicates. For example, entries of the character collections are now
+  `CollectedMount`, `CollectedPet`, `CollectedToy` and `CollectedHeirloom`.
 
-// Use blizzardAPI the same way as in the previous example.
+## Development
+
+```bash
+deno task test        # offline unit tests
+deno task smoke       # live smoke test of every endpoint (needs .env with BLIZZARD_CLIENT_ID / BLIZZARD_CLIENT_SECRET)
+deno task gen:api     # regenerate src/generated/ after adding or changing endpoints
+deno task check:types # check the response types against the responses saved by the smoke test (fixtures/)
+deno task check:fields # list fields the API returns that the response types don't declare
 ```
 
 ## Issues

package/esm/mod.d.ts

@@ -1,7 +1,44 @@
-import { authenticate, getAccessToken, getAuthConfig, requestHref, setup } from "./src/shared/index.js";
-import * as wow from "./src/wow/index.js";
-import * as wowClassic from "./src/wow_classic/index.js";
-import * as hearthstone from "./src/hearthstone/index.js";
-import * as sc2 from "./src/starcraft2/index.js";
+import type { AuthConfig, ClientConfig } from "./src/shared/index.js";
+import type { Diablo3Api, HearthstoneApi, Sc2Api, WowApi, WowClassicApi, WowClassicEraApi } from "./src/client.js";
 import * as errors from "./src/shared/errors.js";
-export { authenticate, errors, getAccessToken, getAuthConfig, hearthstone, requestHref, sc2, setup, wow, wowClassic };
+export { createClient } from "./src/client.js";
+export type { BlizzardClient, Diablo3Api, HearthstoneApi, Sc2Api, WowApi, WowClassicApi, WowClassicEraApi, } from "./src/client.js";
+export type { AuthConfig, AuthorizeUrlOptions, ClientConfig, ExchangeCodeOptions, Locales, Namespaces, Regions, TokenResponse, } from "./src/shared/index.js";
+export { errors };
+/**
+ * Configures the default client used by the module-level API. Prefer createClient() for new code.
+ * @param {Partial<ClientConfig>} userConfig - Configuration properties to update.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError} If the resulting configuration is incomplete.
+ */
+export declare function setup(userConfig: Partial<ClientConfig>): void;
+/**
+ * Obtains a client credentials access token for the default client.
+ * @param {boolean} [forceNewToken] - If true, fetches a new token even if the cached one is valid.
+ */
+export declare function authenticate(forceNewToken?: boolean): Promise<string>;
+/**
+ * Returns the default client's current access token, or an empty string if not authenticated.
+ */
+export declare function getAccessToken(): string;
+/**
+ * Returns a copy of the default client's token state.
+ */
+export declare function getAuthConfig(): AuthConfig;
+/**
+ * Makes an authenticated request with the default client to a full href returned in an API response.
+ * @param {string} href - The full href URL.
+ * @param {Record<string, string | number>} [qs] - Optional query string parameters to append.
+ */
+export declare function requestHref(href: string, qs?: Record<string, string | number>): Promise<unknown>;
+/** World of Warcraft endpoints on the default client. */
+export declare const wow: WowApi;
+/** World of Warcraft Classic (progression) endpoints on the default client. */
+export declare const wowClassic: WowClassicApi;
+/** World of Warcraft Classic Era endpoints on the default client. */
+export declare const wowClassicEra: WowClassicEraApi;
+/** Hearthstone endpoints on the default client. */
+export declare const hearthstone: HearthstoneApi;
+/** StarCraft II endpoints on the default client. */
+export declare const sc2: Sc2Api;
+/** Diablo III endpoints on the default client. */
+export declare const diablo3: Diablo3Api;

package/esm/mod.js

@@ -1,7 +1,70 @@
-import { authenticate, getAccessToken, getAuthConfig, requestHref, setup } from "./src/shared/index.js";
-import * as wow from "./src/wow/index.js";
-import * as wowClassic from "./src/wow_classic/index.js";
-import * as hearthstone from "./src/hearthstone/index.js";
-import * as sc2 from "./src/starcraft2/index.js";
+/**
+ * TS library for the Blizzard Battle.net API: World of Warcraft, World of Warcraft Classic, Hearthstone,
+ * StarCraft II and Diablo III.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@pinta365/blizzard-api";
+ *
+ * const client = createClient({ region: "eu", locale: "en_GB", clientId, clientSecret });
+ * const mount = await client.wow.mount(6);
+ * ```
+ *
+ * @module
+ */
+import { ApiContext, assertConfig } from "./src/shared/index.js";
+import { clientFromContext } from "./src/client.js";
 import * as errors from "./src/shared/errors.js";
-export { authenticate, errors, getAccessToken, getAuthConfig, hearthstone, requestHref, sc2, setup, wow, wowClassic };
+export { createClient } from "./src/client.js";
+export { errors };
+// Default client behind the module-level API (setup() + wow.*, hearthstone.*, ...).
+const defaultContext = new ApiContext();
+const defaultClient = clientFromContext(defaultContext);
+/**
+ * Configures the default client used by the module-level API. Prefer createClient() for new code.
+ * @param {Partial<ClientConfig>} userConfig - Configuration properties to update.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError} If the resulting configuration is incomplete.
+ */
+export function setup(userConfig) {
+    defaultContext.configure(userConfig);
+    assertConfig({ ...defaultContext.config });
+}
+/**
+ * Obtains a client credentials access token for the default client.
+ * @param {boolean} [forceNewToken] - If true, fetches a new token even if the cached one is valid.
+ */
+export function authenticate(forceNewToken) {
+    return defaultContext.authenticate(forceNewToken);
+}
+/**
+ * Returns the default client's current access token, or an empty string if not authenticated.
+ */
+export function getAccessToken() {
+    return defaultContext.getAuthConfig().accessToken;
+}
+/**
+ * Returns a copy of the default client's token state.
+ */
+export function getAuthConfig() {
+    return defaultContext.getAuthConfig();
+}
+/**
+ * Makes an authenticated request with the default client to a full href returned in an API response.
+ * @param {string} href - The full href URL.
+ * @param {Record<string, string | number>} [qs] - Optional query string parameters to append.
+ */
+export function requestHref(href, qs) {
+    return defaultContext.requestHref(href, qs);
+}
+/** World of Warcraft endpoints on the default client. */
+export const wow = defaultClient.wow;
+/** World of Warcraft Classic (progression) endpoints on the default client. */
+export const wowClassic = defaultClient.wowClassic;
+/** World of Warcraft Classic Era endpoints on the default client. */
+export const wowClassicEra = defaultClient.wowClassicEra;
+/** Hearthstone endpoints on the default client. */
+export const hearthstone = defaultClient.hearthstone;
+/** StarCraft II endpoints on the default client. */
+export const sc2 = defaultClient.sc2;
+/** Diablo III endpoints on the default client. */
+export const diablo3 = defaultClient.diablo3;

package/esm/src/client.d.ts

@@ -0,0 +1,95 @@
+import { ApiContext } from "./shared/context.js";
+import type { AuthConfig, AuthorizeUrlOptions, ClientConfig, ExchangeCodeOptions, TokenResponse } from "./shared/context.js";
+import { type Bound } from "./shared/bind.js";
+import * as wowEndpoints from "./wow/index.js";
+import * as wowClassicEndpoints from "./wow_classic/index.js";
+import * as wowClassicEraEndpoints from "./wow_classic/era.js";
+import * as hearthstoneEndpoints from "./hearthstone/index.js";
+import * as sc2Endpoints from "./starcraft2/index.js";
+import * as diablo3Endpoints from "./diablo3/index.js";
+import type { WowApi } from "./generated/wow_api.js";
+import type { WowClassicApi } from "./generated/wow_classic_api.js";
+import type { WowClassicEraApi } from "./generated/wow_classic_era_api.js";
+import type { HearthstoneApi } from "./generated/hearthstone_api.js";
+import type { Sc2Api } from "./generated/sc2_api.js";
+import type { Diablo3Api } from "./generated/diablo3_api.js";
+export type { Diablo3Api, HearthstoneApi, Sc2Api, WowApi, WowClassicApi, WowClassicEraApi };
+type Exact<A, B> = [keyof A] extends [keyof B] ? ([keyof B] extends [keyof A] ? ([A] extends [B] ? true : false) : false) : false;
+type Assert<T extends true> = T;
+export type _GeneratedApisAreCurrent = [
+    Assert<Exact<WowApi, Bound<typeof wowEndpoints>>>,
+    Assert<Exact<WowClassicApi, Bound<typeof wowClassicEndpoints>>>,
+    Assert<Exact<WowClassicEraApi, Bound<typeof wowClassicEraEndpoints>>>,
+    Assert<Exact<HearthstoneApi, Bound<typeof hearthstoneEndpoints>>>,
+    Assert<Exact<Sc2Api, Bound<typeof sc2Endpoints>>>,
+    Assert<Exact<Diablo3Api, Bound<typeof diablo3Endpoints>>>
+];
+/**
+ * A Blizzard API client with its own configuration and token state.
+ */
+export interface BlizzardClient {
+    /** World of Warcraft endpoints. */
+    readonly wow: WowApi;
+    /** World of Warcraft Classic (progression, e.g. Mists of Pandaria Classic) endpoints. */
+    readonly wowClassic: WowClassicApi;
+    /** World of Warcraft Classic Era endpoints (Era, Season of Discovery, Hardcore, Anniversary). */
+    readonly wowClassicEra: WowClassicEraApi;
+    /** Hearthstone endpoints. */
+    readonly hearthstone: HearthstoneApi;
+    /** StarCraft II endpoints. */
+    readonly sc2: Sc2Api;
+    /** Diablo III endpoints. */
+    readonly diablo3: Diablo3Api;
+    /** The client configuration. */
+    readonly config: Readonly<Partial<ClientConfig>>;
+    /**
+     * Obtains a client credentials access token, reusing the cached one while it is valid.
+     * Requests authenticate automatically; calling this is optional.
+     * @param {boolean} [forceNewToken] - If true, fetches a new token even if the cached one is valid.
+     */
+    authenticate(forceNewToken?: boolean): Promise<string>;
+    /** Returns a copy of the client credentials token state. */
+    getAuthConfig(): AuthConfig;
+    /**
+     * Makes an authenticated request to a full href returned in an API response.
+     * @param {string} href - The full href URL.
+     * @param {Record<string, string | number>} [qs] - Optional query string parameters to append.
+     */
+    requestHref(href: string, qs?: Record<string, string | number>): Promise<unknown>;
+    /**
+     * Returns a client 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 client, so it is cheap to create per request.
+     * @param {string} userToken - A user access token, e.g. `access_token` from exchangeCode().
+     */
+    forUser(userToken: string): BlizzardClient;
+    /**
+     * Builds the URL to send a user to for the authorization code flow.
+     * @param {AuthorizeUrlOptions} options - Redirect URI, scopes (e.g. ["wow.profile"]) and state.
+     */
+    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.
+     */
+    exchangeCode(options: ExchangeCodeOptions): Promise<TokenResponse>;
+}
+/**
+ * Wraps a context in a client object.
+ * @param {ApiContext} ctx - The context to wrap.
+ * @returns {BlizzardClient} The client.
+ */
+export declare function clientFromContext(ctx: ApiContext): BlizzardClient;
+/**
+ * Creates a Blizzard API client with its own configuration and token state.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({ region: "eu", locale: "en_GB", clientId, clientSecret });
+ * const mount = await client.wow.mount(6);
+ * ```
+ *
+ * @param {ClientConfig} config - Region, locale and OAuth client credentials.
+ * @returns {BlizzardClient} The client.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError} If the configuration is incomplete.
+ */
+export declare function createClient(config: ClientConfig): BlizzardClient;

package/esm/src/client.js

@@ -0,0 +1,52 @@
+//client.ts
+import { ApiContext, assertConfig } from "./shared/context.js";
+import { bindAll } from "./shared/bind.js";
+import * as wowEndpoints from "./wow/index.js";
+import * as wowClassicEndpoints from "./wow_classic/index.js";
+import * as wowClassicEraEndpoints from "./wow_classic/era.js";
+import * as hearthstoneEndpoints from "./hearthstone/index.js";
+import * as sc2Endpoints from "./starcraft2/index.js";
+import * as diablo3Endpoints from "./diablo3/index.js";
+/**
+ * Wraps a context in a client object.
+ * @param {ApiContext} ctx - The context to wrap.
+ * @returns {BlizzardClient} The client.
+ */
+export function clientFromContext(ctx) {
+    return Object.freeze({
+        wow: bindAll(ctx, wowEndpoints),
+        wowClassic: bindAll(ctx.withNamespaceVariant("classic"), wowClassicEndpoints),
+        wowClassicEra: bindAll(ctx.withNamespaceVariant("classic1x"), wowClassicEraEndpoints),
+        // bind() keeps metadata<T> generic at runtime; the mapped Bound type cannot, so use the generated interface.
+        hearthstone: bindAll(ctx, hearthstoneEndpoints),
+        sc2: bindAll(ctx, sc2Endpoints),
+        diablo3: bindAll(ctx, diablo3Endpoints),
+        get config() {
+            return ctx.config;
+        },
+        authenticate: (forceNewToken) => ctx.authenticate(forceNewToken),
+        getAuthConfig: () => ctx.getAuthConfig(),
+        requestHref: (href, qs) => ctx.requestHref(href, qs),
+        forUser: (userToken) => clientFromContext(ctx.forUser(userToken)),
+        authorizeUrl: (options) => ctx.authorizeUrl(options),
+        exchangeCode: (options) => ctx.exchangeCode(options),
+    });
+}
+/**
+ * Creates a Blizzard API client with its own configuration and token state.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({ region: "eu", locale: "en_GB", clientId, clientSecret });
+ * const mount = await client.wow.mount(6);
+ * ```
+ *
+ * @param {ClientConfig} config - Region, locale and OAuth client credentials.
+ * @returns {BlizzardClient} The client.
+ * @throws {MissingRegionError | MissingClientIdError | MissingClientSecretError} If the configuration is incomplete.
+ */
+export function createClient(config) {
+    const copy = { ...config };
+    assertConfig(copy);
+    return clientFromContext(new ApiContext(copy));
+}

package/esm/src/diablo3/community/act.d.ts

@@ -0,0 +1,29 @@
+import type { ApiContext } from "../../shared/index.js";
+interface Quest {
+    id: number;
+    name: string;
+    slug: string;
+}
+export interface Act {
+    slug: string;
+    number: number;
+    name: string;
+    quests: Quest[];
+}
+export interface Acts {
+    acts: Act[];
+}
+/**
+ * Returns an index of acts.
+ *
+ * @returns A promise that resolves to an object representing an index of acts.
+ */
+export declare function acts(ctx: ApiContext): Promise<Acts>;
+/**
+ * Returns a single act by ID.
+ *
+ * @param seasonId - The season for the leaderboard list.
+ * @returns A promise that resolves to an object representing the data for a single act by ID.
+ */
+export declare function act(ctx: ApiContext, seasonId: number): Promise<Act>;
+export {};

package/esm/src/diablo3/community/act.js

@@ -0,0 +1,23 @@
+/**
+ * Returns an index of acts.
+ *
+ * @returns A promise that resolves to an object representing an index of acts.
+ */
+export async function acts(ctx) {
+    return await ctx.request({
+        method: "GET",
+        url: "/d3/data/act/",
+    });
+}
+/**
+ * Returns a single act by ID.
+ *
+ * @param seasonId - The season for the leaderboard list.
+ * @returns A promise that resolves to an object representing the data for a single act by ID.
+ */
+export async function act(ctx, seasonId) {
+    return await ctx.request({
+        method: "GET",
+        url: `/d3/data/act/${seasonId}`,
+    });
+}

package/esm/src/diablo3/community/artisan.d.ts

@@ -0,0 +1,50 @@
+import type { ApiContext } from "../../shared/index.js";
+interface Item {
+    id: string;
+    slug: string;
+    name: string;
+    icon: string;
+    path: string;
+}
+interface Reagent {
+    quantity: number;
+    item: Item;
+}
+export interface Recipe {
+    id: string;
+    slug: string;
+    name: string;
+    cost: number;
+    reagents: Reagent[];
+    itemProduced: Item;
+}
+interface Tier {
+    tier: number;
+    trainedRecipes: Recipe[];
+    taughtRecipes?: Recipe[];
+}
+interface Training {
+    tiers: Tier[];
+}
+export interface Artisan {
+    slug: string;
+    name: string;
+    portrait: string;
+    training: Training;
+}
+/**
+ * Returns a single artisan by slug.
+ *
+ * @param artisanSlug - The slug of the artisan to retrieve.
+ * @returns A promise that resolves to an object representing the data for a single artisan by slug.
+ */
+export declare function artisan(ctx: ApiContext, artisanSlug: string): Promise<Artisan>;
+/**
+ * Returns a single recipe by slug for the specified artisan.
+ *
+ * @param artisanSlug - The slug of the artisan to retrieve.
+ * @param recipeSlug - The slug of the recipe to retrieve.
+ * @returns A promise that resolves to an object representing the data for a single recipe by slug for the specified artisan.
+ */
+export declare function artisanRecipe(ctx: ApiContext, artisanSlug: string, recipeSlug: string): Promise<Recipe>;
+export {};

package/esm/src/diablo3/community/artisan.js

@@ -0,0 +1,25 @@
+/**
+ * Returns a single artisan by slug.
+ *
+ * @param artisanSlug - The slug of the artisan to retrieve.
+ * @returns A promise that resolves to an object representing the data for a single artisan by slug.
+ */
+export async function artisan(ctx, artisanSlug) {
+    return await ctx.request({
+        method: "GET",
+        url: `/d3/data/artisan/${artisanSlug}`,
+    });
+}
+/**
+ * Returns a single recipe by slug for the specified artisan.
+ *
+ * @param artisanSlug - The slug of the artisan to retrieve.
+ * @param recipeSlug - The slug of the recipe to retrieve.
+ * @returns A promise that resolves to an object representing the data for a single recipe by slug for the specified artisan.
+ */
+export async function artisanRecipe(ctx, artisanSlug, recipeSlug) {
+    return await ctx.request({
+        method: "GET",
+        url: `/d3/data/artisan/${artisanSlug}/recipe/${recipeSlug}`,
+    });
+}

package/esm/src/diablo3/community/follower.d.ts

@@ -0,0 +1,25 @@
+import type { ApiContext } from "../../shared/index.js";
+interface FollowerSkill {
+    slug: string;
+    name: string;
+    icon: string;
+    level: number;
+    tooltipUrl: string;
+    description: string;
+    descriptionHtml: string;
+}
+export interface Follower {
+    slug: string;
+    name: string;
+    realName: string;
+    portrait: string;
+    skills: FollowerSkill[];
+}
+/**
+ * Returns a single follower by slug.
+ *
+ * @param followerSlug - The slug of the follower to retrieve.
+ * @returns A promise that resolves to an object representing the data for a single follower by slug.
+ */
+export declare function follower(ctx: ApiContext, followerSlug: string): Promise<Follower>;
+export {};