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

package/build/webhook/create-webhook-only-client.d.ts

@@ -0,0 +1,35 @@
+import { Client, ClientOptions } from 'discord.js';
+export interface CreateWebhookOnlyClientOptions extends Omit<ClientOptions, 'intents'> {
+    /** No gateway connection is ever opened, so no intents actually apply - defaults to `[]`. */
+    intents?: ClientOptions['intents'];
+    token: string;
+}
+/**
+ * Builds a discord.js `Client` for webhook (HTTP Interactions Endpoint) mode:
+ * fully public API (`new Client()` + `Client#rest.setToken()`, both documented),
+ * but deliberately **never calls `Client#login()`**, since `login()`
+ * unconditionally opens a gateway WebSocket connection
+ * (`this.ws.connect()`, no way to opt out) - the entire reason a bot would
+ * reach for `./webhook` in the first place.
+ *
+ * The resulting client's `rest` is fully authenticated (same
+ * `rest.setToken()` call `login()` itself makes), so `Interaction#reply()`/
+ * `deferReply()`/`editReply()`/etc. work normally - they only ever call
+ * `this.client.rest` against `Routes.interactionCallback()`, with no
+ * `client.application`/gateway dependency. `client.guilds`/`client.channels`
+ * caches stay permanently empty, though - see `interactionFromWebhookPayload`'s
+ * doc comment for what that does and doesn't affect.
+ *
+ * Typed as `Client<true>` (discord.js's "ready" client) rather than the more
+ * literally-accurate `Client<false>`, purely so the result can be passed to
+ * `interactionFromWebhookPayload`/`dispatch*`/`createInteractionRouter`
+ * without a cast at every call site - every discord.js interaction class's
+ * own constructor requires `Client<true>` regardless of whether the client
+ * actually went through the gateway ready lifecycle. This client never does
+ * (there's no gateway connection to become ready on), so anything gated by
+ * `Ready` at the type level but genuinely absent at runtime -
+ * `client.user`/`client.application` chief among them - will be `null`
+ * despite what its type claims; avoid touching those in webhook mode.
+ */
+export declare function createWebhookOnlyClient(options: CreateWebhookOnlyClientOptions): Client<true>;
+//# sourceMappingURL=create-webhook-only-client.d.ts.map

package/build/webhook/create-webhook-only-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-webhook-only-client.d.ts","sourceRoot":"","sources":["../../src/webhook/create-webhook-only-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC;IACpF,6FAA6F;IAC7F,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,MAAM,CAAC,IAAI,CAAC,CAM7F"}

package/build/webhook/create-webhook-only-client.js

@@ -0,0 +1,36 @@
+import { Client } from 'discord.js';
+/**
+ * Builds a discord.js `Client` for webhook (HTTP Interactions Endpoint) mode:
+ * fully public API (`new Client()` + `Client#rest.setToken()`, both documented),
+ * but deliberately **never calls `Client#login()`**, since `login()`
+ * unconditionally opens a gateway WebSocket connection
+ * (`this.ws.connect()`, no way to opt out) - the entire reason a bot would
+ * reach for `./webhook` in the first place.
+ *
+ * The resulting client's `rest` is fully authenticated (same
+ * `rest.setToken()` call `login()` itself makes), so `Interaction#reply()`/
+ * `deferReply()`/`editReply()`/etc. work normally - they only ever call
+ * `this.client.rest` against `Routes.interactionCallback()`, with no
+ * `client.application`/gateway dependency. `client.guilds`/`client.channels`
+ * caches stay permanently empty, though - see `interactionFromWebhookPayload`'s
+ * doc comment for what that does and doesn't affect.
+ *
+ * Typed as `Client<true>` (discord.js's "ready" client) rather than the more
+ * literally-accurate `Client<false>`, purely so the result can be passed to
+ * `interactionFromWebhookPayload`/`dispatch*`/`createInteractionRouter`
+ * without a cast at every call site - every discord.js interaction class's
+ * own constructor requires `Client<true>` regardless of whether the client
+ * actually went through the gateway ready lifecycle. This client never does
+ * (there's no gateway connection to become ready on), so anything gated by
+ * `Ready` at the type level but genuinely absent at runtime -
+ * `client.user`/`client.application` chief among them - will be `null`
+ * despite what its type claims; avoid touching those in webhook mode.
+ */
+export function createWebhookOnlyClient(options) {
+    const { token, intents = [], ...clientOptions } = options;
+    const client = new Client({ intents, ...clientOptions });
+    client.token = token;
+    client.rest.setToken(token);
+    return client;
+}
+//# sourceMappingURL=create-webhook-only-client.js.map

package/build/webhook/create-webhook-only-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-webhook-only-client.js","sourceRoot":"","sources":["../../src/webhook/create-webhook-only-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,YAAY,CAAC;AAQnD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAuC;IAC7E,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,EAAE,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,MAAsB,CAAC;AAChC,CAAC"}

package/build/webhook/handle-webhook-interaction-request.d.ts

@@ -7,12 +7,19 @@ export interface WebhookInteractionRequest {
     timestamp: string | undefined;
     /** The raw (unparsed) request body, exactly as received - required for signature verification. */
     rawBody: string | Buffer;
+    /**
+     * Request headers, lowercase-keyed (matches Node's `http.IncomingMessage`,
+     * Express, Fastify, ... convention). Optional - only used to enrich the
+     * diagnostic `debug` log emitted when signature verification fails,
+     * verification/dispatch behavior is identical either way.
+     */
+    headers?: Record<string, string | undefined>;
 }
 export interface WebhookInteractionResponse {
     status: number;
     body: APIInteractionResponse | {
         error: string;
-    };
+    } | Record<string, never>;
 }
 export interface HandleWebhookInteractionRequestOptions {
     /** The bot's Ed25519 application public key, from the Discord developer portal, as a hex string. */
@@ -24,8 +31,18 @@ export interface HandleWebhookInteractionRequestOptions {
      * Discord as the interaction's initial response (e.g. a `CHANNEL_MESSAGE_WITH_SOURCE`
      * or a `DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE` to be followed up on later via
      * `createWebhookInteractionResponder`).
+     *
+     * If you instead bridge into a real discord.js interaction via
+     * `interactionFromWebhookPayload` and dispatch it through
+     * `dispatchChatInputCommand`/`createInteractionRouter`, the handler's own
+     * `.reply()`/`.deferReply()` call already sends the actual response via
+     * REST before this resolves - return nothing (`void`) in that case, and a
+     * generic 200 ack is sent back to Discord's original request instead.
+     * **This dual response path (a real REST call already made mid-handler,
+     * plus a separate bare HTTP ack to the original webhook POST) is unverified
+     * against live Discord traffic** - see this module's CLAUDE.md entry.
      */
-    onInteraction: (interaction: APIInteraction) => APIInteractionResponse | Promise<APIInteractionResponse>;
+    onInteraction: (interaction: APIInteraction) => APIInteractionResponse | void | Promise<APIInteractionResponse | void>;
 }
 /**
  * Framework-agnostic core of an HTTP Interactions endpoint: verifies the
@@ -36,6 +53,15 @@ export interface HandleWebhookInteractionRequestOptions {
  * `Request`/etc., so it can be wired into any HTTP layer a bot already uses -
  * this package doesn't otherwise depend on one, and picking one here would be
  * a bigger commitment than this function needs to make.
+ *
+ * On a signature-verification failure, logs a `debug`-level diagnostic
+ * (source IP, user-agent, whether the signature/timestamp headers were even
+ * present, signature/body length) alongside the existing `warn` - a public
+ * webhook endpoint draws routine internet-scanner noise as well as genuine
+ * misconfiguration, and this is what tells the two apart after the fact
+ * without every consuming bot re-implementing the same wrapper around this
+ * call. Requires `request.headers` (optional) to populate the IP/user-agent
+ * fields; omit it and those two just come back `undefined`.
  */
 export declare function handleWebhookInteractionRequest(request: WebhookInteractionRequest, options: HandleWebhookInteractionRequestOptions): Promise<WebhookInteractionResponse>;
 //# sourceMappingURL=handle-webhook-interaction-request.d.ts.map

package/build/webhook/handle-webhook-interaction-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-webhook-interaction-request.d.ts","sourceRoot":"","sources":["../../src/webhook/handle-webhook-interaction-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAA4C,MAAM,uBAAuB,CAAC;AACzH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,WAAW,yBAAyB;IACxC,kDAAkD;IAClD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kGAAkG;IAClG,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,sBAAsB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,sCAAsC;IACrD,oGAAoG;IACpG,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,WAAW,EAAE,cAAc,KAAK,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC1G;AAED;;;;;;;;;GASG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,sCAAsC,GAC9C,OAAO,CAAC,0BAA0B,CAAC,CAiCrC"}
+{"version":3,"file":"handle-webhook-interaction-request.d.ts","sourceRoot":"","sources":["../../src/webhook/handle-webhook-interaction-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAA4C,MAAM,uBAAuB,CAAC;AACzH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,WAAW,yBAAyB;IACxC,kDAAkD;IAClD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kGAAkG;IAClG,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,sBAAsB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,sCAAsC;IACrD,oGAAoG;IACpG,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,EAAE,CAAC,WAAW,EAAE,cAAc,KAAK,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CACxH;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,sCAAsC,GAC9C,OAAO,CAAC,0BAA0B,CAAC,CAyCrC"}

package/build/webhook/handle-webhook-interaction-request.js

@@ -1,5 +1,21 @@
 import { InteractionResponseType, InteractionType } from 'discord-api-types/v10';
 import { verifyInteractionRequest } from './verify-interaction-request.js';
+/**
+ * Best-effort source IP for the diagnostic log below - checks the headers a
+ * request sitting behind a reverse proxy (Cloudflare, nginx, ...) actually
+ * carries the real client IP in, since `req.socket.remoteAddress`-equivalent
+ * info is proxy-terminated and not available from headers/body alone. Not
+ * used for anything security-sensitive (signature verification never trusts
+ * client-supplied IP data) - purely to help a bot operator eyeball whether a
+ * batch of rejections looks like internet-scanner noise or something worth a
+ * closer look.
+ */
+function resolveSourceIp(headers) {
+    if (!headers) {
+        return undefined;
+    }
+    return headers['cf-connecting-ip'] ?? headers['x-real-ip'] ?? headers['x-forwarded-for']?.split(',')[0]?.trim();
+}
 /**
  * Framework-agnostic core of an HTTP Interactions endpoint: verifies the
  * request's Ed25519 signature, answers Discord's PING (type 1) validation
@@ -9,6 +25,15 @@ import { verifyInteractionRequest } from './verify-interaction-request.js';
  * `Request`/etc., so it can be wired into any HTTP layer a bot already uses -
  * this package doesn't otherwise depend on one, and picking one here would be
  * a bigger commitment than this function needs to make.
+ *
+ * On a signature-verification failure, logs a `debug`-level diagnostic
+ * (source IP, user-agent, whether the signature/timestamp headers were even
+ * present, signature/body length) alongside the existing `warn` - a public
+ * webhook endpoint draws routine internet-scanner noise as well as genuine
+ * misconfiguration, and this is what tells the two apart after the fact
+ * without every consuming bot re-implementing the same wrapper around this
+ * call. Requires `request.headers` (optional) to populate the IP/user-agent
+ * fields; omit it and those two just come back `undefined`.
  */
 export async function handleWebhookInteractionRequest(request, options) {
     const { publicKey, logger, onInteraction } = options;
@@ -20,6 +45,14 @@ export async function handleWebhookInteractionRequest(request, options) {
     });
     if (!isValid) {
         logger.warn('Rejected webhook interaction request with invalid signature');
+        logger.debug('Webhook interaction signature-rejection diagnostics', {
+            sourceIp: resolveSourceIp(request.headers),
+            userAgent: request.headers?.['user-agent'],
+            hasSignatureHeader: request.signature !== undefined,
+            hasTimestampHeader: request.timestamp !== undefined,
+            signatureLength: request.signature?.length ?? 0,
+            bodyLength: Buffer.byteLength(request.rawBody),
+        });
         return { status: 401, body: { error: 'Invalid request signature' } };
     }
     let interaction;
@@ -35,7 +68,7 @@ export async function handleWebhookInteractionRequest(request, options) {
     }
     try {
         const body = await onInteraction(interaction);
-        return { status: 200, body };
+        return { status: 200, body: body ?? {} };
     }
     catch (e) {
         logger.error('Error while handling webhook interaction', e);

package/build/webhook/handle-webhook-interaction-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"handle-webhook-interaction-request.js","sourceRoot":"","sources":["../../src/webhook/handle-webhook-interaction-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEzH,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AA8B3E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAAkC,EAClC,OAA+C;IAE/C,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,OAAO,GAAG,wBAAwB,CAAC;QACvC,SAAS;QACT,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;QAC3E,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,WAA2B,CAAC;IAChC,IAAI,CAAC;QACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAmB,CAAC;IACzE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,0DAA0D,EAAE,CAAC,CAAC,CAAC;QAC5E,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAC;IAC/D,CAAC;IAED,IAAI,WAAW,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC;IAC5D,CAAC;AACH,CAAC"}
+{"version":3,"file":"handle-webhook-interaction-request.js","sourceRoot":"","sources":["../../src/webhook/handle-webhook-interaction-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEzH,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AA+C3E;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,OAAuD;IAC9E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,CAAC,kBAAkB,CAAC,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAClH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAAkC,EAClC,OAA+C;IAE/C,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,OAAO,GAAG,wBAAwB,CAAC;QACvC,SAAS;QACT,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;QAC3E,MAAM,CAAC,KAAK,CAAC,qDAAqD,EAAE;YAClE,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC;YAC1C,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,YAAY,CAAC;YAC1C,kBAAkB,EAAE,OAAO,CAAC,SAAS,KAAK,SAAS;YACnD,kBAAkB,EAAE,OAAO,CAAC,SAAS,KAAK,SAAS;YACnD,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;YAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;SAC/C,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,WAA2B,CAAC;IAChC,IAAI,CAAC;QACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAmB,CAAC;IACzE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,0DAA0D,EAAE,CAAC,CAAC,CAAC;QAC5E,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAC;IAC/D,CAAC;IAED,IAAI,WAAW,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/build/webhook/index.d.ts

@@ -1,4 +1,6 @@
 export * from './verify-interaction-request.js';
 export * from './handle-webhook-interaction-request.js';
 export * from './create-webhook-interaction-responder.js';
+export * from './create-webhook-only-client.js';
+export * from './interaction-from-webhook-payload.js';
 //# sourceMappingURL=index.d.ts.map

package/build/webhook/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAIA,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAKA,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,uCAAuC,CAAC"}

package/build/webhook/index.js

@@ -1,8 +1,11 @@
 // Experimental: unvalidated against a real bot migration yet. See this
 // module's design-decision entry in CLAUDE.md before relying on it, in
-// particular that `createWebhookInteractionResponder` is not a drop-in
-// discord.js `Interaction` shim.
+// particular that the initial-response HTTP semantics documented on
+// `handleWebhookInteractionRequest`/`interactionFromWebhookPayload` are
+// unverified against live Discord traffic.
 export * from './verify-interaction-request.js';
 export * from './handle-webhook-interaction-request.js';
 export * from './create-webhook-interaction-responder.js';
+export * from './create-webhook-only-client.js';
+export * from './interaction-from-webhook-payload.js';
 //# sourceMappingURL=index.js.map

package/build/webhook/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AACvE,iCAAiC;AACjC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,wEAAwE;AACxE,2CAA2C;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,uCAAuC,CAAC"}

package/build/webhook/interaction-from-webhook-payload.d.ts

@@ -0,0 +1,31 @@
+import { APIInteraction } from 'discord-api-types/v10';
+import { Client, Interaction } from 'discord.js';
+/**
+ * Reconstructs a genuine discord.js `Interaction` instance from a raw
+ * webhook-delivered interaction payload, so existing gateway-shaped handler
+ * code (`interaction.reply()`, `interaction.options.getString()`, etc.) can
+ * run completely unmodified in webhook mode - built on the same `client`
+ * this instance's `.reply()`/`.editReply()`/etc. will make real REST calls
+ * through (see `createWebhookOnlyClient`). Mirrors discord.js's own
+ * `InteractionCreateAction.handle()` class-picking switch (which does the
+ * same thing for gateway-delivered payloads) exactly, one discord-api-types
+ * version at a time - if discord.js adds a new interaction/component type,
+ * this needs a matching new case.
+ *
+ * **Two real gaps versus a gateway-delivered interaction, both from having
+ * no populated gateway cache:**
+ * - `.guild` is always `null` (`client.guilds.cache` is permanently empty in
+ *   webhook mode, and unlike `.channel`, nothing pre-caches a partial for
+ *   it).
+ * - `.channel` is `null` unless the caller pre-caches the interaction's
+ *   inline partial channel data into `client.channels` first - this
+ *   function does not attempt that itself (discord.js's own equivalent step,
+ *   `Action#getChannel`, is a private internal not exposed for reuse).
+ *
+ * `.member` degrades gracefully instead of breaking: it falls back to the
+ * raw `APIInteractionGuildMember` POJO instead of a real `GuildMember`
+ * class instance when `.guild` is `null`, so plain property reads (`.roles`,
+ * `.nick`, ...) keep working - only actual `GuildMember` methods would not.
+ */
+export declare function interactionFromWebhookPayload(client: Client<true>, data: APIInteraction): Interaction;
+//# sourceMappingURL=interaction-from-webhook-payload.d.ts.map

package/build/webhook/interaction-from-webhook-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-from-webhook-payload.d.ts","sourceRoot":"","sources":["../../src/webhook/interaction-from-webhook-payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA0D,MAAM,uBAAuB,CAAC;AAC/G,OAAO,EAKL,MAAM,EACN,WAAW,EASZ,MAAM,YAAY,CAAC;AAwBpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAuCrG"}

package/build/webhook/interaction-from-webhook-payload.js

@@ -0,0 +1,91 @@
+import { ApplicationCommandType, ComponentType, InteractionType } from 'discord-api-types/v10';
+import { AutocompleteInteraction, ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, MentionableSelectMenuInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, PrimaryEntryPointCommandInteraction, RoleSelectMenuInteraction, StringSelectMenuInteraction, UserContextMenuCommandInteraction, UserSelectMenuInteraction, } from 'discord.js';
+/**
+ * Constructs a discord.js interaction class directly against its own real
+ * `(client, data)` constructor - checked against every class this module
+ * uses (discord.js@14.26.x), each one's constructor is either `protected`
+ * (blocks external construction, but not a subclass's `super()` - not used
+ * here since it'd be a second, inconsistent mechanism just for those) or, for
+ * `ButtonInteraction`/`ModalSubmitInteraction`/the 5 select-menu classes,
+ * fully `private` (blocks even subclassing) with a narrower `data` parameter
+ * type (`APIMessageButtonInteractionData`, `APIModalSubmitInteraction`,
+ * `APIMessage*SelectInteractionData`) that isn't part of discord.js's public
+ * export surface to reference by name anyway. Both are pure TypeScript
+ * access-control keywords, erased in the compiled `.js` - this is exactly
+ * what discord.js's own `InteractionCreateAction.handle()` does at runtime
+ * (`new InteractionClass(client, data)`), just reached through a type cast
+ * instead of module-internal privilege, since there's no way to reference a
+ * type discord.js itself doesn't export.
+ */
+function constructInteraction(InteractionClass, client, data) {
+    const Ctor = InteractionClass;
+    return new Ctor(client, data);
+}
+/**
+ * Reconstructs a genuine discord.js `Interaction` instance from a raw
+ * webhook-delivered interaction payload, so existing gateway-shaped handler
+ * code (`interaction.reply()`, `interaction.options.getString()`, etc.) can
+ * run completely unmodified in webhook mode - built on the same `client`
+ * this instance's `.reply()`/`.editReply()`/etc. will make real REST calls
+ * through (see `createWebhookOnlyClient`). Mirrors discord.js's own
+ * `InteractionCreateAction.handle()` class-picking switch (which does the
+ * same thing for gateway-delivered payloads) exactly, one discord-api-types
+ * version at a time - if discord.js adds a new interaction/component type,
+ * this needs a matching new case.
+ *
+ * **Two real gaps versus a gateway-delivered interaction, both from having
+ * no populated gateway cache:**
+ * - `.guild` is always `null` (`client.guilds.cache` is permanently empty in
+ *   webhook mode, and unlike `.channel`, nothing pre-caches a partial for
+ *   it).
+ * - `.channel` is `null` unless the caller pre-caches the interaction's
+ *   inline partial channel data into `client.channels` first - this
+ *   function does not attempt that itself (discord.js's own equivalent step,
+ *   `Action#getChannel`, is a private internal not exposed for reuse).
+ *
+ * `.member` degrades gracefully instead of breaking: it falls back to the
+ * raw `APIInteractionGuildMember` POJO instead of a real `GuildMember`
+ * class instance when `.guild` is `null`, so plain property reads (`.roles`,
+ * `.nick`, ...) keep working - only actual `GuildMember` methods would not.
+ */
+export function interactionFromWebhookPayload(client, data) {
+    switch (data.type) {
+        case InteractionType.ApplicationCommand:
+            switch (data.data.type) {
+                case ApplicationCommandType.ChatInput:
+                    return constructInteraction(ChatInputCommandInteraction, client, data);
+                case ApplicationCommandType.User:
+                    return constructInteraction(UserContextMenuCommandInteraction, client, data);
+                case ApplicationCommandType.Message:
+                    return constructInteraction(MessageContextMenuCommandInteraction, client, data);
+                case ApplicationCommandType.PrimaryEntryPoint:
+                    return constructInteraction(PrimaryEntryPointCommandInteraction, client, data);
+                default:
+                    throw new Error(`Unknown application command interaction type: ${data.data.type}`);
+            }
+        case InteractionType.MessageComponent:
+            switch (data.data.component_type) {
+                case ComponentType.Button:
+                    return constructInteraction(ButtonInteraction, client, data);
+                case ComponentType.StringSelect:
+                    return constructInteraction(StringSelectMenuInteraction, client, data);
+                case ComponentType.UserSelect:
+                    return constructInteraction(UserSelectMenuInteraction, client, data);
+                case ComponentType.RoleSelect:
+                    return constructInteraction(RoleSelectMenuInteraction, client, data);
+                case ComponentType.MentionableSelect:
+                    return constructInteraction(MentionableSelectMenuInteraction, client, data);
+                case ComponentType.ChannelSelect:
+                    return constructInteraction(ChannelSelectMenuInteraction, client, data);
+                default:
+                    throw new Error(`Unknown message component interaction type: ${data.data.component_type}`);
+            }
+        case InteractionType.ApplicationCommandAutocomplete:
+            return constructInteraction(AutocompleteInteraction, client, data);
+        case InteractionType.ModalSubmit:
+            return constructInteraction(ModalSubmitInteraction, client, data);
+        default:
+            throw new Error(`Unknown interaction type: ${data.type}`);
+    }
+}
+//# sourceMappingURL=interaction-from-webhook-payload.js.map

package/build/webhook/interaction-from-webhook-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-from-webhook-payload.js","sourceRoot":"","sources":["../../src/webhook/interaction-from-webhook-payload.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@went.tf/discord-bot-framework",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Shared framework for building Discord bots with discord.js: logging, env validation, interaction dispatch, API client, and optional Postgres/i18next helpers",
   "author": "WentTheFox <mail@went.tf> (https://github.com/WentTheFox)",
   "license": "MIT",