11elo 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# 11elo
+
+[![npm](https://img.shields.io/npm/v/11elo)](https://www.npmjs.com/package/11elo)
+[![Node.js](https://img.shields.io/node/v/11elo)](https://www.npmjs.com/package/11elo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+JavaScript/Node.js client for the **[11elo](https://11elo.com) Soccer ELO API** — live and historical Elo ratings for German football (Bundesliga, 2. Bundesliga, 3. Liga).
+
+Works in **Node.js 18+**, modern browsers, Deno and Bun — uses the native `fetch` API with no extra dependencies.
+
+## Installation
+
+```bash
+npm install 11elo
+```
+
+## Quick start
+
+```js
+import { Client } from '11elo';
+
+const client = new Client({ apiKey: '11e_fre_your_key_here' });
+
+// List all teams
+const teams = await client.getTeams();
+teams.forEach(t => console.log(t.teamName, t.currentElo));
+
+// Get detailed info for one team
+const { team, eloHistory } = await client.getTeam('Bayern München');
+console.log(team.currentElo);
+
+// Upcoming matches
+const upcoming = await client.getUpcomingMatches({ league: 'BL1', limit: 10 });
+upcoming.forEach(m => console.log(m.homeTeam, 'vs', m.awayTeam));
+```
+
+## Getting an API key
+
+Register for free at <https://11elo.com/developer>.  
+Keys follow the format `11e_<tier>_<hex>` and are sent via the `X-API-Key` request header (handled automatically by this client).
+
+**Rate limits by tier:**
+
+| Tier  | Requests / day |
+|-------|---------------|
+| Free  | 100           |
+| Basic | 1,000         |
+| Pro   | 10,000        |
+
+## API reference
+
+### `new Client(options)`
+
+| Option      | Default               | Description                                    |
+|-------------|-----------------------|------------------------------------------------|
+| `apiKey`    | —                     | Your 11elo API key (**required**)              |
+| `baseUrl`   | `https://11elo.com`   | Override for self-hosted / local dev           |
+| `timeoutMs` | `30000`               | Request timeout in milliseconds                |
+
+---
+
+### Teams
+
+#### `client.getTeams() → Promise<object[]>`
+
+Returns all teams with current ELO stats, league info and trend data.
+
+```js
+const teams = await client.getTeams();
+// [{ teamName: 'Bayern München', currentElo: 1847, league: 'BL1', ... }, ...]
+```
+
+#### `client.getTeam(teamName) → Promise<object>`
+
+Full detail for one team — ELO history, recent form, upcoming matches, career stats.
+
+```js
+const { team, eloHistory, recentForm, upcomingMatches } =
+  await client.getTeam('Borussia Dortmund');
+```
+
+#### `client.getHeadToHead(team1, team2) → Promise<object[]>`
+
+Historical head-to-head match results between two teams.
+
+```js
+const h2h = await client.getHeadToHead('Bayern München', 'Borussia Dortmund');
+// [{ date: '2026-02-15', result: '2:1', winner: 'Bayern München', ... }, ...]
+```
+
+---
+
+### Matches
+
+#### `client.getMatches(options?) → Promise<object[]>`
+
+Paginated match history.  All options are optional.
+
+| Option   | Description                             |
+|----------|-----------------------------------------|
+| `season` | Filter by season, e.g. `"2024/2025"`   |
+| `from`   | ISO-8601 start date (`"YYYY-MM-DD"`)   |
+| `to`     | ISO-8601 end date (`"YYYY-MM-DD"`)     |
+| `limit`  | Max results (default 100, max 500)      |
+| `offset` | Pagination offset (default 0)           |
+
+```js
+const matches = await client.getMatches({ season: '2024/2025', limit: 50 });
+```
+
+#### `client.getUpcomingMatches(options?) → Promise<object[]>`
+
+Upcoming fixtures with ELO-difference predictions.
+
+| Option   | Description                              |
+|----------|------------------------------------------|
+| `league` | League code filter, e.g. `"BL1"`        |
+| `sort`   | Sort order (default `"date"`)            |
+| `limit`  | Max results (default 50, max 200)        |
+
+```js
+const upcoming = await client.getUpcomingMatches({ league: 'BL1' });
+```
+
+#### `client.getMatch(matchId) → Promise<object>`
+
+Full detail for a single match.
+
+```js
+const { match, homeRecentForm, headToHead } = await client.getMatch(12345);
+```
+
+---
+
+### Seasons
+
+#### `client.getSeasons() → Promise<{ seasons: string[], latestSeason: string }>`
+
+List all available seasons.
+
+```js
+const { seasons, latestSeason } = await client.getSeasons();
+```
+
+#### `client.getSeason(season, options?) → Promise<object[]>`
+
+Per-team ELO change statistics for a given season.
+
+| Option   | Description                             |
+|----------|-----------------------------------------|
+| `league` | Optional league filter, e.g. `"BL1"`   |
+
+```js
+const entries = await client.getSeason('2024/2025', { league: 'BL1' });
+// [{ teamName: 'Bayern München', startElo: 1820, endElo: 1847, change: 27, ... }, ...]
+```
+
+---
+
+### Comparison
+
+#### `client.getComparisonHistory(teams) → Promise<object>`
+
+Time-series ELO data for multiple teams in one call.
+
+```js
+const history = await client.getComparisonHistory([
+  'Bayern München',
+  'Borussia Dortmund',
+]);
+// {
+//   'Bayern München': [{ Date: 1709856000000, ELO: 1847 }, ...],
+//   'Borussia Dortmund': [{ Date: 1709856000000, ELO: 1720 }, ...]
+// }
+```
+
+---
+
+## Error handling
+
+All exceptions extend `ElevenEloError`.
+
+| Class                | When thrown                                      |
+|----------------------|--------------------------------------------------|
+| `AuthenticationError`| API key is missing or invalid (HTTP 401)         |
+| `RateLimitError`     | Daily quota exceeded (HTTP 429)                  |
+| `NotFoundError`      | Resource does not exist (HTTP 404)               |
+| `ApiError`           | Any other non-2xx response                       |
+
+```js
+import { Client, AuthenticationError, RateLimitError, NotFoundError } from '11elo';
+
+const client = new Client({ apiKey: '11e_fre_your_key_here' });
+
+try {
+  const team = await client.getTeam('Unknown FC');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.error('Team not found');
+  } else if (err instanceof RateLimitError) {
+    console.error('Rate limit hit, resets at', err.resetAt);
+  } else if (err instanceof AuthenticationError) {
+    console.error('Bad API key');
+  } else {
+    throw err;
+  }
+}
+```
+
+## CommonJS usage
+
+The package ships as ES modules (`"type": "module"`).  For CommonJS projects, use dynamic `import()`:
+
+```js
+const { Client } = await import('11elo');
+```
+
+Or use a bundler (webpack, Rollup, esbuild) which handles the interop automatically.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "11elo",
+  "version": "0.1.0",
+  "description": "JavaScript/Node.js client for the 11elo Soccer ELO API",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "soccer",
+    "football",
+    "elo",
+    "bundesliga",
+    "api",
+    "client"
+  ],
+  "license": "MIT",
+  "homepage": "https://11elo.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Chafficui/11elo-sdk.git",
+    "directory": "javascript"
+  },
+  "bugs": {
+    "url": "https://github.com/Chafficui/11elo-sdk/issues"
+  },
+  "scripts": {
+    "test": "node --test src/client.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.test.js

@@ -0,0 +1,214 @@
+/**
+ * Tests for the 11elo JavaScript client.
+ * Uses the built-in Node.js test runner (node:test) – no extra dependencies.
+ *
+ * Run: node --test src/client.test.js
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  Client,
+  ElevenEloError,
+  AuthenticationError,
+  RateLimitError,
+  NotFoundError,
+  ApiError,
+} from './index.js';
+
+const BASE = 'https://11elo.com';
+
+// ---------------------------------------------------------------------------
+// Minimal fetch mock helpers
+// ---------------------------------------------------------------------------
+
+function mockFetch(status, body, headers = {}) {
+  return async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json', ...headers },
+    });
+}
+
+function makeMockClient(fetchFn) {
+  const client = new Client({ apiKey: '11e_fre_testkey' });
+  // Replace global fetch for the duration of the test
+  client._fetch = fetchFn;
+  // Patch internal _get to use _fetch
+  const originalGet = client._get.bind(client);
+  client._get = async (path, params = {}) => {
+    const url = client._url(path) + client._buildQuery(params);
+    const controller = new AbortController();
+    const timerId = setTimeout(() => controller.abort(), client._timeoutMs);
+    let response;
+    try {
+      response = await client._fetch(url, {
+        method: 'GET',
+        headers: { 'X-API-Key': client._apiKey, Accept: 'application/json' },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timerId);
+    }
+    return client._handleResponse(response);
+  };
+  return client;
+}
+
+// ---------------------------------------------------------------------------
+// Constructor tests
+// ---------------------------------------------------------------------------
+
+test('throws when apiKey is missing', () => {
+  assert.throws(() => new Client({}), /apiKey is required/);
+});
+
+test('accepts custom baseUrl and timeoutMs', () => {
+  const c = new Client({ apiKey: 'k', baseUrl: 'http://localhost:3001', timeoutMs: 5000 });
+  assert.equal(c._baseUrl, 'http://localhost:3001');
+  assert.equal(c._timeoutMs, 5000);
+});
+
+// ---------------------------------------------------------------------------
+// Successful responses
+// ---------------------------------------------------------------------------
+
+test('getTeams returns parsed JSON', async () => {
+  const payload = [{ teamName: 'Bayern München', currentElo: 1847 }];
+  const client = makeMockClient(mockFetch(200, payload));
+  const result = await client.getTeams();
+  assert.deepEqual(result, payload);
+});
+
+test('getTeam encodes team name in URL', async () => {
+  const payload = { team: { name: 'Bayern München' } };
+  let capturedUrl;
+  const client = makeMockClient(async (url, opts) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getTeam('Bayern München');
+  assert.ok(capturedUrl.includes('Bayern%20M%C3%BCnchen'));
+});
+
+test('getHeadToHead encodes both team names', async () => {
+  const payload = [{ result: '2:1' }];
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getHeadToHead('Bayern München', 'Borussia Dortmund');
+  assert.ok(capturedUrl.includes('head-to-head'));
+  assert.ok(capturedUrl.includes('Bayern%20M%C3%BCnchen'));
+  assert.ok(capturedUrl.includes('Borussia%20Dortmund'));
+});
+
+test('getMatches passes query params', async () => {
+  const payload = [{ id: 1 }];
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getMatches({ season: '2024/2025', limit: 10, offset: 0 });
+  assert.ok(capturedUrl.includes('limit=10'));
+  assert.ok(capturedUrl.includes('offset=0'));
+  assert.ok(capturedUrl.includes('season='));
+});
+
+test('getUpcomingMatches passes league param', async () => {
+  const payload = [{ id: 2 }];
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getUpcomingMatches({ league: 'BL1' });
+  assert.ok(capturedUrl.includes('league=BL1'));
+});
+
+test('getMatch appends matchId to path', async () => {
+  const payload = { match: { id: 12345 } };
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getMatch(12345);
+  assert.ok(capturedUrl.endsWith('/api/matches/12345'));
+});
+
+test('getSeasons returns seasons object', async () => {
+  const payload = { seasons: ['2025/2026'], latestSeason: '2025/2026' };
+  const client = makeMockClient(mockFetch(200, payload));
+  const result = await client.getSeasons();
+  assert.deepEqual(result, payload);
+});
+
+test('getSeason encodes season in URL', async () => {
+  const payload = [{ teamName: 'Bayern München', change: 27 }];
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getSeason('2024/2025', { league: 'BL1' });
+  assert.ok(capturedUrl.includes('2024'));
+  assert.ok(capturedUrl.includes('league=BL1'));
+});
+
+test('getComparisonHistory joins teams with comma', async () => {
+  const payload = { 'Bayern München': [], 'Borussia Dortmund': [] };
+  let capturedUrl;
+  const client = makeMockClient(async (url) => {
+    capturedUrl = url;
+    return new Response(JSON.stringify(payload), { status: 200 });
+  });
+  await client.getComparisonHistory(['Bayern München', 'Borussia Dortmund']);
+  assert.ok(capturedUrl.includes('teams='));
+});
+
+// ---------------------------------------------------------------------------
+// Error handling
+// ---------------------------------------------------------------------------
+
+test('getTeams throws AuthenticationError on 401', async () => {
+  const client = makeMockClient(mockFetch(401, { error: 'Unauthorized' }));
+  await assert.rejects(() => client.getTeams(), AuthenticationError);
+});
+
+test('getTeams throws RateLimitError on 429 with resetAt', async () => {
+  const client = makeMockClient(
+    mockFetch(429, {}, { 'X-RateLimit-Reset': '2026-03-13T00:00:00Z' }),
+  );
+  try {
+    await client.getTeams();
+    assert.fail('expected RateLimitError');
+  } catch (err) {
+    assert.ok(err instanceof RateLimitError);
+    assert.equal(err.resetAt, '2026-03-13T00:00:00Z');
+  }
+});
+
+test('getTeam throws NotFoundError on 404', async () => {
+  const client = makeMockClient(mockFetch(404, {}));
+  await assert.rejects(() => client.getTeam('Unknown FC'), NotFoundError);
+});
+
+test('getTeams throws ApiError on 500', async () => {
+  const client = makeMockClient(mockFetch(500, {}));
+  try {
+    await client.getTeams();
+    assert.fail('expected ApiError');
+  } catch (err) {
+    assert.ok(err instanceof ApiError);
+    assert.equal(err.statusCode, 500);
+  }
+});
+
+test('getComparisonHistory throws when fewer than two teams given', () => {
+  const client = new Client({ apiKey: 'k' });
+  assert.throws(() => client.getComparisonHistory(['Bayern München']), /at least two/);
+});

package/src/index.js

@@ -0,0 +1,359 @@
+/**
+ * JavaScript/Node.js client for the 11elo Soccer ELO API.
+ *
+ * Requires Node.js 18+ (uses native `fetch`) or any environment that
+ * exposes the global `fetch` function (modern browsers, Deno, Bun, etc.).
+ *
+ * @example
+ * ```js
+ * import { Client } from '11elo';
+ *
+ * const client = new Client({ apiKey: '11e_fre_your_key_here' });
+ *
+ * const teams = await client.getTeams();
+ * console.log(teams[0].teamName, teams[0].currentElo);
+ * ```
+ * @module
+ */
+
+const DEFAULT_BASE_URL = 'https://11elo.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Custom errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Base error class for all 11elo client errors.
+ */
+export class ElevenEloError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ElevenEloError';
+  }
+}
+
+/**
+ * Thrown when the API key is missing or invalid (HTTP 401).
+ */
+export class AuthenticationError extends ElevenEloError {
+  constructor(message = 'Invalid or missing API key. Obtain one at https://11elo.com/developer') {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Thrown when the daily rate limit for the API key tier has been exceeded (HTTP 429).
+ * @property {string|null} resetAt - ISO-8601 timestamp when the limit resets.
+ */
+export class RateLimitError extends ElevenEloError {
+  constructor(message = 'Daily rate limit exceeded. Upgrade your plan at https://11elo.com/developer', resetAt = null) {
+    super(message);
+    this.name = 'RateLimitError';
+    this.resetAt = resetAt;
+  }
+}
+
+/**
+ * Thrown when the requested resource does not exist (HTTP 404).
+ */
+export class NotFoundError extends ElevenEloError {
+  constructor(message) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+/**
+ * Thrown for unexpected API errors (any non-2xx response not covered above).
+ * @property {number} statusCode - The HTTP status code.
+ */
+export class ApiError extends ElevenEloError {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+/**
+ * Synchronous-style async client for the 11elo public API.
+ *
+ * @example
+ * ```js
+ * const client = new Client({ apiKey: '11e_fre_your_key_here' });
+ * const team = await client.getTeam('Bayern München');
+ * console.log(team.team.currentElo);
+ * ```
+ */
+export class Client {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey - Your 11elo API key (required).
+   * @param {string} [options.baseUrl='https://11elo.com'] - Override the base URL.
+   * @param {number} [options.timeoutMs=30000] - Request timeout in milliseconds.
+   */
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    if (!apiKey) {
+      throw new Error('apiKey is required');
+    }
+    this._apiKey = apiKey;
+    this._baseUrl = baseUrl.replace(/\/$/, '');
+    this._timeoutMs = timeoutMs;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  _url(path) {
+    return `${this._baseUrl}${path}`;
+  }
+
+  _buildQuery(params) {
+    const filtered = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v !== undefined && v !== null),
+    );
+    const qs = new URLSearchParams(filtered).toString();
+    return qs ? `?${qs}` : '';
+  }
+
+  async _get(path, params = {}) {
+    const url = this._url(path) + this._buildQuery(params);
+    const controller = new AbortController();
+    const timerId = setTimeout(() => controller.abort(), this._timeoutMs);
+
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': this._apiKey,
+          Accept: 'application/json',
+        },
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new ElevenEloError(`Request timed out after ${this._timeoutMs}ms`);
+      }
+      throw new ElevenEloError(`Network error: ${err.message}`);
+    } finally {
+      clearTimeout(timerId);
+    }
+
+    return this._handleResponse(response);
+  }
+
+  async _handleResponse(response) {
+    if (response.status === 401) {
+      throw new AuthenticationError();
+    }
+    if (response.status === 429) {
+      const resetAt = response.headers.get('X-RateLimit-Reset');
+      throw new RateLimitError(undefined, resetAt);
+    }
+    if (response.status === 404) {
+      throw new NotFoundError(`Resource not found: ${response.url}`);
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new ApiError(
+        `API request failed with status ${response.status}: ${body}`,
+        response.status,
+      );
+    }
+
+    try {
+      return await response.json();
+    } catch {
+      const text = await response.text().catch(() => '');
+      throw new ElevenEloError(`Failed to parse JSON response: ${text}`);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Teams
+  // -------------------------------------------------------------------------
+
+  /**
+   * Return all teams with their current ELO stats and league info.
+   *
+   * @returns {Promise<Array<object>>} Array of team objects.
+   *
+   * @example
+   * ```js
+   * const teams = await client.getTeams();
+   * teams.forEach(t => console.log(t.teamName, t.currentElo));
+   * ```
+   */
+  getTeams() {
+    return this._get('/api/teams');
+  }
+
+  /**
+   * Return detailed information for a single team.
+   *
+   * @param {string} teamName - The canonical team name, e.g. `"Bayern München"`.
+   * @returns {Promise<object>} Object with `team`, `eloHistory`, `recentForm`,
+   *   `significantMatches`, `stats`, and `upcomingMatches`.
+   *
+   * @example
+   * ```js
+   * const { team, eloHistory } = await client.getTeam('Bayern München');
+   * console.log(team.currentElo);
+   * ```
+   */
+  getTeam(teamName) {
+    return this._get(`/api/teams/${encodeURIComponent(teamName)}`);
+  }
+
+  /**
+   * Return head-to-head match history between two teams.
+   *
+   * @param {string} team1 - Name of the first team.
+   * @param {string} team2 - Name of the second team.
+   * @returns {Promise<Array<object>>} Array of match result objects.
+   *
+   * @example
+   * ```js
+   * const h2h = await client.getHeadToHead('Bayern München', 'Borussia Dortmund');
+   * console.log(h2h[0].result);
+   * ```
+   */
+  getHeadToHead(team1, team2) {
+    return this._get(
+      `/api/teams/${encodeURIComponent(team1)}/head-to-head/${encodeURIComponent(team2)}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Matches
+  // -------------------------------------------------------------------------
+
+  /**
+   * Return a paginated list of historical matches.
+   *
+   * @param {object} [options]
+   * @param {string} [options.season] - Season string, e.g. `"2024/2025"`.
+   * @param {string} [options.from] - ISO-8601 start date (`"YYYY-MM-DD"`).
+   * @param {string} [options.to] - ISO-8601 end date (`"YYYY-MM-DD"`).
+   * @param {number} [options.limit] - Max results (default 100, max 500).
+   * @param {number} [options.offset] - Pagination offset (default 0).
+   * @returns {Promise<Array<object>>} Array of match objects.
+   *
+   * @example
+   * ```js
+   * const matches = await client.getMatches({ season: '2024/2025', limit: 20 });
+   * ```
+   */
+  getMatches({ season, from, to, limit, offset } = {}) {
+    return this._get('/api/matches', { season, from, to, limit, offset });
+  }
+
+  /**
+   * Return upcoming fixtures with ELO-difference predictions.
+   *
+   * @param {object} [options]
+   * @param {string} [options.league] - League code filter, e.g. `"BL1"`.
+   * @param {string} [options.sort] - Sort order (default `"date"`).
+   * @param {number} [options.limit] - Max results (default 50, max 200).
+   * @returns {Promise<Array<object>>}
+   *
+   * @example
+   * ```js
+   * const upcoming = await client.getUpcomingMatches({ league: 'BL1', limit: 10 });
+   * ```
+   */
+  getUpcomingMatches({ league, sort, limit } = {}) {
+    return this._get('/api/matches/upcoming', { league, sort, limit });
+  }
+
+  /**
+   * Return full details for a single match.
+   *
+   * @param {number|string} matchId - The numeric match identifier.
+   * @returns {Promise<object>} Object with `match`, `homeRecentForm`, `awayRecentForm`,
+   *   `homeStats`, `awayStats`, and `headToHead`.
+   *
+   * @example
+   * ```js
+   * const { match, headToHead } = await client.getMatch(12345);
+   * console.log(match.homeTeam, match.homeElo);
+   * ```
+   */
+  getMatch(matchId) {
+    return this._get(`/api/matches/${matchId}`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Seasons
+  // -------------------------------------------------------------------------
+
+  /**
+   * Return all available seasons and the latest one.
+   *
+   * @returns {Promise<{seasons: string[], latestSeason: string}>}
+   *
+   * @example
+   * ```js
+   * const { seasons, latestSeason } = await client.getSeasons();
+   * console.log(latestSeason);
+   * ```
+   */
+  getSeasons() {
+    return this._get('/api/seasons');
+  }
+
+  /**
+   * Return per-team ELO change statistics for a specific season.
+   *
+   * @param {string} season - Season string, e.g. `"2024/2025"`.
+   * @param {object} [options]
+   * @param {string} [options.league] - Optional league filter, e.g. `"BL1"`.
+   * @returns {Promise<Array<object>>}
+   *
+   * @example
+   * ```js
+   * const data = await client.getSeason('2024/2025', { league: 'BL1' });
+   * data.forEach(e => console.log(e.teamName, e.change));
+   * ```
+   */
+  getSeason(season, { league } = {}) {
+    return this._get(`/api/seasons/${encodeURIComponent(season)}`, { league });
+  }
+
+  // -------------------------------------------------------------------------
+  // Comparison
+  // -------------------------------------------------------------------------
+
+  /**
+   * Return historical ELO time-series for multiple teams side-by-side.
+   *
+   * @param {string[]} teams - Array of team names (minimum two).
+   * @returns {Promise<object>} Keys are team names; values are arrays of
+   *   `{Date: number, ELO: number}` data points.
+   *
+   * @example
+   * ```js
+   * const history = await client.getComparisonHistory([
+   *   'Bayern München',
+   *   'Borussia Dortmund',
+   * ]);
+   * Object.entries(history).forEach(([team, points]) => {
+   *   console.log(team, points.at(-1).ELO);
+   * });
+   * ```
+   */
+  getComparisonHistory(teams) {
+    if (!Array.isArray(teams) || teams.length < 2) {
+      throw new Error('getComparisonHistory requires an array of at least two team names');
+    }
+    return this._get('/api/comparison/history', { teams: teams.join(',') });
+  }
+}