@blizzard-api/client/dist/index.d.ts

A node.js client to integrate with the blizzard battle.net api.

import { Locales, Origins, Resource, ResourceResponse, getBlizzardApi } from "@blizzard-api/core";
import { Options } from "ky";

//#region src/client/types.d.ts
/**
 * An access token response from the Blizzard API.
 * @see https://develop.battle.net/documentation/guides/using-oauth
 * @see https://develop.battle.net/documentation/guides/using-oauth/client-credentials-flow¨
 * @example
 * const response: AccessToken = {
 *  access_token: 'access-token',
 *  token_type: 'bearer',
 *  expires_in: 86399,
 *  sub: 'client-id',
 * };
 */
interface AccessToken {
  access_token: string;
  expires_in: number;
  sub?: string;
  token_type: 'bearer';
}
/**
 * An access token request.
 * @see https://develop.battle.net/documentation/guides/using-oauth/client-credentials-flow
 * @example
 * const request: AccessTokenRequestArguments = {
 *  origin: 'eu',
 *  key: 'client',
 *  secret: 'secret'
 * };
 */
interface AccessTokenRequestArguments {
  key?: string;
  origin?: Origins;
  secret?: string;
}
/**
 * A client configuration object.
 * @example
 * const options: ClientOptions = {
 *  key: 'client',
 *  kyOptions: { ... },
 *  secret: 'secret',
 *  origin: 'eu',
 *  locale: 'en_GB',
 *  token: 'access'
 * };
 */
interface ClientOptions {
  key: string;
  kyOptions?: Options;
  locale?: Locales;
  origin: Origins;
  secret: string;
  token?: string;
}
/**
 * Validate an access token.
 * @see https://develop.battle.net/documentation/guides/using-oauth/client-credentials-flow
 * @example
 * const request: ValidateAccessTokenArguments = {
 *  origin: 'eu',
 *  token: 'access'
 * };
 */
interface ValidateAccessTokenArguments {
  origin?: Origins;
  token?: string;
}
/**
 * A response from validating an access token.
 * @see https://develop.battle.net/documentation/guides/using-oauth/client-credentials-flow
 * @example
 * const response: ValidateAccessTokenResponse = {
 *  scope: ['wow.profile'],
 *  account_authorities: [],
 *  exp: 1617000000,
 *  client_authorities: [],
 *  authorities: ['wow.profile'],
 *  client_id: 'client'
 * };
 */
interface ValidateAccessTokenResponse {
  account_authorities: Array<unknown>;
  authorities: Array<string>;
  client_authorities: Array<unknown>;
  client_id: string;
  exp: number;
  scope: Array<string>;
}
//#endregion
//#region src/client/client.d.ts
/**
 * A Blizzard API client.
 * @classdesc A client to interact with the Blizzard API.
 * @example
 * const client = new BlizzardApiClient({
 *  key: 'client',
 *  secret: 'secret',
 *  origin: 'eu',
 *  locale: 'en_GB',
 *  token: 'access'
 * });
 */
declare class BlizzardApiClient {
  defaults: {
    key: string;
    locale: Locales;
    origin: Origins;
    secret: string;
    token?: string;
  };
  private ky;
  constructor(options: ClientOptions);
  /**
   * Get an access token.
   * @param options The access token request arguments. See {@link AccessTokenRequestArguments}.
   * @returns The access token. See {@link AccessToken}.
   * @example
   * const response = await client.getAccessToken();
   * const { access_token, token_type, expires_in, sub } = response;
   * console.log(access_token, token_type, expires_in, sub);
   * // => 'access'
   * // => 'bearer'
   * // => 86399
   * // => 'client-id'
   */
  getAccessToken: (options?: AccessTokenRequestArguments) => Promise<AccessToken>;
  /**
   * Set the access token.
   * @param token The access token.
   */
  setAccessToken: (token: string) => void;
  /**
   * Refresh the access token.
   * @param options The access token request arguments. See {@link AccessTokenRequestArguments}.
   * @returns The access token. See {@link AccessToken}.
   * @example
   * const response = await client.refreshAccessToken();
   * const { access_token, token_type, expires_in, sub } = response;
   * console.log(access_token, token_type, expires_in, sub);
   * // => 'access'
   * // => 'bearer'
   * // => 86399
   * // => 'client-id'
   */
  refreshAccessToken: (options?: AccessTokenRequestArguments) => Promise<AccessToken>;
  /**
   * Validate an access token.
   * @param options The validate access token arguments. See {@link ValidateAccessTokenArguments}.
   * @returns The response from the Blizzard API. See {@link ValidateAccessTokenResponse}.
   * @example
   * const response = await client.validateAccessToken({ token: 'access' });
   * console.log(response.client_id);
   * // => 'client-id'
   */
  validateAccessToken: (options?: ValidateAccessTokenArguments) => Promise<ValidateAccessTokenResponse>;
  /**
   * Get the request configuration.
   * @param resource The resource to fetch. See {@link Resource}.
   * @param options Client options. See {@link ClientOptions}.
   * @param headers Additional headers to include in the request. This is deprecated and should be passed into the kyOptions as part of the client options instead.
   * @returns The request configuration.
   */
  getRequestConfig<T, Protected extends boolean = false>(resource: Resource<T, object, Protected>, options?: Partial<ClientOptions>, headers?: Record<string, string>): {
    headers: Record<string, string> & {
      Authorization: `Bearer ${string}`;
      'Battlenet-Namespace'?: string;
      'Content-Type': 'application/json';
    };
    searchParams: Record<string, unknown> & {
      locale: ReturnType<typeof getBlizzardApi>['locale'];
    };
  };
  /**
   * Get the request URL.
   * @param resource The resource to fetch. See {@link Resource}.
   * @param options Client options. See {@link ClientOptions}.
   * @returns The request URL.
   */
  getRequestUrl<T, Protected extends boolean = false>(resource: Resource<T, object, Protected>, options?: Partial<ClientOptions>): string;
  /**
   * Send a request to the Blizzard API.
   * @param resource The resource to fetch. See {@link Resource}.
   * @param options Client options. See {@link ClientOptions}.
   * @param headers Additional headers to include in the request. This is deprecated and should be passed into the kyOptions as part of the client options instead.
   * @returns The response from the Blizzard API. See {@link ResourceResponse}.
   */
  sendRequest<T, Protected extends boolean = false>(resource: Resource<T, object, Protected>, options?: Partial<ClientOptions>, headers?: Record<string, string>): ResourceResponse<T>;
}
//#endregion
//#region src/client/create-client.d.ts
/**
 * Create a new Blizzard API client.
 * @param options Client options, see {@link ClientOptions} & https://develop.battle.net/documentation/guides/getting-started
 * @param onTokenRefresh Callback function to handle token refresh. If set to `true`, the client will automatically refresh the token. If set to `false`, the client will not refresh the token. If set to a function, the function will be called with the new token.
 * @returns A new Blizzard API client.
 */
declare const createBlizzardApiClient: (options: ClientOptions, onTokenRefresh?: ((token: AccessToken) => void) | boolean) => Promise<BlizzardApiClient>;
//#endregion
export { AccessToken, AccessTokenRequestArguments, ClientOptions, ValidateAccessTokenArguments, ValidateAccessTokenResponse, createBlizzardApiClient, createBlizzardApiClient as default };
//# sourceMappingURL=index.d.ts.map