feat(stats): add owners endpoint to list users who own a game

readme.md

@@ -205,9 +205,10 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET` | `/api/public/profiles/library/stats/games?key=&arg=&page=` (`403 NOT_SHARED`, `400 BAD_ARG`) | profile ticket |
 | `GET` | `/api/public/profiles/rewards` (`{equipped}`, the worn looks) | profile ticket |
 | `GET` | `/api/stats/public` (+ games per platform, top genres, finished per year) | public |
+| `GET` | `/api/stats/owners?appid=&key=&arg=&page=` (who owns a game in the set behind a community number, `key` default `OWNED`: `listed` display names only, `listedTotal`, `privateCount`, `includesYou`, not cached, `400 BAD_ARG`) | login |
 | `GET` | `/api/stats/public/games?key=&arg=&page=` (the games behind a landing number, per game `libraries` and `minutes`; `400 BAD_ARG`) | public |
 | `POST`, `PUT` | `/internal/accounts/deleted` (`{userIds}`; POST adds, PUT replaces the whole set; `204`) | service token |
-| `POST`, `PUT` | `/internal/accounts/states` (`{accounts: [{userId, steamId, displayName, blocked, roleChangedAt}]}`, `displayName` and `roleChangedAt` optional, `displayName` at most 100 characters, kept in `account_name` for the audit log, `roleChangedAt` kept in `account_role_change`; POST updates, PUT replaces the whole set; `204`) | service token |
+| `POST`, `PUT` | `/internal/accounts/states` (`{accounts: [{userId, steamId, displayName, blocked, roleChangedAt, listed}]}`, `displayName`, `roleChangedAt` and `listed` optional (`listed`: Auth lists the user by name, kept in `listed_user`, `null` keeps it), `displayName` at most 100 characters, kept in `account_name` for the audit log, `roleChangedAt` kept in `account_role_change`; POST updates, PUT replaces the whole set; `204`) | service token |
 | `POST` | `/internal/accounts/purge` (`{userIds}`), `/internal/accounts/prune` (`{knownUserIds}`, not empty) | service token |
 | `GET` | `/api/version` (`{commit, builtAt}` of the running image, from the CI build; `dev` locally) | public |
 
@@ -254,9 +255,9 @@ flowchart LR
     Igdb -->|"OAuth token"| Twitch["Twitch"]
     Speedrun --> SpeedrunApi["speedrun.com API"]
     LibRepo --> Db[("PostgreSQL tbp_core")]
-    Stats -->|"listed_user_game, counted_user_game, game_mood, coming_game, user_game_status_change, deleted_user, blocked_user"| Db
+    Stats -->|"listed_user_game, counted_user_game, game_mood, coming_game, user_game_status_change, deleted_user, blocked_user, listed_user, account_name, game_alias"| Db
     Auth -->|"service token<br/>/internal/accounts"| Account
-    Account -->|"per-user rows, deleted_user, blocked_user, account_name, user_seen_at"| Db
+    Account -->|"per-user rows, deleted_user, blocked_user, listed_user, account_name, user_seen_at"| Db
 ```
 
 | Module | Content |
@@ -264,13 +265,13 @@ flowchart LR
 | `library` | Sync, backlog, manual games, imports, playtime history, wishlist, achievements, public profile data |
 | `stats` | Public numbers for the landing page |
 | `version` | `GET /api/version`: commit and build time of the running image |
-| `account` | Driven by Auth: tombstones in `deleted_user`, purge and orphan prune of the per-user rows; blocks in `blocked_user`, role changes in `account_role_change`, display names in `account_name`, Steam ID changes stop the nightly sync |
+| `account` | Driven by Auth: tombstones in `deleted_user`, purge and orphan prune of the per-user rows; blocks in `blocked_user`, listing in `listed_user` (users Auth shows by name in owner lists, #26), role changes in `account_role_change`, display names in `account_name`, Steam ID changes stop the nightly sync |
 | `steam_adapter` | Steam Web API client, availability check of Steam CDN pictures |
 | `igdb_adapter` | IGDB client (Twitch OAuth): time to beat, game tags for moods, release years, game search |
 | `speedrun_adapter` | speedrun.com client: game search by name, verified runs |
 
 **One shared schema.** All modules use one database `tbp_core`, and some read or write another module's tables in
-SQL, which ArchUnit cannot see: `stats` reads `listed_user_game`, `counted_user_game`, `steam_game`, `game_mood`, `coming_game`, `user_game_status_change`, `deleted_user` and `blocked_user`; `account`
+SQL, which ArchUnit cannot see: `stats` reads `listed_user`, `account_name`, `game_alias`, `listed_user_game`, `counted_user_game`, `steam_game`, `game_mood`, `coming_game`, `user_game_status_change`, `deleted_user` and `blocked_user`; `account`
 deletes the per-user rows of the library tables (`AccountCleanupRepository`; a new library table with `user_id` goes
 into its list) and writes `user_seen_at` and `last_synced_at` of `user_steam_sync` (`AccountStateRepository`); `library`
 reads `deleted_user` and `blocked_user`. A module that moves to its own service takes these reads along as calls.
@@ -448,12 +449,12 @@ gets no more syncs and leaves the landing stats and the pile snapshots at once.
 flagged set (`PUT`), then `purge` for users flagged 30 days ago (only tombstoned ones), then `prune` with all its
 user ids, which removes the rows of users Auth does not know (refused for more than
 `app.account-cleanup.max-orphans`, default 5). `app.account-cleanup.dry-run` (default `true`) only counts the rows.
-The purge also removes the user's `account_name` row and link requests (`game_link_request`).
+The purge also removes the user's `account_name` and `listed_user` rows and link requests (`game_link_request`).
 
 ### Blocked users and Steam ID changes
 
 Auth sends a user's state (`POST /internal/accounts/states`) after a Steam link, an unlink, a Steam ID another account
-took by a verified link, a display name change, a block and an unblock; its nightly job sends every user (`PUT`). A blocked user is in
+took by a verified link, a display name change, a block, an unblock and a change of the owner-list opt-in (`listed`, #26); its nightly job sends every user (`PUT`). A blocked user is in
 `blocked_user`: no nightly sync, no new sync run, not in the landing stats. `JwtAuthenticationFilter` refuses a blocked
 user's token and a token issued before the user's last role change (`account_role_change`, sent as `roleChangedAt`),
 through the cache `loginStates` (30 s, evicted by every state call). An Auth that does not send `roleChangedAt` changes