district.js 0.3.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/index.d.ts

@@ -1,6 +1,8 @@
 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, Attachment, Ban, Invite, Webhook, 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";

package/dist/index.js

@@ -7,6 +7,8 @@
 export { Client } from "./client.js";
 export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.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";

package/dist/structures.d.ts

@@ -2,6 +2,14 @@ import type { REST } from "./rest.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;
@@ -30,8 +38,8 @@ export declare class Message {
     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. */
@@ -61,8 +69,8 @@ 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. */
@@ -197,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;
@@ -40,10 +51,11 @@ export class Message {
     }
     /** 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) {
@@ -105,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) {
@@ -363,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

@@ -146,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.3.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",