@went.tf/discord-bot-framework 2.4.0 → 2.6.0

package/README.md

@@ -480,6 +480,118 @@ 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!' });
+```
+
+**Running existing gateway-shaped command handlers unmodified:**
+`createWebhookOnlyClient` builds a real discord.js `Client` that's fully
+authenticated for REST but never opens a gateway connection (`Client#login()`
+always does, with no way to opt out, so this sets `client.rest`'s token
+directly instead - both fully public API). `interactionFromWebhookPayload`
+then reconstructs a genuine discord.js `Interaction` instance from the raw
+payload, the same way discord.js's own gateway path does internally - so
+`.reply()`/`.deferReply()`/`.editReply()`/`.options.getString()` etc. all work
+exactly as they do today, and your existing `BotChatInputCommand`/
+`dispatchChatInputCommand`/`createInteractionRouter` code needs zero changes:
+
+```ts
+import { createWebhookOnlyClient, handleWebhookInteractionRequest, interactionFromWebhookPayload } from '@went.tf/discord-bot-framework/webhook';
+import { dispatchChatInputCommand } from '@went.tf/discord-bot-framework/interactions';
+
+const client = createWebhookOnlyClient({ token: env.DISCORD_BOT_TOKEN });
+
+// inside your HTTP handler, in place of the plain onInteraction above:
+onInteraction: async (data) => {
+  const interaction = interactionFromWebhookPayload(client, data);
+  if (interaction.isChatInputCommand()) {
+    await dispatchChatInputCommand(interaction, context, { commands: registry.byName, onError });
+    return; // .reply()/.deferReply() already sent the real response via REST
+  }
+  // ...similarly for dispatchComponent/dispatchModal/dispatchAutocomplete/dispatchContextMenu
+},
+```
+
+Two real gaps versus a gateway-delivered interaction, both from there being no
+populated gateway cache: `.guild` is always `null`, and `.channel` is `null`
+unless you pre-cache the interaction's inline partial channel data yourself.
+`.member` degrades gracefully instead (falls back to the raw
+`APIInteractionGuildMember` object), so plain property reads keep working.
+See `interactionFromWebhookPayload`'s doc comment for the full detail -
+runtime-verified in `interaction-from-webhook-payload.test.ts` (including the
+two discord.js interaction classes with `private` constructors,
+`ButtonInteraction`/`ModalSubmitInteraction`, which still construct correctly
+through this bridge).
+
+**One thing this hasn't verified**, because it needs live Discord traffic,
+not just source-reading: when a handler's `.reply()`/`.deferReply()` call
+already sent the real response via REST mid-handler, what your `onInteraction`
+callback should still return as the literal HTTP response to Discord's
+original webhook POST. `handleWebhookInteractionRequest` sends a bare `{}`
+with a 200 if `onInteraction` returns nothing, on the assumption (backed by
+discord.js's `InteractionResponses` source - every reply method calls the same
+`Routes.interactionCallback()` REST route regardless of gateway vs. webhook
+delivery, so the mechanism is provably delivery-agnostic on Discord's side)
+that this is fine, but that assumption is unconfirmed against a real
+registered endpoint. See CLAUDE.md's `./webhook` design-decision entry before
+relying on this in production.
+
 ### `@went.tf/discord-bot-framework/dev`
 
 Live-reloads compiled command/interaction handler *implementations* during