# LaDOSE.WebApp

Svelte 5 + SvelteKit front-end for `LaDOSE.Api`, styled with Tailwind CSS v4.
It ships as a static SPA (`@sveltejs/adapter-static`) and talks to the API over
JWT bearer auth, so it can be served from any static host.

## Requirements

Node ≥ 22.12 (the toolchain uses Vite 8). An `.nvmrc` is checked in:

```bash
nvm use          # resolves lts/*
npm install
```

## Running

The API must be up — it serves on `http://localhost:5000` in development:

```bash
cd ../LaDOSE.Api && dotnet run          # terminal 1
npm run dev                             # terminal 2 -> http://localhost:5173
```

Point the app at a different API with `VITE_API_BASE_URL` (see `.env.example`).
`LaDOSE.Api` already allows any origin with credentials, so no dev proxy is needed.

## Typed API access

`src/lib/api/schema.d.ts` is **generated** from the API's OpenAPI document — never
edit it by hand. Regenerate whenever a C# controller or DTO changes:

```bash
npm run api:sync     # fetch openapi.json from the running API, then re-emit types
```

That is `api:fetch` (curl `/openapi/v1.json`, override the host with `LADOSE_API_URL`)
followed by `api:types` (`openapi-typescript`). `openapi.json` is committed so the
types can be rebuilt without a running API.

Because paths and DTOs come from the generated types, a renamed route or a changed
DTO field surfaces as a TypeScript error rather than a runtime 404.

| Module | Purpose |
| --- | --- |
| `src/lib/api/schema.d.ts` | Generated types — all 23 API paths and every DTO |
| `src/lib/api/schema-helpers.ts` | Friendly aliases (`ApplicationUserDTO`, `LoginRequest`, …) |
| `src/lib/api/client.ts` | `apiRequest` — bearer auth, JSON, `ApiError`; paths constrained to real routes |
| `src/lib/api/users.ts` | `login` / `register` against `/Users/auth` and `/Users/register` |
| `src/lib/api/errors.ts` | `toErrorMessage` — message to show, or redirect to `/login` on a 401 |
| `src/lib/api/tournaments.ts` | `listEvents` / `importSmashTournament` / `getResults`, authenticated from the session |
| `src/lib/api/games.ts` | `listGames` / `saveGame` / `deleteGame` / `searchSmashGames` |
| `src/lib/api/admin-users.ts` | `listUsers` / `listRoles` / `addUser` / `deleteUser` — all Admin-only |
| `src/lib/api/statistics.ts` | `getMatchStats` against `POST /api/Statistics/Matches` — set-level win/loss and head to head |
| `src/lib/tournaments/results.ts` | Pure reshaping of `TournamentsResultDTO`: ranking grid, per-game placements, WordPress HTML, CSV |
| `src/lib/statistics/aggregate.ts` | Pure aggregation for `/statistiques`: standings, per-game and per-event summaries, CSV |
| `src/lib/statistics/load.ts` | `loadEventResults` — per-event `GetResults` fan-out with progress, partial failure and abort |
| `src/lib/games/draft.ts` | `GameDTO` ⇄ editor form, including the blank-to-NULL rules |
| `src/lib/ui/classes.ts` | The Tailwind class strings shared by the pages |
| `src/lib/stores/session.svelte.ts` | Signed-in user, persisted to `localStorage`, drops expired JWTs |

Calling another endpoint takes one line, and the path is checked at compile time:

```ts
import { apiRequest, buildPath, session } from '$lib';
import type { GameDTO } from '$lib';

const games = await apiRequest<GameDTO[]>('/api/Game', { token: session.token });
const one = await apiRequest<GameDTO>(buildPath('/api/Game/{id}', { id: 3 }));
```

## Routes

- `/login` — username + password, posts to `POST /Users/auth`, stores the returned JWT
- `/` — guarded; greets the signed-in user with **Hello, \<name\>.** and offers sign-out
- `/tournaments` — guarded; the start.gg half of the old Avalonia `TournamentResultView`
- `/statistiques` — guarded; standings, attendance and match statistics over a chosen scope
- `/games` — guarded; the game catalogue editor, from the Avalonia `GamesView`
- `/users` — **Admin only**; add and remove accounts

`session.displayName` prefers `firstName lastName` and falls back to `username`.

### `/tournaments`

Ports the Smash.gg (start.gg) column of `LaDOSE.DesktopApp.Avalonia`:

1. **Import** — a slug (`start.gg/tournament/<slug>`) is sent to
   `GET /api/Tournament/ParseSmash/{slug}`, which pulls the brackets, placements and
   sets into the database. Every bracket must be `COMPLETED` or the API throws.
2. **Events** — `GET /api/Event`, newest first. Tick one event for a single
   tournament, or several to aggregate a ranking season. The regex box replaces the
   selection with every matching event name (e.g. `Ranking #13\d{2}`).
3. **Generate results** — `POST /api/Tournament/GetResults` with the selected ids;
   the API applies the point rules in `ExternalProviderService`. Three views:
   - *Ranking* — players × games with totals, highest first, plus CSV export
   - *By game* — placements and points for one game
   - *HTML* — the podium table for the WordPress recap, with copy-to-clipboard

The Challonge half of the Avalonia view (date range, Challonge tournament list,
`ParseChallonge`) is deliberately not ported.

### `/statistiques`

Pick a scope — everything, the last 6/12 events, or a regex over event names — then
**Compute statistics**. Two independent sources feed the page, and they are kept apart
on purpose:

- **Points, placements, attendance** come from `POST /api/Tournament/GetResults`, called
  **one event at a time**. The endpoint merges everything it is given and never says
  which event a row came from, so per-event calls are the only way to get a time series
  — and they contain the damage, because it throws a 500 on any bracket missing a rank-1
  or rank-2 row. One broken import is reported as a skipped event instead of taking the
  whole scope down with it.
- **Set-level win rates and head to head** come from `POST /api/Statistics/Matches`, in
  a single call for the whole scope.

The **Matches** tab leads with its coverage line, and it matters: brackets imported
before set rows were persisted contribute placements but no matches, so those figures
can describe a fraction of the scope while the standings above cover all of it. Win
rates count **decided sets only**, so a player with no resolvable set is left out rather
than shown at 0%.

Other things worth knowing:

- Rank `999` is the service's "unplaced" sentinel (the participation bucket in
  `ExternalProviderService`), so it never counts as a placement or a podium, and
  **Best** shows `—`.
- Player names are merged case-insensitively, as everywhere else in the app.
- Brackets are counted per event, so a bracket name reused every month counts once
  per event rather than once overall.
- Undated events sort last in the chart and the Events tab — `GET /api/Event` returns
  newest first, which is the least misleading place to put them.
- `aggregate.ts` is pure, so it can be exercised under plain Node with fixtures, the
  same way `src/lib/tournaments/results.ts` is.

### `/games`

Ports `GamesView`: the list on the left (ordered by `Order`), an editor on the right.

- **Save** — `POST /api/Game`. `AddOrUpdate` inserts when `id` is 0 and otherwise
  **replaces every column**, so the form always sends a complete `GameDTO`; blank
  text fields are sent as `null`.
- **New game** — starts an empty draft with `id` 0 and the next free `Order`. The
  desktop app instead posted a blank row immediately and let you fill it in after.
- **Delete** — `DELETE /api/Game/{id}`, behind a confirm.
- **Find on start.gg** — `GET /api/Game/smash/{name}` searches start.gg's videogame
  catalogue using the long name (falling back to the name); picking a match fills
  `smashId`. The ids listed are **start.gg** videogame ids, not LaDOSE game ids.

`smashId` is what bracket imports match on: a game without one collects its results
under a synthetic "GAME NOT FOUND" entry.

Unlike the desktop form, `imgUrl` is editable here — it is part of `GameDTO` and was
otherwise only reachable through the database.

### `/users` (Admin only)

Lists every account with its roles, creates accounts, and deletes them.

`POST /Users/register` used to be `[AllowAnonymous]` so that the first account could be
created. It is now `POST /Users/AddUser` and requires the **Admin** role, so before this
page is reachable at all, one account has to be promoted directly in the database:

```bash
# edit the username in the file first, then:
psql "$LADOSE_DB" -v ON_ERROR_STOP=1 -f ../../Sql/2026-08-05_roles.sql
```

How roles work:

- They live in the pre-existing `applicationrole` / `applicationuserrole` tables. The
  script seeds `Admin` and `User`; no schema change was needed.
- Only user management checks a role. **Every other endpoint is unchanged** — a plain
  or role-less account can still use tournaments, games and the rest.
- The JWT carries only the user id. Roles are read from the database on every request
  (`OnTokenValidated` in `Startup.cs`), so granting or revoking Admin applies to the
  caller's next request instead of whenever their 16-minute token expires.
- `session.isAdmin` hides the link and the page, but that is cosmetic — the API is
  what enforces access, and a non-admin calling these endpoints gets a 403.
- The API refuses to delete the caller's own account. Since only an admin can reach the
  endpoint, that is what guarantees at least one admin always remains.

## Notes

- The API issues 16-minute tokens. A lapsed token is treated as signed out on load;
  there is no refresh flow yet, so long sessions will need a re-login. The guarded
  pages turn a 401 into a redirect back to `/login` (see `toErrorMessage`).
- The API has no exception middleware, so an unhandled server error arrives as an
  HTML developer page. `ApiError` then carries only the status, which is why each
  call site supplies its own fallback message.
- `GetResults` only fills `slug` when **one** event id is requested, so the
  "Voir le Bracket" links appear only for a single-event export.
- Player names are merged case-insensitively across brackets, matching the desktop app.
- `src/routes/+layout.ts` sets `ssr = false`: the JWT lives in the browser, so there
  is nothing meaningful to render on the server.

## Checks

```bash
npm run check    # svelte-check (types + template diagnostics)
npm run build    # static build into ./build
```