Brawl Stars TypeScript SDK

Production-ready TypeScript wrapper for the official Brawl Stars API.

Install

npm install brawlstars-sdk

Quickstart

export BRAWLSTARS_API_TOKEN="your-token"

import { BrawlStarsClient } from "brawlstars-sdk";
const client = new BrawlStarsClient({ token: process.env.BRAWLSTARS_API_TOKEN! });
const player = await client.players.get("#2ABC");

Core Usage

import { BrawlStarsClient } from "brawlstars-sdk";

const client = new BrawlStarsClient({ token: process.env.BRAWLSTARS_API_TOKEN! });

const player = await client.players.get("#2ABC");
const club = await client.clubs.get("#2XYZ");
const brawlers = await client.brawlers.list({ limit: 25 });

Tag Utility

encodeTag is exported for direct use:

import { encodeTag } from "brawlstars-sdk";

encodeTag(" 2ab c "); // %232ABC
encodeTag(" 2AbC ", { uppercase: false }); // %232AbC

Behavior:

• removes whitespace
• prefixes # if missing
• uppercases by default
• applies encodeURIComponent

Configuration

new BrawlStarsClient({
  token: string,
  baseUrl?: string,
  timeoutMs?: number,
  retries?: number | Partial<RetryOptions>,
  concurrencyLimit?: number,
  cache?: boolean | CacheOptions,
  cacheKeyHeaders?: readonly string[],
  validation?: "off" | "warn" | "strict",
  logger?: { warn: (...args: unknown[]) => void; error?: (...args: unknown[]) => void; info?: (...args: unknown[]) => void },
  hooks?: ClientHooks,
  observability?: ObservabilityOptions,
  fetch?: typeof fetch,
});

Validation Modes

• off: no runtime validation (fastest)
• warn (default): validates responses; on mismatch calls logger.warn and returns raw payload
• strict: validates responses and throws ResponseValidationError on mismatch

Detailed semantics are documented in docs/VALIDATION.md.

Per-request overrides:

await client.players.get("#2ABC", {
  timeoutMs: 8_000,
  cache: false,
  validation: "strict",
});

Errors, Rate Limit, and Retries

All request failures throw typed errors (ApiError, RateLimitError, TimeoutError, NetworkError, ResponseValidationError).

Error metadata includes:

• statusCode
• headers
• body
• retryAfter (seconds, when calculable)
• request (method, url, request options)

Example:

import { RateLimitError } from "brawlstars-sdk";

try {
  await client.players.get("#2ABC");
} catch (error) {
  if (error instanceof RateLimitError && error.retryAfter) {
    console.error(`Retry after ${error.retryAfter}s`);
  }
}

Retries use exponential backoff + jitter and respect Retry-After when present.

Hooks

const client = new BrawlStarsClient({
  token,
  hooks: {
    onRateLimit: (ctx) => {
      // ctx.retryAfter is in seconds
      console.warn("Rate-limited", ctx.retryAfter);
    },
    onError: (ctx) => {
      console.error(ctx.error.name, ctx.error.statusCode);
    },
  },
});

Cache

• caches successful GET responses only
• never caches error responses
• cache key format: method|path|sortedQuery|bodyHash|whitelistedHeaders
• default cache-key header whitelist: accept-language
• volatile headers (e.g. authorization, x-request-id, date, traceparent, user-agent) do not affect key
• whitelist is configurable via cacheKeyHeaders

client.invalidateCache("players.get");
client.clearCache();

Scripts

npm run lint
npm run typecheck
npm test
npm run test:integration
npm run test:coverage
npm run verify:api
npm run verify:api -- "./api-spec.txt"
npm run verify:api:report
npm run build
npm run pack:check
npm run scan:secrets
npm run prepublish:verify

verify:api compares key TypeScript models against the provided API reference file (api-spec.txt) and prints JSON:

{"missingInTs":[],"extraInTs":[]}

verify:api:report writes proof output to reports/verify-api.json.

You can provide a custom document path:

npm run verify:api -- --doc ./api-spec.txt
# or positional:
npm run verify:api -- ./api-spec.txt

CI

GitHub Actions runs:

• lint
• typecheck
• verify-api
• unit tests
• integration tests (mocked)
• pack check

tests/integration.live.test.ts is optional and only runs when BRAWLSTARS_TOKEN is set.

Contributing

1. Run npm install
2. Run npm run validate
3. Open PR with tests and documentation updates

Architecture

See docs/ARCHITECTURE.md.

Security

See docs/SECURITY.md.

API Verification

See docs/VERIFY_API_RUN.md.

Audit

See docs/AUDIT.md.