brawlstars-sdk 0.3.0

package/dist/index.js

@@ -0,0 +1,1718 @@
+// src/errors/api-errors.ts
+var ApiError = class extends Error {
+  endpoint;
+  method;
+  request;
+  statusCode;
+  headers;
+  body;
+  responseBody;
+  retryAfter;
+  retryAfterMs;
+  requestId;
+  constructor(message, metadata) {
+    super(message, metadata.cause ? { cause: metadata.cause } : void 0);
+    this.name = "ApiError";
+    this.endpoint = metadata.endpoint;
+    this.method = metadata.method;
+    this.request = metadata.request;
+    this.statusCode = metadata.statusCode;
+    this.headers = metadata.headers ?? {};
+    this.body = metadata.body ?? metadata.responseBody ?? metadata.received;
+    this.responseBody = this.body;
+    this.retryAfter = metadata.retryAfter ?? (metadata.retryAfterMs !== void 0 ? Math.max(0, Math.ceil(metadata.retryAfterMs / 1e3)) : null);
+    this.retryAfterMs = metadata.retryAfterMs ?? (this.retryAfter !== null ? this.retryAfter * 1e3 : void 0);
+    this.requestId = metadata.requestId;
+  }
+};
+var ClientError = class extends ApiError {
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "ClientError";
+  }
+};
+var RateLimitError = class extends ApiError {
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "RateLimitError";
+  }
+};
+var TimeoutError = class extends ApiError {
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "TimeoutError";
+  }
+};
+var NetworkError = class extends ApiError {
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "NetworkError";
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "ValidationError";
+  }
+};
+var ResponseValidationError = class extends ValidationError {
+  expectedSchema;
+  actualPayload;
+  constructor(message, metadata) {
+    super(message, metadata);
+    this.name = "ResponseValidationError";
+    this.expectedSchema = metadata.expectedSchema;
+    this.actualPayload = metadata.actualPayload;
+  }
+};
+
+// src/observability/dispatcher.ts
+function toArray(value) {
+  if (value === void 0) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+var ObservabilityDispatcher = class {
+  listeners;
+  metrics;
+  constructor(listeners, metrics) {
+    this.listeners = {
+      requestStart: toArray(listeners?.requestStart),
+      requestEnd: toArray(listeners?.requestEnd),
+      requestError: toArray(listeners?.requestError)
+    };
+    this.metrics = toArray(metrics);
+  }
+  /**
+   * Emit a request-start event.
+   */
+  async emitRequestStart(event) {
+    for (const listener of this.listeners.requestStart) {
+      await listener(event);
+    }
+    for (const adapter of this.metrics) {
+      adapter.onRequestStart?.(event);
+    }
+  }
+  /**
+   * Emit a request-end event.
+   */
+  async emitRequestEnd(event) {
+    for (const listener of this.listeners.requestEnd) {
+      await listener(event);
+    }
+    for (const adapter of this.metrics) {
+      adapter.onRequestEnd?.(event);
+    }
+  }
+  /**
+   * Emit a request-error event.
+   */
+  async emitRequestError(event) {
+    for (const listener of this.listeners.requestError) {
+      await listener(event);
+    }
+    for (const adapter of this.metrics) {
+      adapter.onRequestError?.(event);
+    }
+  }
+};
+
+// src/utils/abort.ts
+function createRequestSignal(timeoutMs, externalSignal) {
+  const controller = new AbortController();
+  let timeoutId;
+  let didTimeout = false;
+  const onExternalAbort = () => {
+    controller.abort(externalSignal?.reason);
+  };
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort(externalSignal.reason);
+    } else {
+      externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+  }
+  if (timeoutMs > 0) {
+    timeoutId = setTimeout(() => {
+      didTimeout = true;
+      controller.abort(new Error("Request timed out"));
+    }, timeoutMs);
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      externalSignal?.removeEventListener("abort", onExternalAbort);
+    },
+    timedOut: () => didTimeout
+  };
+}
+
+// src/utils/cache-key.ts
+var DEFAULT_CACHE_HEADER_WHITELIST = ["accept-language"];
+function normalizeHeaderName(name) {
+  return name.toLowerCase().trim();
+}
+function serializeBodyValue(value, seen) {
+  if (value === null) {
+    return "null";
+  }
+  const valueType = typeof value;
+  if (valueType === "string") {
+    return JSON.stringify(value);
+  }
+  if (valueType === "number" || valueType === "boolean") {
+    return String(value);
+  }
+  if (valueType === "undefined") {
+    return "undefined";
+  }
+  if (valueType === "bigint") {
+    return `${String(value)}n`;
+  }
+  if (value instanceof Date) {
+    return `date:${value.toISOString()}`;
+  }
+  if (value instanceof URLSearchParams) {
+    const sorted = [...value.entries()].sort(([leftKey, leftValue], [rightKey, rightValue]) => {
+      if (leftKey === rightKey) {
+        return leftValue.localeCompare(rightValue);
+      }
+      return leftKey.localeCompare(rightKey);
+    }).map(([key, entryValue]) => `${encodeURIComponent(key)}=${encodeURIComponent(entryValue)}`).join("&");
+    return `params:${sorted}`;
+  }
+  if (value instanceof ArrayBuffer) {
+    return `buffer:${Array.from(new Uint8Array(value)).join(".")}`;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const view = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    return `view:${Array.from(view).join(".")}`;
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return "[circular]";
+    }
+    seen.add(value);
+    const serialized = `[${value.map((entry) => serializeBodyValue(entry, seen)).join(",")}]`;
+    seen.delete(value);
+    return serialized;
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      return "{circular}";
+    }
+    seen.add(value);
+    const record = value;
+    const serialized = `{${Object.keys(record).sort((left, right) => left.localeCompare(right)).map((key) => `${JSON.stringify(key)}:${serializeBodyValue(record[key], seen)}`).join(",")}}`;
+    seen.delete(value);
+    return serialized;
+  }
+  return JSON.stringify(String(value));
+}
+function hashString(input) {
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function createCacheKey(request, whitelistHeaders = DEFAULT_CACHE_HEADER_WHITELIST) {
+  const url = new URL(request.url);
+  const method = String(request.method).toUpperCase();
+  const query = [...url.searchParams.entries()].sort(([leftKey, leftValue], [rightKey, rightValue]) => {
+    if (leftKey === rightKey) {
+      return leftValue.localeCompare(rightValue);
+    }
+    return leftKey.localeCompare(rightKey);
+  }).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+  const allowed = new Set(whitelistHeaders.map((header) => normalizeHeaderName(header)));
+  const requestHeaders = new Headers(request.headers ?? {});
+  const relevantHeaders = [...requestHeaders.entries()].filter(([name]) => allowed.has(normalizeHeaderName(name))).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `${normalizeHeaderName(name)}:${value}`).join("|");
+  const serializedBody = request.body === void 0 ? "" : serializeBodyValue(request.body, /* @__PURE__ */ new Set());
+  const bodyHash = hashString(serializedBody);
+  return `${method}|${url.pathname}|${query}|${bodyHash}|${relevantHeaders}`;
+}
+
+// src/utils/headers.ts
+function mergeHeaders(defaultHeaders, override) {
+  const headers = new Headers(defaultHeaders);
+  if (!override) {
+    return headers;
+  }
+  const overrideHeaders = new Headers(override);
+  overrideHeaders.forEach((value, key) => {
+    headers.set(key, value);
+  });
+  return headers;
+}
+function toSafeHeaderObject(headers) {
+  const entries = {};
+  headers.forEach((value, key) => {
+    const normalizedKey = key.toLowerCase();
+    if (normalizedKey === "authorization") {
+      entries[key] = "[REDACTED]";
+      return;
+    }
+    entries[key] = value;
+  });
+  return entries;
+}
+
+// src/utils/hooks.ts
+function asArray(hook) {
+  if (hook === void 0) {
+    return [];
+  }
+  if (Array.isArray(hook)) {
+    return hook;
+  }
+  return [hook];
+}
+function normalizeHooks(hooks) {
+  return {
+    beforeRequest: asArray(hooks?.beforeRequest),
+    afterResponse: asArray(hooks?.afterResponse),
+    onError: asArray(hooks?.onError),
+    onRateLimit: asArray(hooks?.onRateLimit)
+  };
+}
+function mergeHooks(globalHooks, requestHooks) {
+  const localHooks = normalizeHooks(requestHooks);
+  return {
+    beforeRequest: [...globalHooks.beforeRequest, ...localHooks.beforeRequest],
+    afterResponse: [...globalHooks.afterResponse, ...localHooks.afterResponse],
+    onError: [...globalHooks.onError, ...localHooks.onError],
+    onRateLimit: [...globalHooks.onRateLimit, ...localHooks.onRateLimit]
+  };
+}
+
+// src/utils/lru-cache.ts
+var LruTtlCache = class {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+    if (!Number.isInteger(maxSize) || maxSize <= 0) {
+      throw new Error("Cache maxSize must be a positive integer.");
+    }
+  }
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * Read an entry and refresh LRU order.
+   */
+  get(key, nowMs = Date.now()) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt <= nowMs) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+  /**
+   * Store an entry with a dedicated TTL.
+   */
+  set(key, value, ttlMs, nowMs = Date.now()) {
+    if (ttlMs <= 0) {
+      return;
+    }
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    }
+    this.entries.set(key, {
+      value,
+      expiresAt: nowMs + ttlMs
+    });
+    this.evictOverflow();
+  }
+  /**
+   * Delete a single cache entry.
+   */
+  delete(key) {
+    return this.entries.delete(key);
+  }
+  /**
+   * Delete entries that match a predicate.
+   */
+  deleteWhere(predicate) {
+    let removed = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      if (predicate(key, entry.value)) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  /**
+   * Current cache size.
+   */
+  size() {
+    return this.entries.size;
+  }
+  /**
+   * Clear all cached entries.
+   */
+  clear() {
+    this.entries.clear();
+  }
+  evictOverflow() {
+    while (this.entries.size > this.maxSize) {
+      const iteratorResult = this.entries.keys().next();
+      if (iteratorResult.done) {
+        break;
+      }
+      this.entries.delete(iteratorResult.value);
+    }
+  }
+};
+
+// src/utils/rate-limit.ts
+var RETRY_AFTER_HEADERS = ["retry-after"];
+var RESET_AFTER_HEADERS = [
+  "x-ratelimit-reset-after",
+  "x-rate-limit-reset-after",
+  "ratelimit-reset-after"
+];
+var RESET_HEADERS = [
+  "x-ratelimit-reset",
+  "x-rate-limit-reset",
+  "ratelimit-reset"
+];
+var REMAINING_HEADERS = [
+  "x-ratelimit-remaining",
+  "x-rate-limit-remaining",
+  "ratelimit-remaining"
+];
+var SCOPE_HEADERS = [
+  "x-ratelimit-scope",
+  "x-rate-limit-scope",
+  "ratelimit-scope"
+];
+function normalizeHeaderName2(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/gu, "");
+}
+function getHeaderValue(headers, candidates) {
+  for (const candidate of candidates) {
+    const value = headers.get(candidate);
+    if (value !== null) {
+      return value;
+    }
+  }
+  const candidateNames = new Set(candidates.map((candidate) => normalizeHeaderName2(candidate)));
+  for (const [name, value] of headers.entries()) {
+    if (candidateNames.has(normalizeHeaderName2(name))) {
+      return value;
+    }
+  }
+  return null;
+}
+function parseRetryAfterSeconds(retryAfterHeader, nowMs = Date.now()) {
+  if (!retryAfterHeader) {
+    return null;
+  }
+  const normalized = retryAfterHeader.trim();
+  if (normalized.length === 0) {
+    return null;
+  }
+  const numericSeconds = Number(normalized);
+  if (Number.isFinite(numericSeconds)) {
+    return Math.max(0, Math.ceil(numericSeconds));
+  }
+  const dateValue = Date.parse(normalized);
+  if (Number.isNaN(dateValue)) {
+    return null;
+  }
+  return Math.max(0, Math.ceil((dateValue - nowMs) / 1e3));
+}
+function parseRetryAfterMs(retryAfterHeader, nowMs = Date.now()) {
+  const retryAfterSeconds = parseRetryAfterSeconds(retryAfterHeader, nowMs);
+  if (retryAfterSeconds === null) {
+    return void 0;
+  }
+  return retryAfterSeconds * 1e3;
+}
+function parseRateLimitResetMs(resetHeader, nowMs = Date.now()) {
+  if (!resetHeader) {
+    return void 0;
+  }
+  const numeric = Number(resetHeader.trim());
+  if (!Number.isFinite(numeric)) {
+    return void 0;
+  }
+  if (numeric > 1e12) {
+    return Math.max(0, Math.round(numeric - nowMs));
+  }
+  if (numeric > 1e9) {
+    return Math.max(0, Math.round(numeric * 1e3 - nowMs));
+  }
+  return Math.max(0, Math.round(numeric * 1e3));
+}
+function parseRateLimitDelayMs(headers, nowMs = Date.now()) {
+  const retryAfterMs = parseRetryAfterMs(getHeaderValue(headers, RETRY_AFTER_HEADERS), nowMs);
+  const resetAfterMs = parseRateLimitResetMs(getHeaderValue(headers, RESET_AFTER_HEADERS), nowMs);
+  const resetMs = parseRateLimitResetMs(getHeaderValue(headers, RESET_HEADERS), nowMs);
+  const values = [retryAfterMs, resetAfterMs, resetMs].filter(
+    (value) => value !== void 0
+  );
+  if (values.length === 0) {
+    return void 0;
+  }
+  return Math.max(...values);
+}
+function extractRetryAfterSeconds(headers, nowMs = Date.now()) {
+  return parseRetryAfterSeconds(getHeaderValue(headers, RETRY_AFTER_HEADERS), nowMs);
+}
+function isRateLimitExhausted(headers) {
+  const remaining = getHeaderValue(headers, REMAINING_HEADERS);
+  if (remaining === null) {
+    return false;
+  }
+  const numeric = Number(remaining);
+  if (!Number.isFinite(numeric)) {
+    return false;
+  }
+  return numeric <= 0;
+}
+function parseRateLimitScope(headers) {
+  const scope = getHeaderValue(headers, SCOPE_HEADERS)?.toLowerCase() ?? "";
+  if (scope.includes("global")) {
+    return "global";
+  }
+  return "route";
+}
+
+// src/utils/retry.ts
+var DEFAULT_RETRY_OPTIONS = {
+  maxAttempts: 4,
+  baseDelayMs: 100,
+  maxDelayMs: 1e4,
+  backoffFactor: 2,
+  jitter: "full",
+  retryableStatusCodes: [429, 500, 502, 503, 504]
+};
+function resolveRetryOptions(input) {
+  if (typeof input === "number") {
+    return {
+      ...DEFAULT_RETRY_OPTIONS,
+      maxAttempts: Math.max(1, Math.floor(input))
+    };
+  }
+  if (!input) {
+    return DEFAULT_RETRY_OPTIONS;
+  }
+  return {
+    maxAttempts: Math.max(1, Math.floor(input.maxAttempts ?? DEFAULT_RETRY_OPTIONS.maxAttempts)),
+    baseDelayMs: Math.max(0, Math.floor(input.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs)),
+    maxDelayMs: Math.max(0, Math.floor(input.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs)),
+    backoffFactor: Math.max(1, input.backoffFactor ?? DEFAULT_RETRY_OPTIONS.backoffFactor),
+    jitter: input.jitter ?? DEFAULT_RETRY_OPTIONS.jitter,
+    retryableStatusCodes: input.retryableStatusCodes ?? DEFAULT_RETRY_OPTIONS.retryableStatusCodes
+  };
+}
+function isRetryableStatus(statusCode, options) {
+  return options.retryableStatusCodes.includes(statusCode);
+}
+function computeRetryDelayMs(retryNumber, options, randomValue, minimumDelayMs) {
+  const exponent = Math.max(0, retryNumber - 1);
+  const cappedDelay = Math.min(
+    options.baseDelayMs * options.backoffFactor ** exponent,
+    options.maxDelayMs
+  );
+  const boundedRandom = Math.min(1, Math.max(0, randomValue));
+  const delay = options.jitter === "full" ? Math.round(boundedRandom * cappedDelay) : Math.round(cappedDelay);
+  if (minimumDelayMs === void 0) {
+    return delay;
+  }
+  return Math.max(delay, minimumDelayMs);
+}
+
+// src/utils/semaphore.ts
+var Semaphore = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error("Semaphore capacity must be a positive integer.");
+    }
+  }
+  queue = [];
+  inUse = 0;
+  /**
+   * Acquire one slot and return a release function.
+   */
+  async acquire() {
+    if (this.inUse < this.capacity) {
+      this.inUse += 1;
+      return () => {
+        this.release();
+      };
+    }
+    await new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+    this.inUse += 1;
+    return () => {
+      this.release();
+    };
+  }
+  release() {
+    this.inUse = Math.max(0, this.inUse - 1);
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    }
+  }
+};
+
+// src/utils/sleep.ts
+function sleep(delayMs) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+}
+
+// src/utils/url.ts
+function buildUrl(baseUrl, apiPath, query) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+  const url = new URL(`${base}${path}`);
+  if (!query) {
+    return url.toString();
+  }
+  const queryEntries = Object.entries(query).filter((entry) => entry[1] !== void 0).sort(([left], [right]) => left.localeCompare(right));
+  for (const [key, value] of queryEntries) {
+    if (value === void 0) {
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+// src/internal/http-client.ts
+var DEFAULT_TIMEOUT_MS = 12e3;
+var DEFAULT_CONCURRENCY_LIMIT = 8;
+var HttpClient = class {
+  fetchFn;
+  baseUrl;
+  timeoutMs;
+  retryOptions;
+  validationMode;
+  logger;
+  defaultHeaders;
+  hooks;
+  observability;
+  cacheSettings;
+  cacheKeyHeaders;
+  cache;
+  semaphore;
+  globalRateLimitUntilMs = 0;
+  routeRateLimitUntilMs = /* @__PURE__ */ new Map();
+  endpointCacheIndex = /* @__PURE__ */ new Map();
+  requestCounter = 0;
+  constructor(options) {
+    const token = options.token.trim();
+    if (!token) {
+      throw new Error("BrawlStarsClient requires a non-empty token.");
+    }
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+    if (!this.fetchFn) {
+      throw new Error("No fetch implementation available. Provide options.fetch.");
+    }
+    this.baseUrl = (options.baseUrl ?? "https://api.brawlstars.com/v1").replace(/\/+$/u, "");
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.retryOptions = resolveRetryOptions(options.retries);
+    this.validationMode = this.resolveValidationMode(options.validation, options.validateResponses);
+    this.logger = options.logger ?? console;
+    this.defaultHeaders = new Headers({
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json"
+    });
+    this.hooks = normalizeHooks(options.hooks);
+    this.observability = new ObservabilityDispatcher(
+      options.observability?.listeners,
+      options.observability?.metrics
+    );
+    this.cacheSettings = this.resolveCacheSettings(options.cache);
+    this.cacheKeyHeaders = options.cacheKeyHeaders ?? DEFAULT_CACHE_HEADER_WHITELIST;
+    this.cache = this.cacheSettings.enabled ? new LruTtlCache(this.cacheSettings.maxSize) : null;
+    const concurrency = options.concurrencyLimit ?? DEFAULT_CONCURRENCY_LIMIT;
+    this.semaphore = new Semaphore(concurrency);
+  }
+  /**
+   * Execute a typed request against the API.
+   */
+  async request(config) {
+    return this.executeRequest(config);
+  }
+  /**
+   * Clear all in-memory cached responses.
+   */
+  clearCache() {
+    this.cache?.clear();
+    this.endpointCacheIndex.clear();
+  }
+  /**
+   * Invalidate cached responses for a given endpoint, or all endpoints when omitted.
+   */
+  invalidateCache(endpoint) {
+    if (!this.cache) {
+      return 0;
+    }
+    if (!endpoint) {
+      const sizeBefore = this.cache.size();
+      this.cache.clear();
+      this.endpointCacheIndex.clear();
+      return sizeBefore;
+    }
+    const keys = this.endpointCacheIndex.get(endpoint);
+    if (!keys) {
+      return 0;
+    }
+    let removed = 0;
+    for (const key of keys) {
+      if (this.cache.delete(key)) {
+        removed += 1;
+      }
+    }
+    this.endpointCacheIndex.delete(endpoint);
+    return removed;
+  }
+  async executeRequest(config) {
+    const retryOptions = resolveRetryOptions(config.options?.retries ?? this.retryOptions);
+    const timeoutMs = config.options?.timeoutMs ?? this.timeoutMs;
+    const validationMode = this.resolveValidationMode(
+      config.options?.validation,
+      config.options?.validateResponse,
+      this.validationMode
+    );
+    const hooks = mergeHooks(this.hooks, config.options?.hooks);
+    const url = buildUrl(this.baseUrl, config.path, config.query);
+    const headers = mergeHeaders(this.defaultHeaders, config.options?.headers);
+    const safeRequestHeaders = toSafeHeaderObject(headers);
+    const requestMetadata = this.createRequestMetadata(config.method, url, config.options, safeRequestHeaders);
+    const requestId = this.createRequestId();
+    const routeKey = config.endpoint;
+    const cachePolicy = this.resolveCachePolicy(config.endpoint, config.options?.cache);
+    const cacheKey = createCacheKey({
+      method: config.method,
+      url,
+      headers
+    }, this.cacheKeyHeaders);
+    const canUseCache = cachePolicy.enabled && this.cache && this.isCacheableMethod(config.method);
+    if (canUseCache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached !== void 0) {
+        return cached;
+      }
+    }
+    for (let attempt = 1; attempt <= retryOptions.maxAttempts; attempt += 1) {
+      await this.waitForRateLimitWindow(routeKey);
+      const release = await this.semaphore.acquire();
+      const startedAt = Date.now();
+      const { signal, cleanup, timedOut } = createRequestSignal(timeoutMs, config.options?.signal);
+      let emittedAttemptError = false;
+      try {
+        await this.observability.emitRequestStart({
+          requestId,
+          endpoint: config.endpoint,
+          method: config.method,
+          url,
+          attempt
+        });
+        for (const hook of hooks.beforeRequest) {
+          await hook({
+            endpoint: config.endpoint,
+            method: config.method,
+            url,
+            attempt,
+            requestId,
+            headers: safeRequestHeaders
+          });
+        }
+        const response = await this.fetchFn(url, {
+          method: config.method,
+          headers,
+          signal
+        });
+        const durationMs = Date.now() - startedAt;
+        const safeResponseHeaders = toSafeHeaderObject(response.headers);
+        await this.observability.emitRequestEnd({
+          requestId,
+          endpoint: config.endpoint,
+          method: config.method,
+          url,
+          attempt,
+          statusCode: response.status,
+          durationMs
+        });
+        for (const hook of hooks.afterResponse) {
+          await hook({
+            endpoint: config.endpoint,
+            method: config.method,
+            url,
+            attempt,
+            requestId,
+            durationMs,
+            statusCode: response.status,
+            headers: safeResponseHeaders
+          });
+        }
+        this.updateRateLimitState(response.headers, response.status, routeKey);
+        if (response.ok) {
+          const payload = await this.parseResponseBody(response);
+          const shouldValidate = validationMode === "strict" || validationMode === "warn";
+          let parsed;
+          try {
+            parsed = config.parser(payload, shouldValidate);
+          } catch (error2) {
+            if (validationMode === "off") {
+              parsed = payload;
+            } else if (validationMode === "warn") {
+              this.logger.warn(
+                `[brawlstars-client] response validation warning (${config.endpoint}): ${error2.message}`
+              );
+              parsed = payload;
+            } else {
+              throw new ResponseValidationError("Response schema validation failed.", {
+                endpoint: config.endpoint,
+                method: config.method,
+                statusCode: response.status,
+                headers: safeResponseHeaders,
+                request: requestMetadata,
+                expectedSchema: config.endpoint,
+                actualPayload: payload,
+                received: payload,
+                requestId,
+                cause: error2
+              });
+            }
+          }
+          if (canUseCache) {
+            this.cache.set(cacheKey, parsed, cachePolicy.ttlMs);
+            this.trackEndpointCacheKey(config.endpoint, cacheKey);
+          }
+          cleanup();
+          return parsed;
+        }
+        const errorBody = await this.parseResponseBody(response);
+        const retryAfter = extractRetryAfterSeconds(response.headers);
+        const requestHeaderId = response.headers.get("x-request-id") ?? void 0;
+        const canRetry = attempt < retryOptions.maxAttempts && isRetryableStatus(response.status, retryOptions);
+        const error = this.createApiError(
+          config.endpoint,
+          config.method,
+          url,
+          config.options,
+          safeRequestHeaders,
+          response.status,
+          safeResponseHeaders,
+          errorBody,
+          retryAfter,
+          requestHeaderId
+        );
+        if (response.status === 429) {
+          for (const hook of hooks.onRateLimit) {
+            await hook({
+              endpoint: config.endpoint,
+              method: config.method,
+              url,
+              attempt,
+              requestId,
+              statusCode: response.status,
+              retryAfter,
+              headers: safeResponseHeaders
+            });
+          }
+        }
+        await this.emitError(hooks, {
+          endpoint: config.endpoint,
+          method: config.method,
+          url,
+          attempt,
+          requestId,
+          durationMs,
+          willRetry: canRetry,
+          error
+        });
+        emittedAttemptError = true;
+        cleanup();
+        if (!canRetry) {
+          throw error;
+        }
+        const rateLimitDelayMs = parseRateLimitDelayMs(response.headers);
+        const retryDelayMs = computeRetryDelayMs(
+          attempt,
+          retryOptions,
+          Math.random(),
+          rateLimitDelayMs
+        );
+        if (retryDelayMs > 0) {
+          await sleep(retryDelayMs);
+        }
+        continue;
+      } catch (error) {
+        cleanup();
+        if (error instanceof ApiError) {
+          if (!emittedAttemptError) {
+            await this.emitError(hooks, {
+              endpoint: config.endpoint,
+              method: config.method,
+              url,
+              attempt,
+              requestId,
+              durationMs: Date.now() - startedAt,
+              willRetry: false,
+              error
+            });
+          }
+          throw error;
+        }
+        const durationMs = Date.now() - startedAt;
+        const wasExternallyAborted = Boolean(config.options?.signal?.aborted) && !timedOut();
+        const canRetry = attempt < retryOptions.maxAttempts && !wasExternallyAborted;
+        const networkError = timedOut() ? new TimeoutError("Request timed out.", {
+          endpoint: config.endpoint,
+          method: config.method,
+          request: requestMetadata,
+          headers: {},
+          retryAfter: null,
+          requestId,
+          cause: error
+        }) : new NetworkError(
+          wasExternallyAborted ? "Request was aborted by caller." : "Network request failed.",
+          {
+            endpoint: config.endpoint,
+            method: config.method,
+            request: requestMetadata,
+            headers: {},
+            retryAfter: null,
+            requestId,
+            cause: error
+          }
+        );
+        await this.emitError(hooks, {
+          endpoint: config.endpoint,
+          method: config.method,
+          url,
+          attempt,
+          requestId,
+          durationMs,
+          willRetry: canRetry,
+          error: networkError
+        });
+        if (!canRetry) {
+          throw networkError;
+        }
+        const retryDelayMs = computeRetryDelayMs(attempt, retryOptions, Math.random());
+        if (retryDelayMs > 0) {
+          await sleep(retryDelayMs);
+        }
+      } finally {
+        release();
+      }
+    }
+    throw new ApiError("Request attempts exhausted.", {
+      endpoint: config.endpoint,
+      method: config.method,
+      request: requestMetadata,
+      headers: {},
+      retryAfter: null,
+      requestId
+    });
+  }
+  createRequestId() {
+    this.requestCounter += 1;
+    return `${Date.now().toString(36)}-${this.requestCounter.toString(36)}`;
+  }
+  createApiError(endpoint, method, url, options, safeRequestHeaders, statusCode, headers, body, retryAfter, requestId) {
+    const request = this.createRequestMetadata(method, url, options, safeRequestHeaders);
+    const metadata = {
+      endpoint,
+      method,
+      request,
+      statusCode,
+      headers,
+      body,
+      retryAfter,
+      requestId
+    };
+    if (statusCode === 429) {
+      return new RateLimitError("Rate limit exceeded.", metadata);
+    }
+    if (statusCode >= 400 && statusCode < 500) {
+      return new ClientError(`API request failed with status ${statusCode}.`, metadata);
+    }
+    return new ApiError(`API request failed with status ${statusCode}.`, metadata);
+  }
+  async emitError(hooks, context) {
+    await this.observability.emitRequestError({
+      requestId: context.requestId,
+      endpoint: context.endpoint,
+      method: context.method,
+      url: context.url,
+      attempt: context.attempt,
+      durationMs: context.durationMs,
+      willRetry: context.willRetry,
+      error: context.error
+    });
+    for (const hook of hooks.onError) {
+      await hook(context);
+    }
+  }
+  resolveValidationMode(mode, deprecatedValidateFlag, fallbackMode = "warn") {
+    if (mode !== void 0) {
+      return mode;
+    }
+    if (deprecatedValidateFlag === void 0) {
+      return fallbackMode;
+    }
+    return deprecatedValidateFlag ? "strict" : "off";
+  }
+  createRequestMetadata(method, url, options, safeHeaders) {
+    if (!options) {
+      return { method, url };
+    }
+    return {
+      method,
+      url,
+      options: {
+        timeoutMs: options.timeoutMs,
+        retries: options.retries,
+        cache: options.cache,
+        validation: this.resolveValidationMode(
+          options.validation,
+          options.validateResponse,
+          this.validationMode
+        ),
+        headers: Object.keys(safeHeaders).length > 0 ? safeHeaders : void 0
+      }
+    };
+  }
+  resolveCacheSettings(cache) {
+    if (cache === false) {
+      return {
+        enabled: false,
+        maxSize: 0,
+        ttlMs: 0,
+        endpointTtlMs: {}
+      };
+    }
+    if (cache === true || cache === void 0) {
+      return {
+        enabled: cache === true,
+        maxSize: 500,
+        ttlMs: 3e4,
+        endpointTtlMs: {}
+      };
+    }
+    return {
+      enabled: true,
+      maxSize: cache.maxSize ?? 500,
+      ttlMs: cache.ttlMs ?? 3e4,
+      endpointTtlMs: cache.endpointTtlMs ?? {}
+    };
+  }
+  resolveCachePolicy(endpoint, requestCache) {
+    if (!this.cacheSettings.enabled || this.cache === null) {
+      return { enabled: false, ttlMs: 0 };
+    }
+    if (requestCache === false) {
+      return { enabled: false, ttlMs: 0 };
+    }
+    const endpointTtlMs = this.cacheSettings.endpointTtlMs[endpoint];
+    const ttlMs = typeof requestCache === "object" && requestCache.ttlMs !== void 0 ? requestCache.ttlMs : endpointTtlMs ?? this.cacheSettings.ttlMs;
+    const enabled = requestCache === true || requestCache === void 0 || typeof requestCache === "object" && requestCache.enabled !== false;
+    return {
+      enabled,
+      ttlMs
+    };
+  }
+  isCacheableMethod(method) {
+    return method === "GET";
+  }
+  trackEndpointCacheKey(endpoint, cacheKey) {
+    const existing = this.endpointCacheIndex.get(endpoint);
+    if (existing) {
+      existing.add(cacheKey);
+      return;
+    }
+    this.endpointCacheIndex.set(endpoint, /* @__PURE__ */ new Set([cacheKey]));
+  }
+  async waitForRateLimitWindow(routeKey) {
+    const now = Date.now();
+    const routeLimit = this.routeRateLimitUntilMs.get(routeKey) ?? 0;
+    const nextAllowedAtMs = Math.max(this.globalRateLimitUntilMs, routeLimit);
+    if (nextAllowedAtMs <= now) {
+      return;
+    }
+    await sleep(nextAllowedAtMs - now);
+  }
+  updateRateLimitState(headers, statusCode, routeKey) {
+    const delayMs = parseRateLimitDelayMs(headers);
+    if (delayMs === void 0) {
+      return;
+    }
+    const shouldUpdate = statusCode === 429 || isRateLimitExhausted(headers);
+    if (!shouldUpdate) {
+      return;
+    }
+    const updateUntil = Date.now() + delayMs;
+    const scope = parseRateLimitScope(headers);
+    if (scope === "global") {
+      this.globalRateLimitUntilMs = Math.max(this.globalRateLimitUntilMs, updateUntil);
+      return;
+    }
+    const currentRouteLimit = this.routeRateLimitUntilMs.get(routeKey) ?? 0;
+    this.routeRateLimitUntilMs.set(routeKey, Math.max(currentRouteLimit, updateUntil));
+  }
+  async parseResponseBody(response) {
+    if (response.status === 204) {
+      return void 0;
+    }
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (contentType.includes("application/json")) {
+      try {
+        return await response.json();
+      } catch {
+        return void 0;
+      }
+    }
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+};
+
+// src/validation/guards.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isStringMap(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every((entry) => typeof entry === "string");
+}
+function isArrayOf(value, guard) {
+  return Array.isArray(value) && value.every((entry) => guard(entry));
+}
+
+// src/validation/list-response.ts
+function isPaging(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (value.cursors === void 0) {
+    return true;
+  }
+  if (!isRecord(value.cursors)) {
+    return false;
+  }
+  const before = value.cursors.before;
+  const after = value.cursors.after;
+  return (before === void 0 || isString(before)) && (after === void 0 || isString(after));
+}
+function normalizeListResponse(payload, itemGuard) {
+  if (isArrayOf(payload, itemGuard)) {
+    return { items: payload };
+  }
+  if (!isRecord(payload)) {
+    throw new Error("Expected list response object or array.");
+  }
+  const items = payload.items;
+  if (!isArrayOf(items, itemGuard)) {
+    throw new Error("Expected `items` array in list response.");
+  }
+  const paging = payload.paging;
+  if (paging !== void 0 && !isPaging(paging)) {
+    throw new Error("Invalid `paging` object in list response.");
+  }
+  return {
+    items,
+    paging
+  };
+}
+
+// src/validation/validators.ts
+function hasString(record, key) {
+  return isString(record[key]);
+}
+function hasNumber(record, key) {
+  return isNumber(record[key]);
+}
+function hasBoolean(record, key) {
+  return isBoolean(record[key]);
+}
+function isJsonLocalizedName(value) {
+  return isStringMap(value);
+}
+function isPlayerIcon(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id");
+}
+function isAccessory(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name);
+}
+function isStarPower(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name);
+}
+function isHyperCharge(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name);
+}
+function isGearStat(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && hasNumber(value, "level") && isJsonLocalizedName(value.name);
+}
+function isSkin(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name);
+}
+function isBrawlerBuffies(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasBoolean(value, "gadget") && hasBoolean(value, "starPower") && hasBoolean(value, "hyperCharge");
+}
+function isBrawlerStat(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && hasNumber(value, "rank") && hasNumber(value, "trophies") && hasNumber(value, "highestTrophies") && hasNumber(value, "prestigeLevel") && hasNumber(value, "power") && hasNumber(value, "currentWinStreak") && hasNumber(value, "maxWinStreak") && isJsonLocalizedName(value.name) && isArrayOf(value.gadgets, isAccessory) && isArrayOf(value.starPowers, isStarPower) && isArrayOf(value.hyperCharges, isHyperCharge) && isArrayOf(value.gears, isGearStat) && isBrawlerBuffies(value.buffies) && isSkin(value.skin);
+}
+function isPlayerClub(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "tag") && hasString(value, "name");
+}
+function isPlayer(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const hasClub = value.club === void 0 || isPlayerClub(value.club);
+  return hasString(value, "tag") && hasString(value, "name") && hasString(value, "nameColor") && isPlayerIcon(value.icon) && hasClub && hasNumber(value, "trophies") && hasNumber(value, "highestTrophies") && hasNumber(value, "totalPrestigeLevel") && hasNumber(value, "expLevel") && hasNumber(value, "expPoints") && hasNumber(value, "soloVictories") && hasNumber(value, "duoVictories") && hasNumber(value, "bestRoboRumbleTime") && hasNumber(value, "bestTimeAsBigBrawler") && hasBoolean(value, "isQualifiedFromChampionshipChallenge") && hasNumber(value, "3vs3Victories") && isArrayOf(value.brawlers, isBrawlerStat);
+}
+function isClubMember(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "tag") && hasString(value, "name") && hasString(value, "nameColor") && hasNumber(value, "trophies") && hasString(value, "role") && isPlayerIcon(value.icon);
+}
+function isClub(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "tag") && hasString(value, "name") && hasString(value, "description") && hasNumber(value, "trophies") && hasNumber(value, "requiredTrophies") && isArrayOf(value.members, isClubMember) && hasString(value, "type") && hasNumber(value, "badgeId") && hasBoolean(value, "isFamilyFriendly");
+}
+function isClubRanking(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "tag") && hasString(value, "name") && hasNumber(value, "trophies") && hasNumber(value, "rank") && hasNumber(value, "memberCount") && hasNumber(value, "badgeId");
+}
+function isPlayerRankingClub(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "name");
+}
+function isPlayerRanking(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "tag") && hasString(value, "name") && hasString(value, "nameColor") && hasNumber(value, "rank") && hasNumber(value, "trophies") && isPlayerIcon(value.icon) && isPlayerRankingClub(value.club);
+}
+function isBrawler(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name) && isArrayOf(value.gadgets, isAccessory) && isArrayOf(value.starPowers, isStarPower) && isArrayOf(value.hyperCharges, isHyperCharge) && isArrayOf(value.gears, isGearStat);
+}
+function isEventType(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && isJsonLocalizedName(value.name);
+}
+function isScheduledEventLocation(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const modifiers = value.modifiers;
+  const modifiersValid = modifiers === void 0 || Array.isArray(modifiers) && modifiers.every((entry) => isString(entry));
+  return hasNumber(value, "id") && hasNumber(value, "modeId") && hasString(value, "mode") && isJsonLocalizedName(value.map) && modifiersValid;
+}
+function isScheduledEvent(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "slotId") && hasString(value, "startTime") && hasString(value, "endTime") && isScheduledEventLocation(value.event);
+}
+function isEvent(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasNumber(value, "id") && hasNumber(value, "modeId") && hasString(value, "mode") && isJsonLocalizedName(value.map);
+}
+function isBattle(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return hasString(value, "battleTime") && isRecord(value.battle) && isEvent(value.event);
+}
+
+// src/internal/response-parsers.ts
+function parseSingle(endpoint, payload, validate, guard) {
+  if (!validate) {
+    return payload;
+  }
+  if (!guard(payload)) {
+    throw new Error(`Response validation failed for endpoint '${endpoint}'.`);
+  }
+  return payload;
+}
+function normalizeListWithoutValidation(payload) {
+  if (Array.isArray(payload)) {
+    return { items: payload };
+  }
+  if (!isRecord(payload)) {
+    throw new Error("Expected list response object or array.");
+  }
+  if (!Array.isArray(payload.items)) {
+    throw new Error("Expected `items` array in list response.");
+  }
+  if (payload.paging !== void 0 && !isRecord(payload.paging)) {
+    throw new Error("Invalid `paging` value in list response.");
+  }
+  return {
+    items: payload.items,
+    paging: payload.paging
+  };
+}
+function parseList(endpoint, payload, validate, guard) {
+  if (!validate) {
+    return normalizeListWithoutValidation(payload);
+  }
+  try {
+    return normalizeListResponse(payload, guard);
+  } catch (error) {
+    throw new Error(
+      `Response validation failed for endpoint '${endpoint}': ${error.message}`
+    );
+  }
+}
+var endpointParsers = {
+  "players.get": (payload, validate) => parseSingle("players.get", payload, validate, isPlayer),
+  "players.getBattleLog": (payload, validate) => parseList("players.getBattleLog", payload, validate, isBattle),
+  "clubs.get": (payload, validate) => parseSingle("clubs.get", payload, validate, isClub),
+  "clubs.getMembers": (payload, validate) => parseList("clubs.getMembers", payload, validate, isClubMember),
+  "rankings.getClubs": (payload, validate) => parseList("rankings.getClubs", payload, validate, isClubRanking),
+  "rankings.getPlayers": (payload, validate) => parseList("rankings.getPlayers", payload, validate, isPlayerRanking),
+  "rankings.getBrawlers": (payload, validate) => parseList("rankings.getBrawlers", payload, validate, isPlayerRanking),
+  "brawlers.list": (payload, validate) => parseList("brawlers.list", payload, validate, isBrawler),
+  "brawlers.get": (payload, validate) => parseSingle("brawlers.get", payload, validate, isBrawler),
+  "gamemodes.list": (payload, validate) => parseList("gamemodes.list", payload, validate, isEventType),
+  "events.getRotation": (payload, validate) => parseList("events.getRotation", payload, validate, isScheduledEvent)
+};
+
+// src/utils/pagination.ts
+function normalizeCursorPaginationQuery(query) {
+  if (!query) {
+    return void 0;
+  }
+  const hasBefore = typeof query.before === "string" && query.before.length > 0;
+  const hasAfter = typeof query.after === "string" && query.after.length > 0;
+  if (hasBefore && hasAfter) {
+    throw new Error("Only one of `before` or `after` can be provided.");
+  }
+  if (query.limit !== void 0) {
+    if (!Number.isInteger(query.limit) || query.limit <= 0) {
+      throw new Error("`limit` must be a positive integer when provided.");
+    }
+  }
+  return {
+    before: hasBefore ? query.before : void 0,
+    after: hasAfter ? query.after : void 0,
+    limit: query.limit
+  };
+}
+
+// src/utils/options.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isValidationMode(value) {
+  return value === "off" || value === "warn" || value === "strict";
+}
+function resolvePaginatedArgs(first, second) {
+  if (second !== void 0) {
+    return {
+      query: first,
+      requestOptions: second
+    };
+  }
+  if (!first) {
+    return {
+      query: void 0,
+      requestOptions: void 0
+    };
+  }
+  if (!isObject(first)) {
+    return {
+      query: void 0,
+      requestOptions: void 0
+    };
+  }
+  const query = {
+    before: typeof first.before === "string" ? first.before : void 0,
+    after: typeof first.after === "string" ? first.after : void 0,
+    limit: typeof first.limit === "number" ? first.limit : void 0
+  };
+  const requestOptions = {
+    timeoutMs: typeof first.timeoutMs === "number" ? first.timeoutMs : void 0,
+    retries: typeof first.retries === "number" || isObject(first.retries) ? first.retries : void 0,
+    signal: first.signal instanceof AbortSignal ? first.signal : void 0,
+    headers: first.headers,
+    cache: typeof first.cache === "boolean" || isObject(first.cache) ? first.cache : void 0,
+    validation: isValidationMode(first.validation) ? first.validation : void 0,
+    validateResponse: typeof first.validateResponse === "boolean" ? first.validateResponse : void 0,
+    hooks: isObject(first.hooks) ? first.hooks : void 0
+  };
+  const hasQuery = query.before !== void 0 || query.after !== void 0 || query.limit !== void 0;
+  const hasRequestOptions = requestOptions.timeoutMs !== void 0 || requestOptions.retries !== void 0 || requestOptions.signal !== void 0 || requestOptions.headers !== void 0 || requestOptions.cache !== void 0 || requestOptions.validation !== void 0 || requestOptions.validateResponse !== void 0 || requestOptions.hooks !== void 0;
+  return {
+    query: hasQuery ? query : void 0,
+    requestOptions: hasRequestOptions ? requestOptions : void 0
+  };
+}
+
+// src/resources/brawlers-resource.ts
+var BrawlersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  list(optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "brawlers.list",
+      method: "GET",
+      path: "/brawlers",
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["brawlers.list"]
+    });
+  }
+  /**
+   * Get one brawler by identifier.
+   */
+  get(brawlerId, opts) {
+    return this.http.request({
+      endpoint: "brawlers.get",
+      method: "GET",
+      path: `/brawlers/${encodeURIComponent(String(brawlerId))}`,
+      options: opts,
+      parser: endpointParsers["brawlers.get"]
+    });
+  }
+};
+
+// src/utils/tag.ts
+function encodeTag(tag, options) {
+  const uppercase = options?.uppercase ?? true;
+  const compactTag = String(tag).replace(/\s+/gu, "");
+  const normalizedTag = uppercase ? compactTag.toUpperCase() : compactTag;
+  const prefixedTag = normalizedTag.startsWith("#") ? normalizedTag : `#${normalizedTag}`;
+  return encodeURIComponent(prefixedTag);
+}
+
+// src/resources/clubs-resource.ts
+var ClubsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get full club details by tag.
+   */
+  get(clubTag, opts) {
+    return this.http.request({
+      endpoint: "clubs.get",
+      method: "GET",
+      path: `/clubs/${encodeTag(clubTag)}`,
+      options: opts,
+      parser: endpointParsers["clubs.get"]
+    });
+  }
+  getMembers(clubTag, optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "clubs.getMembers",
+      method: "GET",
+      path: `/clubs/${encodeTag(clubTag)}/members`,
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["clubs.getMembers"]
+    });
+  }
+};
+
+// src/resources/events-resource.ts
+var EventsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get currently active event rotation.
+   */
+  getRotation(opts) {
+    return this.http.request({
+      endpoint: "events.getRotation",
+      method: "GET",
+      path: "/events/rotation",
+      options: opts,
+      parser: endpointParsers["events.getRotation"]
+    });
+  }
+};
+
+// src/resources/gamemodes-resource.ts
+var GameModesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  list(optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "gamemodes.list",
+      method: "GET",
+      path: "/gamemodes",
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["gamemodes.list"]
+    });
+  }
+};
+
+// src/resources/players-resource.ts
+var PlayersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get a player profile by tag.
+   *
+   * @example
+   * const player = await client.players.get("#2PP");
+   */
+  get(playerTag, opts) {
+    return this.http.request({
+      endpoint: "players.get",
+      method: "GET",
+      path: `/players/${encodeTag(playerTag)}`,
+      options: opts,
+      parser: endpointParsers["players.get"]
+    });
+  }
+  /**
+   * Get recent battle log entries for a player.
+   *
+   * @example
+   * const battles = await client.players.getBattleLog("#2PP");
+   */
+  getBattleLog(playerTag, opts) {
+    return this.http.request({
+      endpoint: "players.getBattleLog",
+      method: "GET",
+      path: `/players/${encodeTag(playerTag)}/battlelog`,
+      options: opts,
+      parser: endpointParsers["players.getBattleLog"]
+    });
+  }
+};
+
+// src/resources/rankings-resource.ts
+var RankingsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  getClubs(countryCode, optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "rankings.getClubs",
+      method: "GET",
+      path: `/rankings/${encodeURIComponent(countryCode)}/clubs`,
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["rankings.getClubs"]
+    });
+  }
+  getPlayers(countryCode, optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "rankings.getPlayers",
+      method: "GET",
+      path: `/rankings/${encodeURIComponent(countryCode)}/players`,
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["rankings.getPlayers"]
+    });
+  }
+  getBrawlers(countryCode, brawlerId, optsOrQuery, legacyOpts) {
+    const { query, requestOptions } = resolvePaginatedArgs(optsOrQuery, legacyOpts);
+    return this.http.request({
+      endpoint: "rankings.getBrawlers",
+      method: "GET",
+      path: `/rankings/${encodeURIComponent(countryCode)}/brawlers/${encodeURIComponent(String(brawlerId))}`,
+      query: normalizeCursorPaginationQuery(query),
+      options: requestOptions,
+      parser: endpointParsers["rankings.getBrawlers"]
+    });
+  }
+};
+
+// src/client/brawl-stars-client.ts
+var BrawlStarsClient = class {
+  http;
+  /**
+   * Player operations.
+   */
+  players;
+  /**
+   * Club operations.
+   */
+  clubs;
+  /**
+   * Ranking operations.
+   */
+  rankings;
+  /**
+   * Brawler operations.
+   */
+  brawlers;
+  /**
+   * Game mode operations.
+   */
+  gamemodes;
+  /**
+   * Event operations.
+   */
+  events;
+  /**
+   * Create a new API client.
+   */
+  constructor(options) {
+    this.http = new HttpClient(options);
+    this.players = new PlayersResource(this.http);
+    this.clubs = new ClubsResource(this.http);
+    this.rankings = new RankingsResource(this.http);
+    this.brawlers = new BrawlersResource(this.http);
+    this.gamemodes = new GameModesResource(this.http);
+    this.events = new EventsResource(this.http);
+  }
+  /**
+   * Clear all in-memory cached responses.
+   */
+  clearCache() {
+    this.http.clearCache();
+  }
+  /**
+   * Invalidate cache entries for one endpoint or all endpoints.
+   */
+  invalidateCache(endpoint) {
+    return this.http.invalidateCache(endpoint);
+  }
+};
+
+// src/client/create-client.ts
+function createBrawlStarsClient(options) {
+  return new BrawlStarsClient(options);
+}
+
+// src/observability/prom-client-adapter.ts
+function createPromClientAdapter(options) {
+  return {
+    onRequestStart(event) {
+      options.requestsStarted?.inc({
+        endpoint: event.endpoint,
+        method: event.method
+      });
+    },
+    onRequestEnd(event) {
+      options.requestsCompleted?.inc({
+        endpoint: event.endpoint,
+        method: event.method,
+        statusCode: event.statusCode
+      });
+      options.requestDurationMs?.observe(
+        {
+          endpoint: event.endpoint,
+          method: event.method,
+          statusCode: event.statusCode
+        },
+        event.durationMs
+      );
+    },
+    onRequestError(event) {
+      options.requestsFailed?.inc({
+        endpoint: event.endpoint,
+        method: event.method,
+        errorName: event.error.name
+      });
+    }
+  };
+}
+export {
+  ApiError,
+  BrawlStarsClient,
+  ClientError,
+  NetworkError,
+  RateLimitError,
+  ResponseValidationError,
+  TimeoutError,
+  ValidationError,
+  createBrawlStarsClient,
+  createPromClientAdapter,
+  encodeTag
+};
+//# sourceMappingURL=index.js.map