@went.tf/discord-bot-framework 2.3.0 → 2.5.0

package/README.md

@@ -152,15 +152,34 @@ If other code (e.g. a locale-file type, or a helper building a command
 mention) needs the literal name/id union as a *type*, derive it from the
 registry you already built instead of hand-writing a parallel
 `const enum CommandName { ... }` — that enum is exactly the duplication the
-registry's `const` type inference exists to avoid:
+registry's `const` type inference exists to avoid. **This only works if each
+command's own `name` stays a literal type up to the point it's passed into
+`createChatInputCommandRegistry`** — a real gotcha, not a hypothetical one:
+a plain, unannotated `const pingCommand = { name: 'ping', handle: ... };`
+widens `name` to `string` right there (standard TS object-literal-property
+widening, the same reason `const x = { n: 1 }; x.n` is `number` not `1`),
+*before* it ever reaches the registry call, so `RegistryName` would silently
+resolve to `string` too. `satisfies BotChatInputCommand` does **not** fix
+this either — it only checks compatibility, it doesn't request a literal.
+Pin each command's own name as an explicit generic argument instead (the
+same pattern this package's own registry tests use):
 
 ```ts
-import { RegistryName } from '@went.tf/discord-bot-framework/interactions';
+import { NamedChatInputCommand, RegistryName } from '@went.tf/discord-bot-framework/interactions';
+
+const pingCommand: NamedChatInputCommand<Ctx, 'ping'> = { name: 'ping', handle: (i) => i.reply('pong') };
+const searchCommand: NamedChatInputCommand<Ctx, 'search'> = { name: 'search', handle: (i) => i.reply('...') };
 
 const chatInputCommandRegistry = createChatInputCommandRegistry([pingCommand, searchCommand]);
 type ChatInputCommandName = RegistryName<typeof chatInputCommandRegistry>; // 'ping' | 'search'
 ```
 
+(Object literals passed directly inline into the array — not through an
+intermediate `const` — infer literally on their own, since TS 5's `const`
+type parameter modifier on `createChatInputCommandRegistry` requests literal
+inference for its argument; the explicit-generic form above is what you need
+once each command lives in its own file, which is the normal case.)
+
 A command's name should only ever be written down in two places: its
 `commands.json` entry and its own registry object's `name` field — nothing
 else should define it again, only reference the same string (or the derived
@@ -433,6 +452,101 @@ const manager = await createShardManager({
 });
 ```
 
+**Graceful deploys with `gracefulRespawnSignal`:** a plain process restart
+kills every shard at once, then respawns them sequentially — Discord's
+identify rate limit forces roughly one shard every 5s, so a bot with 20+
+shards can be fully down for minutes on every deploy. Passing
+`gracefulRespawnSignal: 'SIGUSR2'` registers a handler that calls the
+manager's `respawnAll()` instead, which kills/respawns shards **one at a
+time** on the same long-lived manager process — at most one shard is briefly
+offline (a few seconds) at any point, not the whole fleet:
+
+```ts
+const manager = await createShardManager({
+  token, botScriptPath, logger,
+  beforeSpawn: () => startupCommandsUpdate(logger),
+  gracefulRespawnSignal: 'SIGUSR2',
+});
+```
+
+Your deploy script then sends that signal to the running manager process
+(e.g. `kill -s USR2 "$(pm2 pid my-bot)"` — note dash's `kill` builtin
+rejects bash's `-SIGUSR2` form, use `-s USR2`) instead of restarting it,
+whenever only shard-side code changed. Since a forked shard process re-reads
+its script fresh off disk, this picks up ordinary code changes fine — but
+NOT changes to the top-level process that calls `createShardManager` itself
+(this file, its `beforeSpawn`, or anything it holds in memory), since that
+process is never restarted. Fall back to a real restart for those, and for
+anything that needs `beforeSpawn`'s one-time setup (e.g. slash command
+registration) to re-run.
+
+### `@went.tf/discord-bot-framework/webhook` (experimental)
+
+> **Experimental, unvalidated against a real bot.** Unlike every other
+> subpath in this package, `./webhook` hasn't yet been proven against a real
+> migration — see the scope note at the end of this section and CLAUDE.md's
+> `./webhook` design-decision entry. The API may change in a minor/patch
+> release until that validation happens, despite semver-major otherwise being
+> reserved for breaking changes in this package.
+
+An alternate, independent transport alongside `./client`'s gateway-based
+`createBotClient`/`createShardManager`, for bots that want to receive
+interactions over an HTTP Interactions Endpoint instead of holding a
+WebSocket open. As with `createBotClient`/`createShardManager`, this doesn't
+unify with the gateway path behind one entry point — pick one transport per
+bot and use its functions directly.
+
+`verifyInteractionRequest` checks a request's `X-Signature-Ed25519`/
+`X-Signature-Timestamp` headers against your application's public key, using
+Node's native `crypto` module (no `tweetnacl`/`discord-interactions`
+dependency needed). `handleWebhookInteractionRequest` wraps that plus
+Discord's PING→PONG endpoint-validation handshake around your own handler,
+taking/returning plain data so it can be wired into any HTTP framework (or
+none):
+
+```ts
+import { handleWebhookInteractionRequest } from '@went.tf/discord-bot-framework/webhook';
+import { createServer } from 'node:http';
+
+createServer(async (req, res) => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const rawBody = Buffer.concat(chunks);
+
+  const { status, body } = await handleWebhookInteractionRequest(
+    {
+      signature: req.headers['x-signature-ed25519'] as string,
+      timestamp: req.headers['x-signature-timestamp'] as string,
+      rawBody,
+    },
+    {
+      publicKey: env.DISCORD_PUBLIC_KEY,
+      logger,
+      onInteraction: (interaction) => handleInteraction(interaction), // bot-side: build an APIInteractionResponse
+    },
+  );
+  res.writeHead(status, { 'Content-Type': 'application/json' }).end(JSON.stringify(body));
+}).listen(3000);
+```
+
+`createWebhookInteractionResponder` gives you the REST calls needed *after*
+that initial response — editing a deferred reply, sending a follow-up, or
+deleting the reply — built on `@discordjs/rest` (already a peer dependency):
+
+```ts
+import { createWebhookInteractionResponder } from '@went.tf/discord-bot-framework/webhook';
+
+const responder = createWebhookInteractionResponder({ rest, applicationId, interactionToken: interaction.token });
+await responder.editReply({ content: 'Done!' });
+```
+
+**This is not a drop-in replacement for discord.js's `Interaction#reply()`/
+`editReply()`/`options.get*()` surface.** It's intentionally the thinner,
+already-validated half of that problem (signature verification, the PING
+handshake, and the plain REST calls) — see CLAUDE.md's `./webhook`
+design-decision entry for why a discord.js-`Interaction`-shaped compatibility
+adapter isn't built here yet.
+
 ### `@went.tf/discord-bot-framework/dev`
 
 Live-reloads compiled command/interaction handler *implementations* during