mlsz-adatbank 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haverfalat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# mlsz-adatbank
+
+TypeScript client for the public fixtures, results and statistics pages of the
+Hungarian football federation (MLSZ) Adatbank site.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Services](#services)
+  - [LeaguesService](#leaguesservice)
+  - [MatchesService](#matchesservice)
+  - [StandingsService](#standingsservice)
+  - [ClubsService](#clubsservice)
+  - [PlayersService](#playersservice)
+  - [StatsService](#statsservice)
+- [Low-level Parsers](#low-level-parsers)
+- [HTTP client](#http-client)
+- [Data model](#data-model)
+- [Limitations](#limitations)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+```sh
+npm install mlsz-adatbank
+```
+
+Requires Node.js 18 or newer. The package is pure ESM and ships its own
+TypeScript declarations.
+
+## Quick Start
+
+```ts
+import { createAdatbankClient } from 'mlsz-adatbank';
+
+const client = createAdatbankClient();
+
+// Pick the selected league and round from the homepage dropdowns.
+const options = await client.leagues.options();
+const league = options.leagues.find((o) => o.selected)!.value!;
+const round = options.rounds.find((o) => o.selected)!.value!;
+
+const roundCtx = {
+  season: options.state.season!,
+  federation: options.state.federation!,
+  league,
+  round,
+};
+
+const standings = await client.standings.get(roundCtx);
+const fixtures = await client.matches.listRound(roundCtx);
+const detail = await client.matches.detail(fixtures[0].matchId!);
+const scorers = await client.stats.topScorers(roundCtx);
+const yellowCards = await client.stats.cards(roundCtx, 'yellow');
+```
+
+Every service method returns parsed data directly. Nothing is written back to
+the site.
+
+## Configuration
+
+```ts
+createAdatbankClient({
+  baseUrl: 'https://adatbank.mlsz.hu',
+  meccsCenterUrl: 'https://ada1bank.mlsz.hu',
+  timeoutMs: 15000,
+  retries: 2,
+  fetchFn: customFetch,
+});
+```
+
+| Option         | Default                     | Meaning                                 |
+| -------------- | --------------------------- | --------------------------------------- |
+| `baseUrl`      | `https://adatbank.mlsz.hu`  | League, match and club pages.           |
+| `meccsCenterUrl` | `https://ada1bank.mlsz.hu` | Fixture and lineup pages.               |
+| `timeoutMs`    | `15000`                     | Per-request timeout in milliseconds.    |
+| `retries`      | `2`                         | Extra attempts after a failed request.  |
+| `fetchFn`      | global `fetch`              | Drop-in replacement for testing or proxying. |
+
+The client sets a common browser user agent and an `accept-language: hu` header
+on every request.
+
+## Services
+
+Methods that need a league context take a `RoundContext`:
+
+```ts
+interface LeagueContext {
+  season: number;
+  federation: number;
+  league: number;
+}
+
+interface RoundContext extends LeagueContext {
+  round: number;
+}
+```
+
+### LeaguesService
+
+Reads the homepage dropdowns and the hidden current selection.
+
+```ts
+const options = await client.leagues.options();
+// { seasons, federations, leagues, rounds, state }
+
+const seasons = await client.leagues.seasons();     // SelectOption[]
+const feds = await client.leagues.federations();    // SelectOption[]
+const leagues = await client.leagues.leagues();     // SelectOption[]
+const rounds = await client.leagues.rounds();       // SelectOption[]
+```
+
+`options()` returns everything in one request. The other four are thin
+convenience wrappers around it.
+
+### MatchesService
+
+```ts
+const fixtures = await client.matches.listRound(roundCtx);   // Fixture[]
+const detail = await client.matches.detail(2186424);          // MatchDetail
+const day = await client.matches.listByDate({ date: '2026-09-19' }); // MatchDay
+```
+
+- `listRound` reads the round selector on the league page. Played fixtures
+  carry the final score, scheduled ones carry the kickoff time. Both include
+  the match page URL and, when present, the video link.
+- `detail` reads the match page: teams, score, goals, timeline events,
+  officials, lineups, substitutions and staff. The lineup page is hosted on a
+  different domain, the redirect is followed transparently.
+- `listByDate` reads all leagues for one day, grouped by federation and
+  league. Match state is one of `finalized`, `partial`, `open`.
+
+### StandingsService
+
+```ts
+const standings = await client.standings.get(roundCtx);
+// { context, updatedAt, updatedBy, rows }
+```
+
+Each row gives the position, club, the full W/D/L goal tally, points, the
+opposition column, the next opponent (date, venue, teams, match id) and the
+recent form chips with their result descriptions.
+
+### ClubsService
+
+```ts
+const club = await client.clubs.get(roundCtx, 328184);   // ClubDetail
+const schedule = await client.clubs.schedule(roundCtx, 328184); // Fixture[]
+```
+
+- `get` returns the club header block (name, logo, founded, city, official
+  name, colours, website, contact) as a list that is safe to render as-is.
+- `schedule` reads the club fixture list for the given round.
+
+### PlayersService
+
+```ts
+const profile = await client.players.get(437842);   // PlayerProfile
+```
+
+The profile includes the player photo, season-by-season statistics (appearances,
+subs, goals, own goals, yellow/red cards), and the transfer history with dates
+and club names.
+
+### StatsService
+
+```ts
+const scorers = await client.stats.topScorers(roundCtx); // ScorerRow[]
+const cards = await client.stats.cards(roundCtx, 'yellow'); // CardRow[]
+const red = await client.stats.cards(roundCtx, 'red');
+```
+
+Scorer rows carry rank, player (name, id, photo), goals and club. Card rows
+carry the same player bounds with the yellow and red totals.
+
+## Low-level Parsers
+
+Every page parser is exported standalone. Each takes a raw HTML string and
+returns the plain data shape, which is useful if you want to cache responses or
+feed in fixtures from disk.
+
+| Parser                    | Input rule                                            |
+| ------------------------- | ----------------------------------------------------- |
+| `parseLeagueOptions`      | Homepage HTML.                                        |
+| `parseFixtures`           | League HTML, plus a CSS selector for the fixture pane.|
+| `parseStandings`          | League HTML.                                          |
+| `parseMatchDay`           | A day page HTML.                                      |
+| `parseScorers`, `parseCards` | Leaderboard HTML.                                  |
+| `parseMatchDetail`        | A match HTML string and the match id.                 |
+| `parseClubDetail`         | A club page HTML.                                     |
+| `parsePlayerProfile`      | A player page HTML.                                   |
+
+## HTTP client
+
+`AdatbankHttp` handles the retries, timeout and header defaults. It is exported
+so you can reuse it with the parsers directly if you ever need to skip the
+services layer. Requests that fail after all retries throw an `HttpError` with
+the status code attached.
+
+## Data model
+
+The domain types are grouped by page family in `src/domain`:
+
+- `common.ts`: `LeagueContext`, `RoundContext`, `SelectOption`, `PageState`,
+  `TeamRef`, `PlayerRef`, `Scored`.
+- `fixture.ts`: `Fixture` (home/away, kickoff, venue, score, whether the match
+  was played, match id, page and video links).
+- `standings.ts`: `Standings`, `StandingRow`, `NextOpponent`, `FormResult`.
+- `match.ts`: `MatchDetail`, `TeamDetail`, `MatchScore`, `GoalEvent`,
+  `TimelineEvent`, `Official`, `Lineup`, `LineupPlayer`, `CrewMember`.
+- `matchday.ts`: `MatchDay`, `MatchDayGroup`, `MatchDayMatch`, `MatchState`.
+- `stats.ts`: `ScorerRow`, `CardRow`, `CardColor`.
+- `club.ts`: `ClubDetail`, `ClubContact`.
+- `player.ts`: `PlayerProfile`, `PlayerSeasonStats`, `PlayerTransfer`.
+
+All values are returned exactly as published, except that surrounding
+whitespace is trimmed and missing optional values are `undefined` rather than
+empty strings.
+
+## Limitations
+
+This is an unofficial client. The whole library works by scraping HTML, so a
+single markup change on the site can break any parser. Treat the data as
+read-only and keep your request rate low. The per-player InStat advanced
+statistics feed (`ajax.php` with its query-string contract) is intentionally
+not covered.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+The test suite runs against small captured HTML fixtures, not the live site, so
+it stays deterministic and offline.
+
+## License
+
+MIT

package/dist/config/defaults.d.ts

@@ -0,0 +1,19 @@
+export interface ClientConfig {
+    baseUrl: string;
+    meccsCenterUrl: string;
+    timeoutMs: number;
+    retries: number;
+    headers: Record<string, string>;
+    fetchFn: typeof fetch;
+}
+interface ConfigOverrides {
+    baseUrl?: string;
+    meccsCenterUrl?: string;
+    timeoutMs?: number;
+    retries?: number;
+    headers?: Record<string, string>;
+    fetchFn?: typeof fetch;
+}
+export declare const DEFAULT_CONFIG: ClientConfig;
+export declare function resolveConfig(overrides?: ConfigOverrides): ClientConfig;
+export {};

package/dist/config/defaults.js

@@ -0,0 +1,21 @@
+export const DEFAULT_CONFIG = {
+    baseUrl: 'https://adatbank.mlsz.hu',
+    meccsCenterUrl: 'https://ada1bank.mlsz.hu',
+    timeoutMs: 15000,
+    retries: 2,
+    headers: {
+        'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36',
+        'accept-language': 'hu-HU,hu;q=0.9,en;q=0.8',
+    },
+    fetchFn: fetch,
+};
+export function resolveConfig(overrides = {}) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...overrides,
+        headers: {
+            ...DEFAULT_CONFIG.headers,
+            ...overrides.headers,
+        },
+    };
+}

package/dist/domain/club.d.ts

@@ -0,0 +1,27 @@
+import { PlayerRef } from './common.js';
+export interface ClubContact {
+    mailingAddress?: string;
+    seat?: string;
+    phone?: string;
+    fax?: string;
+    email?: string;
+    website?: string;
+}
+export interface SquadPlayer {
+    player: PlayerRef;
+    photo?: string;
+    age?: number;
+}
+export interface StaffMember {
+    name: string;
+    role: string;
+}
+export interface ClubDetail {
+    id?: number;
+    name: string;
+    logo?: string;
+    contact: ClubContact;
+    competitions: string[];
+    squad: SquadPlayer[];
+    staff: StaffMember[];
+}

package/dist/domain/club.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/common.d.ts

@@ -0,0 +1,33 @@
+export interface LeagueContext {
+    season: number;
+    federation: number;
+    league: number;
+}
+export interface RoundContext extends LeagueContext {
+    round: number;
+}
+export interface SelectOption {
+    value: number | null;
+    label: string;
+    selected: boolean;
+}
+export interface PageState {
+    season: number | null;
+    federation: number | null;
+    league: number | null;
+    round: number | null;
+}
+export interface TeamRef {
+    name: string;
+    id?: number;
+    href?: string;
+}
+export interface PlayerRef {
+    name: string;
+    id?: number;
+    href?: string;
+}
+export interface Scored {
+    home: number;
+    away: number;
+}

package/dist/domain/common.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/fixture.d.ts

@@ -0,0 +1,13 @@
+import { Scored, TeamRef } from './common.js';
+export type FixtureState = 'scheduled' | 'played';
+export interface Fixture {
+    matchId?: number;
+    home: TeamRef;
+    away: TeamRef;
+    kickoff?: Date;
+    venue?: string;
+    state: FixtureState;
+    score?: Scored;
+    href?: string;
+    videoHref?: string;
+}

package/dist/domain/fixture.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/match.d.ts

@@ -0,0 +1,78 @@
+import { FormResult, MatchScore } from './standings.js';
+import { PlayerRef, Scored } from './common.js';
+export interface Official {
+    role: string;
+    name: string;
+}
+export interface MatchTeamForm {
+    result: FormResult;
+    matchId?: number;
+    description?: string;
+}
+export interface MatchTeamBlock {
+    name: string;
+    href?: string;
+    id?: number;
+    logo?: string;
+    form: MatchTeamForm[];
+}
+export type EventKind = 'goal' | 'ownGoal' | 'substitution' | 'yellowCard' | 'redCard';
+export interface TimelineEvent {
+    minute?: number;
+    kind: EventKind;
+    home: boolean;
+    player?: string;
+    off?: string;
+    on?: string;
+}
+export interface GoalEvent {
+    order: number;
+    home: boolean;
+    player?: string;
+    playerId?: number;
+    minute?: number;
+    ownGoal: boolean;
+    score?: Scored;
+}
+export interface PlayerEvent {
+    kind: EventKind;
+    minute: number;
+}
+export interface LineupEntry {
+    number?: number;
+    name: string;
+    href?: string;
+    id?: number;
+    subbedBy?: PlayerRef;
+    events: PlayerEvent[];
+}
+export interface TeamLineup {
+    name: string;
+    href?: string;
+    logo?: string;
+    starters: LineupEntry[];
+    bench: LineupEntry[];
+    coach?: string;
+    crew: {
+        name: string;
+        role: string;
+    }[];
+}
+export interface MatchDetail {
+    id: number;
+    title?: string;
+    league?: string;
+    organizer?: string;
+    kickoff?: Date;
+    venue?: string;
+    home: MatchTeamBlock;
+    away: MatchTeamBlock;
+    score?: MatchScore;
+    officials: Official[];
+    goals: GoalEvent[];
+    timeline: TimelineEvent[];
+    lineups: {
+        home?: TeamLineup;
+        away?: TeamLineup;
+    };
+}

package/dist/domain/match.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/matchday.d.ts

@@ -0,0 +1,27 @@
+import { Scored, TeamRef } from './common.js';
+export type MatchDayStatus = 'finalized' | 'partial' | 'open';
+export type StatusFilter = 'all' | 'finished' | 'live' | 'upcoming';
+export interface MatchDayFilter {
+    date?: string;
+    status?: StatusFilter;
+    federation?: number;
+}
+export interface MatchDayMatch {
+    matchId?: number;
+    home: TeamRef;
+    away: TeamRef;
+    kickoff?: Date;
+    round?: number;
+    status: MatchDayStatus;
+    score?: Scored;
+    href?: string;
+}
+export interface MatchDayGroup {
+    federation: number;
+    organizer: string;
+    league: string;
+    matches: MatchDayMatch[];
+}
+export interface MatchDay {
+    groups: MatchDayGroup[];
+}

package/dist/domain/matchday.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/player.d.ts

@@ -0,0 +1,49 @@
+import { PlayerRef, TeamRef } from './common.js';
+export interface PlayerSeasonStat {
+    appearances: number;
+    starts: number;
+    subs: number;
+    bench: number;
+    goals: number;
+    ownGoals: number;
+    yellows: number;
+    reds: number;
+}
+export interface PlayerSeasonTotals extends PlayerSeasonStat {
+    season: string;
+    club: string;
+}
+export interface PlayerCompetitionStat extends PlayerSeasonStat {
+    competition: string;
+    position?: string;
+    teamId?: number;
+    leagueId?: number;
+}
+export interface PlayerSeasonBlock {
+    season: string;
+    club: string;
+    totals: PlayerSeasonTotals;
+    competitions: PlayerCompetitionStat[];
+}
+export interface PlayerTransfer {
+    from?: string;
+    to?: string;
+    start?: Date;
+    end?: Date;
+    type?: string;
+}
+export interface PlayerTeammate {
+    player: PlayerRef;
+    age?: number;
+}
+export interface PlayerProfile {
+    id?: number;
+    name: string;
+    photo?: string;
+    birthDate?: Date;
+    age?: number;
+    club?: TeamRef;
+    seasons: PlayerSeasonBlock[];
+    transfers: PlayerTransfer[];
+    teammates: PlayerTeammate[];
+}

package/dist/domain/player.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/standings.d.ts

@@ -0,0 +1,36 @@
+import { Scored, TeamRef } from './common.js';
+export type FormResult = 'W' | 'D' | 'L';
+export interface FormChip {
+    result: FormResult;
+    matchId?: number;
+    description?: string;
+}
+export interface NextOpponent {
+    date?: Date;
+    venue?: string;
+    home?: string;
+    away?: string;
+    matchId?: number;
+}
+export interface StandingRow {
+    position: number;
+    team: TeamRef;
+    logo?: string;
+    played: number;
+    won: number;
+    drawn: number;
+    lost: number;
+    goalsFor: number;
+    goalsAgainst: number;
+    goalDiff: number;
+    points: number;
+    opposition?: string;
+    comment?: string;
+    nextOpponent?: NextOpponent;
+    form: FormChip[];
+}
+export type Standings = StandingRow[];
+export interface MatchScore {
+    full: Scored;
+    half?: Scored;
+}

package/dist/domain/standings.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/stats.d.ts

@@ -0,0 +1,16 @@
+import { PlayerRef, TeamRef } from './common.js';
+export interface ScorerRow {
+    rank: number;
+    player: PlayerRef;
+    photo?: string;
+    goals: number;
+    club: TeamRef;
+}
+export interface CardRow {
+    rank: number;
+    player: PlayerRef;
+    photo?: string;
+    yellow: number;
+    red: number;
+    club: TeamRef;
+}

package/dist/domain/stats.js

@@ -0,0 +1 @@
+export {};

package/dist/http/client.d.ts

@@ -0,0 +1,12 @@
+import { ClientConfig } from '../config/defaults.js';
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class AdatbankHttp {
+    private readonly config;
+    constructor(config: ClientConfig);
+    getText(url: string, params?: Record<string, string | number | undefined>): Promise<string>;
+    private targetUrl;
+    private timeoutFetch;
+}