🎮 Brawl Stars SDK

A lightweight and fully typed TypeScript SDK for the Brawl Stars API (Node.js & JavaScript).

✨ Features

• 🚀 Easy-to-use API
• 🧠 Fully typed (TypeScript)
• 🔁 Built-in retry & timeout handling (better reliability)
• 🧩 Modular architecture (endpoints, mappers ready)
• 🔌 Optional proxy support

🤔 Why this SDK?

• Clean and typed responses (no raw API mess)
• Designed for developer experience
• Works in Node.js and serverless environments
• Easy to extend and customize
• Lightweight alternative to heavier API wrappers

📦 Installation

npm install @logintobrawl/brawlstars-sdk

🚀 Quick Start

import { BrawlStarsSDK } from "@logintobrawl/brawlstars-sdk"

const client = new BrawlStarsSDK({
  apiKey: "YOUR_API_KEY"
})

const player = await client.players.get("#2PP") // or { tag: "#2PP" }
console.log(player)

💡 Player tags can be used with or without # (e.g. #2PP or 2PP)

⚙️ Configuration

const client = new BrawlStarsSDK({
  apiKey: "YOUR_API_KEY",
  proxyUrl: "https://bsproxy.royaleapi.dev",
  timeoutMs: 5000,
  logger: console.log
})

Options

• apiKey – required API key
• proxyUrl – optional proxy for non-static IP environments
• timeoutMs – request timeout in milliseconds
• logger – custom logging function

🔑 Getting API Key

To use this SDK, you need an API key from the official Brawl Stars API.

👉 Go here: https://developer.brawlstars.com

1. Log in or create an account
2. Go to My Account
3. Create a new API key
4. Add your IP address
5. Copy the key

🌐 Proxy (IMPORTANT for serverless)

The official API requires a static IP.

If you're using:

• Vercel
• Netlify
• serverless / cloud functions

👉 you will likely need a proxy.

You can use the free proxy from RoyaleAPI:
https://docs.royaleapi.com/proxy.html

Example:

const client = new BrawlStarsSDK({
  apiKey: "YOUR_API_KEY",
  proxyUrl: "https://bsproxy.royaleapi.dev"
})

If you don't use a proxy or static IP, requests may fail with 403 errors.

📚 API

players.get(tag: string)

Fetch player data by tag.

const player = await client.players.get("#2PP")

players.getBattleLog(tag: string)

Fetch player battle log by tag.

const battles = await client.players.getBattleLog("#2PP")

players.getSkins(tag: string)

Fetch all player skins by tag.

const skins = await client.players.getSkins("#2PP")

🧩 Notes about endpoints

• All endpoints return mapped data (clean models, not raw API)
• Tag can be:
  • "#2PP"
  • { tag: "#2PP" } (depending on method overloads)
• Errors throw ApiError

⚠️ Errors

import { ApiError } from "@logintobrawl/brawlstars-sdk"

try {
  await client.players.get("invalid")
} catch (e) {
  if (e instanceof ApiError) {
    console.log(e.status)
    console.log(e.message)
  }
}

🧱 Architecture

The SDK is organized into layered modules:

endpoints/  → raw API communication layer
mappers/    → transforms API responses into typed models
models/     → shared TypeScript domain types
services/   → high-level logic built on mapped data (feature classes, helpers)

🔄 Data Flow

API → endpoints → mappers → models → services → user

🛠️ Development

npm install
npm run build

📄 License

MIT

🙏 Credits

• mawelek ❤️ – feedback & suggestions on improvements

💡 Notes

• This SDK returns mapped API responses
• Proxy support is optional and depends on your configuration

📈 Use Cases

This SDK is useful for:

• Building Brawl Stars stat trackers
• Creating Discord bots
• Developing web apps with player stats
• Analyzing battle logs and performance
• Backend services using the Brawl Stars API

🔗 Links

• NPM: https://www.npmjs.com/package/@logintobrawl/brawlstars-sdk