chapterjs 0.1.2 → 0.1.4

package/dist/structures/member.d.ts

@@ -0,0 +1,140 @@
+import { type ImageOptions } from '../discord/cdn.js';
+import { Permissions } from '../discord/permissions.js';
+import type { Snowflake } from '../discord/types/common.js';
+import type { RawGuildMember } from '../discord/types/guild.js';
+import { Structure } from './base.js';
+import type { GuildChannel, VoiceChannel } from './channel.js';
+import type { Context } from './context.js';
+import { type Guild } from './guild.js';
+import type { Message } from './message.js';
+import type { MessageInput } from './payload.js';
+import type { Role } from './role.js';
+import type { User } from './user.js';
+/** The data of a member, without the user it belongs to. */
+export type MemberData = Omit<RawGuildMember, 'user'>;
+export interface BanOptions {
+    /** Why, shown in the audit log of the server. */
+    reason?: string;
+    /**
+     * Also deletes the messages the user sent in the last seconds given: from
+     * 0 (the default, nothing) to 604800 (7 days).
+     */
+    deleteMessageSeconds?: number;
+}
+export interface MemberEditOptions {
+    /** The nickname; `null` removes it. */
+    nick?: string | null;
+    /** Replaces every role of the member. */
+    roles?: (Snowflake | Role)[];
+    /** Mutes the member in voice channels. */
+    mute?: boolean;
+    /** Deafens the member in voice channels. */
+    deaf?: boolean;
+    /** Moves the member to another voice channel; `null` disconnects them. */
+    voiceChannel?: Snowflake | {
+        id: Snowflake;
+    } | null;
+    /** Until when the member is timed out; `null` ends the timeout. */
+    timeoutUntil?: Date | null;
+}
+/**
+ * A user as a member of one server: nickname, roles, permissions.
+ * @see https://docs.discord.com/developers/resources/guild#guild-member-object
+ */
+export declare class GuildMember extends Structure<MemberData> {
+    /** The id of the server. */
+    readonly guildId: Snowflake;
+    /** The account of the member. */
+    readonly user: User;
+    constructor(ctx: Context, data: MemberData, guildId: Snowflake, user: User);
+    /** The id of the user. */
+    get id(): Snowflake;
+    /** The server the member is in. */
+    get guild(): Guild;
+    /** The nickname of the member in this server, when they have one. */
+    get nick(): string | null;
+    /** The name to show: nickname, or display name, or username. */
+    get displayName(): string;
+    /** The ids of the roles of the member (@everyone is not listed). */
+    get roleIds(): readonly Snowflake[];
+    /** The roles of the member, @everyone included, highest first. */
+    get roles(): Role[];
+    /** The highest role of the member in the hierarchy; @everyone at least. */
+    get highestRole(): Role;
+    /**
+     * The voice channel the member is in; `null` when they are in none. The
+     * bot knows it when Discord sends it voice states: in a project with a
+     * file that joins a voice channel or listens to a voice event.
+     */
+    get voiceChannel(): VoiceChannel | null;
+    /** When the member joined the server. */
+    get joinedAt(): Date | null;
+    /** Since when the member boosts the server. */
+    get boostingSince(): Date | null;
+    /** Whether the member has not passed the membership screening yet. */
+    get pending(): boolean;
+    /** Until when the member is timed out; `null` when they are not. */
+    get timeoutUntil(): Date | null;
+    /** Whether the member is timed out right now. */
+    get isTimedOut(): boolean;
+    /** Whether the member owns the server. */
+    get isOwner(): boolean;
+    /**
+     * What the member can do in the server (channels may change it: see
+     * `permissionsIn`).
+     * @see https://docs.discord.com/developers/topics/permissions#permission-overwrites
+     */
+    get permissions(): Permissions;
+    /** What the member can do in a channel of the server. */
+    permissionsIn(channel: GuildChannel): Permissions;
+    /** The avatar of the member in this server, or else of their account. */
+    avatarURL(options?: ImageOptions): string;
+    /**
+     * Whether this member is above another one in the role hierarchy, which
+     * is what allows to kick, ban or rename them.
+     * @see https://docs.discord.com/developers/topics/permissions#permission-hierarchy
+     */
+    isHigherThan(other: GuildMember): boolean;
+    /**
+     * Changes the member.
+     * @see https://docs.discord.com/developers/resources/guild#modify-guild-member
+     */
+    edit(options: MemberEditOptions, reason?: string): Promise<GuildMember>;
+    /** Changes the nickname of the member; `null` removes it. */
+    setNick(nick: string | null, reason?: string): Promise<GuildMember>;
+    /**
+     * Gives a role to the member.
+     * @see https://docs.discord.com/developers/resources/guild#add-guild-member-role
+     */
+    addRole(role: Snowflake | Role, reason?: string): Promise<void>;
+    /**
+     * Takes a role from the member.
+     * @see https://docs.discord.com/developers/resources/guild#remove-guild-member-role
+     */
+    removeRole(role: Snowflake | Role, reason?: string): Promise<void>;
+    /** Whether the member has a role. */
+    hasRole(role: Snowflake | Role): boolean;
+    /**
+     * Prevents the member from writing, reacting and speaking for a while.
+     * @param duration how long, in milliseconds (28 days at most)
+     */
+    timeout(duration: number, reason?: string): Promise<GuildMember>;
+    /** Ends the timeout of the member. */
+    removeTimeout(reason?: string): Promise<GuildMember>;
+    /**
+     * Removes the member from the server; they can come back with an invite.
+     * @see https://docs.discord.com/developers/resources/guild#remove-guild-member
+     */
+    kick(reason?: string): Promise<void>;
+    /**
+     * Bans the member from the server.
+     * @see https://docs.discord.com/developers/resources/guild#create-guild-ban
+     */
+    ban(options?: BanOptions): Promise<void>;
+    /** Sends a private message to the member. */
+    send(message: MessageInput): Promise<Message>;
+    /** `<@id>`: mentions the member when put in a message. */
+    toString(): string;
+}
+/** One mechanism to ban, used by members and servers. */
+export declare function banUser(ctx: Context, guildId: Snowflake, userId: Snowflake, { reason, deleteMessageSeconds }: BanOptions): Promise<void>;

package/dist/structures/member.js

@@ -0,0 +1,260 @@
+import { Limits } from '../discord/api.js';
+import { cdn } from '../discord/cdn.js';
+import { AddGuildMemberRole, CreateGuildBan, ModifyCurrentMember, ModifyGuildMember, RemoveGuildMember, RemoveGuildMemberRole, } from '../discord/endpoints.js';
+import { applyTimeout, computeBasePermissions, Permissions, } from '../discord/permissions.js';
+import { ctxOf, dataOf, idOf, Structure, toDate } from './base.js';
+import { guildOf } from './known.js';
+import { storesOf } from './guild.js';
+/**
+ * A user as a member of one server: nickname, roles, permissions.
+ * @see https://docs.discord.com/developers/resources/guild#guild-member-object
+ */
+export class GuildMember extends Structure {
+    /** The id of the server. */
+    guildId;
+    /** The account of the member. */
+    user;
+    constructor(ctx, data, guildId, user) {
+        super(ctx, data);
+        this.guildId = guildId;
+        this.user = user;
+    }
+    /** The id of the user. */
+    get id() {
+        return this.user.id;
+    }
+    /** The server the member is in. */
+    get guild() {
+        return guildOf(this, this.guildId);
+    }
+    /** The nickname of the member in this server, when they have one. */
+    get nick() {
+        return dataOf(this).nick ?? null;
+    }
+    /** The name to show: nickname, or display name, or username. */
+    get displayName() {
+        return this.nick ?? this.user.displayName;
+    }
+    /** The ids of the roles of the member (@everyone is not listed). */
+    get roleIds() {
+        return dataOf(this).roles;
+    }
+    /** The roles of the member, @everyone included, highest first. */
+    get roles() {
+        const guild = this.guild;
+        const roles = [];
+        for (const id of [...this.roleIds, this.guildId]) {
+            const role = guild.roles.get(id);
+            if (role)
+                roles.push(role);
+        }
+        return roles.sort((a, b) => (a.isHigherThan(b) ? -1 : 1));
+    }
+    /** The highest role of the member in the hierarchy; @everyone at least. */
+    get highestRole() {
+        return this.roles[0] ?? this.guild.everyoneRole;
+    }
+    /**
+     * The voice channel the member is in; `null` when they are in none. The
+     * bot knows it when Discord sends it voice states: in a project with a
+     * file that joins a voice channel or listens to a voice event.
+     */
+    get voiceChannel() {
+        return storesOf(this.guild).voiceStates.get(this.id)?.channel ?? null;
+    }
+    /** When the member joined the server. */
+    get joinedAt() {
+        return toDate(dataOf(this).joined_at);
+    }
+    /** Since when the member boosts the server. */
+    get boostingSince() {
+        return toDate(dataOf(this).premium_since);
+    }
+    /** Whether the member has not passed the membership screening yet. */
+    get pending() {
+        return dataOf(this).pending ?? false;
+    }
+    /** Until when the member is timed out; `null` when they are not. */
+    get timeoutUntil() {
+        const until = toDate(dataOf(this).communication_disabled_until);
+        return until && until.getTime() > Date.now() ? until : null;
+    }
+    /** Whether the member is timed out right now. */
+    get isTimedOut() {
+        return this.timeoutUntil !== null;
+    }
+    /** Whether the member owns the server. */
+    get isOwner() {
+        return this.guild?.ownerId === this.id;
+    }
+    /**
+     * What the member can do in the server (channels may change it: see
+     * `permissionsIn`).
+     * @see https://docs.discord.com/developers/topics/permissions#permission-overwrites
+     */
+    get permissions() {
+        const guild = this.guild;
+        if (!guild) {
+            throw new Error('The permissions of this member are unknown: its server is not in the cache.');
+        }
+        const base = computeBasePermissions({
+            guildId: this.guildId,
+            ownerId: guild.ownerId,
+            userId: this.id,
+            memberRoleIds: this.roleIds,
+            roles: [...guild.roles.values()].map(role => ({
+                id: role.id,
+                permissions: role.permissions.bits,
+            })),
+        });
+        return new Permissions(this.isTimedOut ? applyTimeout(base) : base);
+    }
+    /** What the member can do in a channel of the server. */
+    permissionsIn(channel) {
+        return channel.permissionsFor(this);
+    }
+    /** The avatar of the member in this server, or else of their account. */
+    avatarURL(options) {
+        const avatar = dataOf(this).avatar;
+        return avatar
+            ? cdn.memberAvatar(this.guildId, this.id, avatar, options)
+            : this.user.avatarURL(options);
+    }
+    /**
+     * Whether this member is above another one in the role hierarchy, which
+     * is what allows to kick, ban or rename them.
+     * @see https://docs.discord.com/developers/topics/permissions#permission-hierarchy
+     */
+    isHigherThan(other) {
+        if (this.isOwner)
+            return true;
+        if (other.isOwner)
+            return false;
+        const mine = this.highestRole;
+        const theirs = other.highestRole;
+        if (!mine || !theirs)
+            return false;
+        return mine.id !== theirs.id && mine.isHigherThan(theirs);
+    }
+    /**
+     * Changes the member.
+     * @see https://docs.discord.com/developers/resources/guild#modify-guild-member
+     */
+    async edit(options, reason) {
+        const { rest, entities } = ctxOf(this);
+        if (typeof options.nick === 'string' &&
+            options.nick.length > Limits.Nickname) {
+            throw new RangeError(`A nickname is ${Limits.Nickname} characters long at most, got ${options.nick.length}.`);
+        }
+        if (options.timeoutUntil) {
+            const ms = options.timeoutUntil.getTime() - Date.now();
+            if (!(ms > 0) || ms > Limits.TimeoutMaxDuration) {
+                throw new RangeError('A timeout ends in the future, 28 days from now at most.');
+            }
+        }
+        const raw = await rest.request(ModifyGuildMember, [this.guildId, this.id], {
+            // `null` is meaningful for these fields; the documented type only
+            // lists what they are when set.
+            body: {
+                nick: options.nick,
+                roles: options.roles?.map(idOf),
+                mute: options.mute,
+                deaf: options.deaf,
+                channel_id: options.voiceChannel === null || options.voiceChannel === undefined
+                    ? options.voiceChannel
+                    : idOf(options.voiceChannel),
+                communication_disabled_until: options.timeoutUntil === null || options.timeoutUntil === undefined
+                    ? options.timeoutUntil
+                    : options.timeoutUntil.toISOString(),
+            },
+            reason,
+        });
+        return entities.member(this.guildId, { ...raw, user: raw.user });
+    }
+    /** Changes the nickname of the member; `null` removes it. */
+    async setNick(nick, reason) {
+        const { rest, entities, self } = ctxOf(this);
+        if (self?.userId === this.id) {
+            // A bot renames itself through another endpoint.
+            // https://docs.discord.com/developers/resources/guild#modify-current-member
+            const raw = await rest.request(ModifyCurrentMember, [this.guildId], {
+                body: { nick },
+                reason,
+            });
+            return entities.member(this.guildId, raw);
+        }
+        return this.edit({ nick }, reason);
+    }
+    /**
+     * Gives a role to the member.
+     * @see https://docs.discord.com/developers/resources/guild#add-guild-member-role
+     */
+    async addRole(role, reason) {
+        await ctxOf(this).rest.request(AddGuildMemberRole, [this.guildId, this.id, idOf(role)], { reason });
+    }
+    /**
+     * Takes a role from the member.
+     * @see https://docs.discord.com/developers/resources/guild#remove-guild-member-role
+     */
+    async removeRole(role, reason) {
+        await ctxOf(this).rest.request(RemoveGuildMemberRole, [this.guildId, this.id, idOf(role)], { reason });
+    }
+    /** Whether the member has a role. */
+    hasRole(role) {
+        const id = idOf(role);
+        return id === this.guildId || this.roleIds.includes(id);
+    }
+    /**
+     * Prevents the member from writing, reacting and speaking for a while.
+     * @param duration how long, in milliseconds (28 days at most)
+     */
+    async timeout(duration, reason) {
+        if (!Number.isFinite(duration) || duration <= 0) {
+            throw new RangeError(`A timeout lasts a positive number of milliseconds, got ${duration}. Use removeTimeout() to end one.`);
+        }
+        return this.edit({ timeoutUntil: new Date(Date.now() + duration) }, reason);
+    }
+    /** Ends the timeout of the member. */
+    async removeTimeout(reason) {
+        return this.edit({ timeoutUntil: null }, reason);
+    }
+    /**
+     * Removes the member from the server; they can come back with an invite.
+     * @see https://docs.discord.com/developers/resources/guild#remove-guild-member
+     */
+    async kick(reason) {
+        await ctxOf(this).rest.request(RemoveGuildMember, [this.guildId, this.id], {
+            reason,
+        });
+    }
+    /**
+     * Bans the member from the server.
+     * @see https://docs.discord.com/developers/resources/guild#create-guild-ban
+     */
+    async ban(options = {}) {
+        await banUser(ctxOf(this), this.guildId, this.id, options);
+    }
+    /** Sends a private message to the member. */
+    async send(message) {
+        return this.user.send(message);
+    }
+    /** `<@id>`: mentions the member when put in a message. */
+    toString() {
+        return this.user.toString();
+    }
+}
+/** One mechanism to ban, used by members and servers. */
+export async function banUser(ctx, guildId, userId, { reason, deleteMessageSeconds }) {
+    if (deleteMessageSeconds !== undefined &&
+        (!Number.isInteger(deleteMessageSeconds) ||
+            deleteMessageSeconds < 0 ||
+            deleteMessageSeconds > Limits.BanDeleteMessageSeconds)) {
+        throw new RangeError(`deleteMessageSeconds is a whole number between 0 and ${Limits.BanDeleteMessageSeconds} (7 days), got ${deleteMessageSeconds}.`);
+    }
+    await ctx.rest.request(CreateGuildBan, [guildId, userId], {
+        body: deleteMessageSeconds === undefined
+            ? {}
+            : { delete_message_seconds: deleteMessageSeconds },
+        reason,
+    });
+}

package/dist/structures/message.d.ts

@@ -0,0 +1,197 @@
+import type { StartThreadFromMessageJSONParams } from '../discord/types/channel.js';
+import type { Snowflake } from '../discord/types/common.js';
+import type { RawPartialEmoji } from '../discord/types/emoji.js';
+import { MessageFlags, MessageType, type RawAttachment, type RawMessage, type RawReaction } from '../discord/types/message.js';
+import { type Camelize } from '../util/case.js';
+import { IdStructure } from './base.js';
+import type { DMChannel, GuildTextBasedChannel, TextBasedChannel, ThreadChannel } from './channel.js';
+import type { Context } from './context.js';
+import type { Guild } from './guild.js';
+import type { GuildMember } from './member.js';
+import { type Embed, type MessageEditOptions, type MessageInput } from './payload.js';
+import type { User } from './user.js';
+/** What the message stores: users are kept as structures, not copies. */
+export type MessageData = Omit<RawMessage, 'author' | 'mentions'> & {
+    guild_id?: Snowflake;
+};
+/** The name of a flag of a message: a key of `MessageFlags`. */
+export type MessageFlagName = keyof typeof MessageFlags;
+/** A file attached to a message. */
+export type Attachment = Camelize<RawAttachment>;
+/** The reactions of one emoji on a message. */
+export type Reaction = Camelize<RawReaction>;
+/**
+ * The emoji of a reaction: a standard one has only a `name` (`"👍"`), a
+ * custom one has an `id` too.
+ * @see https://docs.discord.com/developers/resources/emoji#emoji-object
+ */
+export type ReactionEmoji = Camelize<RawPartialEmoji>;
+/** An emoji to react with: a standard one (`"👍"`), or a custom one. */
+export type EmojiInput = string | {
+    id?: Snowflake | null;
+    name?: string | null;
+};
+/**
+ * A message sent in a channel.
+ * @see https://docs.discord.com/developers/resources/message#message-object
+ */
+export declare class Message extends IdStructure<MessageData> {
+    /** Who wrote the message. */
+    readonly author: User;
+    /** The users mentioned in the message. */
+    readonly mentions: readonly User[];
+    constructor(ctx: Context, data: MessageData, author: User, mentions: readonly User[]);
+    /** The id of the channel of the message. */
+    get channelId(): Snowflake;
+    /** The id of the server; `null` for a private message. */
+    get guildId(): Snowflake | null;
+    /** The channel of the message, when it is known. */
+    get channel(): TextBasedChannel | null;
+    /** The server of the message; `null` for a private message. */
+    get guild(): Guild | null;
+    /** The author as a member of the server, when it is known. */
+    get member(): GuildMember | null;
+    /**
+     * The text of the message. Empty when the bot is not allowed to read it:
+     * reading the messages of others needs the Message Content intent.
+     */
+    get content(): string;
+    /** The kind of message, as a value of `MessageType` (a regular one, a reply, a join notice...). */
+    get type(): MessageType;
+    /** When the message was last edited; `null` when it never was. */
+    get editedAt(): Date | null;
+    /** Whether the message is pinned. */
+    get pinned(): boolean;
+    /** Whether the message was read aloud. */
+    get tts(): boolean;
+    /** The embeds of the message. */
+    get embeds(): Embed[];
+    /** The files attached to the message. */
+    get attachments(): Attachment[];
+    /** The reactions on the message, one entry per emoji. */
+    get reactions(): Reaction[];
+    /** Whether the message mentions @everyone or @here. */
+    get mentionsEveryone(): boolean;
+    /** The ids of the roles mentioned in the message. */
+    get mentionedRoleIds(): readonly Snowflake[];
+    /** The flags of the message, by name (`Ephemeral`, `SuppressEmbeds`...). */
+    get flags(): MessageFlagName[];
+    /** The id of the webhook that sent the message, when one did. */
+    get webhookId(): Snowflake | null;
+    /** The id of the message this one replies to, when it is a reply. */
+    get repliedMessageId(): Snowflake | null;
+    /** Whether a person wrote it: not a bot, a webhook or Discord itself. */
+    get isFromUser(): boolean;
+    /** The link that opens the message in Discord. */
+    get url(): string;
+    /** Asks Discord for the latest version of the message. */
+    fetch(): Promise<Message>;
+    /**
+     * Answers the message, in the same channel.
+     * @see https://docs.discord.com/developers/resources/message#create-message
+     */
+    reply(message: MessageInput): Promise<Message>;
+    /**
+     * Changes the message. Only the content, embeds, components and files of
+     * a message the bot wrote can change.
+     * @see https://docs.discord.com/developers/resources/message#edit-message
+     */
+    edit(message: string | MessageEditOptions): Promise<Message>;
+    /**
+     * Deletes the message.
+     * @see https://docs.discord.com/developers/resources/message#delete-message
+     */
+    delete(reason?: string): Promise<void>;
+    /**
+     * Adds a reaction of the bot to the message.
+     * @see https://docs.discord.com/developers/resources/message#create-reaction
+     */
+    react(emoji: EmojiInput): Promise<void>;
+    /**
+     * Removes a reaction: of the bot, or of the given user.
+     * @see https://docs.discord.com/developers/resources/message#delete-user-reaction
+     */
+    removeReaction(emoji: EmojiInput, user?: Snowflake | {
+        id: Snowflake;
+    }): Promise<void>;
+    /**
+     * Removes every reaction of the message, or every reaction of one emoji.
+     * @see https://docs.discord.com/developers/resources/message#delete-all-reactions
+     */
+    clearReactions(emoji?: EmojiInput): Promise<void>;
+    /**
+     * The users who reacted with an emoji (100 at most per call).
+     * @see https://docs.discord.com/developers/resources/message#get-reactions
+     */
+    fetchReactionUsers(emoji: EmojiInput, options?: {
+        limit?: number;
+        after?: Snowflake;
+    }): Promise<User[]>;
+    /**
+     * Pins the message in its channel.
+     * @see https://docs.discord.com/developers/resources/message#pin-message
+     */
+    pin(reason?: string): Promise<void>;
+    /**
+     * Unpins the message.
+     * @see https://docs.discord.com/developers/resources/message#unpin-message
+     */
+    unpin(reason?: string): Promise<void>;
+    /**
+     * Publishes a message of an announcement channel to the servers that
+     * follow it.
+     * @see https://docs.discord.com/developers/resources/message#crosspost-message
+     */
+    crosspost(): Promise<Message>;
+    /**
+     * Starts a thread from the message.
+     * @see https://docs.discord.com/developers/resources/channel#start-thread-from-message
+     */
+    startThread(options: Camelize<StartThreadFromMessageJSONParams>, reason?: string): Promise<ThreadChannel>;
+}
+/** One mechanism to send a message, used by channels, replies and users. */
+export declare function sendMessage(ctx: Context, channelId: Snowflake, message: MessageInput, guildId?: Snowflake): Promise<Message>;
+/**
+ * A message of a server: its server is known. It is what the events about
+ * messages give for what happens in a server.
+ */
+export interface GuildMessage extends Message {
+    /** The id of the server. */
+    readonly guildId: Snowflake;
+    /** The server of the message. */
+    readonly guild: Guild;
+    /** The channel of the message. */
+    readonly channel: GuildTextBasedChannel;
+}
+/**
+ * A message written in a server by one of its members: neither a private
+ * message nor the message of a webhook. It is what the events about
+ * messages give by default.
+ */
+export interface MemberMessage extends GuildMessage {
+    /** The author as a member of the server. */
+    readonly member: GuildMember;
+}
+/**
+ * A private message, for a file that receives both kinds
+ * (`{ where: 'both' }`): there is no server, which is how it is told apart
+ * from a `GuildMessage`.
+ */
+export interface PrivateMessage extends Message {
+    /** No server: it is a private message. */
+    readonly guildId: null;
+    /** No server: it is a private message. */
+    readonly guild: null;
+    /** No member: the author is `author`. */
+    readonly member: null;
+    /** The private conversation, when the bot knows it. */
+    readonly channel: DMChannel | null;
+}
+/**
+ * A private message, for a file that only receives those
+ * (`{ where: 'dm' }`): nothing about a server exists on it.
+ */
+export interface DmMessage extends Omit<Message, 'guildId' | 'guild' | 'member' | 'channel'> {
+    /** The private conversation, when the bot knows it. */
+    readonly channel: DMChannel | null;
+}