privage.js 0.22.0 → 0.25.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Client } from './Client';
 export { Intents } from './intents';
 export type { Intent } from './intents';
 export { Message, TextChannel } from './structures/Message';
-export type { MessageThread, MessageReference, ReferencedMessage, MessageAttachment, MessageEmbed, } from './structures/Message';
+export type { MessageThread, MessageReference, ReferencedMessage, MessageAttachment, MessageEmbed, MessageInteraction, } from './structures/Message';
 export { Member } from './structures/Member';
 export { Server } from './structures/Server';
 export { Channel } from './structures/Channel';

package/dist/structures/Interaction.d.ts

@@ -20,7 +20,12 @@ export interface InteractionReplyData {
      * persisted, so there is nowhere for the bytes to live).
      */
     ephemeral?: boolean;
-    /** Components on the reply — ephemeral replies only (they render, but aren't clickable v1). */
+    /**
+     * Components on the reply — ephemeral replies only. They are fully
+     * interactive: clicks arrive as fresh `interaction` events carrying
+     * `ephemeralMessageId`, recipient-locked to the user the ephemeral was
+     * delivered to, for 15 minutes after sending.
+     */
     components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
     /**
      * File attachments on the reply — `AttachmentBuilder`s, paths, raw bytes,
@@ -85,8 +90,18 @@ export declare class Interaction {
     readonly command: InteractionCommand | null;
     /** Submitted modal fields — `kind: 'modal_submit'` only, `null` otherwise. */
     readonly fields: ModalSubmitField[] | null;
-    /** The source message. `null` for commands (and command-born modal submits) — `update()` is invalid then. */
+    /** The source message. `null` for commands, command-born modal submits, and ephemeral-born interactions — `update()` is invalid then. */
     readonly messageId: string | null;
+    /**
+     * Set when this interaction came from a component on an **ephemeral
+     * reply** — the synthetic ephemeral message's id. Recipient-locked:
+     * only the ephemeral's recipient can click, within the panel's
+     * 15-minute window (every click also re-checks membership/timeout).
+     * Respond with `update()` to morph the panel in place (the wizard
+     * pattern — updating refreshes the window), or `reply()` to post a
+     * new message.
+     */
+    readonly ephemeralMessageId: string | null;
     readonly channelId: string;
     readonly serverId: string | null;
     readonly user: {
@@ -115,10 +130,15 @@ export declare class Interaction {
     /** `kind === 'modal_submit'`. */
     isModalSubmit(): boolean;
     /**
-     * Terminal: edit the original message (content/embeds/components).
-     * Broadcasts a normal edit. Only valid when the interaction HAS a source
-     * message — throws client-side for `kind: 'command'` and for modal submits
-     * born from a command (the server would 400).
+     * Terminal: edit the message this interaction came from
+     * (content/embeds/components). On a persisted message that's a normal
+     * edit broadcast. On an interaction born from an **ephemeral reply**
+     * (`ephemeralMessageId` set) it morphs the ephemeral panel in place —
+     * patch semantics (only the fields you send change), refreshing the
+     * panel's 15-minute window; clearing `components: []` ends the panel,
+     * and an expired panel rejects with a 404. Throws client-side for
+     * `kind: 'command'` and command-born modal submits (no source at all —
+     * the server would 400).
      */
     update(data: InteractionUpdateData): Promise<any>;
     /**
@@ -140,7 +160,12 @@ export declare class Interaction {
      * deferred reply and replying are the same terminal callback.
      */
     editReply(data: string | InteractionReplyData): Promise<any>;
-    /** Extend the response window to 15 minutes; must still be followed by `update()` or `reply()`. */
+    /**
+     * Extend the response window to 15 minutes; must still be followed by
+     * `update()` or `reply()`. The invoker's client is told the bot needs
+     * more time, so a command's "thinking" row waits patiently instead of
+     * timing out at 15 seconds.
+     */
     defer(): Promise<any>;
     /**
      * Open a modal dialog for the interacting user; their submission arrives

package/dist/structures/Interaction.js

@@ -49,6 +49,7 @@ class Interaction {
             ? data.modal.fields.map((f) => ({ customId: String(f?.custom_id ?? ''), value: String(f?.value ?? '') }))
             : null;
         this.messageId = data.message_id != null ? String(data.message_id) : null;
+        this.ephemeralMessageId = data.ephemeral_message_id != null ? String(data.ephemeral_message_id) : null;
         this.channelId = String(data.channel_id ?? '');
         this.serverId = data.server_id != null ? String(data.server_id) : null;
         this.user = {
@@ -87,17 +88,22 @@ class Interaction {
         return this.kind === 'modal_submit';
     }
     /**
-     * Terminal: edit the original message (content/embeds/components).
-     * Broadcasts a normal edit. Only valid when the interaction HAS a source
-     * message — throws client-side for `kind: 'command'` and for modal submits
-     * born from a command (the server would 400).
+     * Terminal: edit the message this interaction came from
+     * (content/embeds/components). On a persisted message that's a normal
+     * edit broadcast. On an interaction born from an **ephemeral reply**
+     * (`ephemeralMessageId` set) it morphs the ephemeral panel in place —
+     * patch semantics (only the fields you send change), refreshing the
+     * panel's 15-minute window; clearing `components: []` ends the panel,
+     * and an expired panel rejects with a 404. Throws client-side for
+     * `kind: 'command'` and command-born modal submits (no source at all —
+     * the server would 400).
      */
     update(data) {
         if (this.kind === 'command') {
             throw new RangeError('update() is not valid for command interactions — there is no source message. Use reply() instead.');
         }
-        if (this.kind === 'modal_submit' && !this.messageId) {
-            throw new RangeError('update() is not valid for this modal submit — its parent interaction had no source message. Use reply() instead.');
+        if (!this.messageId && !this.ephemeralMessageId) {
+            throw new RangeError('update() is not valid for this interaction — it has no source message. Use reply() instead.');
         }
         return this.transition('responded', () => this.client.rest.interactionCallback(this.id, this.token, 'update', data));
     }
@@ -126,7 +132,12 @@ class Interaction {
     editReply(data) {
         return this.reply(data);
     }
-    /** Extend the response window to 15 minutes; must still be followed by `update()` or `reply()`. */
+    /**
+     * Extend the response window to 15 minutes; must still be followed by
+     * `update()` or `reply()`. The invoker's client is told the bot needs
+     * more time, so a command's "thinking" row waits patiently instead of
+     * timing out at 15 seconds.
+     */
     defer() {
         if (this.state !== 'pending') {
             return this.client.rest.interactionCallback(this.id, this.token, 'defer');

package/dist/structures/Message.d.ts

@@ -76,6 +76,25 @@ export interface MessageEmbed {
     timestamp: string | null;
     createdAt: Date | null;
 }
+/**
+ * Server-verified attribution on an interaction-born bot reply — who
+ * invoked the command/component that produced this message ("X used
+ * /price"). `user` is a frozen snapshot from interaction time; later
+ * renames never rewrite it. Ordinary messages carry `interaction: null`.
+ */
+export interface MessageInteraction {
+    kind: 'command' | 'button' | 'select' | 'modal_submit';
+    /** Command name — `kind: 'command'` only, `null` otherwise. */
+    name: string | null;
+    /** Component/modal custom_id — component-born interactions only, `null` otherwise. */
+    customId: string | null;
+    /** The invoking user, snapshotted at interaction time. */
+    user: {
+        id: string;
+        username: string | null;
+        displayName: string | null;
+    };
+}
 /** A frozen or live preview of the message a reference points at. */
 export interface ReferencedMessage {
     id: string;
@@ -144,6 +163,8 @@ export declare class Message {
     readonly reference: MessageReference | null;
     /** Thread badge — `null` unless this message has (or had) a thread. */
     readonly thread: MessageThread | null;
+    /** Attribution for interaction-born bot replies, or `null` (see {@link MessageInteraction}). */
+    readonly interaction: MessageInteraction | null;
     /** The raw wire payload, for anything the typed surface doesn't expose yet. */
     readonly raw: any;
     constructor(client: Client, data: any);

package/dist/structures/Message.js

@@ -123,6 +123,22 @@ class Message {
                     deletedAt: t.deleted_at ? new Date(t.deleted_at) : null,
                 }
                 : null;
+        const ix = data.interaction;
+        this.interaction =
+            ix && typeof ix === 'object'
+                ? {
+                    kind: ix.kind === 'select' || ix.kind === 'command' || ix.kind === 'modal_submit'
+                        ? ix.kind
+                        : 'button',
+                    name: ix.name != null ? String(ix.name) : null,
+                    customId: ix.custom_id != null ? String(ix.custom_id) : null,
+                    user: {
+                        id: String(ix.user?.id ?? ''),
+                        username: ix.user?.username ?? null,
+                        displayName: ix.user?.display_name ?? null,
+                    },
+                }
+                : null;
     }
     /**
      * Compat alias (discord.js-style): the id of the message this one replies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privage.js",
-  "version": "0.22.0",
+  "version": "0.25.0",
   "description": "Official SDK for building Privage bots.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",