@fluxerjs/core 1.2.1 → 1.2.3

package/dist/index.d.mts

@@ -6,9 +6,15 @@ export { GatewayOpcodes, MessageAttachmentFlags, Routes } from '@fluxerjs/types'
 import { Collection } from '@fluxerjs/collection';
 import { EmbedBuilder } from '@fluxerjs/builders';
 export { AttachmentBuilder, EmbedBuilder, MessagePayload } from '@fluxerjs/builders';
-import { PermissionResolvable } from '@fluxerjs/util';
+import { PermissionsBitField, PermissionResolvable, BitField } from '@fluxerjs/util';
 export { PermissionFlags, PermissionResolvable, PermissionString, PermissionsBitField, UserFlagsBitField, UserFlagsBits, UserFlagsResolvable, UserFlagsString, parsePrefixCommand, parseUserMention, resolvePermissionsToBitfield, resolveTenorToImageUrl } from '@fluxerjs/util';
 
+/** Resolved file data (after URL fetch). Used internally by REST layer. */
+interface ResolvedMessageFile {
+    name: string;
+    data: Blob | ArrayBuffer | Uint8Array | Buffer;
+    filename?: string;
+}
 /** File data for message attachment uploads. Use `data` for buffers or `url` to fetch from a URL. */
 type MessageFileData = {
     name: string;
@@ -31,7 +37,7 @@ interface MessageAttachmentMeta {
 /** Options for sending a message (content, embeds, files). Used by Message.send, Channel.send, ChannelManager.send.
  * EmbedBuilder instances are auto-converted to API format—no need to call .toJSON().
  */
-type MessageSendOptions = string | {
+type MessageSendOptions = {
     content?: string;
     /** EmbedBuilder instances are auto-converted; raw APIEmbed also supported. */
     embeds?: (APIEmbed | EmbedBuilder)[];
@@ -39,7 +45,23 @@ type MessageSendOptions = string | {
     files?: MessageFileData[];
     /** Attachment metadata for files (id = index). Use when files are provided. */
     attachments?: MessageAttachmentMeta[];
+    /** Message flags (e.g. MessageFlags.SuppressNotifications for reply without ping). */
+    flags?: number;
 };
+/** API-ready body from MessageSendOptions or text content (serializes EmbedBuilder, includes attachments when files present). */
+interface SendBodyResult {
+    content?: string;
+    embeds?: APIEmbed[];
+    attachments?: Array<{
+        id: number;
+        filename: string;
+        title?: string | null;
+        description?: string | null;
+        flags?: number;
+    }>;
+    /** Message flags (e.g. SuppressNotifications for reply without ping). */
+    flags?: number;
+}
 
 /** Base class for all Fluxer structures. Provides the client reference. */
 declare abstract class Base {
@@ -112,7 +134,7 @@ declare class Role extends Base {
     name: string;
     color: number;
     position: number;
-    permissions: string;
+    _permissions: string;
     hoist: boolean;
     mentionable: boolean;
     unicodeEmoji: string | null;
@@ -122,19 +144,11 @@ declare class Role extends Base {
     /** @param data - API role from GET /guilds/{id}/roles or gateway role events */
     /** @param guildId - The guild this role belongs to */
     constructor(client: Client, data: APIRole, guildId: string);
+    get permissions(): PermissionsBitField;
     /** Update mutable fields from fresh API data. Used by edit and gateway events. */
     _patch(data: Partial<APIRole>): void;
     /** Returns a mention string (e.g. `<@&123456>`). */
     toString(): string;
-    /**
-     * Check if this role has a permission. Administrator grants all permissions.
-     * @param permission - Permission flag, name, or resolvable
-     * @returns true if the role has the permission
-     * @example
-     * if (role.has(PermissionFlags.BanMembers)) { ... }
-     * if (role.has('ManageChannels')) { ... }
-     */
-    has(permission: PermissionResolvable): boolean;
     /**
      * Edit this role.
      * Requires Manage Roles permission.
@@ -314,9 +328,7 @@ declare class GuildMember extends Base {
      * const perms = member.permissions;
      * if (perms.has(PermissionFlags.BanMembers)) { ... }
      */
-    get permissions(): {
-        has(permission: PermissionResolvable): boolean;
-    };
+    get permissions(): BitField<"CreateInstantInvite" | "KickMembers" | "BanMembers" | "Administrator" | "ManageChannels" | "ManageGuild" | "AddReactions" | "ViewAuditLog" | "PrioritySpeaker" | "Stream" | "ViewChannel" | "SendMessages" | "SendTtsMessages" | "ManageMessages" | "EmbedLinks" | "AttachFiles" | "ReadMessageHistory" | "MentionEveryone" | "UseExternalEmojis" | "Connect" | "Speak" | "MuteMembers" | "DeafenMembers" | "MoveMembers" | "UseVad" | "ChangeNickname" | "ManageNicknames" | "ManageRoles" | "ManageWebhooks" | "ManageEmojisAndStickers" | "ManageExpressions" | "UseExternalStickers" | "ModerateMembers" | "CreateExpressions" | "PinMessages" | "BypassSlowmode" | "UpdateRtcRegion">;
     /**
      * Compute the member's effective permissions in a guild channel.
      * Applies role permissions and channel overwrites.
@@ -326,9 +338,7 @@ declare class GuildMember extends Base {
      * const perms = member.permissionsIn(channel);
      * if (perms.has(PermissionFlags.SendMessages)) { ... }
      */
-    permissionsIn(channel: GuildChannel): {
-        has(permission: PermissionResolvable): boolean;
-    };
+    permissionsIn(channel: GuildChannel): BitField<"CreateInstantInvite" | "KickMembers" | "BanMembers" | "Administrator" | "ManageChannels" | "ManageGuild" | "AddReactions" | "ViewAuditLog" | "PrioritySpeaker" | "Stream" | "ViewChannel" | "SendMessages" | "SendTtsMessages" | "ManageMessages" | "EmbedLinks" | "AttachFiles" | "ReadMessageHistory" | "MentionEveryone" | "UseExternalEmojis" | "Connect" | "Speak" | "MuteMembers" | "DeafenMembers" | "MoveMembers" | "UseVad" | "ChangeNickname" | "ManageNicknames" | "ManageRoles" | "ManageWebhooks" | "ManageEmojisAndStickers" | "ManageExpressions" | "UseExternalStickers" | "ModerateMembers" | "CreateExpressions" | "PinMessages" | "BypassSlowmode" | "UpdateRtcRegion">;
     private _computeBasePermissions;
 }
 
@@ -908,6 +918,23 @@ interface MessageEditOptions {
     /** New embeds (replaces existing) */
     embeds?: (APIEmbed | EmbedBuilder)[];
 }
+type MessagePayload = {
+    files?: ResolvedMessageFile[];
+    body: SendBodyResult & {
+        message_reference?: APIMessageReference;
+        flags?: number;
+    };
+};
+/** Options for message.reply() — ping toggle and reply-to-different-message. */
+interface ReplyOptions {
+    /** Whether to ping the replied-to user (default true). Use false to suppress the mention notification. */
+    ping?: boolean;
+    /** Reply to a different message instead of this one. Default: this message. */
+    replyTo?: Message | {
+        channelId: string;
+        messageId: string;
+    };
+}
 
 /** Represents a message in a channel. */
 declare class Message extends Base {
@@ -940,8 +967,11 @@ declare class Message extends Base {
     readonly mentionRoles: string[];
     /** Client-side nonce for acknowledgment. Null if not provided. */
     readonly nonce: string | null;
-    /** Channel where this message was sent. Resolved from cache; null if not cached (e.g. DM channel not in cache). */
-    get channel(): Channel | null;
+    /**
+     * Channel where this message was sent. Resolved from cache; null if not cached.
+     * Messages can only exist in text-based channels (text, DM, announcement), so this always has send() when non-null.
+     */
+    get channel(): (TextChannel | DMChannel | GuildChannel) | null;
     /** Guild where this message was sent. Resolved from cache; null for DMs or if not cached. */
     get guild(): Guild | null;
     /**
@@ -965,7 +995,7 @@ declare class Message extends Base {
      * await message.send({ embeds: [embed] }); // EmbedBuilder auto-converted
      * await message.send({ content: 'File', files: [{ name: 'data.txt', data }] });
      */
-    send(options: MessageSendOptions): Promise<Message>;
+    send(options: string | MessageSendOptions): Promise<Message>;
     /**
      * Send a message to a specific channel. Use for logging, forwarding, or sending to another channel in the guild.
      * @param channelId - Snowflake of the target channel (e.g. log channel ID)
@@ -977,12 +1007,21 @@ declare class Message extends Base {
     sendTo(channelId: string, options: MessageSendOptions): Promise<Message>;
     /**
      * Reply to this message (shows as a reply in the client).
-     * @param options - Text content or object with content, embeds, and/or files
+     * @param options - Text content or object with content, embeds, and/or reply options (ping, replyTo)
      * @example
      * await message.reply('Pong!');
      * await message.reply({ embeds: [embed] });
-     */
-    reply(options: MessageSendOptions): Promise<Message>;
+     * await message.reply('No ping!', { ping: false });
+     * await message.reply({ content: 'Reply to other', replyTo: otherMessage });
+     */
+    reply(options: string | (MessageSendOptions & ReplyOptions), replyOptions?: ReplyOptions): Promise<Message>;
+    /** Exposed for testing purposes, use Message.reply() or send() for normal use */
+    static _createMessageBody(content: string | MessageSendOptions, referenced_message?: {
+        channel_id: string;
+        message_id: string;
+        guild_id?: string;
+    }, ping?: boolean): Promise<MessagePayload>;
+    _send(payload: MessagePayload): Promise<Message>;
     /**
      * Edit this message. Only the author (or admins) can edit.
      * @param options - New content and/or embeds
@@ -1077,15 +1116,23 @@ declare class Message extends Base {
 /**
  * Manages messages for a channel. Access via channel.messages.
  * @example
- * const message = await channel.messages.fetch(messageId);
+ * const message = channel.messages.get(messageId);  // from cache (if enabled)
+ * const message = await channel.messages.fetch(messageId);  // from API
  * if (message) await message.edit({ content: 'Updated!' });
  */
 declare class MessageManager {
     private readonly client;
     private readonly channelId;
     constructor(client: Client, channelId: string);
+    /**
+     * Get a message from cache. Returns undefined if not cached or caching is disabled.
+     * Requires options.cache.messages > 0.
+     * @param messageId - Snowflake of the message
+     */
+    get(messageId: string): Message | undefined;
     /**
      * Fetch a message by ID from this channel.
+     * When message caching is enabled, the fetched message is added to the cache.
      * @param messageId - Snowflake of the message
      * @returns The message
      * @throws FluxerError with MESSAGE_NOT_FOUND if the message does not exist
@@ -1162,11 +1209,12 @@ declare class Invite extends Base {
 /** Base class for all channel types. */
 declare abstract class Channel extends Base {
     /** Whether this channel has a send method (TextChannel, DMChannel). */
-    isSendable(): this is TextChannel | DMChannel;
+    isTextBased(): this is TextChannel | DMChannel;
     /** Whether this channel is a DM or Group DM. */
-    isDM(): boolean;
+    isDM(): this is DMChannel;
     /** Whether this channel is voice-based (VoiceChannel). */
-    isVoice(): boolean;
+    isVoice(): this is VoiceChannel;
+    isLink(): this is LinkChannel;
     /** Create a DM channel from API data (type DM or GroupDM). */
     static createDM(client: Client, data: APIChannelPartial): DMChannel;
     readonly client: Client;
@@ -1200,6 +1248,12 @@ declare abstract class Channel extends Base {
      * Send a typing indicator to the channel. Lasts ~10 seconds.
      */
     sendTyping(): Promise<void>;
+    /**
+     * Whether the bot can send messages in this channel.
+     * For DMs: always true (when the channel exists).
+     * For guild channels: checks ViewChannel and SendMessages permissions via guild.members.me.
+     */
+    canSendMessage(): boolean;
 }
 declare class GuildChannel extends Channel {
     readonly guildId: string;
@@ -1249,6 +1303,17 @@ declare class GuildChannel extends Channel {
         allow?: string;
         deny?: string;
     }): Promise<void>;
+    /**
+     * Whether the bot can send messages in this channel.
+     * Checks ViewChannel and SendMessages via guild.members.me permissions.
+     * Returns false if guild or bot member not cached.
+     */
+    canSendMessage(): boolean;
+    /**
+     * Send a message to this guild channel.
+     * Works for text and announcement channels. Voice/category/link channels will fail at the API.
+     */
+    send(options: MessageSendOptions): Promise<Message>;
     /**
      * Remove a permission overwrite. DELETE /channels/{id}/permissions/{overwriteId}.
      */
@@ -1326,7 +1391,7 @@ declare class VoiceChannel extends GuildChannel {
     constructor(client: Client, data: APIChannel);
 }
 declare class LinkChannel extends GuildChannel {
-    url?: string | null;
+    url: string | null;
     constructor(client: Client, data: APIChannel);
 }
 /** DM channel (direct message between bot and a user). */
@@ -1395,7 +1460,7 @@ declare class ChannelManager extends Collection<string, Channel | GuildChannel>
      * @throws FluxerError with CHANNEL_NOT_FOUND if the channel does not exist
      * @example
      * const channel = await client.channels.resolve(message.channelId);
-     * if (channel?.isSendable()) await channel.send('Hello!');
+     * if (channel?.isTextBased()) await channel.send('Hello!');
      */
     resolve(channelId: string): Promise<Channel>;
     /**
@@ -1405,7 +1470,7 @@ declare class ChannelManager extends Collection<string, Channel | GuildChannel>
      * @throws FluxerError with CHANNEL_NOT_FOUND if the channel does not exist
      * @example
      * const channel = await client.channels.fetch(channelId);
-     * if (channel?.isSendable()) await channel.send('Hello!');
+     * if (channel?.isTextBased()) await channel.send('Hello!');
      */
     fetch(channelId: string): Promise<Channel>;
     /**
@@ -1431,7 +1496,7 @@ declare class ChannelManager extends Collection<string, Channel | GuildChannel>
      * await client.channels.send(channelId, { embeds: [embed] });
      * await client.channels.send(channelId, { content: 'Report', files: [{ name: 'log.txt', data }] });
      */
-    send(channelId: string, payload: MessageSendOptions): Promise<Message>;
+    send(channelId: string, payload: string | MessageSendOptions): Promise<Message>;
 }
 
 /**
@@ -1479,6 +1544,8 @@ interface CacheSizeLimits {
     channels?: number;
     guilds?: number;
     users?: number;
+    /** Max messages per channel to cache. Enables channel.messages.get() and oldMessage in messageUpdate. 0 = disabled. */
+    messages?: number;
 }
 interface ClientOptions {
     rest?: Partial<ConstructorParameters<typeof REST>[0]>;
@@ -1486,6 +1553,8 @@ interface ClientOptions {
     intents?: number;
     /** Suppress the warning when intents are set (Fluxer does not support intents yet). */
     suppressIntentWarning?: boolean;
+    /** When true, delay the Ready event until all guilds from READY (including unavailable) have been received via GUILD_CREATE. Default: false. */
+    waitForGuilds?: boolean;
     /** Cache size limits (channels, guilds, users). When exceeded, oldest entries are evicted. Omit or 0 = unbounded. */
     cache?: CacheSizeLimits;
     /** Initial presence (status, custom_status, etc.) sent on identify. Can also update via PresenceUpdate after connect. */
@@ -1720,6 +1789,10 @@ declare class Client extends EventEmitter {
     /** Timestamp when the client became ready. Null until READY is received. */
     readyAt: Date | null;
     private _ws;
+    /** When waitForGuilds, set of guild IDs we're waiting for GUILD_CREATE on. Null when not waiting. */
+    _pendingGuildIds: Set<string> | null;
+    /** Per-channel message cache (channelId -> messageId -> APIMessage). Used when options.cache.messages > 0. */
+    private _messageCaches;
     /** @param options - Token, REST config, WebSocket, presence, etc. */
     constructor(options?: ClientOptions);
     /**
@@ -1762,11 +1835,25 @@ declare class Client extends EventEmitter {
     /**
      * Send a message to any channel by ID. Shorthand for client.channels.send().
      * Works even when the channel is not cached.
+     * @deprecated Use client.channels.send(channelId, payload).
      */
-    sendToChannel(channelId: string, payload: string | {
-        content?: string;
-        embeds?: APIEmbed[];
-    }): Promise<Message>;
+    sendToChannel(channelId: string, payload: string | MessageSendOptions): Promise<Message>;
+    /**
+     * Get the message cache for a channel. Returns null if message caching is disabled.
+     * Used by MessageManager.get() and event handlers.
+     * @internal
+     */
+    _getMessageCache(channelId: string): Map<string, APIMessage> | null;
+    /**
+     * Add a message to the channel cache. Evicts oldest (FIFO) when over limit.
+     * @internal
+     */
+    _addMessageToCache(channelId: string, data: APIMessage): void;
+    /**
+     * Remove a message from the channel cache.
+     * @internal
+     */
+    _removeMessageFromCache(channelId: string, messageId: string): void;
     /**
      * Get or create a User from API data. Caches in client.users.
      * Updates existing user's username, avatar, etc. when fresh data is provided.
@@ -1786,6 +1873,16 @@ declare class Client extends EventEmitter {
      * @param token - Bot token (e.g. from FLUXER_BOT_TOKEN)
      */
     login(token: string): Promise<string>;
+    /**
+     * Called when all guilds have been received (or immediately if not waiting).
+     * Sets readyAt, emits Ready, clears pending state.
+     */
+    _finalizeReady(): void;
+    /**
+     * Called by GUILD_CREATE handler when waitForGuilds is enabled.
+     * Removes guild from pending set; when empty, finalizes ready.
+     */
+    _onGuildReceived(guildId: string): void;
     /** Disconnect from the gateway and clear cached data. */
     destroy(): Promise<void>;
     /** Returns true if the client has received Ready and `user` is set. */
@@ -1891,4 +1988,4 @@ declare function cdnMemberBannerURL(guildId: string, userId: string, bannerHash:
  */
 declare function cdnDefaultAvatarURL(userIdOrIndex: string | number): string;
 
-export { Base, CDN_URL, CategoryChannel, type CdnUrlOptions, Channel, ChannelManager, Client, type ClientEventMethods, type ClientEvents, ClientUser, type CollectedReaction, DMChannel, ErrorCodes, Events, type FetchedUserWithProfile, FluxerError, type FluxerErrorOptions, Guild, GuildBan, GuildChannel, GuildEmoji, GuildMember, GuildMemberManager, GuildMemberRoleManager, GuildSticker, Invite, LinkChannel, Message, MessageCollector, type MessageCollectorEndReason, type MessageCollectorOptions, type MessageEditOptions, MessageManager, MessageReaction, type MessageSendOptions, type PartialMessage, ReactionCollector, type ReactionCollectorEndReason, type ReactionCollectorOptions, Role, type RoleResolvable, STATIC_CDN_URL, TextChannel, User, UsersManager, VoiceChannel, Webhook, type WebhookSendOptions, cdnAvatarURL, cdnBannerURL, cdnDefaultAvatarURL, cdnDisplayAvatarURL, cdnMemberAvatarURL, cdnMemberBannerURL };
+export { Base, CDN_URL, CategoryChannel, type CdnUrlOptions, Channel, ChannelManager, Client, type ClientEventMethods, type ClientEvents, ClientUser, type CollectedReaction, DMChannel, ErrorCodes, Events, type FetchedUserWithProfile, FluxerError, type FluxerErrorOptions, Guild, GuildBan, GuildChannel, GuildEmoji, GuildMember, GuildMemberManager, GuildMemberRoleManager, GuildSticker, Invite, LinkChannel, Message, MessageCollector, type MessageCollectorEndReason, type MessageCollectorOptions, type MessageEditOptions, MessageManager, MessageReaction, type MessageSendOptions, type PartialMessage, ReactionCollector, type ReactionCollectorEndReason, type ReactionCollectorOptions, type ReplyOptions, Role, type RoleResolvable, STATIC_CDN_URL, TextChannel, User, UsersManager, VoiceChannel, Webhook, type WebhookSendOptions, cdnAvatarURL, cdnBannerURL, cdnDefaultAvatarURL, cdnDisplayAvatarURL, cdnMemberAvatarURL, cdnMemberBannerURL };