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

package/README.md

@@ -480,14 +480,16 @@ 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)
+### `@went.tf/discord-bot-framework/webhook`
 
-> **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.
+> **Validated against a real bot.** HammerTimeBot ran this against a real
+> registered Discord Interactions Endpoint URL (portal PING validation, then
+> a live `/unix` slash command end-to-end) on its `migrate-discord-bot-framework`
+> branch — signature verification, PING/PONG, the discord.js-`Interaction`
+> bridge, and the REST-callback-based ack path all confirmed working with
+> zero modifications needed to its 16 command files + component handler. See
+> CLAUDE.md's `./webhook` design-decision entry for the one open item that
+> validation surfaced (a Discord portal-side double-PING quirk, not blocking).
 
 An alternate, independent transport alongside `./client`'s gateway-based
 `createBotClient`/`createShardManager`, for bots that want to receive
@@ -518,6 +520,7 @@ createServer(async (req, res) => {
       signature: req.headers['x-signature-ed25519'] as string,
       timestamp: req.headers['x-signature-timestamp'] as string,
       rawBody,
+      headers: req.headers as Record<string, string | undefined>, // optional - enriches the signature-rejection debug log
     },
     {
       publicKey: env.DISCORD_PUBLIC_KEY,
@@ -529,6 +532,17 @@ createServer(async (req, res) => {
 }).listen(3000);
 ```
 
+On a signature-verification failure, `handleWebhookInteractionRequest` logs a
+`debug`-level diagnostic alongside the existing `warn` - source IP (checking
+`cf-connecting-ip`/`x-real-ip`/`x-forwarded-for` in turn, for bots sitting
+behind a reverse proxy), user-agent, whether the signature/timestamp headers
+were present at all vs. present-but-wrong, and signature/body length. A
+public webhook endpoint draws routine internet-scanner noise as well as
+genuine misconfiguration; this is what tells the two apart after the fact,
+without every consuming bot re-implementing the same wrapper. Pass `headers`
+to populate it - omit it and the IP/user-agent fields just come back
+`undefined`.
+
 `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):
@@ -540,12 +554,54 @@ const responder = createWebhookInteractionResponder({ rest, applicationId, inter
 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.
+**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).
+
+**The REST-callback-based ack path is confirmed working against live Discord
+traffic**, not just source-reading: when a handler's `.reply()`/`.deferReply()`
+call already sent the real response via REST mid-handler,
+`handleWebhookInteractionRequest` sends a bare `{}` with a 200 as the literal
+HTTP response to Discord's original webhook POST if `onInteraction` returns
+nothing - HammerTimeBot confirmed this is accepted end-to-end via a real
+`/unix` slash command run through a registered Interactions Endpoint URL. See
+CLAUDE.md's `./webhook` design-decision entry for that validation's one open
+item (a portal-side double-PING quirk, not blocking).
 
 ### `@went.tf/discord-bot-framework/dev`