privage.js 0.21.0 → 0.25.0

package/README.md

@@ -205,6 +205,9 @@ which have no source message) or `interaction.reply(...)` — optionally after
 (`reply({ ..., ephemeral: true })`) are visible only to the interacting user
 and never persisted — great for confirmations and errors; valid for every
 kind. Selected values arrive on `interaction.values` (selects only).
+Replies can carry uploads — `reply({ files: [...] })`, same limits and
+`ATTACH_FILES` requirement as `client.send` (non-ephemeral only, no
+embeds/components alongside in v1).
 
 Limits: 5 rows/message; a row holds either ≤5 buttons or exactly one select
 (≤25 interactive components/message); label ≤80, `custom_id` ≤100 and unique

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/rest.d.ts

@@ -119,11 +119,11 @@ export declare class Rest {
     /**
      * Respond to an interaction. `type`: 'update' (terminal — edit the
      * original message), 'reply' (terminal — post a reply; `data.ephemeral:
-     * true` for an only-you reply), 'defer' (extend the window; a terminal
-     * callback must follow), or 'modal' (open a modal — pending interactions
-     * only, once). Response: `{ success, message }` for update/reply (an
-     * ephemeral reply's `message` is a reduced, never-persisted object);
-     * defer/modal are 204s and resolve `null`.
+     * true` for an only-you reply, `data.files` for uploads), 'defer' (extend
+     * the window; a terminal callback must follow), or 'modal' (open a modal
+     * — pending interactions only, once). Response: `{ success, message }`
+     * for update/reply (an ephemeral reply's `message` is a reduced,
+     * never-persisted object); defer/modal are 204s and resolve `null`.
      */
     interactionCallback(interactionId: string, token: string, type: 'update' | 'reply' | 'defer' | 'modal', data?: object): Promise<any>;
     /** PUT /api/bots/commands — bulk overwrite the bot's slash commands (whole-or-400). Response: `{ success, commands }`. */

package/dist/rest.js

@@ -144,14 +144,48 @@ class Rest {
     /**
      * Respond to an interaction. `type`: 'update' (terminal — edit the
      * original message), 'reply' (terminal — post a reply; `data.ephemeral:
-     * true` for an only-you reply), 'defer' (extend the window; a terminal
-     * callback must follow), or 'modal' (open a modal — pending interactions
-     * only, once). Response: `{ success, message }` for update/reply (an
-     * ephemeral reply's `message` is a reduced, never-persisted object);
-     * defer/modal are 204s and resolve `null`.
+     * true` for an only-you reply, `data.files` for uploads), 'defer' (extend
+     * the window; a terminal callback must follow), or 'modal' (open a modal
+     * — pending interactions only, once). Response: `{ success, message }`
+     * for update/reply (an ephemeral reply's `message` is a reduced,
+     * never-persisted object); defer/modal are 204s and resolve `null`.
      */
-    interactionCallback(interactionId, token, type, data) {
-        return this.request(`/interactions/${interactionId}/${encodeURIComponent(token)}/callback`, { method: 'POST', body: data === undefined ? { type } : { type, data } });
+    async interactionCallback(interactionId, token, type, data) {
+        const path = `/interactions/${interactionId}/${encodeURIComponent(token)}/callback`;
+        const d = data;
+        if (d?.files?.length) {
+            // File replies upload as multipart; the server accepts them for
+            // non-ephemeral 'reply' only — fail loud and local on everything else.
+            if (type !== 'reply') {
+                throw new RangeError(`File attachments are only valid on reply callbacks (got '${type}').`);
+            }
+            if (d.ephemeral) {
+                throw new RangeError('Ephemeral replies cannot carry file attachments — nothing is persisted, so there is nowhere for the files to live.');
+            }
+            if (d.embeds?.length || d.components?.length) {
+                throw new RangeError('Attachments cannot be combined with embeds or components in one reply (v1) — send them separately.');
+            }
+            if (d.files.length > 10) {
+                throw new RangeError(`At most 10 attachments per reply (got ${d.files.length}).`);
+            }
+            const { files, ephemeral: _e, embeds: _em, components: _c, nonce, ...rest } = d;
+            const form = new FormData();
+            form.append('type', 'reply');
+            // Always carry a nonce: the server commits the message before the
+            // terminal state change, so a retried callback dedupes against it
+            // instead of inserting a second message.
+            form.append('data', JSON.stringify({ ...rest, nonce: nonce ?? (0, crypto_1.randomUUID)() }));
+            const parts = await (0, attachments_1.resolveFiles)(files);
+            for (const { blob, name } of parts) {
+                form.append('files', blob, name);
+            }
+            if (parts.some((p) => p.spoiler)) {
+                form.append('attachment_spoilers', JSON.stringify(parts.map((p) => p.spoiler)));
+            }
+            // Uploads get a longer budget than ordinary REST calls.
+            return this.request(path, { method: 'POST', body: form, timeoutMs: 60000 });
+        }
+        return this.request(path, { method: 'POST', body: data === undefined ? { type } : { type, data } });
     }
     /** PUT /api/bots/commands — bulk overwrite the bot's slash commands (whole-or-400). Response: `{ success, commands }`. */
     setCommands(commands) {

package/dist/structures/Interaction.d.ts

@@ -1,6 +1,7 @@
 import type { Client } from '../Client';
 import type { EmbedBuilder, Embed } from '../embeds';
 import type { ActionRow, ActionRowBuilder } from '../components';
+import type { AttachmentBuilder, AttachmentSource } from '../attachments';
 import { ModalBuilder, type Modal } from '../modals';
 /** Discriminates what the user did. Pre-v2 envelopes (no `kind`) read as `'button'`. */
 export type InteractionKind = 'button' | 'select' | 'command' | 'modal_submit';
@@ -15,11 +16,27 @@ export interface InteractionReplyData {
     /**
      * Only-you reply: never persisted, delivered as an event to the
      * interacting user alone ("Only you can see this"). Valid for every
-     * interaction kind. Still terminal.
+     * interaction kind. Still terminal. Cannot carry `files` (nothing is
+     * 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,
+     * or Blobs (max 10, 25 MB each). Non-ephemeral replies only; cannot be
+     * combined with `embeds` or `components` (v1). Uploads as multipart with
+     * an auto-generated `nonce`, so a retried callback never duplicates the
+     * message.
+     */
+    files?: (AttachmentBuilder | AttachmentSource)[];
+    /** Client-dedupe nonce — auto-generated for file replies when omitted. */
+    nonce?: string;
 }
 export type CommandOptionType = 'string' | 'integer' | 'number' | 'boolean' | 'user' | 'channel' | 'role';
 /** One resolved option of a slash-command invocation (already validated + coerced by the server). */
@@ -73,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: {
@@ -103,16 +130,22 @@ 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>;
     /**
      * Terminal: post a bot message replying to the original (a plain channel
      * message for commands). Pass `{ ephemeral: true }` for an only-you reply
-     * that is never persisted.
+     * that is never persisted, or `{ files: [...] }` to attach uploads
+     * (non-ephemeral only; needs `ATTACH_FILES` in the channel).
      */
     reply(data: string | InteractionReplyData): Promise<any>;
     /**
@@ -127,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,24 +88,30 @@ 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));
     }
     /**
      * Terminal: post a bot message replying to the original (a plain channel
      * message for commands). Pass `{ ephemeral: true }` for an only-you reply
-     * that is never persisted.
+     * that is never persisted, or `{ files: [...] }` to attach uploads
+     * (non-ephemeral only; needs `ATTACH_FILES` in the channel).
      */
     reply(data) {
         return this.transition('responded', () => this.client.rest.interactionCallback(this.id, this.token, 'reply', typeof data === 'string' ? { content: data } : data));
@@ -125,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.21.0",
+  "version": "0.25.0",
   "description": "Official SDK for building Privage bots.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",