district.js 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -2,9 +2,11 @@ import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
 import { Store } from "./store.js";
+import { type EmbedResolvable } from "./embed.js";
+import { type CommandResolvable, type CommandData } from "./commands.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";
+import type { ClientOptions, ReactionEvent, DeletedMessage, MemberEvent, ScheduledEvent, ScheduleInput } from "./types.js";
 /** The events a Client emits, and their argument tuples. */
 export interface ClientEvents {
     ready: [user: ClientUser];
@@ -13,6 +15,9 @@ export interface ClientEvents {
     messageDelete: [message: DeletedMessage];
     messageReactionAdd: [reaction: ReactionEvent];
     messageReactionRemove: [reaction: ReactionEvent];
+    memberJoin: [member: MemberEvent];
+    memberLeave: [member: MemberEvent];
+    scheduled: [event: ScheduledEvent];
     interactionCreate: [interaction: Interaction];
     error: [error: Error];
 }
@@ -36,14 +41,53 @@ export declare class Client extends EventEmitter implements ClientContext {
         /** Send a message to a channel (text or { content, embeds }). */
         send: (channelId: string, content: MessageContent) => Promise<Message>;
     };
-    /** Fetch users by id. */
+    /** Fetch users by id, or DM them. */
     readonly users: {
         fetch: (id: string) => Promise<User>;
+        /** Open (or reuse) a 1-on-1 DM with a user and send them a message. */
+        send: (userId: string, content: string | {
+            content?: string;
+            embeds?: EmbedResolvable[];
+        }) => Promise<{
+            channelId: string;
+        }>;
     };
     /** Fetch spaces by id. */
     readonly spaces: {
         fetch: (id: string) => Promise<Space>;
     };
+    /** Register / list / delete this bot's slash commands (they show in the `/`
+     *  picker). `set` replaces the entire command set, discord.js-style. */
+    readonly commands: {
+        /** Replace all of the bot's commands with this set. `handlerUrl` defaults to
+         *  the app's active event-subscription endpoint. */
+        set: (commands: CommandResolvable[], opts?: {
+            handlerUrl?: string;
+        }) => Promise<{
+            ok: boolean;
+            count: number;
+        }>;
+        /** List the bot's currently-registered commands. */
+        list: () => Promise<CommandData[]>;
+        /** Delete one command by name. */
+        delete: (name: string) => Promise<void>;
+    };
+    /** Register / list / delete recurring scheduled jobs. When one is due District
+     *  POSTs a `scheduled` event to the bot — listen with `client.on("scheduled", …)`. */
+    readonly schedules: {
+        /** Replace all schedules with this set (min interval 60s). `handlerUrl`
+         *  defaults to the app's active event-subscription endpoint. */
+        set: (schedules: ScheduleInput[], opts?: {
+            handlerUrl?: string;
+        }) => Promise<{
+            ok: boolean;
+            count: number;
+        }>;
+        /** List the bot's registered schedules (with next/last run times). */
+        list: () => Promise<any[]>;
+        /** Delete one schedule by name. */
+        delete: (name: string) => Promise<void>;
+    };
     /** Validate the token, load the bot's identity, and emit `ready`. */
     login(): Promise<ClientUser>;
     /**

package/dist/client.js

@@ -4,6 +4,8 @@ import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
 import { Store } from "./store.js";
+import { resolveEmbed } from "./embed.js";
+import { resolveCommand } from "./commands.js";
 import { ClientUser, Message, TextChannel, Interaction, User, Space } from "./structures.js";
 import { verifyAndParse } from "./webhook.js";
 export class Client extends EventEmitter {
@@ -45,14 +47,43 @@ export class Client extends EventEmitter {
         /** Send a message to a channel (text or { content, embeds }). */
         send: (channelId, content) => new TextChannel(this, channelId).send(content),
     };
-    /** Fetch users by id. */
+    /** Fetch users by id, or DM them. */
     users = {
         fetch: (id) => this.rest.get(`/users/${id}`).then((r) => new User(r.user)),
+        /** Open (or reuse) a 1-on-1 DM with a user and send them a message. */
+        send: (userId, content) => {
+            const body = typeof content === "string"
+                ? { content }
+                : { content: content.content, embeds: content.embeds?.map(resolveEmbed) };
+            return this.rest.post(`/users/${userId}/dm`, body);
+        },
     };
     /** Fetch spaces by id. */
     spaces = {
         fetch: (id) => this.rest.get(`/spaces/${id}`).then((r) => new Space(this, r.space)),
     };
+    /** Register / list / delete this bot's slash commands (they show in the `/`
+     *  picker). `set` replaces the entire command set, discord.js-style. */
+    commands = {
+        /** Replace all of the bot's commands with this set. `handlerUrl` defaults to
+         *  the app's active event-subscription endpoint. */
+        set: (commands, opts = {}) => this.rest.put("/commands", { commands: commands.map(resolveCommand), ...(opts.handlerUrl ? { handlerUrl: opts.handlerUrl } : {}) }),
+        /** List the bot's currently-registered commands. */
+        list: () => this.rest.get("/commands").then((r) => r.commands),
+        /** Delete one command by name. */
+        delete: (name) => this.rest.delete(`/commands/${encodeURIComponent(name)}`).then(() => undefined),
+    };
+    /** Register / list / delete recurring scheduled jobs. When one is due District
+     *  POSTs a `scheduled` event to the bot — listen with `client.on("scheduled", …)`. */
+    schedules = {
+        /** Replace all schedules with this set (min interval 60s). `handlerUrl`
+         *  defaults to the app's active event-subscription endpoint. */
+        set: (schedules, opts = {}) => this.rest.put("/schedules", { schedules, ...(opts.handlerUrl ? { handlerUrl: opts.handlerUrl } : {}) }),
+        /** List the bot's registered schedules (with next/last run times). */
+        list: () => this.rest.get("/schedules").then((r) => r.schedules),
+        /** Delete one schedule by name. */
+        delete: (name) => this.rest.delete(`/schedules/${encodeURIComponent(name)}`).then(() => undefined),
+    };
     /** Validate the token, load the bot's identity, and emit `ready`. */
     async login() {
         const res = await this.rest.get("/me");
@@ -142,6 +173,15 @@ export class Client extends EventEmitter {
             case "message.reaction_remove":
                 this.emit("messageReactionRemove", toReaction(evt));
                 break;
+            case "member.join":
+                this.emit("memberJoin", { spaceId: evt.space_id, userId: evt.member.user_id, joinedAt: evt.member.joined_at ?? null });
+                break;
+            case "member.leave":
+                this.emit("memberLeave", { spaceId: evt.space_id, userId: evt.member.user_id, joinedAt: evt.member.joined_at ?? null });
+                break;
+            case "scheduled":
+                this.emit("scheduled", { schedule: evt.schedule, data: evt.data ?? {} });
+                break;
             case "interaction.create":
                 this.emit("interactionCreate", new Interaction(this, evt));
                 break;

package/dist/commands.d.ts

@@ -0,0 +1,73 @@
+/** Option value types a command argument can declare. */
+export type CommandOptionType = "string" | "integer" | "number" | "boolean" | "user" | "channel" | "role" | "subcommand";
+/** A fixed choice for an option (what the picker offers). */
+export interface CommandOptionChoice {
+    name: string;
+    value: string | number;
+}
+/** One declared command argument (or a subcommand, when `type` is "subcommand"). */
+export interface CommandOption {
+    type: CommandOptionType;
+    name: string;
+    description: string;
+    required?: boolean;
+    choices?: CommandOptionChoice[];
+    /** Numeric bounds (integer/number options). */
+    minValue?: number;
+    maxValue?: number;
+    /** Nested options — present when `type` is "subcommand". */
+    options?: CommandOption[];
+}
+/** The serialized command payload sent to the API. */
+export interface CommandData {
+    name: string;
+    description: string;
+    options?: CommandOption[];
+    /** Permission bits required to invoke (0 = anyone). */
+    defaultPerms?: number;
+}
+type AddOpts = {
+    required?: boolean;
+    choices?: CommandOptionChoice[];
+    minValue?: number;
+    maxValue?: number;
+};
+/** Shared option-adding surface for both commands and subcommands. */
+declare class OptionsBuilder {
+    options: CommandOption[];
+    protected addOption(type: CommandOptionType, name: string, description: string, opts?: AddOpts): this;
+    addStringOption(name: string, description: string, opts?: AddOpts): this;
+    addIntegerOption(name: string, description: string, opts?: AddOpts): this;
+    addNumberOption(name: string, description: string, opts?: AddOpts): this;
+    addBooleanOption(name: string, description: string, opts?: AddOpts): this;
+    addUserOption(name: string, description: string, opts?: AddOpts): this;
+    addChannelOption(name: string, description: string, opts?: AddOpts): this;
+    addRoleOption(name: string, description: string, opts?: AddOpts): this;
+}
+/** A subcommand under a top-level command (e.g. `/setup channels`). */
+export declare class SlashCommandSubcommandBuilder extends OptionsBuilder {
+    name: string;
+    description: string;
+    setName(name: string): this;
+    setDescription(description: string): this;
+    toJSON(): CommandOption;
+}
+/** Fluent builder for a slash command. */
+export declare class SlashCommandBuilder extends OptionsBuilder {
+    name: string;
+    description: string;
+    defaultPerms: number;
+    setName(name: string): this;
+    setDescription(description: string): this;
+    /** Permission bits required to run this command (see PermissionsBitField). */
+    setDefaultPerms(bits: number): this;
+    /** Add a subcommand (e.g. `/setup channels`). A command with subcommands is
+     *  invoked as `/name subcommand …`; read the chosen one with
+     *  `interaction.options.getSubcommand()`. */
+    addSubcommand(fn: (sub: SlashCommandSubcommandBuilder) => SlashCommandSubcommandBuilder): this;
+    toJSON(): CommandData;
+}
+/** Accept either a builder or a plain object anywhere a command is expected. */
+export type CommandResolvable = SlashCommandBuilder | CommandData;
+export declare function resolveCommand(c: CommandResolvable): CommandData;
+export {};

package/dist/commands.js

@@ -0,0 +1,70 @@
+// Slash command definitions — the district.js equivalent of Discord's
+// SlashCommandBuilder. Build a command with typed options (and optional
+// subcommands), then register your whole set with `client.commands.set([...])`
+// so they show in the `/` picker.
+//
+//   const roll = new SlashCommandBuilder()
+//     .setName("roll").setDescription("Roll a die")
+//     .addIntegerOption("sides", "How many sides", { minValue: 2, maxValue: 100 });
+//
+//   const setup = new SlashCommandBuilder()
+//     .setName("setup").setDescription("Configure the bot")
+//     .addSubcommand(s => s.setName("channels").setDescription("Set channels")
+//       .addChannelOption("giveaway", "Where giveaways post", { required: true }));
+/** Shared option-adding surface for both commands and subcommands. */
+class OptionsBuilder {
+    options = [];
+    addOption(type, name, description, opts = {}) {
+        const o = { type, name, description, required: !!opts.required };
+        if (opts.choices && opts.choices.length)
+            o.choices = opts.choices;
+        if (opts.minValue != null)
+            o.minValue = opts.minValue;
+        if (opts.maxValue != null)
+            o.maxValue = opts.maxValue;
+        this.options.push(o);
+        return this;
+    }
+    addStringOption(name, description, opts) { return this.addOption("string", name, description, opts); }
+    addIntegerOption(name, description, opts) { return this.addOption("integer", name, description, opts); }
+    addNumberOption(name, description, opts) { return this.addOption("number", name, description, opts); }
+    addBooleanOption(name, description, opts) { return this.addOption("boolean", name, description, opts); }
+    addUserOption(name, description, opts) { return this.addOption("user", name, description, opts); }
+    addChannelOption(name, description, opts) { return this.addOption("channel", name, description, opts); }
+    addRoleOption(name, description, opts) { return this.addOption("role", name, description, opts); }
+}
+/** A subcommand under a top-level command (e.g. `/setup channels`). */
+export class SlashCommandSubcommandBuilder extends OptionsBuilder {
+    name = "";
+    description = "";
+    setName(name) { this.name = name; return this; }
+    setDescription(description) { this.description = description; return this; }
+    toJSON() {
+        return { type: "subcommand", name: this.name, description: this.description, options: this.options };
+    }
+}
+/** Fluent builder for a slash command. */
+export class SlashCommandBuilder extends OptionsBuilder {
+    name = "";
+    description = "";
+    defaultPerms = 0;
+    setName(name) { this.name = name; return this; }
+    setDescription(description) { this.description = description; return this; }
+    /** Permission bits required to run this command (see PermissionsBitField). */
+    setDefaultPerms(bits) { this.defaultPerms = bits; return this; }
+    /** Add a subcommand (e.g. `/setup channels`). A command with subcommands is
+     *  invoked as `/name subcommand …`; read the chosen one with
+     *  `interaction.options.getSubcommand()`. */
+    addSubcommand(fn) {
+        const sub = new SlashCommandSubcommandBuilder();
+        fn(sub);
+        this.options.push(sub.toJSON());
+        return this;
+    }
+    toJSON() {
+        return { name: this.name, description: this.description, options: this.options, defaultPerms: this.defaultPerms };
+    }
+}
+export function resolveCommand(c) {
+    return c instanceof SlashCommandBuilder ? c.toJSON() : c;
+}

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 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 { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, type ClientContext, type MessageContent, type MessageFile, } from "./structures.js";
 export { EmbedBuilder, resolveEmbed, type EmbedData, type EmbedField, type EmbedResolvable } from "./embed.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 { SlashCommandBuilder, SlashCommandSubcommandBuilder, resolveCommand, type CommandData, type CommandOption, type CommandOptionType, type CommandOptionChoice, type CommandResolvable, } from "./commands.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, RawAttachment, RawBan, RawInvite, RawWebhook, DistrictEvent, ReactionEvent, DeletedMessage, } from "./types.js";
+export type { ClientOptions, RawMessage, RawSelfUser, RawUser, RawSpace, RawChannel, RawRole, RawMember, RawAttachment, RawBan, RawInvite, RawWebhook, DistrictEvent, ReactionEvent, DeletedMessage, MemberEvent, ScheduledEvent, ScheduleInput, } from "./types.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember
 export { EmbedBuilder, resolveEmbed } from "./embed.js";
 export { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, } from "./components.js";
 export { Store, StoreCollection } from "./store.js";
+export { SlashCommandBuilder, SlashCommandSubcommandBuilder, resolveCommand, } from "./commands.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/structures.d.ts

@@ -5,10 +5,19 @@ 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. */
+/** A file to attach to a message. `data` is base64-encoded bytes. */
+export interface MessageFile {
+    filename: string;
+    /** Base64-encoded file contents. */
+    data: string;
+    /** MIME type (e.g. "image/png"). Defaults to application/octet-stream. */
+    contentType?: string;
+}
 export type MessageContent = string | {
     content?: string;
     embeds?: EmbedResolvable[];
     components?: ComponentResolvable[];
+    files?: MessageFile[];
 };
 /** Minimal client surface the structures need (avoids a circular import). */
 export interface ClientContext {
@@ -110,6 +119,13 @@ export declare class Space {
     members(limit?: number): Promise<Collection<string, SpaceMember>>;
     /** The space's roles. */
     roles(): Promise<Collection<string, Role>>;
+    /** A member's roles in this space — use to gate on "has role X". */
+    memberRoles(userId: string): Promise<Array<{
+        id: string;
+        name: string | null;
+        color: string | null;
+        position: number;
+    }>>;
     /** The space owner's profile. */
     fetchOwner(): Promise<User>;
     /** Banned users. */
@@ -246,6 +262,26 @@ export declare class Interaction {
     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>;
+    /** Typed accessors for slash-command option values (read from `args`), à la
+     *  discord.js: `interaction.options.getInteger("amount")`. Returns null when
+     *  the option was not provided. `getUser` returns the user id. */
+    get options(): {
+        get: (name: string) => unknown;
+        getString: (name: string) => string | null;
+        getInteger: (name: string) => number | null;
+        getNumber: (name: string) => number | null;
+        getBoolean: (name: string) => boolean | null;
+        getUser: (name: string) => string | null;
+        getChannel: (name: string) => string | null;
+        getRole: (name: string) => string | null;
+        /** The chosen subcommand name (for commands with subcommands), or null. */
+        getSubcommand: () => string | null;
+    };
+    /** Respond to the command by posting a message in its channel. Pass
+     *  `{ ephemeral: true }` to send a private reply only the invoking user sees
+     *  (content + embeds only) — this resolves to null since no public message is
+     *  created. */
+    reply(content: MessageContent, opts?: {
+        ephemeral?: boolean;
+    }): Promise<Message | null>;
 }

package/dist/structures.js

@@ -11,6 +11,7 @@ function toPayload(input) {
         content: input.content,
         embeds: input.embeds?.map(resolveEmbed),
         components: input.components?.map(resolveComponent),
+        files: input.files,
     };
 }
 export class ClientUser {
@@ -211,6 +212,11 @@ export class Space {
             out.set(r.id, new Role(r));
         return out;
     }
+    /** A member's roles in this space — use to gate on "has role X". */
+    async memberRoles(userId) {
+        const r = await this.client.rest.get(`/spaces/${this.id}/members/${userId}/roles`);
+        return r.roles ?? [];
+    }
     /** The space owner's profile. */
     async fetchOwner() {
         const { user } = await this.client.rest.get(`/users/${this.ownerId}`);
@@ -416,9 +422,41 @@ export class Interaction {
     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) {
+    /** Typed accessors for slash-command option values (read from `args`), à la
+     *  discord.js: `interaction.options.getInteger("amount")`. Returns null when
+     *  the option was not provided. `getUser` returns the user id. */
+    get options() {
+        const args = this.args;
+        return {
+            get: (name) => args[name] ?? null,
+            getString: (name) => { const v = args[name]; return v == null ? null : String(v); },
+            getInteger: (name) => { const v = Number(args[name]); return Number.isFinite(v) ? Math.trunc(v) : null; },
+            getNumber: (name) => { const v = Number(args[name]); return Number.isFinite(v) ? v : null; },
+            getBoolean: (name) => {
+                const v = args[name];
+                if (typeof v === "boolean")
+                    return v;
+                if (v == null)
+                    return null;
+                return v === "true" || v === 1 || v === "1";
+            },
+            getUser: (name) => { const v = args[name]; return v == null ? null : String(v); },
+            getChannel: (name) => { const v = args[name]; return v == null ? null : String(v); },
+            getRole: (name) => { const v = args[name]; return v == null ? null : String(v); },
+            /** The chosen subcommand name (for commands with subcommands), or null. */
+            getSubcommand: () => { const v = args.subcommand; return v == null ? null : String(v); },
+        };
+    }
+    /** Respond to the command by posting a message in its channel. Pass
+     *  `{ ephemeral: true }` to send a private reply only the invoking user sees
+     *  (content + embeds only) — this resolves to null since no public message is
+     *  created. */
+    async reply(content, opts) {
         const p = toPayload(content);
+        if (opts?.ephemeral) {
+            await this.client.rest.post(`/channels/${this.channelId}/messages`, { ...p, ephemeral: true, userId: this.userId });
+            return null;
+        }
         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

@@ -144,6 +144,24 @@ export type DistrictEvent = {
     message_id: string;
     user_id: string;
     emoji: string;
+} | {
+    event: "member.join";
+    space_id: string;
+    member: {
+        user_id: string;
+        joined_at?: string | null;
+    };
+} | {
+    event: "member.leave";
+    space_id: string;
+    member: {
+        user_id: string;
+        joined_at?: string | null;
+    };
+} | {
+    event: "scheduled";
+    schedule: string;
+    data?: Record<string, unknown>;
 } | {
     event: "interaction.create";
     type?: "command" | "component" | "modal_submit";
@@ -167,6 +185,27 @@ export interface ReactionEvent {
     userId: string;
     emoji: string;
 }
+/** A member joining or leaving a space (`memberJoin` / `memberLeave`). */
+export interface MemberEvent {
+    spaceId: string;
+    userId: string;
+    joinedAt: string | null;
+}
+/** A due scheduled job firing (`scheduled` event). */
+export interface ScheduledEvent {
+    /** The schedule name you registered. */
+    schedule: string;
+    /** The arbitrary data you attached when registering it. */
+    data: Record<string, unknown>;
+}
+/** One schedule to register with `client.schedules.set([...])`. */
+export interface ScheduleInput {
+    name: string;
+    /** How often to fire, in seconds (minimum 60). */
+    intervalSeconds: number;
+    /** Arbitrary data delivered back on every tick. */
+    data?: Record<string, unknown>;
+}
 export interface DeletedMessage {
     id: string;
     channelId: string;

package/package.json

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