district.js 0.5.0 → 0.7.0

package/README.md

@@ -110,6 +110,34 @@ client.on("interactionCreate", (i) => {
 });
 ```
 
+## Select menus & modals
+
+```js
+import { ActionRowBuilder, StringSelectMenuBuilder, ButtonBuilder, ModalBuilder, TextInputBuilder } from "district.js";
+
+// Dropdown
+const menu = new ActionRowBuilder().addComponents(
+  new StringSelectMenuBuilder().setCustomId("role").setPlaceholder("Pick a role")
+    .addOptions({ label: "Dev", value: "dev" }, { label: "Design", value: "design" }),
+);
+await channel.send({ content: "Choose:", components: [menu] });
+
+// Modal (opens instantly on click; only the submit is delivered to the bot)
+const modal = new ModalBuilder().setCustomId("feedback").setTitle("Feedback")
+  .addComponents(new TextInputBuilder().setCustomId("msg").setLabel("Your message").setStyle("paragraph"));
+const row = new ActionRowBuilder().addComponents(
+  new ButtonBuilder().setLabel("Give feedback").setStyle("primary").setModal(modal),
+);
+await channel.send({ components: [row] });
+
+client.on("interactionCreate", (i) => {
+  if (i.isSelectMenu() && i.customId === "role") i.reply(`You picked ${i.values[0]}`);
+  if (i.isModalSubmit() && i.customId === "feedback") i.reply(`Thanks: ${i.field("msg")}`);
+});
+```
+
+> Because District delivers interactions asynchronously, modals are attached to a button and shown **instantly, client-side**; only the submitted values are sent back to your bot.
+
 ## Slash commands
 
 Register the command in the portal (name + handler URL), then:

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
+import { Store } from "./store.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";
@@ -17,6 +18,8 @@ export interface ClientEvents {
 }
 export declare class Client extends EventEmitter implements ClientContext {
     readonly rest: REST;
+    /** The bot's persistent document store (`client.store.collection("users")…`). */
+    readonly store: Store;
     /** The bot's own identity — populated after `login()`. */
     user: ClientUser | null;
     private signingSecret?;

package/dist/client.js

@@ -3,10 +3,13 @@
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
+import { Store } from "./store.js";
 import { ClientUser, Message, TextChannel, Interaction, User, Space } from "./structures.js";
 import { verifyAndParse } from "./webhook.js";
 export class Client extends EventEmitter {
     rest;
+    /** The bot's persistent document store (`client.store.collection("users")…`). */
+    store;
     /** The bot's own identity — populated after `login()`. */
     user = null;
     signingSecret;
@@ -15,6 +18,7 @@ export class Client extends EventEmitter {
         if (!options?.token)
             throw new Error("district.js: `token` is required");
         this.rest = new REST(options.token, options.apiBase);
+        this.store = new Store(this.rest);
         this.signingSecret = options.signingSecret;
     }
     // ── typed emitter surface ──────────────────────────────────────────────────

package/dist/components.d.ts

@@ -1,4 +1,17 @@
 export type ButtonStyle = "primary" | "secondary" | "success" | "danger" | "link";
+export interface TextInputData {
+    custom_id: string;
+    label: string;
+    style: "short" | "paragraph";
+    placeholder?: string;
+    required?: boolean;
+    max_length?: number;
+}
+export interface ModalData {
+    custom_id: string;
+    title: string;
+    fields: TextInputData[];
+}
 export interface ButtonData {
     type: "button";
     style: ButtonStyle;
@@ -7,10 +20,27 @@ export interface ButtonData {
     url?: string;
     emoji?: string;
     disabled?: boolean;
+    /** A modal shown (instantly, client-side) when the button is clicked. */
+    modal?: ModalData;
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+    description?: string;
+}
+export interface SelectData {
+    type: "select";
+    custom_id: string;
+    options: SelectOption[];
+    placeholder?: string;
+    min_values?: number;
+    max_values?: number;
+    disabled?: boolean;
 }
+export type ComponentData = ButtonData | SelectData;
 export interface ActionRowData {
     type: "action_row";
-    components: ButtonData[];
+    components: ComponentData[];
 }
 export declare class ButtonBuilder {
     data: Partial<ButtonData>;
@@ -22,12 +52,43 @@ export declare class ButtonBuilder {
     setUrl(url: string): this;
     setEmoji(emoji: string): this;
     setDisabled(disabled?: boolean): this;
+    /** Attach a modal — clicking the button opens it instantly; submit fires a
+     *  modal_submit interaction with the field values. */
+    setModal(modal: ModalBuilder | ModalData): this;
     toJSON(): ButtonData;
 }
+export declare class StringSelectMenuBuilder {
+    data: SelectData;
+    setCustomId(id: string): this;
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+    setDisabled(disabled?: boolean): this;
+    addOptions(...options: SelectOption[]): this;
+    toJSON(): SelectData;
+}
+export declare class TextInputBuilder {
+    data: Partial<TextInputData>;
+    setCustomId(id: string): this;
+    setLabel(label: string): this;
+    setStyle(style: "short" | "paragraph"): this;
+    setPlaceholder(text: string): this;
+    setRequired(required?: boolean): this;
+    setMaxLength(n: number): this;
+    toJSON(): TextInputData;
+}
+export declare class ModalBuilder {
+    data: ModalData;
+    setCustomId(id: string): this;
+    setTitle(title: string): this;
+    /** Add text inputs to the modal (up to 5). */
+    addComponents(...inputs: (TextInputBuilder | TextInputData)[]): this;
+    toJSON(): ModalData;
+}
 export declare class ActionRowBuilder {
     data: ActionRowData;
-    /** Add up to 5 buttons to this row. */
-    addComponents(...buttons: (ButtonBuilder | ButtonData)[]): this;
+    /** Add up to 5 buttons, or a single select menu. */
+    addComponents(...components: (ButtonBuilder | StringSelectMenuBuilder | ComponentData)[]): this;
     toJSON(): ActionRowData;
 }
 export type ComponentResolvable = ActionRowBuilder | ActionRowData;

package/dist/components.js

@@ -12,14 +12,58 @@ export class ButtonBuilder {
     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; }
+    /** Attach a modal — clicking the button opens it instantly; submit fires a
+     *  modal_submit interaction with the field values. */
+    setModal(modal) {
+        this.data.modal = modal instanceof ModalBuilder ? modal.toJSON() : modal;
+        if (!this.data.custom_id)
+            this.data.custom_id = this.data.modal.custom_id;
+        return this;
+    }
+    toJSON() { return this.data; }
+}
+export class StringSelectMenuBuilder {
+    data = { type: "select", custom_id: "", options: [] };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setPlaceholder(text) { this.data.placeholder = text; return this; }
+    setMinValues(n) { this.data.min_values = n; return this; }
+    setMaxValues(n) { this.data.max_values = n; return this; }
+    setDisabled(disabled = true) { this.data.disabled = disabled; return this; }
+    addOptions(...options) {
+        this.data.options.push(...options);
+        return this;
+    }
+    toJSON() { return this.data; }
+}
+export class TextInputBuilder {
+    data = { style: "short", required: true };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setLabel(label) { this.data.label = label; return this; }
+    setStyle(style) { this.data.style = style; return this; }
+    setPlaceholder(text) { this.data.placeholder = text; return this; }
+    setRequired(required = true) { this.data.required = required; return this; }
+    setMaxLength(n) { this.data.max_length = n; return this; }
+    toJSON() { return this.data; }
+}
+export class ModalBuilder {
+    data = { custom_id: "", title: "", fields: [] };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setTitle(title) { this.data.title = title; return this; }
+    /** Add text inputs to the modal (up to 5). */
+    addComponents(...inputs) {
+        for (const i of inputs)
+            this.data.fields.push(i instanceof TextInputBuilder ? i.toJSON() : i);
+        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);
+    /** Add up to 5 buttons, or a single select menu. */
+    addComponents(...components) {
+        for (const c of components) {
+            this.data.components.push(c instanceof ButtonBuilder || c instanceof StringSelectMenuBuilder ? c.toJSON() : c);
+        }
         return this;
     }
     toJSON() { return this.data; }

package/dist/index.d.ts

@@ -2,7 +2,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, 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 { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, type ButtonStyle, type ButtonData, type SelectData, type SelectOption, type ComponentData, type ModalData, type TextInputData, type ActionRowData, type ComponentResolvable, } from "./components.js";
+export { Store, StoreCollection, type StoreDocument } from "./store.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField, type PermissionResolvable, type PermissionFlagName } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/index.js

@@ -8,7 +8,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 { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, } from "./components.js";
+export { Store, StoreCollection } from "./store.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/store.d.ts

@@ -0,0 +1,41 @@
+import { REST } from "./rest.js";
+/** One stored document: its `key` and JSON `value` (+ last-updated time on reads). */
+export interface StoreDocument<T = any> {
+    key: string;
+    value: T;
+    updatedAt?: string;
+}
+/** A handle to one collection of documents (e.g. "users", "guilds"). */
+export declare class StoreCollection {
+    private readonly rest;
+    readonly name: string;
+    constructor(rest: REST, name: string);
+    /** Read one document's value, or `null` if it doesn't exist. */
+    get<T = any>(key: string): Promise<T | null>;
+    /** Create or fully replace a document. Returns the stored value. */
+    set<T = any>(key: string, value: T): Promise<T>;
+    /** Shallow-merge `partial` into an existing document (creates it if absent).
+     *  Returns the merged value. */
+    update<T = any>(key: string, partial: Partial<T>): Promise<T>;
+    /** Delete a document. No-op if it doesn't exist. */
+    delete(key: string): Promise<void>;
+    /** Atomically add `amount` to a numeric field (default field: `value`). Safe
+     *  under concurrency — two simultaneous increments never lose a write. Pass an
+     *  array for a nested path, e.g. `increment(id, ["stats", "wins"], 1)`. Returns
+     *  the whole updated document value. */
+    increment<T = any>(key: string, field?: string | string[], amount?: number): Promise<T>;
+    /** List documents in this collection (newest-updated first by default). */
+    all<T = any>(opts?: {
+        limit?: number;
+        offset?: number;
+        order?: "asc" | "desc";
+    }): Promise<StoreDocument<T>[]>;
+}
+/** The bot's persistent store. Get a collection with `.collection(name)`. */
+export declare class Store {
+    private readonly rest;
+    private readonly cache;
+    constructor(rest: REST);
+    /** A handle to a named collection (memoized). */
+    collection(name: string): StoreCollection;
+}

package/dist/store.js

@@ -0,0 +1,90 @@
+// Persistent bot storage — the district.js equivalent of "bring your own
+// database". Each bot gets an isolated document store, addressed as
+// `collection` → `key` → JSON `value`, so you can model users, balances,
+// transactions, leaderboards, config… anything a data-heavy bot needs.
+//
+//   const users = client.store.collection("users");
+//   await users.set("42", { balance: 100, streak: 0 });
+//   const me = await users.get<{ balance: number }>("42");
+//   await users.increment("42", "balance", 250);   // atomic — safe under load
+//   const leaderboard = await users.all({ limit: 10 });
+//
+// Everything is scoped to your application automatically; a bot can only ever
+// see its own data.
+import { DistrictAPIError } from "./rest.js";
+const enc = encodeURIComponent;
+/** A handle to one collection of documents (e.g. "users", "guilds"). */
+export class StoreCollection {
+    rest;
+    name;
+    constructor(rest, name) {
+        this.rest = rest;
+        this.name = name;
+    }
+    /** Read one document's value, or `null` if it doesn't exist. */
+    async get(key) {
+        try {
+            const r = await this.rest.get(`/storage/${enc(this.name)}/${enc(key)}`);
+            return r.value;
+        }
+        catch (e) {
+            if (e instanceof DistrictAPIError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Create or fully replace a document. Returns the stored value. */
+    async set(key, value) {
+        const r = await this.rest.put(`/storage/${enc(this.name)}/${enc(key)}`, value);
+        return r.value;
+    }
+    /** Shallow-merge `partial` into an existing document (creates it if absent).
+     *  Returns the merged value. */
+    async update(key, partial) {
+        const r = await this.rest.patch(`/storage/${enc(this.name)}/${enc(key)}`, partial);
+        return r.value;
+    }
+    /** Delete a document. No-op if it doesn't exist. */
+    async delete(key) {
+        await this.rest.delete(`/storage/${enc(this.name)}/${enc(key)}`);
+    }
+    /** Atomically add `amount` to a numeric field (default field: `value`). Safe
+     *  under concurrency — two simultaneous increments never lose a write. Pass an
+     *  array for a nested path, e.g. `increment(id, ["stats", "wins"], 1)`. Returns
+     *  the whole updated document value. */
+    async increment(key, field = "value", amount = 1) {
+        const path = Array.isArray(field) ? field : [field];
+        const r = await this.rest.post(`/storage/${enc(this.name)}/${enc(key)}/increment`, { path, amount });
+        return r.value;
+    }
+    /** List documents in this collection (newest-updated first by default). */
+    async all(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        if (opts.offset != null)
+            q.set("offset", String(opts.offset));
+        if (opts.order)
+            q.set("order", opts.order);
+        const qs = q.toString();
+        const r = await this.rest.get(`/storage/${enc(this.name)}${qs ? `?${qs}` : ""}`);
+        return r.items ?? [];
+    }
+}
+/** The bot's persistent store. Get a collection with `.collection(name)`. */
+export class Store {
+    rest;
+    cache = new Map();
+    constructor(rest) {
+        this.rest = rest;
+    }
+    /** A handle to a named collection (memoized). */
+    collection(name) {
+        let c = this.cache.get(name);
+        if (!c) {
+            c = new StoreCollection(this.rest, name);
+            this.cache.set(name, c);
+        }
+        return c;
+    }
+}

package/dist/structures.d.ts

@@ -205,14 +205,18 @@ export declare class Role {
 }
 export declare class Interaction {
     private client;
-    /** "command" (slash command) or "component" (button click). */
-    type: "command" | "component";
+    /** "command" (slash), "component" (button/select), or "modal_submit". */
+    type: "command" | "component" | "modal_submit";
     commandName: string;
     commandId: string;
-    /** The clicked button's customId (component interactions). */
+    /** The component/modal customId that triggered this. */
     customId: string;
-    /** The message the component is on (component interactions). */
+    /** The message the component is on. */
     messageId: string | null;
+    /** Selected values (select-menu interactions). */
+    values: string[];
+    /** Submitted field values keyed by input customId (modal submits). */
+    fields: Record<string, string>;
     spaceId: string;
     channelId: string;
     userId: string;
@@ -227,11 +231,21 @@ export declare class Interaction {
         channel_id: string;
         user_id: string;
         args?: Record<string, unknown>;
+        data?: {
+            values?: string[];
+            fields?: Record<string, string>;
+        };
     });
-    /** True if this is a button click. */
-    isButton(): boolean;
     /** True if this is a slash command. */
     isCommand(): boolean;
+    /** True if this is a button click (component with no selected values). */
+    isButton(): boolean;
+    /** True if this is a select-menu choice. */
+    isSelectMenu(): boolean;
+    /** True if this is a submitted modal. */
+    isModalSubmit(): boolean;
+    /** Get a submitted modal field value by its input customId. */
+    field(customId: string): string | undefined;
     /** Respond to the command by posting a message in its channel. */
     reply(content: MessageContent): Promise<Message>;
 }

package/dist/structures.js

@@ -376,34 +376,46 @@ export class Role {
 }
 export class Interaction {
     client;
-    /** "command" (slash command) or "component" (button click). */
+    /** "command" (slash), "component" (button/select), or "modal_submit". */
     type;
     commandName;
     commandId;
-    /** The clicked button's customId (component interactions). */
+    /** The component/modal customId that triggered this. */
     customId;
-    /** The message the component is on (component interactions). */
+    /** The message the component is on. */
     messageId;
+    /** Selected values (select-menu interactions). */
+    values;
+    /** Submitted field values keyed by input customId (modal submits). */
+    fields;
     spaceId;
     channelId;
     userId;
     args;
     constructor(client, raw) {
         this.client = client;
-        this.type = raw.type === "component" ? "component" : "command";
+        this.type = raw.type === "component" ? "component" : raw.type === "modal_submit" ? "modal_submit" : "command";
         this.commandName = raw.command ?? "";
         this.commandId = raw.command_id ?? "";
         this.customId = raw.custom_id ?? "";
         this.messageId = raw.message_id ?? null;
+        this.values = Array.isArray(raw.data?.values) ? raw.data.values : [];
+        this.fields = raw.data?.fields && typeof raw.data.fields === "object" ? raw.data.fields : {};
         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"; }
+    /** True if this is a button click (component with no selected values). */
+    isButton() { return this.type === "component" && this.values.length === 0; }
+    /** True if this is a select-menu choice. */
+    isSelectMenu() { return this.type === "component" && this.values.length > 0; }
+    /** True if this is a submitted modal. */
+    isModalSubmit() { return this.type === "modal_submit"; }
+    /** Get a submitted modal field value by its input customId. */
+    field(customId) { return this.fields[customId]; }
     /** Respond to the command by posting a message in its channel. */
     async reply(content) {
         const p = toPayload(content);

package/dist/types.d.ts

@@ -146,7 +146,7 @@ export type DistrictEvent = {
     emoji: string;
 } | {
     event: "interaction.create";
-    type?: "command" | "component";
+    type?: "command" | "component" | "modal_submit";
     command?: string;
     command_id?: string;
     custom_id?: string;
@@ -155,6 +155,10 @@ export type DistrictEvent = {
     channel_id: string;
     user_id: string;
     args?: Record<string, unknown>;
+    data?: {
+        values?: string[];
+        fields?: Record<string, string>;
+    };
 };
 export interface ReactionEvent {
     spaceId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "district.js",
-  "version": "0.5.0",
+  "version": "0.7.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",