brawlstars-sdk 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,929 @@
+/**
+ * Player or club tag used by the official API.
+ */
+type EntityTag = `#${string}` | string;
+/**
+ * Country code accepted by ranking endpoints.
+ */
+type CountryCode = "global" | string;
+/**
+ * Brawler identifier used by brawler endpoints.
+ */
+type BrawlerId = string | number;
+/**
+ * Cursor set used by paginated Brawl Stars list responses.
+ */
+interface PagingCursors {
+    before?: string | undefined;
+    after?: string | undefined;
+}
+/**
+ * Pagination metadata wrapper.
+ */
+interface Paging {
+    cursors?: PagingCursors | undefined;
+}
+/**
+ * Normalized list response shape returned by this client.
+ */
+interface ApiListResponse<TItem> {
+    items: TItem[];
+    paging?: Paging | undefined;
+}
+/**
+ * Common query parameters for cursor-based endpoints.
+ */
+interface CursorPaginationQuery {
+    before?: string | undefined;
+    after?: string | undefined;
+    limit?: number | undefined;
+}
+/**
+ * Localized name payload. The API export does not provide locale keys,
+ * so values are represented as a dictionary.
+ */
+interface JsonLocalizedName {
+    [locale: string]: string;
+}
+/**
+ * Generic accessory model (gadgets and similar unlocks).
+ */
+interface Accessory {
+    id: number;
+    name: JsonLocalizedName;
+}
+/**
+ * Star power model.
+ */
+interface StarPower {
+    id: number;
+    name: JsonLocalizedName;
+}
+/**
+ * Hyper charge model.
+ */
+interface HyperCharge {
+    id: number;
+    name: JsonLocalizedName;
+}
+/**
+ * Gear model with level information.
+ */
+interface GearStat {
+    id: number;
+    name: JsonLocalizedName;
+    level: number;
+}
+/**
+ * Skin model for brawler stats.
+ */
+interface Skin {
+    id: number;
+    name: JsonLocalizedName;
+}
+/**
+ * Brawler buff toggles available for a player.
+ */
+interface BrawlerBuffies {
+    gadget: boolean;
+    starPower: boolean;
+    hyperCharge: boolean;
+}
+/**
+ * Detailed brawler stats for a specific player.
+ */
+interface BrawlerStat {
+    id: number;
+    name: JsonLocalizedName;
+    rank: number;
+    trophies: number;
+    highestTrophies: number;
+    prestigeLevel: number;
+    power: number;
+    currentWinStreak: number;
+    maxWinStreak: number;
+    gadgets: Accessory[];
+    starPowers: StarPower[];
+    hyperCharges: HyperCharge[];
+    gears: GearStat[];
+    buffies: BrawlerBuffies;
+    skin: Skin;
+}
+/**
+ * Basic player icon descriptor.
+ */
+interface PlayerIcon {
+    id: number;
+}
+/**
+ * Player club information embedded in player responses.
+ */
+interface PlayerClub {
+    tag: string;
+    name: string;
+}
+/**
+ * Main player model.
+ */
+interface Player {
+    tag: string;
+    name: string;
+    nameColor: string;
+    icon: PlayerIcon;
+    club?: PlayerClub | undefined;
+    trophies: number;
+    highestTrophies: number;
+    totalPrestigeLevel: number;
+    expLevel: number;
+    expPoints: number;
+    soloVictories: number;
+    duoVictories: number;
+    bestRoboRumbleTime: number;
+    bestTimeAsBigBrawler: number;
+    isQualifiedFromChampionshipChallenge: boolean;
+    brawlers: BrawlerStat[];
+    "3vs3Victories": number;
+}
+/**
+ * Club member model.
+ */
+interface ClubMember {
+    tag: string;
+    name: string;
+    nameColor: string;
+    trophies: number;
+    role: string;
+    icon: PlayerIcon;
+}
+/**
+ * Club model.
+ */
+interface Club {
+    tag: string;
+    name: string;
+    description: string;
+    trophies: number;
+    requiredTrophies: number;
+    members: ClubMember[];
+    type: string;
+    badgeId: number;
+    isFamilyFriendly: boolean;
+}
+/**
+ * Club ranking entry.
+ */
+interface ClubRanking {
+    tag: string;
+    name: string;
+    trophies: number;
+    rank: number;
+    memberCount: number;
+    badgeId: number;
+}
+/**
+ * Player club info inside ranking entries.
+ */
+interface PlayerRankingClub {
+    name: string;
+}
+/**
+ * Player ranking entry.
+ */
+interface PlayerRanking {
+    tag: string;
+    name: string;
+    nameColor: string;
+    rank: number;
+    trophies: number;
+    icon: PlayerIcon;
+    club: PlayerRankingClub;
+}
+/**
+ * Static brawler metadata.
+ */
+interface Brawler {
+    id: number;
+    name: JsonLocalizedName;
+    gadgets: Accessory[];
+    starPowers: StarPower[];
+    hyperCharges: HyperCharge[];
+    gears: GearStat[];
+}
+/**
+ * Game mode descriptor.
+ */
+interface EventType {
+    id: number;
+    name: JsonLocalizedName;
+}
+/**
+ * Scheduled event location details.
+ */
+interface ScheduledEventLocation {
+    id: number;
+    modeId: number;
+    mode: string;
+    map: JsonLocalizedName;
+    modifiers?: string[] | undefined;
+}
+/**
+ * Scheduled event entry in the event rotation response.
+ */
+interface ScheduledEvent {
+    slotId: number;
+    startTime: string;
+    endTime: string;
+    event: ScheduledEventLocation;
+}
+/**
+ * Event payload in battle log entries.
+ */
+interface Event {
+    id: number;
+    modeId: number;
+    mode: string;
+    map: JsonLocalizedName;
+}
+/**
+ * Battle result payload is not expanded in the source export.
+ */
+interface BattleResult {
+    [key: string]: unknown;
+}
+/**
+ * Battle log entry.
+ */
+interface Battle {
+    battleTime: string;
+    battle: BattleResult;
+    event: Event;
+}
+/**
+ * Standard client error body returned by non-2xx responses.
+ */
+interface ClientErrorResponse {
+    reason: string;
+    message: string;
+    type: string;
+    detail?: Record<string, unknown> | undefined;
+}
+/**
+ * Battle log response.
+ */
+type BattleLogResponse = ApiListResponse<Battle>;
+/**
+ * Club members response.
+ */
+type ClubMembersResponse = ApiListResponse<ClubMember>;
+/**
+ * Club rankings response.
+ */
+type ClubRankingsResponse = ApiListResponse<ClubRanking>;
+/**
+ * Player rankings response.
+ */
+type PlayerRankingsResponse = ApiListResponse<PlayerRanking>;
+/**
+ * Brawler list response.
+ */
+type BrawlersResponse = ApiListResponse<Brawler>;
+/**
+ * Game modes response.
+ */
+type GameModesResponse = ApiListResponse<EventType>;
+/**
+ * Event rotation response.
+ */
+type EventRotationResponse = ApiListResponse<ScheduledEvent>;
+
+/**
+ * Request metadata attached to errors.
+ */
+interface ApiErrorRequest {
+    method: HttpMethod;
+    url: string;
+    options?: {
+        timeoutMs?: number | undefined;
+        retries?: number | Partial<RetryOptions> | undefined;
+        cache?: boolean | RequestCacheOptions | undefined;
+        validation?: ValidationMode | undefined;
+        headers?: Readonly<Record<string, string>> | undefined;
+    } | undefined;
+}
+/**
+ * Structured metadata attached to all API errors.
+ */
+interface ApiErrorMetadata {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    request?: ApiErrorRequest | undefined;
+    statusCode?: number | undefined;
+    headers?: Readonly<Record<string, string>> | undefined;
+    body?: unknown;
+    responseBody?: unknown;
+    received?: unknown;
+    retryAfter?: number | null | undefined;
+    retryAfterMs?: number | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * Metadata for strict response validation failures.
+ */
+interface ResponseValidationMetadata extends ApiErrorMetadata {
+    expectedSchema: string;
+    actualPayload: unknown;
+}
+/**
+ * Base error for all request failures.
+ */
+declare class ApiError extends Error {
+    readonly endpoint: EndpointName;
+    readonly method: HttpMethod;
+    readonly request?: ApiErrorRequest | undefined;
+    readonly statusCode?: number | undefined;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+    readonly responseBody?: unknown;
+    readonly retryAfter: number | null;
+    readonly retryAfterMs?: number | undefined;
+    readonly requestId?: string | undefined;
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised for 4xx responses produced by the API.
+ */
+declare class ClientError extends ApiError {
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised when the API returns a throttling response.
+ */
+declare class RateLimitError extends ApiError {
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised when a request exceeds the configured timeout.
+ */
+declare class TimeoutError extends ApiError {
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised when network transport fails.
+ */
+declare class NetworkError extends ApiError {
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised when runtime response validation fails.
+ */
+declare class ValidationError extends ApiError {
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * Error raised when strict response schema validation fails.
+ */
+declare class ResponseValidationError extends ValidationError {
+    readonly expectedSchema: string;
+    readonly actualPayload: unknown;
+    constructor(message: string, metadata: ResponseValidationMetadata);
+}
+
+/**
+ * Event emitted before dispatching a request.
+ */
+interface RequestStartEvent {
+    requestId: string;
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+}
+/**
+ * Event emitted after receiving a successful or failed HTTP response.
+ */
+interface RequestEndEvent {
+    requestId: string;
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    statusCode: number;
+    durationMs: number;
+}
+/**
+ * Event emitted when a request attempt fails.
+ */
+interface RequestErrorEvent {
+    requestId: string;
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    willRetry: boolean;
+    durationMs: number;
+    error: Error;
+}
+/**
+ * Listener functions for request lifecycle events.
+ */
+interface ObservabilityListeners {
+    requestStart?: ((event: RequestStartEvent) => void | Promise<void>) | ReadonlyArray<(event: RequestStartEvent) => void | Promise<void>> | undefined;
+    requestEnd?: ((event: RequestEndEvent) => void | Promise<void>) | ReadonlyArray<(event: RequestEndEvent) => void | Promise<void>> | undefined;
+    requestError?: ((event: RequestErrorEvent) => void | Promise<void>) | ReadonlyArray<(event: RequestErrorEvent) => void | Promise<void>> | undefined;
+}
+/**
+ * Adapter contract for optional metrics backends.
+ */
+interface MetricsAdapter {
+    onRequestStart?(event: RequestStartEvent): void;
+    onRequestEnd?(event: RequestEndEvent): void;
+    onRequestError?(event: RequestErrorEvent): void;
+}
+/**
+ * Observability configuration passed to the client.
+ */
+interface ObservabilityOptions {
+    listeners?: ObservabilityListeners | undefined;
+    metrics?: MetricsAdapter | ReadonlyArray<MetricsAdapter> | undefined;
+}
+
+/**
+ * HTTP method supported by the Brawl Stars API wrapper.
+ */
+type HttpMethod = "GET";
+/**
+ * Endpoint identifiers used internally and in hook contexts.
+ */
+type EndpointName = "players.get" | "players.getBattleLog" | "clubs.get" | "clubs.getMembers" | "rankings.getClubs" | "rankings.getPlayers" | "rankings.getBrawlers" | "brawlers.list" | "brawlers.get" | "gamemodes.list" | "events.getRotation";
+/**
+ * Strategy used for retry jitter.
+ */
+type RetryJitter = "full" | "none";
+/**
+ * Runtime response validation mode.
+ */
+type ValidationMode = "off" | "warn" | "strict";
+/**
+ * Logger used by the SDK for runtime warnings and diagnostics.
+ */
+interface ClientLogger {
+    warn: (...messages: ReadonlyArray<unknown>) => void;
+    error?: (...messages: ReadonlyArray<unknown>) => void;
+    info?: (...messages: ReadonlyArray<unknown>) => void;
+}
+/**
+ * Retry strategy options.
+ */
+interface RetryOptions {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffFactor: number;
+    jitter: RetryJitter;
+    retryableStatusCodes: ReadonlyArray<number>;
+}
+/**
+ * Per-endpoint cache policy overrides.
+ */
+type EndpointCachePolicy = Partial<Record<EndpointName, number>>;
+/**
+ * In-memory cache options.
+ */
+interface CacheOptions {
+    maxSize?: number | undefined;
+    ttlMs?: number | undefined;
+    endpointTtlMs?: EndpointCachePolicy | undefined;
+}
+/**
+ * Request-level cache override.
+ */
+interface RequestCacheOptions {
+    enabled?: boolean | undefined;
+    ttlMs?: number | undefined;
+}
+/**
+ * Context passed to `beforeRequest` hooks.
+ */
+interface BeforeRequestContext {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    requestId: string;
+    headers: Readonly<Record<string, string>>;
+}
+/**
+ * Context passed to `afterResponse` hooks.
+ */
+interface AfterResponseContext {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    requestId: string;
+    durationMs: number;
+    statusCode: number;
+    headers: Readonly<Record<string, string>>;
+}
+/**
+ * Context passed to `onError` hooks.
+ */
+interface ErrorContext {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    requestId: string;
+    durationMs: number;
+    willRetry: boolean;
+    error: ApiError;
+}
+/**
+ * Context passed to `onRateLimit` hooks.
+ */
+interface RateLimitContext {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    requestId: string;
+    statusCode: number;
+    retryAfter: number | null;
+    headers: Readonly<Record<string, string>>;
+}
+/**
+ * Async hook function.
+ */
+type HookFn<TContext> = (context: TContext) => void | Promise<void>;
+/**
+ * Hook definitions for request lifecycle events.
+ */
+interface ClientHooks {
+    beforeRequest?: HookFn<BeforeRequestContext> | ReadonlyArray<HookFn<BeforeRequestContext>> | undefined;
+    afterResponse?: HookFn<AfterResponseContext> | ReadonlyArray<HookFn<AfterResponseContext>> | undefined;
+    onError?: HookFn<ErrorContext> | ReadonlyArray<HookFn<ErrorContext>> | undefined;
+    onRateLimit?: HookFn<RateLimitContext> | ReadonlyArray<HookFn<RateLimitContext>> | undefined;
+}
+/**
+ * Main client constructor options.
+ */
+interface BrawlStarsClientOptions {
+    token: string;
+    baseUrl?: string | undefined;
+    timeoutMs?: number | undefined;
+    retries?: number | Partial<RetryOptions> | undefined;
+    concurrencyLimit?: number | undefined;
+    cache?: boolean | CacheOptions | undefined;
+    validation?: ValidationMode | undefined;
+    /**
+     * @deprecated Use `validation` instead.
+     */
+    validateResponses?: boolean | undefined;
+    hooks?: ClientHooks | undefined;
+    observability?: ObservabilityOptions | undefined;
+    fetch?: typeof fetch | undefined;
+    logger?: ClientLogger | undefined;
+    cacheKeyHeaders?: ReadonlyArray<string> | undefined;
+}
+/**
+ * Per-request override options.
+ */
+interface RequestOptions {
+    timeoutMs?: number | undefined;
+    retries?: number | Partial<RetryOptions> | undefined;
+    signal?: AbortSignal | undefined;
+    headers?: HeadersInit | undefined;
+    cache?: boolean | RequestCacheOptions | undefined;
+    validation?: ValidationMode | undefined;
+    /**
+     * @deprecated Use `validation` instead.
+     */
+    validateResponse?: boolean | undefined;
+    hooks?: ClientHooks | undefined;
+}
+
+/**
+ * Shared options for paginated endpoints.
+ */
+interface PaginatedEndpointOptions extends RequestOptions, CursorPaginationQuery {
+}
+/**
+ * Options for `players.get`.
+ */
+type GetPlayerOptions = RequestOptions;
+/**
+ * Options for `players.getBattleLog`.
+ */
+type GetPlayerBattleLogOptions = RequestOptions;
+/**
+ * Options for `clubs.get`.
+ */
+type GetClubOptions = RequestOptions;
+/**
+ * Options for `clubs.getMembers`.
+ */
+type GetClubMembersOptions = PaginatedEndpointOptions;
+/**
+ * Options for `rankings.getClubs`.
+ */
+type GetClubRankingsOptions = PaginatedEndpointOptions;
+/**
+ * Options for `rankings.getPlayers`.
+ */
+type GetPlayerRankingsOptions = PaginatedEndpointOptions;
+/**
+ * Options for `rankings.getBrawlers`.
+ */
+type GetBrawlerRankingsOptions = PaginatedEndpointOptions;
+/**
+ * Options for `brawlers.list`.
+ */
+type ListBrawlersOptions = PaginatedEndpointOptions;
+/**
+ * Options for `brawlers.get`.
+ */
+type GetBrawlerOptions = RequestOptions;
+/**
+ * Options for `gamemodes.list`.
+ */
+type ListGameModesOptions = PaginatedEndpointOptions;
+/**
+ * Options for `events.getRotation`.
+ */
+type GetEventRotationOptions = RequestOptions;
+
+/**
+ * Endpoint parser function with optional runtime validation.
+ */
+type EndpointParser<TResponse> = (payload: unknown, validate: boolean) => TResponse;
+
+interface InternalRequestConfig<TResponse> {
+    endpoint: EndpointName;
+    method: HttpMethod;
+    path: string;
+    query?: Readonly<Record<string, string | number | boolean | undefined>> | undefined;
+    options?: RequestOptions | undefined;
+    parser: EndpointParser<TResponse>;
+}
+/**
+ * Internal HTTP layer used by all endpoint resources.
+ */
+declare class HttpClient {
+    private readonly fetchFn;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly retryOptions;
+    private readonly validationMode;
+    private readonly logger;
+    private readonly defaultHeaders;
+    private readonly hooks;
+    private readonly observability;
+    private readonly cacheSettings;
+    private readonly cacheKeyHeaders;
+    private readonly cache;
+    private readonly semaphore;
+    private globalRateLimitUntilMs;
+    private readonly routeRateLimitUntilMs;
+    private readonly endpointCacheIndex;
+    private requestCounter;
+    constructor(options: BrawlStarsClientOptions);
+    /**
+     * Execute a typed request against the API.
+     */
+    request<TResponse>(config: InternalRequestConfig<TResponse>): Promise<TResponse>;
+    /**
+     * Clear all in-memory cached responses.
+     */
+    clearCache(): void;
+    /**
+     * Invalidate cached responses for a given endpoint, or all endpoints when omitted.
+     */
+    invalidateCache(endpoint?: EndpointName): number;
+    private executeRequest;
+    private createRequestId;
+    private createApiError;
+    private emitError;
+    private resolveValidationMode;
+    private createRequestMetadata;
+    private resolveCacheSettings;
+    private resolveCachePolicy;
+    private isCacheableMethod;
+    private trackEndpointCacheKey;
+    private waitForRateLimitWindow;
+    private updateRateLimitState;
+    private parseResponseBody;
+}
+
+/**
+ * Brawler endpoint group.
+ */
+declare class BrawlersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all brawlers.
+     */
+    list(opts?: ListBrawlersOptions): Promise<BrawlersResponse>;
+    /**
+     * @deprecated Use `list(opts?)`.
+     */
+    list(query?: CursorPaginationQuery, opts?: RequestOptions): Promise<BrawlersResponse>;
+    /**
+     * Get one brawler by identifier.
+     */
+    get(brawlerId: BrawlerId, opts?: GetBrawlerOptions): Promise<Brawler>;
+}
+
+/**
+ * Club endpoint group.
+ */
+declare class ClubsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get full club details by tag.
+     */
+    get(clubTag: EntityTag, opts?: GetClubOptions): Promise<Club>;
+    /**
+     * List members for a club with optional cursor pagination.
+     */
+    getMembers(clubTag: EntityTag, opts?: GetClubMembersOptions): Promise<ClubMembersResponse>;
+    /**
+     * @deprecated Use `getMembers(clubTag, opts?)`.
+     */
+    getMembers(clubTag: EntityTag, query?: CursorPaginationQuery, opts?: RequestOptions): Promise<ClubMembersResponse>;
+}
+
+/**
+ * Events endpoint group.
+ */
+declare class EventsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get currently active event rotation.
+     */
+    getRotation(opts?: GetEventRotationOptions): Promise<EventRotationResponse>;
+}
+
+/**
+ * Game modes endpoint group.
+ */
+declare class GameModesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List available game modes.
+     */
+    list(opts?: ListGameModesOptions): Promise<GameModesResponse>;
+    /**
+     * @deprecated Use `list(opts?)`.
+     */
+    list(query?: CursorPaginationQuery, opts?: RequestOptions): Promise<GameModesResponse>;
+}
+
+/**
+ * Player endpoint group.
+ */
+declare class PlayersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get a player profile by tag.
+     *
+     * @example
+     * const player = await client.players.get("#2PP");
+     */
+    get(playerTag: EntityTag, opts?: GetPlayerOptions): Promise<Player>;
+    /**
+     * Get recent battle log entries for a player.
+     *
+     * @example
+     * const battles = await client.players.getBattleLog("#2PP");
+     */
+    getBattleLog(playerTag: EntityTag, opts?: GetPlayerBattleLogOptions): Promise<BattleLogResponse>;
+}
+
+/**
+ * Ranking endpoint group.
+ */
+declare class RankingsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get club rankings for a country or globally.
+     */
+    getClubs(countryCode: CountryCode, opts?: GetClubRankingsOptions): Promise<ClubRankingsResponse>;
+    /**
+     * @deprecated Use `getClubs(countryCode, opts?)`.
+     */
+    getClubs(countryCode: CountryCode, query?: CursorPaginationQuery, opts?: RequestOptions): Promise<ClubRankingsResponse>;
+    /**
+     * Get player rankings for a country or globally.
+     */
+    getPlayers(countryCode: CountryCode, opts?: GetPlayerRankingsOptions): Promise<PlayerRankingsResponse>;
+    /**
+     * @deprecated Use `getPlayers(countryCode, opts?)`.
+     */
+    getPlayers(countryCode: CountryCode, query?: CursorPaginationQuery, opts?: RequestOptions): Promise<PlayerRankingsResponse>;
+    /**
+     * Get rankings for one brawler in a country or globally.
+     */
+    getBrawlers(countryCode: CountryCode, brawlerId: BrawlerId, opts?: GetBrawlerRankingsOptions): Promise<PlayerRankingsResponse>;
+    /**
+     * @deprecated Use `getBrawlers(countryCode, brawlerId, opts?)`.
+     */
+    getBrawlers(countryCode: CountryCode, brawlerId: BrawlerId, query?: CursorPaginationQuery, opts?: RequestOptions): Promise<PlayerRankingsResponse>;
+}
+
+/**
+ * Main Brawl Stars API client.
+ */
+declare class BrawlStarsClient {
+    private readonly http;
+    /**
+     * Player operations.
+     */
+    readonly players: PlayersResource;
+    /**
+     * Club operations.
+     */
+    readonly clubs: ClubsResource;
+    /**
+     * Ranking operations.
+     */
+    readonly rankings: RankingsResource;
+    /**
+     * Brawler operations.
+     */
+    readonly brawlers: BrawlersResource;
+    /**
+     * Game mode operations.
+     */
+    readonly gamemodes: GameModesResource;
+    /**
+     * Event operations.
+     */
+    readonly events: EventsResource;
+    /**
+     * Create a new API client.
+     */
+    constructor(options: BrawlStarsClientOptions);
+    /**
+     * Clear all in-memory cached responses.
+     */
+    clearCache(): void;
+    /**
+     * Invalidate cache entries for one endpoint or all endpoints.
+     */
+    invalidateCache(endpoint?: EndpointName): number;
+}
+
+/**
+ * Convenience factory for creating a `BrawlStarsClient`.
+ */
+declare function createBrawlStarsClient(options: BrawlStarsClientOptions): BrawlStarsClient;
+
+interface CounterLike {
+    inc(labels?: Record<string, string | number>, value?: number): void;
+}
+interface HistogramLike {
+    observe(labels: Record<string, string | number>, value: number): void;
+}
+/**
+ * Minimal prom-client compatible adapter contract.
+ */
+interface PromClientAdapterOptions {
+    requestsStarted?: CounterLike;
+    requestsCompleted?: CounterLike;
+    requestsFailed?: CounterLike;
+    requestDurationMs?: HistogramLike;
+}
+/**
+ * Create a metrics adapter for projects already using `prom-client`.
+ */
+declare function createPromClientAdapter(options: PromClientAdapterOptions): MetricsAdapter;
+
+/**
+ * Options for tag encoding.
+ */
+interface EncodeTagOptions {
+    uppercase?: boolean | undefined;
+}
+/**
+ * Normalize a player/club tag and encode it for use inside API paths.
+ */
+declare function encodeTag(tag: EntityTag, options?: EncodeTagOptions): string;
+
+/**
+ * Public alias for constructor options.
+ */
+interface ClientOptions extends BrawlStarsClientOptions {
+}
+/**
+ * Public validation mode options.
+ */
+type ClientValidationMode = ValidationMode;
+
+export { type Accessory, type AfterResponseContext, ApiError, type ApiErrorMetadata, type ApiErrorRequest, type ApiListResponse, type Battle, type BattleLogResponse, type BattleResult, type BeforeRequestContext, BrawlStarsClient, type BrawlStarsClientOptions, type Brawler, type BrawlerBuffies, type BrawlerId, type BrawlerStat, type BrawlersResponse, type CacheOptions, ClientError, type ClientErrorResponse, type ClientHooks, type ClientLogger, type ClientOptions, type ClientValidationMode, type Club, type ClubMember, type ClubMembersResponse, type ClubRanking, type ClubRankingsResponse, type CountryCode, type CursorPaginationQuery, type EncodeTagOptions, type EndpointCachePolicy, type EndpointName, type EntityTag, type ErrorContext, type Event, type EventRotationResponse, type EventType, type GameModesResponse, type GearStat, type GetBrawlerOptions, type GetBrawlerRankingsOptions, type GetClubMembersOptions, type GetClubOptions, type GetClubRankingsOptions, type GetEventRotationOptions, type GetPlayerBattleLogOptions, type GetPlayerOptions, type GetPlayerRankingsOptions, type HookFn, type HttpMethod, type HyperCharge, type JsonLocalizedName, type ListBrawlersOptions, type ListGameModesOptions, type MetricsAdapter, NetworkError, type ObservabilityListeners, type ObservabilityOptions, type PaginatedEndpointOptions, type Paging, type PagingCursors, type Player, type PlayerClub, type PlayerIcon, type PlayerRanking, type PlayerRankingsResponse, type RateLimitContext, RateLimitError, type RequestCacheOptions, type RequestEndEvent, type RequestErrorEvent, type RequestOptions, type RequestStartEvent, ResponseValidationError, type ResponseValidationMetadata, type RetryJitter, type RetryOptions, type ScheduledEvent, type ScheduledEventLocation, type Skin, type StarPower, TimeoutError, ValidationError, type ValidationMode, createBrawlStarsClient, createPromClientAdapter, encodeTag };