Overview
This volume is the TypeScript successor to the original pbbot.py. It keeps the same Google Sheet as its database and the same slash-command surface. The sheet is the source of truth: on startup the bot creates missing tabs, migrates headers and adds newly seeded bosses and categories — but it never deletes admin-added rows.
A record's journey: a member posts a time and screenshot in the submit channel → the bot re-hosts the proof on a review message with Approve / Reject buttons → staff decide → approved runs are announced (optionally pinging a role when an old record falls) and the leaderboard is redrawn.
SHEET_ID and it will reuse the config, bosses, categories and submissions tabs, adding submissions_archive the first time you prune.Features
Quick start
Unzip the source somewhere, then from that folder:
npm ci # or: npm install
copy .env.example .env # then fill in your values
npm run build
npm start
While developing you can skip the build step entirely:
npm run dev
On first launch the bot creates any missing tabs, seeds the boss and category lists, and builds the leaderboard messages in the channel you configured.
Discord setup
- Create an application and bot in the Developer Portal, then copy its token into
DISCORD_TOKEN. - Under Bot → Privileged Gateway Intents, enable Server Members Intent — the bot resolves teammates into members and display names.
- Invite it with the
botandapplications.commandsscopes. Grant View Channel, Send Messages, Embed Links, Attach Files, Manage Messages, Read Message History and Mention Roles. - Optionally set
DEV_GUILD_IDto a test server so commands sync instantly. Leave it unset for global commands. - Run
/pbadmin set-channelfor the submit, review, announce and leaderboard channels, then/pbadmin set-rolefor staff.
The Spreadsheet
- Create or reuse a Google Sheet and put its ID (from the URL) into
SHEET_ID. - In Google Cloud, create a service account, generate a JSON key and save it beside the bot as
google-key.json— or pointGOOGLE_KEYFILEat its path. Enable the Sheets API for that project. - Share the sheet with the service account's email address as Editor.
Tabs the ledger expects. Missing ones are created for you:
| Tab | Purpose |
|---|---|
config | Key/value settings: channels, roles, group titles and banners, ordering, meme text, digest state. |
bosses | Boss id, name, aliases, blert support, group, active flag, detail-board image URL. |
categories | Categories per boss with team size, active flag and record type (time or level). |
submissions | Every run, its review state, links, roster and proof URL. |
submissions_archive | Created on first prune; holds archived rejected and reverted rows. |
Environment
| Variable | Required | Description |
|---|---|---|
DISCORD_TOKEN | Yes | Discord bot token. |
GOOGLE_KEYFILE | Yes | Path to the service-account JSON key, e.g. google-key.json. |
SHEET_ID | Yes | The Google Sheet ID. |
DEV_GUILD_ID | No | Guild ID for instant slash-command sync during development. |
Commands
For members
| Command | Description |
|---|---|
/pb submit | Submit a time or level with proof image and up to seven teammates; optional blert link and notes. |
/pb top <boss> | Quick top five for a boss. |
/pb history <boss> | Record-by-record progression in every category. |
/pb lookup <player> | A player's best approved value and clan rank in each category they appear in. |
For officers (Manage Server required)
| Command | Description |
|---|---|
/pbadmin set-channel | Set the submit, review, announce or leaderboard channel. |
/pbadmin set-role | Set the staff role. |
/pbadmin set-submitter-role | Restrict submissions to a role; omit to open them to everyone. |
/pbadmin record-ping | Ping a role when a long-standing record falls; omit the role to disable. |
/pbadmin show · status | Show configuration, or health, cache state, counts and uptime. |
/pbadmin export | Download every tab as one .xlsx file. |
/pbadmin revert | Soft-revert an approved submission with a reason. |
/pbadmin prune | Archive rejected (optionally reverted) rows and remove them from the active tab. |
/pbadmin refresh · migrate | Redraw the board, or re-run the sheet schema sync. |
/pbadmin boss add|edit|remove|list | Manage bosses. Removal is a soft delete; history is kept. |
/pbadmin category add|remove|list | Manage the categories of a boss. |
/pbadmin group list|set-banner|clear-banner|set-title|reorder|reorder-default|insert | Manage board groups, banners, titles and their order. |
/pbadmin entries reorder|reorder-default | Reorder the leaderboard dropdown entries. |
Structure of the code
index.ts startup, cache pre-warm, background tasks
config.ts env + constants (SEED, headers, entries, groups)
types.ts shared interfaces
state.ts discord.js client + staff/channel helpers
sheets/
client.ts Sheets API wrapper (auth, retry, CRUD)
store.ts caches, config, migration, submission helpers
lib/
time.ts format.ts blert.ts records.ts export.ts
leaderboard/
render.ts Master Board + embed rendering
nav.ts jump links and nav buttons
manage.ts create / rebuild / refresh the board
components/
review.ts reorder.ts leaderboard.ts
commands/
autocomplete.ts submit.ts admin.ts pb.ts index.ts
interactions/
handler.ts interaction router + error handler
Build output lands in dist/. This manual itself lives in docs/.
Publishing this page
The docs/ folder is a complete static site — one index.html with all styling and script inline. No build tools, no dependencies.
- In Cloudflare, choose Workers & Pages → Create → Pages → Direct Upload.
- Drag in the
docsfolder itself (not the HTML file). - Deploy. You'll get a
*.pages.devaddress immediately; add a custom domain under Custom domains if you like.
Connecting a Git repository instead? Use these settings:
Build command: (leave empty)
Build output directory: docs
Root directory: (leave empty)
Re-upload the folder or push a commit to update the manual — connected repositories redeploy automatically.
Security
- Never commit or upload
.envorgoogle-key.json. Add both to.gitignore. - If a token or key leaks, rotate it: reset the Discord token in the Developer Portal, or delete and recreate the service-account key.
- Only trusted members should hold the staff role — they can decide submissions and run every
/pbadmincommand. - The bot reaches outside Discord only when a submitter supplies a blert.io link. Everything else stays between Discord and your sheet.