@blizzard-api/client

@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 calling getAccessToken/setAccessToken yourself.
• (token: AccessToken) => void — behaves like true, 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.