@blizzard-api/client
This package provides a client that is meant to be used together with one or more of the packages dedicated to a blizzard game.
Currently available packages are:
@blizzard-api/classic-wow@blizzard-api/d3@blizzard-api/hs@blizzard-api/sc2@blizzard-api/wow
Installation
npm i @blizzard-api/client
Usage
import { createBlizzardApiClient } from '@blizzard-api/client';
//or
import createBlizzardApiClient from '@blizzard-api/client';
import { wow } from '@blizzard-api/wow';
const client = await createBlizzardApiClient({
key: 'environment.blizzardClientId',
secret: 'environment.blizzardClientSecret',
origin: 'eu',
});
//Response will automatically be typed with the appropriate values
const response = await client.sendRequest(wow.commodities());
console.log(response);
^ typeof AuctionHouseCommoditiesResponse
Client options
createBlizzardApiClient accepts a ClientOptions object:
| Option | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Your Blizzard API client ID. |
secret | string | Yes | Your Blizzard API client secret. |
origin | Origins | Yes | The region to talk to, e.g. 'eu', 'us', 'kr', 'tw', 'cn'. |
locale | Locales | No | The locale to request responses in, e.g. 'en_GB'. Defaults to a sensible locale for the origin. |
token | string | No | A pre-existing access token. If supplied it is validated and reused when still valid. |
kyOptions | KyOptions | No | Options forwarded to the underlying ky instance. |
Automatic token refresh
createBlizzardApiClient takes an optional second argument, onTokenRefresh, that controls how access tokens are managed:
true(default) — the client obtains a token on creation and automatically schedules a refresh shortly before it expires.false— the client is returned without obtaining or scheduling any token. You are responsible for callinggetAccessToken/setAccessTokenyourself.(token: AccessToken) => void— behaves liketrue, but your callback is invoked with each newly obtained token (useful for persisting it).
const client = await createBlizzardApiClient({ key, secret, origin: 'eu' }, (token) => {
console.log('Refreshed token', token.access_token);
});
If a token is provided in the options, it is validated first. A still-valid token is reused and a refresh is scheduled for when it nears expiry; an expired or invalid token is refreshed immediately. Refresh timers are unref'd, so they never keep your process alive.
Sending requests
Pass a resource from one of the game packages to sendRequest. The response type is inferred from the resource, and per-request overrides can be supplied:
import { wow } from '@blizzard-api/wow';
const response = await client.sendRequest(wow.commodities(), {
locale: 'de_DE',
// Any other ClientOptions field can be overridden per request,
// including kyOptions for retries, timeouts, hooks, etc.
kyOptions: { timeout: 10_000 },
});
sendRequest resolves to undefined for endpoints that return 204 No Content or an empty body.
API
The client returned by createBlizzardApiClient (an instance of BlizzardApiClient) exposes:
| Member | Description |
|---|---|
defaults | The resolved default key, secret, origin, locale, and current token. |
sendRequest(resource, options?) | Send a request for a resource and return its typed response (or undefined for empty responses). |
getAccessToken(options?) | Request a new access token using the client-credentials flow. |
refreshAccessToken(options?) | Request a new access token and store it on the client. |
validateAccessToken(options?) | Validate an access token against Blizzard's OAuth endpoint. |
setAccessToken(token) | Manually set the access token used for subsequent requests. |
getRequestUrl(resource, options?) | Build the request URL for a resource without sending it. |
getRequestConfig(resource, options?) | Build the headers and search params for a resource without sending it. |
Authentication
Please refer to the battle.net documentation for guides on how to obtain Blizzard API credentials.