JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Blizzard.js

    A promise-based Node.JS library for the Blizzard Battle.net Community Platform API
    Filed under  › 

    • 🔾24%Overall
    • 125
    • 9.4 days
    • 🕩28
    • 👥5

    Blizzard.js

    Blizzard.js is a promise-based Node.js library for the Blizzard Community Platform API written with TypeScript.

    Install

    Install blizzard.js and save to your package.json dependencies in one easy step:

    With npm:

    $ npm install blizzard.js
    

    With yarn:

    $ yarn add blizzard.js
    

    Battle.net API Key

    Please refer to the documentation at the Blizzard Developer Portal to obtain Blizzard API credentials.

    Usage

    Game Clients

    All game clients are available via their named export.

    • Diablo 3: d3
    • Hearthstone: hs
    • Starcraft 2: sc2
    • World of Warcraft (Retail): wow
    • World of Warcraft (Classic): wow.classic

    With TypeScript & ES modules

    import { wow } from 'blizzard.js'
    
    const wowClient = await wow.createInstance({
      key: BLIZZARD_CLIENT_ID,
      secret: BLIZZARD_CLIENT_SECRET,
      origin: 'us', // optional
      locale: 'en_US' // optional
      token: '' // optional
    })
    

    With CommonJS

    const blizzard = require('blizzard.js')
    
    const wowClient = await blizzard.wow.createInstance({
      key: BLIZZARD_CLIENT_ID,
      secret: BLIZZARD_CLIENT_SECRET,
      origin: 'us', // optional
      locale: 'en_US' // optional
      token: '' // optional
    });
    

    API Methods

    All API methods can accept the same key, secret, token, origin, locale parameters as createInstance, for cases where you need to use different values to the default.

    Method parameters are encoded with encodeURIComponent for URL safety. Sanitizing your inputs is still important, but just be aware in case certain requests fail for this reason.

    Refer to the resource references for the available methods and parameters:

    User Tokens

    Certain protected profile requests for World of Warcraft require a user token provisioned by the OAuth 2.0 Authorization Code Flow. This is outside the scope of blizzard.js and a OAuth library like passport is highly recommended.

    Application Tokens

    In most cases you shouldn't need to handle the application token yourself. Instantiating a game client with createInstance will fetch a token if the initial value is undefined, and refresh the token when it expires (typically valid for 24hrs).

    If a token value is provided, the client will simply validate and only refresh if it's expired/invalid. Passing an optional callback funtion as the 2nd argument to createInstance will return the token object when it is refreshed, allowing you to listen for changes if you are managing the token state manually.

    const wow = await createInstance(
      {
        key: BLIZZARD_CLIENT_ID,
        secret: BLIZZARD_CLIENT_SECRET,
      },
      (token) => {
        // {
        //   access_token: string
        //   token_type: 'bearer'
        //   expires_in: number (in seconds)
        // }
      },
    )
    

    To completely disable validating/refreshing the application token, pass false to the 2nd argument.

    const wow = await createInstance(
      {
        key: BLIZZARD_CLIENT_ID,
        secret: BLIZZARD_CLIENT_SECRET,
      },
      false,
    )
    

    By opting out of the default application token handling, it is your responsibility to manage application tokens as required with the available methods

    Validate

    const validateTokenRequest = await wow.validateApplicationToken({
      token: 'string',
    })
    
    // validateTokenRequest.data =>
    // {
    //   scope: [],
    //   exp: number (in seconds),
    //   authorities: [
    //     {
    //       authority: string,
    //     },
    //   ],
    //   client_id: string,
    // }
    

    Automatic Get & Set

    await wow.refreshApplicationToken()
    

    Manual Get & Set

    const getTokenRequest = await wow.getApplicationToken()
    
    // getTokenRequest.data =>
    // {
    //   access_token: string,
    //   token_type: 'bearer',
    //   expires_in: number (in seconds),
    // }
    
    wow.setApplicationToken(getTokenRequest.data.access_token)
    
    Show All