⚔
Clan Records · Field Manual · Vol. I

The Clan Ledger

A personal-best tracker for the discerning clan.

SYSTEM ONLINE · v1.0
✦

Members submit kill-time proofs, staff weigh in, and the ledger keeps the books: a navigable leaderboard, a full history of fallen records, and a monthly dispatch — all written into Google Sheets.

discord.js 14 googleapis v4 Node 18+ TypeScript Sheets as the archive
01

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.

✦ Bring your own ledgerNo spreadsheet migration is needed. Point the bot at your existing SHEET_ID and it will reuse the config, bosses, categories and submissions tabs, adding submissions_archive the first time you prune.
02

Features

⚖
Submissions & reviewProof re-hosting, duplicate guard, a five-minute edit window, blert.io checks and staff decisions with reasons.
🏆
The Master BoardTop three per category in uniform ANSI codeblocks, with configurable group titles and banner images.
📜
The detail boardA persistent Select menu; each pick opens a private page with roster mentions and proof links.
📈
Record loreEvery record broken, in order — plus per-player standings and an automatic monthly digest.
🛡
Admin controlChannels, roles, banners, titles and ordering are all edited from Discord. No code edits, no restarts.
🧹
UpkeepHealth checks, .xlsx export, pruning and archiving, cache refresh and sheet migration commands.
03

Quick start

Unzip the source somewhere, then from that folder:

First run
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:

Development
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.

04

Discord setup

  1. Create an application and bot in the Developer Portal, then copy its token into DISCORD_TOKEN.
  2. Under Bot → Privileged Gateway Intents, enable Server Members Intent — the bot resolves teammates into members and display names.
  3. Invite it with the bot and applications.commands scopes. Grant View Channel, Send Messages, Embed Links, Attach Files, Manage Messages, Read Message History and Mention Roles.
  4. Optionally set DEV_GUILD_ID to a test server so commands sync instantly. Leave it unset for global commands.
  5. Run /pbadmin set-channel for the submit, review, announce and leaderboard channels, then /pbadmin set-role for staff.
⚠ Guard the tokenNever share your bot token. If it leaks, reset it in the Developer Portal. To let a friend use the bot in their server, simply invite your bot there — they need neither the code nor the token.
05

The Spreadsheet

  1. Create or reuse a Google Sheet and put its ID (from the URL) into SHEET_ID.
  2. In Google Cloud, create a service account, generate a JSON key and save it beside the bot as google-key.json — or point GOOGLE_KEYFILE at its path. Enable the Sheets API for that project.
  3. Share the sheet with the service account's email address as Editor.

Tabs the ledger expects. Missing ones are created for you:

TabPurpose
configKey/value settings: channels, roles, group titles and banners, ordering, meme text, digest state.
bossesBoss id, name, aliases, blert support, group, active flag, detail-board image URL.
categoriesCategories per boss with team size, active flag and record type (time or level).
submissionsEvery run, its review state, links, roster and proof URL.
submissions_archiveCreated on first prune; holds archived rejected and reverted rows.
✦ A second scribe?Two bots writing to one sheet at once can race — there is no row-level locking. Stop the first bot before starting another against the same sheet, or give each its own ledger.
06

Environment

VariableRequiredDescription
DISCORD_TOKENYesDiscord bot token.
GOOGLE_KEYFILEYesPath to the service-account JSON key, e.g. google-key.json.
SHEET_IDYesThe Google Sheet ID.
DEV_GUILD_IDNoGuild ID for instant slash-command sync during development.
07

Commands

For members

CommandDescription
/pb submitSubmit 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)

CommandDescription
/pbadmin set-channelSet the submit, review, announce or leaderboard channel.
/pbadmin set-roleSet the staff role.
/pbadmin set-submitter-roleRestrict submissions to a role; omit to open them to everyone.
/pbadmin record-pingPing a role when a long-standing record falls; omit the role to disable.
/pbadmin show · statusShow configuration, or health, cache state, counts and uptime.
/pbadmin exportDownload every tab as one .xlsx file.
/pbadmin revertSoft-revert an approved submission with a reason.
/pbadmin pruneArchive rejected (optionally reverted) rows and remove them from the active tab.
/pbadmin refresh · migrateRedraw the board, or re-run the sheet schema sync.
/pbadmin boss add|edit|remove|listManage bosses. Removal is a soft delete; history is kept.
/pbadmin category add|remove|listManage the categories of a boss.
/pbadmin group list|set-banner|clear-banner|set-title|reorder|reorder-default|insertManage board groups, banners, titles and their order.
/pbadmin entries reorder|reorder-defaultReorder the leaderboard dropdown entries.
08

Structure of the code

src/
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/.

09

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.

  1. In Cloudflare, choose Workers & Pages → Create → Pages → Direct Upload.
  2. Drag in the docs folder itself (not the HTML file).
  3. Deploy. You'll get a *.pages.dev address immediately; add a custom domain under Custom domains if you like.

Connecting a Git repository instead? Use these settings:

Build 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.

10

Security

  • Never commit or upload .env or google-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 /pbadmin command.
  • The bot reaches outside Discord only when a submitter supplies a blert.io link. Everything else stays between Discord and your sheet.
✦