Getting started

Prerequisites

Node.js 24 (matches serverless.yml runtime)
AWS CLI with profiles AbstractPlayDev and AbstractPlayProd in ~/.aws/credentials
Access to the @abstractplay GitHub Packages scope

Install and build

npm install
npm run build

npm run build runs ESLint and TypeScript typecheck (tsc --noEmit). Lambda handlers are bundled at deploy time by serverless-esbuild; there is no separate lib/*.js compile step.

Ops scripts under bin/ that only talk to AWS run with node bin/<script>.mjs. Scripts that import lib/*.ts (e.g. dump-dashboard, import-bgg-wishlist, import-discord-feedback) run via tsx — see npm run dump-dashboard, npm run import-bgg-wishlist, and npm run import-discord-feedback. BGG and Discord imports accept optional user maps (bin/bgg-ap-user-map.json, bin/discord-ap-user-map.json; see .example.json files for format).

GitHub Packages

Private packages require a .npmrc:

@abstractplay:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<PAT with read:packages>

CI creates this from the PAT_READ_PACKAGES secret (see .github/workflows/deploy-dev.js.yml).

Local gameslib development

To test against a local rules engine build:

npm install /path/to/gameslib.tgz

Or point at a packed tarball from a gameslib checkout.

Environment variables

Lambda env vars are set in serverless.yml. Secrets are injected in CI from GitHub Actions secrets:

Variable	Purpose
`TOTP_KEY`	Organizer TOTP validation
`VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY`	Web push
`OPENSSH_PRIVATE_KEY`	Some maintenance/crypto paths
`TEST_BOT_CLIENT_ID` / `TEST_BOT_CLIENT_SECRET`	Dev reference bot (dev only)

Do not commit secret values. Names only are listed here.

Dev reference bot

The testBot Lambda is enabled on the dev stage only. Full protocol documentation is in the header of api/testBot.ts. See Bots.

Project layout

api/           Lambda entries (query.ts, authQuery.ts, botQuery.ts, routes/, sockets/, testBot.ts)
lib/           Shared libraries (bots, DDB, WebSocket broadcast)
utils/         Shared handlers (yourturn, feedback jobs — deployed via crons/); bot-outbound SQS consumer
crons/         Scheduled Lambda stack (Serverless app abstract-play-backend-crons)
locales/       i18n strings for emails and push notifications
serverless.yml Infrastructure and function definitions