lunibee 0.2.3 → 0.3.0

package/dist/sharding/supervisor.d.ts

@@ -0,0 +1,32 @@
+/** How a crashed cluster is restarted. The defaults restart every crash after a fixed delay. */
+export interface SupervisorOptions {
+    /** Delay before the first restart, in milliseconds (default 5000). */
+    restartDelay?: number;
+    /** Each further crash in the window multiplies the delay by this (default 1: a fixed delay). */
+    backoff?: number;
+    /** The longest delay (default 5 minutes). */
+    maxDelay?: number;
+    /** Random spread added to each delay, as a fraction of it (0-1, default 0). */
+    jitter?: number;
+    /** Give up after this many restarts inside `window` (default unlimited). */
+    maxRestarts?: number;
+    /** The time over which restarts are counted, and after which a stable cluster is forgiven (default 60,000). */
+    window?: number;
+}
+/**
+ * Decides when, and whether, a crashed cluster comes back. It only does
+ * arithmetic on timestamps (pass `now` in tests), so `ClusterManager` stays in
+ * charge of forking.
+ */
+export declare class ShardSupervisor {
+    #private;
+    constructor(options?: SupervisorOptions, random?: () => number);
+    /**
+     * A cluster exited. @returns How many milliseconds to wait before
+     * restarting it, or `null` to give up because it crashed more than
+     * `maxRestarts` times inside `window`.
+     */
+    next(id: number, now?: number): number | null;
+    /** Forgets a cluster's crashes, e.g. after a deliberate respawn. */
+    reset(id?: number): void;
+}

package/dist/sharding/transport.d.ts

@@ -0,0 +1,45 @@
+import type { ShardMessage } from "./bus.js";
+/** Carries {@link ShardMessage}s between the processes or threads that run shards. */
+export interface ShardBusTransport {
+    /** Sends a message to the other shards. Delivery to the sender itself is not required. */
+    post(message: ShardMessage): void;
+    /** Listens for messages from other shards. */
+    onMessage(listener: (message: ShardMessage) => void): void;
+    /** Listens for the shards of a cluster that died, so pending requests to them can fail early. */
+    onPeerDown?(listener: (shardIds: readonly number[]) => void): void;
+    /** Stops listening and releases the channel. */
+    close(): void;
+}
+/** One process: shards in the same process (or worker threads of it) talk over a `BroadcastChannel`. */
+export declare class BroadcastChannelTransport implements ShardBusTransport {
+    #private;
+    constructor(name: string);
+    post(message: ShardMessage): void;
+    onMessage(listener: (message: ShardMessage) => void): void;
+    close(): void;
+}
+/** Marks a bus message on the IPC channel, so it cannot be confused with the bot's own `process.send()` traffic. */
+export declare const BUS_FRAME = "__lunibeeBus";
+/** Marks the parent's notice that a cluster's shards are gone. */
+export declare const PEER_DOWN_FRAME = "__lunibeePeerDown";
+/** The part of `process` (or a child process handle) the IPC transport uses. */
+export interface IpcEndpoint {
+    send?(message: unknown): unknown;
+    on(event: "message", listener: (message: unknown) => void): unknown;
+    off(event: "message", listener: (message: unknown) => void): unknown;
+}
+/**
+ * Forked clusters: a worker `send()`s to its parent, and the parent
+ * ({@link ClusterManager}) relays to every other worker. Selected
+ * automatically in a worker forked by `ClusterManager`.
+ */
+export declare class IpcTransport implements ShardBusTransport {
+    #private;
+    constructor(endpoint?: IpcEndpoint);
+    post(message: ShardMessage): void;
+    onMessage(listener: (message: ShardMessage) => void): void;
+    onPeerDown(listener: (shardIds: readonly number[]) => void): void;
+    close(): void;
+}
+/** Picks the transport for a bus: IPC inside a forked cluster, `BroadcastChannel` otherwise. */
+export declare function defaultTransport(name: string): ShardBusTransport;

package/dist/structures/audit-log.d.ts

@@ -1,21 +1,114 @@
 import { BaseStructure } from "./base.js";
 import type { APIAuditLog, APIAuditLogEntry, APIAuditLogChange, APIAuditLogOptions } from "@lunibee/types";
+/** What `info` holds for each action type that carries extra details (numbers are parsed from Discord's strings). */
+export interface AuditLogInfoByType {
+    /** Overwrite created, updated or deleted: a role (`type` 0) or a member (`type` 1). */
+    13: AuditLogOverwriteInfo;
+    14: AuditLogOverwriteInfo;
+    15: AuditLogOverwriteInfo;
+    /** Member prune. */
+    21: {
+        deleteMemberDays: number;
+        membersRemoved: number;
+    };
+    /** Members moved between voice channels. */
+    26: {
+        channelId: string;
+        count: number;
+    };
+    /** Members disconnected from voice. */
+    27: {
+        count: number;
+    };
+    /** Message deleted in a channel. */
+    72: {
+        channelId: string;
+        count: number;
+    };
+    /** Messages bulk deleted. */
+    73: {
+        count: number;
+    };
+    /** Message pinned or unpinned. */
+    74: {
+        channelId: string;
+        messageId: string;
+    };
+    75: {
+        channelId: string;
+        messageId: string;
+    };
+    /** Stage instance created, updated or deleted. */
+    83: {
+        channelId: string;
+    };
+    84: {
+        channelId: string;
+    };
+    85: {
+        channelId: string;
+    };
+    /** Application command permissions updated. */
+    121: {
+        applicationId: string;
+    };
+    /** AutoMod blocked a message, flagged it, or timed a member out. */
+    143: AuditLogAutoModInfo;
+    144: AuditLogAutoModInfo;
+    145: AuditLogAutoModInfo;
+}
+/** The overwrite an audit entry is about. */
+export interface AuditLogOverwriteInfo {
+    /** The role or user the overwrite is for. */
+    id: string;
+    /** 0 role, 1 member. */
+    type: number;
+    roleName?: string;
+}
+/** The rule behind an AutoMod audit entry. */
+export interface AuditLogAutoModInfo {
+    ruleName: string;
+    ruleTriggerType: number;
+    channelId?: string;
+}
+/** The details object of an action type, or `undefined` when the type has none. */
+export type AuditLogInfo<T extends number> = number extends T ? AuditLogInfoByType[keyof AuditLogInfoByType] | undefined : T extends keyof AuditLogInfoByType ? AuditLogInfoByType[T] : undefined;
 /** Represents a single entry in a Discord audit log. */
-export declare class AuditLogEntry extends BaseStructure {
+export declare class AuditLogEntry<T extends number = number> extends BaseStructure {
     /** The ID of the affected entity. */
     readonly targetId: string | null;
     /** The ID of the user who made the changes. */
     readonly userId: string | null;
     /** The action type of this entry. */
-    readonly actionType: number;
+    readonly actionType: T;
     /** The changes made to the target. */
     readonly changes: APIAuditLogChange[];
     /** Additional info for certain action types. */
     readonly options: APIAuditLogOptions | null;
+    /** The action's details with numbers parsed, typed by action type (`undefined` for types that have none). `options` is Discord's raw object. */
+    readonly info: AuditLogInfo<T>;
     /** The reason for the change, if any. */
     readonly reason: string | null;
     /** Creates an audit log entry. */
     constructor(data: APIAuditLogEntry);
+    /** Narrows the entry to one action type, so `info` is typed for it. */
+    is<K extends number>(type: K): this is AuditLogEntry<K>;
+    /** One change by its key (`"nick"`, `"permissions"`...), or `undefined`. */
+    change(key: string): {
+        old: unknown;
+        new: unknown;
+    } | undefined;
+}
+/** Which entries {@link AuditLog.find} and {@link AuditLog.filter} keep. Every field given must match. */
+export interface AuditLogQuery<T extends number = number> {
+    /** One action type, or any of several. */
+    type?: T | readonly T[];
+    /** The affected entity. */
+    targetId?: string;
+    /** Who did it. */
+    userId?: string;
+    /** Only entries created at or after this time (a Date, an ISO string or milliseconds). */
+    since?: Date | string | number;
 }
 /** Represents a Discord audit log. */
 export declare class AuditLog {
@@ -23,4 +116,8 @@ export declare class AuditLog {
     readonly entries: Map<string, AuditLogEntry>;
     /** Creates an audit log. */
     constructor(data: APIAuditLog);
+    /** The entries that match `query`, newest first (the order Discord returns them in). */
+    filter<T extends number = number>(query: AuditLogQuery<T>): AuditLogEntry<T>[];
+    /** The newest entry that matches `query`, or `undefined`. */
+    find<T extends number = number>(query: AuditLogQuery<T>): AuditLogEntry<T> | undefined;
 }

package/dist/structures/base.d.ts

@@ -1,19 +1,19 @@
+import { type ChannelKind, type MessageCreateOptions, type MessageEditOptions, type UnknownChannelKind } from "@lunibee/types";
+import type { ChannelOfKind } from "./channels.js";
 /** Common Discord snowflake-backed structure. */
 export declare class BaseStructure {
     readonly id: string;
     constructor(id: string);
     /** Returns the snowflake ID as a string. */
     toString(): string;
+    /** Milliseconds since the Unix epoch at which this snowflake was created. */
+    get createdTimestamp(): number;
     /** Returns the timestamp this snowflake was created at. */
     get createdAt(): Date;
 }
 export interface ResourceContext {
-    sendMessage(channelId: string, options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<import("./index.js").Message>;
-    editMessage(channelId: string, messageId: string, options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<import("./index.js").Message>;
+    sendMessage(channelId: string, options: MessageCreateOptions): Promise<import("./index.js").Message>;
+    editMessage(channelId: string, messageId: string, options: MessageEditOptions): Promise<import("./index.js").Message>;
     deleteMessage(channelId: string, messageId: string, reason?: string): Promise<void>;
     crosspostMessage(channelId: string, messageId: string): Promise<import("./index.js").Message>;
     editChannel?(channelId: string, options: Record<string, unknown>): Promise<import("./base.js").Channel>;
@@ -29,7 +29,7 @@ export interface ResourceContext {
      * (with overwrites) when a channel ID is given. Null when the guild (or
      * channel) is not cached.
      */
-    memberPermissions?(guildId: string, memberId: string, roleIds: readonly string[], channelId?: string): import("@lunibee/core").PermissionSet | null;
+    memberPermissions?(guildId: string, memberId: string, roleIds: readonly string[], channelId?: string, timedOutUntil?: Date | null): import("@lunibee/core").PermissionSet | null;
     kickMember?(guildId: string, userId: string, reason?: string): Promise<void>;
     banMember?(guildId: string, userId: string, options?: {
         reason?: string;
@@ -97,13 +97,7 @@ export declare class Channel extends BaseStructure {
     /** Creates a channel structure from Discord channel data. */
     constructor(data: import("@lunibee/types").APIChannel, context?: ResourceContext);
     /** Sends a message to this channel. @param options Message payload. @returns The created message. @throws {Error} If the channel is not attached to a client. */
-    send(options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<import("./index.js").Message>;
-    /** @deprecated Use {@link Channel.send}. Removed in 0.3.0. */
-    sendMessage(options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<import("./index.js").Message>;
+    send(options: MessageCreateOptions): Promise<import("./index.js").Message>;
     /** Edits this channel. @param options Channel fields to change. @returns The updated channel. @throws {Error} If the channel is not attached to a client. */
     edit(options: Record<string, unknown>): Promise<Channel>;
     /** Changes only this channel's name. @param name New channel name. @returns The updated channel. @throws {TypeError} If the name is empty. @throws {Error} If the channel is not attached to a client. */
@@ -127,6 +121,18 @@ export declare class Channel extends BaseStructure {
     delete(reason?: string): Promise<void>;
     /** Updates this channel using the same resource operation as edit. @param options Channel fields to change. @returns The updated channel. @throws {Error} If the channel is not attached to a client. */
     update(options: Record<string, unknown>): Promise<Channel>;
+    /** What kind of channel this is: `"text"`, `"voice"`, `"thread"`, `"forum"`… (`"unknown"` for a type this version does not know). */
+    get kind(): ChannelKind | UnknownChannelKind;
+    /**
+     * Whether this channel is one of `kinds`, narrowing its type to match.
+     * @example if (channel.is("text", "announcement")) await channel.send("hi");
+     */
+    is<K extends ChannelKind | UnknownChannelKind>(...kinds: K[]): this is ChannelOfKind<K>;
+    /**
+     * Returns this channel typed as one of `kinds`.
+     * @throws {TypeError} If it is a different kind.
+     */
+    as<K extends ChannelKind | UnknownChannelKind>(...kinds: K[]): ChannelOfKind<K>;
     /** Whether this is a thread (announcement, public or private). */
     isThread(): boolean;
     /** Whether messages can be sent in this channel (text, DM, announcement, voice, stage, threads). */
@@ -170,15 +176,26 @@ export declare class Guild extends BaseStructure {
     explicitContentFilter: number;
     /** Default notification level for new members. */
     defaultMessageNotifications: number;
-    /** AFK voice channel, or null. */ afkChannelId: string | null;
-    /** Seconds before a silent member is moved to the AFK channel. */ afkTimeout?: number;
-    /** Whether the server widget is on. */ widgetEnabled: boolean;
-    /** Channel the widget invites to, or null. */ widgetChannelId: string | null;
-    /** Application that created the guild, if a bot did. */ applicationId: string | null;
-    /** Channel for Discord's community updates, or null. */ publicUpdatesChannelId: string | null;
-    /** Channel for safety alerts, or null. */ safetyAlertsChannelId: string | null;
-    /** Maximum presences (null for the default limit). */ maxPresences: number | null;
-    /** Maximum users in a video channel. */ maxVideoChannelUsers?: number;
+    /** AFK voice channel, or null. */
+    afkChannelId: string | null;
+    /** Seconds before a silent member is moved to the AFK channel. */
+    afkTimeout?: number;
+    /** Whether the server widget is on. */
+    widgetEnabled: boolean;
+    /** Channel the widget invites to, or null. */
+    widgetChannelId: string | null;
+    /** Application that created the guild, if a bot did. */
+    applicationId: string | null;
+    /** Channel for Discord's community updates, or null. */
+    publicUpdatesChannelId: string | null;
+    /** Channel for safety alerts, or null. */
+    safetyAlertsChannelId: string | null;
+    /** Maximum presences (null for the default limit). */
+    maxPresences: number | null;
+    /** Maximum users in a video channel. */
+    maxVideoChannelUsers?: number;
+    /** Whether the boost progress bar shows. */
+    premiumProgressBarEnabled: boolean;
     constructor(data: import("@lunibee/types").APIGuild);
     /** Returns the guild icon URL, or null if no icon is set. */
     iconURL(options?: ImageURLOptions): string | null;

package/dist/structures/channels.d.ts

@@ -6,16 +6,22 @@ export declare class NewsChannel extends TextChannel {
 }
 /** A direct-message or group DM channel. */
 export declare class DMChannel extends Channel {
-    /** Users in the conversation. */ readonly recipients: User[];
-    /** Owner of a group DM. */ readonly ownerId: string | null;
+    /** Users in the conversation. */
+    readonly recipients: User[];
+    /** Owner of a group DM. */
+    readonly ownerId: string | null;
     constructor(data: APIChannel, context?: ResourceContext);
 }
 /** A guild voice channel. */
 export declare class VoiceChannel extends Channel {
-    /** Bitrate in bits per second. */ bitrate: number;
-    /** User limit (0 = unlimited). */ userLimit: number;
-    /** Voice region override, or null for automatic. */ rtcRegion: string | null;
-    /** Camera video quality mode. */ videoQualityMode: number;
+    /** Bitrate in bits per second. */
+    bitrate: number;
+    /** User limit (0 = unlimited). */
+    userLimit: number;
+    /** Voice region override, or null for automatic. */
+    rtcRegion: string | null;
+    /** Camera video quality mode. */
+    videoQualityMode: number;
     constructor(data: APIChannel, context?: ResourceContext);
 }
 /** A guild stage channel. */
@@ -26,10 +32,14 @@ export declare class CategoryChannel extends Channel {
 }
 /** A thread (announcement, public or private). */
 export declare class ThreadChannel extends Channel {
-    /** User who created the thread. */ readonly ownerId: string | null;
-    /** Approximate message count. */ messageCount: number;
-    /** Approximate member count (stops counting at 50). */ memberCount: number;
-    /** Thread metadata. */ metadata: APIThreadMetadata | null;
+    /** User who created the thread. */
+    readonly ownerId: string | null;
+    /** Approximate message count. */
+    messageCount: number;
+    /** Approximate member count (stops counting at 50). */
+    memberCount: number;
+    /** Thread metadata. */
+    metadata: APIThreadMetadata | null;
     constructor(data: APIChannel, context?: ResourceContext);
     /** Whether the thread is archived. */
     get archived(): boolean;
@@ -40,10 +50,14 @@ export declare class ThreadChannel extends Channel {
 }
 /** A guild forum channel. */
 export declare class ForumChannel extends Channel {
-    /** Tags that threads can apply. */ availableTags: APIForumTag[];
-    /** Default reaction for new threads. */ defaultReactionEmoji: APIPartialEmoji | null;
-    /** Default slowmode for new threads. */ defaultThreadRateLimitPerUser: number;
-    /** Default auto-archive duration for new threads. */ defaultAutoArchiveDuration: number | null;
+    /** Tags that threads can apply. */
+    availableTags: APIForumTag[];
+    /** Default reaction for new threads. */
+    defaultReactionEmoji: APIPartialEmoji | null;
+    /** Default slowmode for new threads. */
+    defaultThreadRateLimitPerUser: number;
+    /** Default auto-archive duration for new threads. */
+    defaultAutoArchiveDuration: number | null;
     constructor(data: APIChannel, context?: ResourceContext);
 }
 /** A guild media channel. */
@@ -54,3 +68,20 @@ export declare class MediaChannel extends ForumChannel {
  * to {@link Channel} for types without a dedicated class.
  */
 export declare function createChannel(data: APIChannel, context?: ResourceContext): Channel;
+/** The class of each channel kind, so `channel.is("voice")` can narrow to `VoiceChannel`. */
+export interface ChannelsByKind {
+    text: TextChannel;
+    announcement: NewsChannel;
+    voice: VoiceChannel;
+    stage: StageChannel;
+    category: CategoryChannel;
+    thread: ThreadChannel;
+    forum: ForumChannel;
+    media: MediaChannel;
+    dm: DMChannel;
+    "group-dm": DMChannel;
+    directory: Channel;
+    unknown: Channel;
+}
+/** The channel class for a kind (or a union of them). */
+export type ChannelOfKind<K extends keyof ChannelsByKind> = ChannelsByKind[K];

package/dist/structures/index.d.ts

@@ -1,4 +1,5 @@
 /** Resource structures for Discord messages and related entities. */
+import type { MessageCreateOptions, MessageEditOptions } from "@lunibee/types";
 import { BaseStructure, Channel, User } from "./base.js";
 import { GuildMember } from "./resources.js";
 import type { ComponentInteraction } from "./interactions.js";
@@ -54,19 +55,13 @@ export declare class Message extends BaseStructure {
      * snowflake-only `BaseStructure.createdAt` to honour the message `timestamp`. */
     get createdAt(): Date;
     /** Edits this message. @param options Message fields to change. @returns The updated message. @throws {Error} If the message is not attached to a client. */
-    edit(options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<Message>;
+    edit(options: MessageEditOptions): Promise<Message>;
     /** Updates this message using the same resource operation as edit. @param options Message fields to change. @returns The updated message. @throws {Error} If the message is not attached to a client. */
-    update(options: Record<string, unknown> & {
-        content?: string;
-    }): Promise<Message>;
+    update(options: MessageEditOptions): Promise<Message>;
     /** Deletes this message. @param reason Audit-log reason (shown when deleting someone else's message). @returns A promise fulfilled when Discord confirms deletion. @throws {Error} If the message is not attached to a client. */
     delete(reason?: string): Promise<void>;
     /** Replies to this message. @param options Message content or payload. @returns The created reply message. @throws {Error} If the message is not attached to a client. */
-    reply(options: string | (Record<string, unknown> & {
-        content?: string;
-    })): Promise<Message>;
+    reply(options: string | MessageCreateOptions): Promise<Message>;
     /** Crossposts this message. @returns The resulting message. @throws {Error} If the message is not attached to a client. */
     crosspost(): Promise<Message>;
     /**
@@ -115,9 +110,10 @@ export declare class Message extends BaseStructure {
     /** Returns a plain-object snapshot of all message fields. */
     toJSON(): Record<string, unknown>;
 }
-export { GuildMember, Role, TextChannel, Invite, Webhook, WebhookEnum, WebhookType, Emoji, AutoModerationRule, WelcomeScreenChannel, GuildWelcomeScreen, OnboardingPromptOption, OnboardingPrompt, GuildOnboarding, } from "./resources.js";
-export { NewsChannel, DMChannel, VoiceChannel, StageChannel, CategoryChannel, ThreadChannel, ForumChannel, MediaChannel, createChannel, } from "./channels.js";
+export { GuildMember, Role, TextChannel, Invite, Webhook, WebhookEnum, Emoji, AutoModerationRule, WelcomeScreenChannel, GuildWelcomeScreen, OnboardingPromptOption, OnboardingPrompt, GuildOnboarding, } from "./resources.js";
+export { NewsChannel, DMChannel, VoiceChannel, StageChannel, CategoryChannel, ThreadChannel, ForumChannel, MediaChannel, createChannel, type ChannelOfKind, type ChannelsByKind, } from "./channels.js";
 export * from "./interactions.js";
 export { Embed } from "./embed.js";
-export { AuditLog, AuditLogEntry } from "./audit-log.js";
+export { AuditLog, AuditLogEntry, type AuditLogAutoModInfo, type AuditLogInfo, type AuditLogInfoByType, type AuditLogOverwriteInfo, type AuditLogQuery, } from "./audit-log.js";
+export { Sticker, stickerURL } from "./sticker.js";
 export { PermissionsBitField } from "@lunibee/core";