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

The core helpers used by all @blizzard-api/* packages.

/**
 * Possible locales for use within the Blizzard API.
 */
type Locales = 'de_DE' | 'en_GB' | 'en_US' | 'es_ES' | 'es_MX' | 'fr_FR' | 'it_IT' | 'ko_KR' | 'multi' | 'pt_BR' | 'pt_PT' | 'ru_RU' | 'zh_CN' | 'zh_TW';
/**
 * Possible regions for use within the Blizzard API.
 */
type Origins = 'cn' | 'eu' | 'kr' | 'tw' | 'us';
/**
 * A record of regions and their supported locales.
 */
declare const _regionLocaleMap: {
    readonly cn: ["zh_CN"];
    readonly eu: ["en_GB", "es_ES", "fr_FR", "ru_RU", "de_DE", "pt_PT", "it_IT", "multi"];
    readonly kr: ["ko_KR", "en_GB", "en_US", "multi"];
    readonly tw: ["zh_TW", "en_GB", "en_US", "multi"];
    readonly us: ["en_US", "es_MX", "pt_BR", "multi"];
};
/**
 * The default Blizzard API configuration for each region.
 */
interface BlizzardApiDefault<T extends Origins> {
    defaultLocale: (typeof _regionLocaleMap)[T][number];
    hostname: T extends 'cn' ? 'https://gateway.battlenet.com.cn' : `https://${T}.api.blizzard.com`;
}
/**
 * A Blizzard API configuration object.
 * @template T The region of the Blizzard API.
 */
interface BlizzardApi<T extends Origins> {
    hostname: BlizzardApiDefault<Origins>['hostname'];
    locale: (typeof _regionLocaleMap)[T][number];
    origin: Origins;
}
/**
 * Get the Blizzard API configuration for a given region.
 * @template T The region of the Blizzard API.
 * @param origin The region of the Blizzard API.
 * @param locale The locale of the Blizzard API.
 * @returns The Blizzard API configuration for the given region.
 * @example
 * const api = getBlizzardApi('us', 'en_US');
 * console.log(api.hostname); // 'https://us.api.blizzard.com'
 * console.log(api.locale); // 'en_US'
 * console.log(api.origin); // 'us'
 */
declare function getBlizzardApi<T extends Origins>(origin: T, locale?: (typeof _regionLocaleMap)[typeof origin][number]): BlizzardApi<typeof origin>;

/**
 * Blizzard API namespaces.
 * @see https://develop.battle.net/documentation/world-of-warcraft/guides/namespaces
 */
type BlizzardNamespaces = 'dynamic' | 'dynamic-classic1x' | 'dynamic-classic' | 'profile' | 'profile-classic1x' | 'profile-classic' | 'static' | 'static-classic1x' | 'static-classic';

/**
 * Extracts the response type from a resource
 * @param Type The resource type
 * @returns The response type
 * @example
 * type extracted = ExtractResourceType<Resource<{ id: number }>>;
 */
type ExtractResourceType<Type> = Type extends Resource<infer R, infer _SearchOptions, infer _Protected> ? R : never;
/**
 * Represents a resource that requires a token to be requested
 * @param Response The response type of the resource
 * @param SearchOptions The search options that can be passed to the resource
 */
type ProtectedResource<Response, SearchOptions extends object = Record<string, never>> = Resource<Response, SearchOptions, true>;
/**
 * Represents a resource that can be requested from the Blizzard API
 * @param _Response The response type of the resource
 * @param SearchOptions The search options that can be passed to the resource
 * @param ProtectedResource Whether the resource requires a token to be requested
 */
type Resource<Response, SearchOptions extends object = Record<string, never>, IsProtectedResource extends boolean = false> = (IsProtectedResource extends true ? {
    token: string;
} : unknown) & {
    /**
     * The response type of the resource
     * @internal
     */
    _responseType?: Response;
    namespace?: BlizzardNamespaces;
    parameters?: SearchOptions;
    path: string;
};
/**
 * Represents the response of a resource
 * @param T The response type of the resource
 * @example
 * type response = ResourceResponse<{ id: number }>;
 * const response: response = Promise.resolve({ id: 1 });
 * response.then((data) => console.log(data.id));
 */
type ResourceResponse<T = unknown> = Promise<T>;

/**
 * Base search parameters
 * orderby The field to order results by.
 * _page The page number to return.
 * @example
 * const params: BaseSearchParameters = {
 *  orderby: 'name',
 *  _page: 1,
 * };
 */
interface BaseSearchParameters {
    _page?: number;
    orderby?: Array<string> | string;
}
/**
 * Search response
 * page The current page number.
 * pageSize The number of results per page.
 * maxPageSize The maximum number of results per page.
 * pageCount The total number of pages.
 * results The search results.
 * @example
 * const response: SearchResponse = {
 *  page: 1,
 *  pageSize: 20,
 *  maxPageSize: 100,
 *  pageCount: 10,
 *  results: [],
 * };
 */
interface SearchResponse<T> {
    maxPageSize: number;
    page: number;
    pageCount: number;
    pageSize: number;
    resultCountCapped?: boolean;
    results: Array<T>;
}

export { type BaseSearchParameters, type BlizzardNamespaces, type ExtractResourceType, type Locales, type Origins, type ProtectedResource, type Resource, type ResourceResponse, type SearchResponse, getBlizzardApi };