district.js 0.2.0 → 0.5.0

package/README.md

@@ -69,6 +69,47 @@ import { Formatters } from "district.js";
 channel.send(Formatters.bold("Heads up!") + " " + Formatters.code("v0.2.0"));
 ```
 
+## Embeds
+
+```js
+import { EmbedBuilder } from "district.js";
+
+const embed = new EmbedBuilder()
+  .setTitle("Deploy complete")
+  .setUrl("https://example.com/builds/128")
+  .setColor("#c6a86b")
+  .setDescription("Build **#128** shipped to production.")
+  .addFields(
+    { name: "Env", value: "prod", inline: true },
+    { name: "By", value: "ci-bot", inline: true },
+  )
+  .setFooter({ text: "district.js" })
+  .setTimestamp();
+
+await channel.send({ content: "New release 🎉", embeds: [embed] });
+```
+
+The District app renders it as an embed card (accent bar, title, fields, image).
+
+## Buttons
+
+```js
+import { ActionRowBuilder, ButtonBuilder } from "district.js";
+
+const row = new ActionRowBuilder().addComponents(
+  new ButtonBuilder().setLabel("Approve").setStyle("success").setCustomId("approve"),
+  new ButtonBuilder().setLabel("Deny").setStyle("danger").setCustomId("deny"),
+  new ButtonBuilder().setLabel("Docs").setUrl("https://usedistrict.org/developers/docs"),
+);
+
+await channel.send({ content: "Review this?", components: [row] });
+
+// A click delivers an interactionCreate (needs an Event Subscription endpoint)
+client.on("interactionCreate", (i) => {
+  if (i.isButton() && i.customId === "approve") i.reply("Approved ✅");
+});
+```
+
 ## Slash commands
 
 Register the command in the portal (name + handler URL), then:

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
-import { ClientUser, Message, TextChannel, Interaction, User, Space, type ClientContext } from "./structures.js";
+import { ClientUser, Message, TextChannel, Interaction, User, Space, type ClientContext, type MessageContent } from "./structures.js";
 import { type EventHeaders } from "./webhook.js";
 import type { ClientOptions, ReactionEvent, DeletedMessage } from "./types.js";
 /** The events a Client emits, and their argument tuples. */
@@ -30,8 +30,8 @@ export declare class Client extends EventEmitter implements ClientContext {
     readonly channels: {
         /** Fetch a channel's info (kind, name, space). */
         fetch: (id: string) => Promise<TextChannel>;
-        /** Send a message to a channel. */
-        send: (channelId: string, content: string) => Promise<Message>;
+        /** Send a message to a channel (text or { content, embeds }). */
+        send: (channelId: string, content: MessageContent) => Promise<Message>;
     };
     /** Fetch users by id. */
     readonly users: {

package/dist/client.js

@@ -38,7 +38,7 @@ export class Client extends EventEmitter {
     channels = {
         /** Fetch a channel's info (kind, name, space). */
         fetch: (id) => new TextChannel(this, id).fetch(),
-        /** Send a message to a channel. */
+        /** Send a message to a channel (text or { content, embeds }). */
         send: (channelId, content) => new TextChannel(this, channelId).send(content),
     };
     /** Fetch users by id. */

package/dist/components.d.ts

@@ -0,0 +1,34 @@
+export type ButtonStyle = "primary" | "secondary" | "success" | "danger" | "link";
+export interface ButtonData {
+    type: "button";
+    style: ButtonStyle;
+    label: string;
+    custom_id?: string;
+    url?: string;
+    emoji?: string;
+    disabled?: boolean;
+}
+export interface ActionRowData {
+    type: "action_row";
+    components: ButtonData[];
+}
+export declare class ButtonBuilder {
+    data: Partial<ButtonData>;
+    setLabel(label: string): this;
+    setStyle(style: ButtonStyle): this;
+    /** A custom id you'll match in the interactionCreate handler (non-link buttons). */
+    setCustomId(id: string): this;
+    /** A link button — opens the URL, fires no interaction. */
+    setUrl(url: string): this;
+    setEmoji(emoji: string): this;
+    setDisabled(disabled?: boolean): this;
+    toJSON(): ButtonData;
+}
+export declare class ActionRowBuilder {
+    data: ActionRowData;
+    /** Add up to 5 buttons to this row. */
+    addComponents(...buttons: (ButtonBuilder | ButtonData)[]): this;
+    toJSON(): ActionRowData;
+}
+export type ComponentResolvable = ActionRowBuilder | ActionRowData;
+export declare function resolveComponent(c: ComponentResolvable): ActionRowData;

package/dist/components.js

@@ -0,0 +1,29 @@
+// Interactive message components — action rows of buttons. Built objects go in
+// a message's payload.components; the District app renders them, and a click on
+// a non-link button fires an `interactionCreate` (type "component") back to the
+// bot with the button's customId.
+export class ButtonBuilder {
+    data = { type: "button", style: "secondary" };
+    setLabel(label) { this.data.label = label; return this; }
+    setStyle(style) { this.data.style = style; return this; }
+    /** A custom id you'll match in the interactionCreate handler (non-link buttons). */
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    /** A link button — opens the URL, fires no interaction. */
+    setUrl(url) { this.data.url = url; this.data.style = "link"; return this; }
+    setEmoji(emoji) { this.data.emoji = emoji; return this; }
+    setDisabled(disabled = true) { this.data.disabled = disabled; return this; }
+    toJSON() { return this.data; }
+}
+export class ActionRowBuilder {
+    data = { type: "action_row", components: [] };
+    /** Add up to 5 buttons to this row. */
+    addComponents(...buttons) {
+        for (const b of buttons)
+            this.data.components.push(b instanceof ButtonBuilder ? b.toJSON() : b);
+        return this;
+    }
+    toJSON() { return this.data; }
+}
+export function resolveComponent(c) {
+    return c instanceof ActionRowBuilder ? c.toJSON() : c;
+}

package/dist/embed.d.ts

@@ -0,0 +1,55 @@
+export interface EmbedField {
+    name: string;
+    value: string;
+    inline?: boolean;
+}
+export interface EmbedData {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: string;
+    author?: {
+        name: string;
+        iconUrl?: string;
+        url?: string;
+    };
+    fields?: EmbedField[];
+    image?: {
+        url: string;
+    };
+    thumbnail?: {
+        url: string;
+    };
+    footer?: {
+        text: string;
+        iconUrl?: string;
+    };
+    timestamp?: string;
+}
+export declare class EmbedBuilder {
+    data: EmbedData;
+    constructor(data?: EmbedData);
+    setTitle(title: string): this;
+    setDescription(description: string): this;
+    setUrl(url: string): this;
+    setColor(color: string | number): this;
+    setAuthor(author: {
+        name: string;
+        iconUrl?: string;
+        url?: string;
+    }): this;
+    setImage(url: string): this;
+    setThumbnail(url: string): this;
+    setFooter(footer: {
+        text: string;
+        iconUrl?: string;
+    }): this;
+    setTimestamp(ts?: Date | string | number): this;
+    /** Add one or more fields. */
+    addFields(...fields: EmbedField[]): this;
+    /** The plain object to send (also used implicitly by JSON.stringify). */
+    toJSON(): EmbedData;
+}
+/** Accept either a builder or a plain embed object wherever embeds are taken. */
+export type EmbedResolvable = EmbedBuilder | EmbedData;
+export declare function resolveEmbed(e: EmbedResolvable): EmbedData;

package/dist/embed.js

@@ -0,0 +1,37 @@
+// A rich embed builder (discord.js-style). The built object is sent in a
+// message's payload.embeds and rendered by the District app as an embed card.
+function toHex(color) {
+    if (typeof color === "number")
+        return "#" + color.toString(16).padStart(6, "0");
+    return color.startsWith("#") ? color : "#" + color;
+}
+export class EmbedBuilder {
+    data;
+    constructor(data = {}) {
+        this.data = { ...data };
+    }
+    setTitle(title) { this.data.title = title; return this; }
+    setDescription(description) { this.data.description = description; return this; }
+    setUrl(url) { this.data.url = url; return this; }
+    setColor(color) { this.data.color = toHex(color); return this; }
+    setAuthor(author) { this.data.author = author; return this; }
+    setImage(url) { this.data.image = { url }; return this; }
+    setThumbnail(url) { this.data.thumbnail = { url }; return this; }
+    setFooter(footer) { this.data.footer = footer; return this; }
+    setTimestamp(ts = new Date()) {
+        this.data.timestamp = ts instanceof Date ? ts.toISOString() : new Date(ts).toISOString();
+        return this;
+    }
+    /** Add one or more fields. */
+    addFields(...fields) {
+        this.data.fields = [...(this.data.fields ?? []), ...fields];
+        return this;
+    }
+    /** The plain object to send (also used implicitly by JSON.stringify). */
+    toJSON() {
+        return this.data;
+    }
+}
+export function resolveEmbed(e) {
+    return e instanceof EmbedBuilder ? e.toJSON() : e;
+}

package/dist/enums.d.ts

@@ -0,0 +1,15 @@
+export declare const ChannelType: {
+    readonly Text: "text";
+    readonly Voice: "voice";
+    readonly Stage: "stage";
+    readonly Event: "event";
+    readonly Lobby: "lobby";
+    readonly Announcement: "announcement";
+    readonly Rules: "rules";
+    readonly Calendar: "calendar";
+    readonly Media: "media";
+    readonly DM: "dm";
+    readonly Overview: "overview";
+    readonly AuditLog: "audit-log";
+};
+export type ChannelTypeValue = (typeof ChannelType)[keyof typeof ChannelType];

package/dist/enums.js

@@ -0,0 +1,15 @@
+// District channel kinds (mirrors the channels.kind check constraint).
+export const ChannelType = {
+    Text: "text",
+    Voice: "voice",
+    Stage: "stage",
+    Event: "event",
+    Lobby: "lobby",
+    Announcement: "announcement",
+    Rules: "rules",
+    Calendar: "calendar",
+    Media: "media",
+    DM: "dm",
+    Overview: "overview",
+    AuditLog: "audit-log",
+};

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export { Client, type ClientEvents } from "./client.js";
 export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
-export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, type ClientContext, } from "./structures.js";
+export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, type ClientContext, type MessageContent, } from "./structures.js";
+export { EmbedBuilder, resolveEmbed, type EmbedData, type EmbedField, type EmbedResolvable } from "./embed.js";
+export { ButtonBuilder, ActionRowBuilder, resolveComponent, type ButtonStyle, type ButtonData, type ActionRowData, type ComponentResolvable, } from "./components.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField, type PermissionResolvable, type PermissionFlagName } from "./permissions.js";
 export { Formatters } from "./formatters.js";
+export { ChannelType, type ChannelTypeValue } from "./enums.js";
 export { verifySignature, parseEvent, verifyAndParse, type EventHeaders } from "./webhook.js";
-export type { ClientOptions, RawMessage, RawSelfUser, RawUser, RawSpace, RawChannel, RawRole, RawMember, DistrictEvent, ReactionEvent, DeletedMessage, } from "./types.js";
+export type { ClientOptions, RawMessage, RawSelfUser, RawUser, RawSpace, RawChannel, RawRole, RawMember, RawAttachment, RawBan, RawInvite, RawWebhook, DistrictEvent, ReactionEvent, DeletedMessage, } from "./types.js";

package/dist/index.js

@@ -6,8 +6,11 @@
 //   client.listen(3000);
 export { Client } from "./client.js";
 export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
-export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, } from "./structures.js";
+export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, } from "./structures.js";
+export { EmbedBuilder, resolveEmbed } from "./embed.js";
+export { ButtonBuilder, ActionRowBuilder, resolveComponent, } from "./components.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField } from "./permissions.js";
 export { Formatters } from "./formatters.js";
+export { ChannelType } from "./enums.js";
 export { verifySignature, parseEvent, verifyAndParse } from "./webhook.js";

package/dist/structures.d.ts

@@ -1,7 +1,15 @@
 import type { REST } from "./rest.js";
-import type { RawMessage, RawSelfUser, RawUser, RawSpace, RawChannel, RawRole, RawMember } from "./types.js";
+import type { RawMessage, RawSelfUser, RawUser, RawSpace, RawChannel, RawRole, RawMember, RawAttachment, RawBan, RawInvite, RawWebhook } from "./types.js";
 import { Collection } from "./collection.js";
 import { PermissionsBitField } from "./permissions.js";
+import { type EmbedResolvable } from "./embed.js";
+import { type ComponentResolvable } from "./components.js";
+/** What you can pass to send/reply: a string, or content + embeds + components. */
+export type MessageContent = string | {
+    content?: string;
+    embeds?: EmbedResolvable[];
+    components?: ComponentResolvable[];
+};
 /** Minimal client surface the structures need (avoids a circular import). */
 export interface ClientContext {
     rest: REST;
@@ -25,11 +33,13 @@ export declare class Message {
     createdAt: string | null;
     editedAt: string | null;
     parentId: string | null;
+    /** Media/files on the message (populated from fetchMessages / fetchAttachments). */
+    attachments: Attachment[];
     constructor(client: ClientContext, raw: RawMessage);
     /** True if this message was sent by the current bot. */
     get authoredByMe(): boolean;
-    /** Reply to this message (threads it via replyTo). */
-    reply(content: string): Promise<Message>;
+    /** Reply to this message (threads it via replyTo). Accepts text or { content, embeds }. */
+    reply(content: MessageContent): Promise<Message>;
     /** Edit this message (only the bot's own messages). */
     edit(content: string): Promise<this>;
     /** Delete this message. */
@@ -42,6 +52,8 @@ export declare class Message {
     fetchAuthor(): Promise<User>;
     /** A handle to the channel this message is in. */
     get channel(): TextChannel;
+    /** Fetch this message's attachments (useful for messages from events). */
+    fetchAttachments(): Promise<Attachment[]>;
 }
 export declare class TextChannel {
     private client;
@@ -57,10 +69,16 @@ export declare class TextChannel {
     fetch(): Promise<this>;
     /** @internal populate info fields from a raw channel row. */
     applyInfo(raw: RawChannel): this;
-    /** Send a message to this channel. */
-    send(content: string): Promise<Message>;
+    /** Send a message to this channel. Accepts text or { content, embeds }. */
+    send(content: MessageContent): Promise<Message>;
     /** Fetch recent messages (oldest → newest), up to 100. */
     fetchMessages(limit?: number): Promise<Collection<string, Message>>;
+    /** The channel's webhooks. */
+    webhooks(): Promise<Collection<string, Webhook>>;
+    /** Create a webhook. The returned Webhook has a one-time url + token you can send() with. */
+    createWebhook(name: string, options?: {
+        avatarUrl?: string;
+    }): Promise<Webhook>;
 }
 /** A District user's public profile. */
 export declare class User {
@@ -94,6 +112,76 @@ export declare class Space {
     roles(): Promise<Collection<string, Role>>;
     /** The space owner's profile. */
     fetchOwner(): Promise<User>;
+    /** Banned users. */
+    bans(): Promise<Collection<string, Ban>>;
+    /** Ban a user (needs the Ban Members permission). Removes their membership. */
+    ban(userId: string, options?: {
+        reason?: string;
+        until?: string | Date;
+    }): Promise<void>;
+    /** Lift a user's ban. */
+    unban(userId: string): Promise<void>;
+    /** Active invites. */
+    invites(): Promise<Collection<string, Invite>>;
+    /** Create an invite (needs Create Invites). `expiresIn` is seconds. */
+    createInvite(options?: {
+        maxUses?: number;
+        expiresIn?: number;
+    }): Promise<Invite>;
+}
+/** A file or media on a message. */
+export declare class Attachment {
+    id: string;
+    kind: string;
+    url: string;
+    thumbUrl: string | null;
+    filename: string | null;
+    mimeType: string | null;
+    size: number | null;
+    width: number | null;
+    height: number | null;
+    spoiler: boolean;
+    constructor(raw: RawAttachment);
+    get isImage(): boolean;
+    get isVideo(): boolean;
+}
+/** A space ban. */
+export declare class Ban {
+    userId: string;
+    reason: string | null;
+    until: string | null;
+    by: string;
+    constructor(raw: RawBan);
+    /** True if the ban is permanent (no expiry). */
+    get permanent(): boolean;
+}
+/** A space invite. */
+export declare class Invite {
+    id: string;
+    code: string;
+    url: string;
+    maxUses: number | null;
+    useCount: number;
+    expiresAt: string | null;
+    constructor(raw: RawInvite);
+}
+/** A channel webhook. `url`/`token` are only present on the one you just created. */
+export declare class Webhook {
+    private client;
+    id: string;
+    name: string;
+    channelId: string;
+    avatarUrl: string | null;
+    url: string | null;
+    token: string | null;
+    constructor(client: ClientContext, raw: RawWebhook);
+    /** Post via this webhook. Only works on a webhook you just created (has a url). */
+    send(content: string, options?: {
+        username?: string;
+        avatarUrl?: string;
+    }): Promise<void>;
+    /** Delete this webhook. */
+    delete(): Promise<void>;
 }
 /** A user's membership in a space. */
 export declare class SpaceMember {
@@ -117,20 +205,33 @@ export declare class Role {
 }
 export declare class Interaction {
     private client;
+    /** "command" (slash command) or "component" (button click). */
+    type: "command" | "component";
     commandName: string;
     commandId: string;
+    /** The clicked button's customId (component interactions). */
+    customId: string;
+    /** The message the component is on (component interactions). */
+    messageId: string | null;
     spaceId: string;
     channelId: string;
     userId: string;
     args: Record<string, unknown>;
     constructor(client: ClientContext, raw: {
-        command: string;
-        command_id: string;
+        type?: string;
+        command?: string;
+        command_id?: string;
+        custom_id?: string;
+        message_id?: string;
         space_id: string;
         channel_id: string;
         user_id: string;
-        args: Record<string, unknown>;
+        args?: Record<string, unknown>;
     });
+    /** True if this is a button click. */
+    isButton(): boolean;
+    /** True if this is a slash command. */
+    isCommand(): boolean;
     /** Respond to the command by posting a message in its channel. */
-    reply(content: string): Promise<Message>;
+    reply(content: MessageContent): Promise<Message>;
 }

package/dist/structures.js

@@ -2,6 +2,17 @@
 // act on it directly: message.reply(), channel.send(), interaction.reply().
 import { Collection } from "./collection.js";
 import { PermissionsBitField } from "./permissions.js";
+import { resolveEmbed } from "./embed.js";
+import { resolveComponent } from "./components.js";
+function toPayload(input) {
+    if (typeof input === "string")
+        return { content: input };
+    return {
+        content: input.content,
+        embeds: input.embeds?.map(resolveEmbed),
+        components: input.components?.map(resolveComponent),
+    };
+}
 export class ClientUser {
     id;
     handle;
@@ -25,6 +36,8 @@ export class Message {
     createdAt;
     editedAt;
     parentId;
+    /** Media/files on the message (populated from fetchMessages / fetchAttachments). */
+    attachments;
     constructor(client, raw) {
         this.client = client;
         this.id = raw.id;
@@ -34,13 +47,15 @@ export class Message {
         this.createdAt = raw.created_at ?? null;
         this.editedAt = raw.edited_at ?? null;
         this.parentId = raw.parent_id ?? null;
+        this.attachments = (raw.attachments ?? []).map((a) => new Attachment(a));
     }
     /** True if this message was sent by the current bot. */
     get authoredByMe() { return !!this.client.user && this.authorId === this.client.user.id; }
-    /** Reply to this message (threads it via replyTo). */
+    /** Reply to this message (threads it via replyTo). Accepts text or { content, embeds }. */
     async reply(content) {
-        const { message } = await this.client.rest.post(`/channels/${this.channelId}/messages`, { content, replyTo: this.id });
-        return new Message(this.client, { ...message, content, author_id: this.client.user?.id ?? "" });
+        const p = toPayload(content);
+        const { message } = await this.client.rest.post(`/channels/${this.channelId}/messages`, { ...p, replyTo: this.id });
+        return new Message(this.client, { ...message, content: p.content ?? "", author_id: this.client.user?.id ?? "" });
     }
     /** Edit this message (only the bot's own messages). */
     async edit(content) {
@@ -69,6 +84,11 @@ export class Message {
     get channel() {
         return new TextChannel(this.client, this.channelId);
     }
+    /** Fetch this message's attachments (useful for messages from events). */
+    async fetchAttachments() {
+        const { attachments } = await this.client.rest.get(`/channels/${this.channelId}/messages/${this.id}/attachments`);
+        return (attachments ?? []).map((a) => new Attachment(a));
+    }
 }
 export class TextChannel {
     client;
@@ -97,10 +117,11 @@ export class TextChannel {
         this.position = raw.position ?? null;
         return this;
     }
-    /** Send a message to this channel. */
+    /** Send a message to this channel. Accepts text or { content, embeds }. */
     async send(content) {
-        const { message } = await this.client.rest.post(`/channels/${this.id}/messages`, { content });
-        return new Message(this.client, { ...message, content, author_id: this.client.user?.id ?? "" });
+        const p = toPayload(content);
+        const { message } = await this.client.rest.post(`/channels/${this.id}/messages`, p);
+        return new Message(this.client, { ...message, content: p.content ?? "", author_id: this.client.user?.id ?? "" });
     }
     /** Fetch recent messages (oldest → newest), up to 100. */
     async fetchMessages(limit = 50) {
@@ -110,6 +131,19 @@ export class TextChannel {
             out.set(m.id, new Message(this.client, m));
         return out;
     }
+    /** The channel's webhooks. */
+    async webhooks() {
+        const { webhooks } = await this.client.rest.get(`/channels/${this.id}/webhooks`);
+        const out = new Collection();
+        for (const w of (webhooks ?? []))
+            out.set(w.id, new Webhook(this.client, w));
+        return out;
+    }
+    /** Create a webhook. The returned Webhook has a one-time url + token you can send() with. */
+    async createWebhook(name, options) {
+        const { webhook } = await this.client.rest.post(`/channels/${this.id}/webhooks`, { name, avatarUrl: options?.avatarUrl });
+        return new Webhook(this.client, webhook);
+    }
 }
 /** A District user's public profile. */
 export class User {
@@ -182,6 +216,128 @@ export class Space {
         const { user } = await this.client.rest.get(`/users/${this.ownerId}`);
         return new User(user);
     }
+    /** Banned users. */
+    async bans() {
+        const { bans } = await this.client.rest.get(`/spaces/${this.id}/bans`);
+        const out = new Collection();
+        for (const b of (bans ?? []))
+            out.set(b.user_id, new Ban(b));
+        return out;
+    }
+    /** Ban a user (needs the Ban Members permission). Removes their membership. */
+    async ban(userId, options) {
+        const until = options?.until ? new Date(options.until).toISOString() : undefined;
+        await this.client.rest.put(`/spaces/${this.id}/bans/${userId}`, { reason: options?.reason, until });
+    }
+    /** Lift a user's ban. */
+    async unban(userId) {
+        await this.client.rest.delete(`/spaces/${this.id}/bans/${userId}`);
+    }
+    /** Active invites. */
+    async invites() {
+        const { invites } = await this.client.rest.get(`/spaces/${this.id}/invites`);
+        const out = new Collection();
+        for (const i of (invites ?? []))
+            out.set(i.code, new Invite(i));
+        return out;
+    }
+    /** Create an invite (needs Create Invites). `expiresIn` is seconds. */
+    async createInvite(options) {
+        const { invite } = await this.client.rest.post(`/spaces/${this.id}/invites`, { maxUses: options?.maxUses, expiresIn: options?.expiresIn });
+        return new Invite(invite);
+    }
+}
+/** A file or media on a message. */
+export class Attachment {
+    id;
+    kind;
+    url;
+    thumbUrl;
+    filename;
+    mimeType;
+    size;
+    width;
+    height;
+    spoiler;
+    constructor(raw) {
+        this.id = raw.id;
+        this.kind = raw.kind;
+        this.url = raw.url;
+        this.thumbUrl = raw.thumb_url ?? null;
+        this.filename = raw.filename ?? null;
+        this.mimeType = raw.mime_type ?? null;
+        this.size = raw.size_bytes ?? null;
+        this.width = raw.width ?? null;
+        this.height = raw.height ?? null;
+        this.spoiler = raw.spoiler ?? false;
+    }
+    get isImage() { return this.kind === "image" || this.kind === "gifv"; }
+    get isVideo() { return this.kind === "video"; }
+}
+/** A space ban. */
+export class Ban {
+    userId;
+    reason;
+    until;
+    by;
+    constructor(raw) {
+        this.userId = raw.user_id;
+        this.reason = raw.reason;
+        this.until = raw.until;
+        this.by = raw.by;
+    }
+    /** True if the ban is permanent (no expiry). */
+    get permanent() { return this.until === null; }
+}
+/** A space invite. */
+export class Invite {
+    id;
+    code;
+    url;
+    maxUses;
+    useCount;
+    expiresAt;
+    constructor(raw) {
+        this.id = raw.id;
+        this.code = raw.code;
+        this.url = raw.url ?? `https://usedistrict.org/i/${raw.code}`;
+        this.maxUses = raw.max_uses;
+        this.useCount = raw.use_count ?? 0;
+        this.expiresAt = raw.expires_at;
+    }
+}
+/** A channel webhook. `url`/`token` are only present on the one you just created. */
+export class Webhook {
+    client;
+    id;
+    name;
+    channelId;
+    avatarUrl;
+    url;
+    token;
+    constructor(client, raw) {
+        this.client = client;
+        this.id = raw.id;
+        this.name = raw.name;
+        this.channelId = raw.channel_id;
+        this.avatarUrl = raw.avatar_url ?? null;
+        this.url = raw.url ?? null;
+        this.token = raw.token ?? null;
+    }
+    /** Post via this webhook. Only works on a webhook you just created (has a url). */
+    async send(content, options) {
+        if (!this.url)
+            throw new Error("This webhook has no url/token — those are only returned when it's first created.");
+        await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ content, username: options?.username, avatar_url: options?.avatarUrl }),
+        });
+    }
+    /** Delete this webhook. */
+    async delete() {
+        await this.client.rest.delete(`/channels/${this.channelId}/webhooks/${this.id}`);
+    }
 }
 /** A user's membership in a space. */
 export class SpaceMember {
@@ -220,24 +376,38 @@ export class Role {
 }
 export class Interaction {
     client;
+    /** "command" (slash command) or "component" (button click). */
+    type;
     commandName;
     commandId;
+    /** The clicked button's customId (component interactions). */
+    customId;
+    /** The message the component is on (component interactions). */
+    messageId;
     spaceId;
     channelId;
     userId;
     args;
     constructor(client, raw) {
         this.client = client;
-        this.commandName = raw.command;
-        this.commandId = raw.command_id;
+        this.type = raw.type === "component" ? "component" : "command";
+        this.commandName = raw.command ?? "";
+        this.commandId = raw.command_id ?? "";
+        this.customId = raw.custom_id ?? "";
+        this.messageId = raw.message_id ?? null;
         this.spaceId = raw.space_id;
         this.channelId = raw.channel_id;
         this.userId = raw.user_id;
         this.args = raw.args ?? {};
     }
+    /** True if this is a button click. */
+    isButton() { return this.type === "component"; }
+    /** True if this is a slash command. */
+    isCommand() { return this.type === "command"; }
     /** Respond to the command by posting a message in its channel. */
     async reply(content) {
-        const { message } = await this.client.rest.post(`/channels/${this.channelId}/messages`, { content });
-        return new Message(this.client, { ...message, content, author_id: this.client.user?.id ?? "" });
+        const p = toPayload(content);
+        const { message } = await this.client.rest.post(`/channels/${this.channelId}/messages`, p);
+        return new Message(this.client, { ...message, content: p.content ?? "", author_id: this.client.user?.id ?? "" });
     }
 }

package/dist/types.d.ts

@@ -19,6 +19,47 @@ export interface RawMessage {
     created_at?: string;
     edited_at?: string | null;
     parent_id?: string | null;
+    attachments?: RawAttachment[];
+}
+/** A message attachment (image/video/file/…). */
+export interface RawAttachment {
+    id: string;
+    kind: string;
+    url: string;
+    thumb_url?: string | null;
+    filename?: string | null;
+    mime_type?: string | null;
+    size_bytes?: number | null;
+    width?: number | null;
+    height?: number | null;
+    spoiler?: boolean;
+}
+/** A space ban (`GET /spaces/:id/bans`). */
+export interface RawBan {
+    user_id: string;
+    reason: string | null;
+    until: string | null;
+    by: string;
+    created_at?: string;
+}
+/** A space invite (`GET/POST /spaces/:id/invites`). */
+export interface RawInvite {
+    id: string;
+    code: string;
+    url?: string;
+    max_uses: number | null;
+    use_count?: number;
+    expires_at: string | null;
+    revoked_at?: string | null;
+}
+/** A channel webhook (`GET/POST /channels/:id/webhooks`). */
+export interface RawWebhook {
+    id: string;
+    name: string;
+    channel_id: string;
+    avatar_url?: string | null;
+    token?: string;
+    url?: string;
 }
 /** The bot's own identity (`GET /me`). */
 export interface RawSelfUser {
@@ -105,12 +146,15 @@ export type DistrictEvent = {
     emoji: string;
 } | {
     event: "interaction.create";
-    command: string;
-    command_id: string;
+    type?: "command" | "component";
+    command?: string;
+    command_id?: string;
+    custom_id?: string;
+    message_id?: string;
     space_id: string;
     channel_id: string;
     user_id: string;
-    args: Record<string, unknown>;
+    args?: Record<string, unknown>;
 };
 export interface ReactionEvent {
     spaceId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "district.js",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "A powerful Node.js module for building District bots — post, react, run slash commands, and receive events.",
   "type": "module",
   "main": "./dist/index.js",