Auth queries

Handler: module.exports.authQuery — requires Cognito user JWT.

POST body: { "query": "<name>", "pars": { ... } }

The authenticated user id is cognitoPoolClaims.sub.

Profile and dashboard

Query	Purpose	Key `pars`
`me_profile`	Site-wide profile for navbar, settings, and game renderer: settings, bots, tags, `activeGames` (`CURRENTGAMES#` keys only). No dashboard maintenance, challenges, or `lastSeen` writes.	—
`me_dashboard`	Dashboard tables: full `games`, challenges, maintenance (prune + timeout sweep). Clears `USER.cleaned` when set by abandoned-account cron. No `lastSeen` writes.	`vars`, `update` (legacy; reserved)
`me`	Legacy — delegates to `me_dashboard`. `size: small` delegates to `me_profile`. Prefer explicit queries in new clients.	`size` (`small` → `me_profile`), `vars`, `update`
`next_game`	Next game id in user's list	—
`my_settings`	Minimal profile for settings UI	—
`new_setting`	Update name, language, country, bggid, about	`attribute`, `value`
`new_profile`	Bulk profile update	profile fields
`set_lastSeen`	Update last-seen timestamp (participating or watched game)	`gameId`, optional `interval`
`dismiss_completed_game`	Remove a completed game from the dashboard (does not delete game history)	`id` or `gameId`
`toggle_star`	Favorite a metaGame	`metaGame`

Watch, highlight, and representative games

Query	Purpose	Key `pars`
`watch_game`	Spectate a game (non-participant)	`metaGame`, `id`
`unwatch_game`	Stop spectating	`metaGame`, `id`
`highlight_game`	Pin a participated game on player page	`metaGame`, `id`
`unhighlight_game`	Remove highlight	`metaGame`, `id`
`recommend_game`	Recommend completed game for metaGame (max 2 per metaGame)	`metaGame`, `id`
`unrecommend_game`	Remove recommendation	`metaGame`, `id`
`log_recommendation_event`	Log game-recommendation impression event (show/click/challenge)	`event`, `batchId`, `surface`, `tier`, plus event-specific fields
`log_layout_feedback_event`	Log beta Game Move layout feedback event	`event`, `layoutId`, plus event-specific fields

See Recommendations for recommendation event schemas and DynamoDB layout.

See Game Move layout feedback for layout feedback event schemas.

Mutations return the updated list (watchedGames, highlights, or representatives) on success.

Push, tags, palettes, customizations

Query	Purpose	Key `pars`
`set_push`	User push preference; `{ state: false }` removes all device subscriptions	`state` (boolean)
`set_public_rivalries`	Opt in to public rivalries table (both players must opt in for a pair to be named)	`state` (boolean)
`save_push`	Register or refresh this device	`payload` (Web Push subscription object)
`delete_push`	Remove this device subscription	`endpoint` (subscription URL)
`save_tags`	Save game tags	`payload` (tag lists)
`save_palettes`	Save color palettes	`palettes`
`save_customization`	Per-game UI customization	`metaGame`, settings
`delete_customization`	Remove customization	`metaGame`
`update_standing`	SDG-style standing challenge preferences	`entries`
`update_user_settings`	User settings blob	settings fields

Player blocking

Query	Purpose	Key `pars`
`block_player`	Block a player	`playerId`
`unblock_player`	Unblock a player	`playerId`

See Player blocking.

Challenges and games

Query	Purpose	Key `pars`
`new_challenge`	Issue direct or standing challenge	`FullChallenge` fields
`challenge_revoke`	Cancel a challenge	`id`, `metaGame`, `standing`, `comment`
`challenge_response`	Accept or decline	`response`, `id`, `standing`, `metaGame`, `comment`
`standing_challenges`	Open challenges (filters blocked issuers)	`metaGame`
`submit_move`	Play a move	`metaGame`, `id`, `move`, …
`timeloss`	Report time loss	game ids
`abandoned`	Mark game abandoned	game ids
`invoke_pie`	Pie rule: reverse player order	game ids
`get_game`	Game with user context and `watchCount`	`metaGame`, `id`, `cbit`
`update_game_settings`	Per-game settings	game + settings
`update_note`	User note on a game	`gameId`, note text
`update_commented`	Mark comments seen	game ids
`submit_comment`	Game chat message	`gameId`, comment
`set_game_state`	Admin: replace game state	game id, state (admin only)
`mark_published`	Publish exploration	exploration ids

Explorations and playground

Query	Purpose	Key `pars`
`save_exploration`	Save exploration branch	game + move tree
`get_exploration`	Load exploration	game, user, move
`get_private_exploration`	Private exploration	game, user, move
`list_playground_saves`	List user's playground saves (metadata only)	—
`get_playground_save`	Load one playground save	`id`
`create_playground_save`	Create playground save	`name`, `metaGame`, `date`, `body`
`save_playground_save`	Overwrite playground save	`id`, `name`, `metaGame`, `date`, `body`
`delete_playground_save`	Delete playground save	`id`

Tournaments

Query	Purpose	Key `pars`
`new_tournament`	Create automated tournament	tournament spec
`join_tournament`	Enter tournament	`id`
`withdraw_tournament`	Leave tournament	`id`
`start_tournament`	Start one tournament (organizer)	`id`
`end_tournament`	End tournament	`id`

Organizer events

Query	Purpose	Key `pars`
`event_create`	Create event	event fields
`event_delete`	Delete event	`id`
`event_publish`	Publish event	`id`
`event_register`	Register player	`id`
`event_withdraw`	Withdraw player	`id`
`event_update_start`	Update start time	`id`, start
`event_update_name`	Rename event	`id`, name
`event_update_desc`	Update description	`id`, desc
`event_update_invites`	Update invite list	`id`, invites
`event_update_result`	Record result	`id`, result
`event_update_divisions`	Update divisions	`id`, divisions
`event_create_games`	Create linked games	`id`
`event_close`	Close event	`id`

Bots (owner)

Query	Aliases	Purpose	Key `pars`
`create_bot`	`createBot`	Register a bot	name, endpoint URL, …
`update_bot`	`updateBot`	Update bot config	`clientId`, fields
`delete_bot`	`deleteBot`	Delete bot	`clientId`
`begin_bot_secret_rotation`	`beginBotSecretRotation`	Start secret rotation	`clientId`
`finalize_bot_secret_rotation`	`finalizeBotSecretRotation`	Complete rotation	`clientId`, secret
`ping_bot`	—	Health check bot endpoint	`clientId`
`test_bot_status`	—	Dev test bot status	—
`update_test_bot`	—	Dev test bot config	fields

Admin and maintenance

Post–Phase 5 the dashboard is index-only (CURRENTGAMES#, RECENTCOMPLETED#, USERGAME#). Legacy USER.games[] is retired.

Still supported (authQuery)

Query	Purpose	Key `pars`
`update_meta_game_counts`	Recompute sharded `METAGAMES#<metaGame>/COUNTS` from live queries	—
`delete_games`	Hard-delete game records and all related dashboard / spectator / exploration rows	`metaGame`, `cbit` (`0` active / `1` completed), `gameids` (comma-separated)
`set_game_state`	Replace in-progress game state (`GAME` only; stream refreshes `CURRENTGAMES#`)	`id`, `metaGame`, `newState`
`test_push`	Send test push notification	—
`test_async`	Async test hook	varies

delete_games removes, per game id:

GAME, NOTE, GAMECOMMENTS, exploration branches
CURRENTGAMES# / RECENTCOMPLETED# / USERGAME# for human participants
WATCHED# / GAMEWATCHERS#, participant HIGHLIGHT#, REPRESENTATIVE# / PLAYER# recommendation rows
Sharded meta counts (currentgames for active deletes; completed deletes rely on the stream projector for completedgames after GAME removal)

If cbit does not match the stored game, the handler tries the other completion bit automatically.

Retired — returns `{ deprecated: true, useInstead: ... }`

Do not run these from the admin UI; use the replacement instead.

Query	Replacement
`fix_games`	`bin/verify-dashboard-index.mjs` then `bin/dashboard-index-maintenance.mjs --step prune-stale-recent-completed` / `purge-usergame-orphans --user-id <cognitoSub>`
`purge_retired_completed_games`	One-time purge complete (no retired rows remain)
`onetime_fix`	No replacement (legacy `USERS` directory sync)

Local scripts (not authQuery)

Task	Command
Dashboard health check	`node bin/verify-dashboard-index.mjs --stage prod [--verbose] <userId>…`
Prune stale `RECENTCOMPLETED#`	`node bin/dashboard-index-maintenance.mjs --stage prod --step prune-stale-recent-completed [--user-id <id>]`
Purge `USERGAME#` orphans	`node bin/dashboard-index-maintenance.mjs --stage prod --step purge-usergame-orphans [--user-id <id>]`

# Example dashboard repair for one user
node bin/verify-dashboard-index.mjs --stage prod --verbose <cognitoSub>
node bin/dashboard-index-maintenance.mjs --stage prod --step prune-stale-recent-completed --user-id <cognitoSub>
node bin/dashboard-index-maintenance.mjs --stage prod --step purge-usergame-orphans --user-id <cognitoSub>
node bin/verify-dashboard-index.mjs --stage prod <cognitoSub>