@erinjs/core 1.0.0

package/core/packages/fluxer-core/src/client/EventHandlerRegistry.ts

@@ -0,0 +1,469 @@
+import { Events } from '../util/Events.js';
+import {
+  APIMessage,
+  APIChannel,
+  APIChannelPartial,
+  APIGuild,
+  APIGuildPartial,
+  APIGuildMember,
+  APIInvite,
+  APIUserPartial,
+  APIApplicationCommandInteraction,
+  APIBan,
+} from '@erinjs/types';
+import {
+  GatewayMessageReactionAddDispatchData,
+  GatewayMessageReactionRemoveDispatchData,
+  GatewayMessageReactionRemoveEmojiDispatchData,
+  GatewayMessageReactionRemoveAllDispatchData,
+  GatewayVoiceStateUpdateDispatchData,
+  GatewayVoiceServerUpdateDispatchData,
+  GatewayMessageDeleteDispatchData,
+  GatewayMessageDeleteBulkDispatchData,
+  GatewayGuildBanAddDispatchData,
+  GatewayGuildBanRemoveDispatchData,
+  GatewayInviteCreateDispatchData,
+  GatewayInviteDeleteDispatchData,
+  GatewayGuildRoleCreateDispatchData,
+  GatewayGuildRoleUpdateDispatchData,
+  GatewayGuildRoleDeleteDispatchData,
+  GatewayTypingStartDispatchData,
+  GatewayUserUpdateDispatchData,
+  GatewayGuildMemberRemoveDispatchData,
+} from '@erinjs/types';
+import { Client } from './Client.js';
+import { normalizeGuildPayload } from '../util/guildUtils';
+import { GuildMember } from '../structures/GuildMember';
+import { Message } from '../structures/Message';
+import { MessageReaction } from '../structures/MessageReaction';
+import { Guild } from '../structures/Guild';
+import { Channel, GuildChannel } from '../structures/Channel';
+import { GuildBan } from '../structures/GuildBan';
+import { Role } from '../structures/Role';
+import { Invite } from '../structures/Invite';
+import { GuildEmoji } from '../structures/GuildEmoji';
+
+export type DispatchHandler = (client: Client, data: unknown) => Promise<void>;
+
+const handlers = new Map<string, DispatchHandler>();
+
+function normalizeInviteCreatePayload(
+  client: Client,
+  payload: GatewayInviteCreateDispatchData,
+): APIInvite | null {
+  if (!payload?.code) return null;
+
+  const guildId = payload.guild?.id ?? payload.guild_id ?? '0';
+  const cachedGuild = guildId !== '0' ? client.guilds.get(guildId) : null;
+  const guild: APIGuildPartial = {
+    id: guildId,
+    name: payload.guild?.name ?? cachedGuild?.name ?? 'Unknown Guild',
+    icon: payload.guild?.icon ?? null,
+    banner: payload.guild?.banner ?? null,
+    splash: payload.guild?.splash ?? null,
+    features: payload.guild?.features,
+  };
+
+  const channelId = payload.channel?.id ?? payload.channel_id ?? '0';
+  const cachedChannel = channelId !== '0' ? client.channels.get(channelId) : null;
+  const channel: APIChannelPartial = {
+    id: channelId,
+    type: payload.channel?.type ?? cachedChannel?.type ?? 0,
+    name: payload.channel?.name ?? cachedChannel?.name ?? null,
+    icon: payload.channel?.icon ?? null,
+  };
+
+  return {
+    code: payload.code,
+    type: typeof payload.type === 'number' ? payload.type : 0,
+    guild,
+    channel,
+    inviter: payload.inviter ?? null,
+    member_count: payload.member_count,
+    presence_count: payload.presence_count,
+    expires_at: payload.expires_at,
+    temporary: payload.temporary,
+    created_at: payload.created_at,
+    uses: payload.uses,
+    max_uses: payload.max_uses,
+    max_age: payload.max_age,
+  };
+}
+
+handlers.set('MESSAGE_CREATE', async (client, d) => {
+  const data = d as APIMessage & { member?: APIGuildMember };
+  if (data.guild_id && data.member && data.author) {
+    const guild = client.guilds.get(data.guild_id);
+    if (guild) {
+      const memberData = { ...data.member, user: data.author, guild_id: data.guild_id };
+      const member = new GuildMember(client, memberData, guild);
+      guild.members.set(member.id, member);
+    }
+  }
+  client._addMessageToCache(data.channel_id, data);
+  client.emit(Events.MessageCreate, new Message(client, data));
+});
+
+handlers.set('MESSAGE_UPDATE', async (client, d) => {
+  const partial = d as APIMessage;
+  const cache = client._getMessageCache(partial.channel_id);
+  let oldMessage: Message | null = null;
+  let mergedData: APIMessage = partial;
+
+  if (cache) {
+    const oldData = cache.get(partial.id);
+    if (oldData) {
+      oldMessage = new Message(client, oldData);
+      mergedData = { ...oldData, ...partial } as APIMessage;
+    }
+    cache.set(partial.id, mergedData);
+  }
+
+  const newMessage = new Message(client, mergedData);
+  client.emit(Events.MessageUpdate, oldMessage, newMessage);
+});
+
+handlers.set('MESSAGE_DELETE', async (client, d) => {
+  const data = d as GatewayMessageDeleteDispatchData;
+  client._removeMessageFromCache(data.channel_id, data.id);
+  const channel = client.channels.get(data.channel_id) ?? null;
+  client.emit(Events.MessageDelete, {
+    id: data.id,
+    channelId: data.channel_id,
+    channel,
+    content: data.content ?? null,
+    authorId: data.author_id ?? null,
+  });
+});
+
+handlers.set('MESSAGE_REACTION_ADD', async (client, d) => {
+  const data = d as GatewayMessageReactionAddDispatchData;
+  const reaction = new MessageReaction(client, data);
+  const user = client.getOrCreateUser({
+    id: data.user_id,
+    username: 'Unknown',
+    discriminator: '0',
+  } as APIUserPartial);
+  client.emit(Events.MessageReactionAdd, reaction, user);
+});
+
+handlers.set('MESSAGE_REACTION_REMOVE', async (client, d) => {
+  const data = d as GatewayMessageReactionRemoveDispatchData;
+  const reaction = new MessageReaction(client, data);
+  const user = client.getOrCreateUser({
+    id: data.user_id,
+    username: 'Unknown',
+    discriminator: '0',
+  } as APIUserPartial);
+  client.emit(Events.MessageReactionRemove, reaction, user);
+});
+
+handlers.set('MESSAGE_REACTION_REMOVE_ALL', async (client, d) => {
+  client.emit(Events.MessageReactionRemoveAll, d as GatewayMessageReactionRemoveAllDispatchData);
+});
+
+handlers.set('MESSAGE_REACTION_REMOVE_EMOJI', async (client, d) => {
+  client.emit(
+    Events.MessageReactionRemoveEmoji,
+    d as GatewayMessageReactionRemoveEmojiDispatchData,
+  );
+});
+
+handlers.set('GUILD_CREATE', async (client, d) => {
+  const guildData = normalizeGuildPayload(d as unknown);
+  if (!guildData) return;
+  const guild = new Guild(client, guildData);
+  client.guilds.set(guild.id, guild);
+  const g = d as APIGuild & {
+    channels?: APIChannel[];
+    voice_states?: Array<{ user_id: string; channel_id: string | null }>;
+    members?: Array<APIGuildMember & { user: { id: string }; guild_id?: string }>;
+  };
+  for (const ch of g.channels ?? []) {
+    const channel = Channel.from(client, ch);
+    if (channel) {
+      client.channels.set(channel.id, channel);
+      guild.channels.set(channel.id, channel as GuildChannel);
+    }
+  }
+  for (const m of g.members ?? []) {
+    if (m?.user?.id) {
+      const memberData = { ...m, guild_id: guild.id };
+      const member = new GuildMember(client, memberData, guild);
+      guild.members.set(member.id, member);
+    }
+  }
+  client.emit(Events.GuildCreate, guild);
+  if (g.voice_states?.length) {
+    client.emit(Events.VoiceStatesSync, { guildId: guild.id, voiceStates: g.voice_states });
+  }
+  client._onGuildReceived(guild.id);
+});
+
+handlers.set('GUILD_UPDATE', async (client, d) => {
+  const guildData = normalizeGuildPayload(d as unknown);
+  if (!guildData) return;
+  const old = client.guilds.get(guildData.id);
+  const updated = new Guild(client, guildData);
+  client.guilds.set(updated.id, updated);
+  client.emit(Events.GuildUpdate, old ?? updated, updated);
+});
+
+handlers.set('GUILD_DELETE', async (client, d) => {
+  const g = d as { id: string };
+  const guild = client.guilds.get(g.id);
+  if (guild) {
+    client.guilds.delete(g.id);
+    client.emit(Events.GuildDelete, guild);
+  }
+});
+
+handlers.set('CHANNEL_CREATE', async (client, d) => {
+  const ch = Channel.from(client, d as APIChannel);
+  if (ch) {
+    client.channels.set(ch.id, ch);
+    if ('guildId' in ch && ch.guildId) {
+      const guild = client.guilds.get(ch.guildId);
+      if (guild) guild.channels.set(ch.id, ch as GuildChannel);
+    }
+    client.emit(Events.ChannelCreate, ch as GuildChannel);
+  }
+});
+
+handlers.set('CHANNEL_UPDATE', async (client, d) => {
+  const ch = d as APIChannel;
+  const oldCh = client.channels.get(ch.id);
+  const newCh = Channel.from(client, ch);
+  if (newCh) {
+    client.channels.set(newCh.id, newCh);
+    if ('guildId' in newCh && newCh.guildId) {
+      const guild = client.guilds.get(newCh.guildId);
+      if (guild) guild.channels.set(newCh.id, newCh as GuildChannel);
+    }
+    client.emit(Events.ChannelUpdate, oldCh ?? newCh, newCh);
+  }
+});
+
+handlers.set('CHANNEL_DELETE', async (client, d) => {
+  const ch = d as { id: string; guild_id?: string };
+  const channel = client.channels.get(ch.id);
+  if (channel) {
+    if ('guildId' in channel && channel.guildId) {
+      const guild = client.guilds.get(channel.guildId);
+      if (guild) guild.channels.delete(channel.id);
+    }
+    client.channels.delete(ch.id);
+    client.emit(Events.ChannelDelete, channel);
+  }
+});
+
+handlers.set('GUILD_MEMBER_ADD', async (client, d) => {
+  const data = d as APIGuildMember & { guild_id: string };
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) {
+    const member = new GuildMember(client, data, guild);
+    guild.members.set(member.id, member);
+    client.emit(Events.GuildMemberAdd, member);
+  }
+});
+
+handlers.set('GUILD_MEMBER_UPDATE', async (client, d) => {
+  const data = d as APIGuildMember & { guild_id: string };
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) {
+    const oldM = guild.members.get(data.user.id);
+    const newM = new GuildMember(client, data, guild);
+    guild.members.set(newM.id, newM);
+    client.emit(Events.GuildMemberUpdate, oldM ?? newM, newM);
+  }
+});
+
+handlers.set('GUILD_MEMBER_REMOVE', async (client, d) => {
+  const data = d as GatewayGuildMemberRemoveDispatchData;
+  const guild = client.guilds.get(data.guild_id);
+  if (!guild || !data.user?.id) return;
+
+  let member = guild.members.get(data.user.id);
+  if (member) {
+    guild.members.delete(data.user.id);
+  } else {
+    // Member was never cached (e.g. joined before bot cached guild). Build partial from payload
+    // so leave handlers run for all leaves, not only cached members.
+    const user: APIUserPartial = {
+      ...data.user,
+      id: data.user.id,
+      username: data.user.username ?? 'Unknown',
+      discriminator: data.user.discriminator ?? '0',
+    };
+    const memberData: APIGuildMember & { guild_id?: string } = {
+      user,
+      roles: [],
+      joined_at: new Date(0).toISOString(),
+      nick: null,
+    };
+    member = new GuildMember(client, memberData, guild);
+  }
+  client.emit(Events.GuildMemberRemove, member);
+});
+
+handlers.set('INTERACTION_CREATE', async (client, d) => {
+  client.emit(Events.InteractionCreate, d as APIApplicationCommandInteraction);
+});
+
+handlers.set('VOICE_STATE_UPDATE', async (client, d) => {
+  client.emit(Events.VoiceStateUpdate, d as GatewayVoiceStateUpdateDispatchData);
+});
+
+handlers.set('VOICE_SERVER_UPDATE', async (client, d) => {
+  client.emit(Events.VoiceServerUpdate, d as GatewayVoiceServerUpdateDispatchData);
+});
+
+handlers.set('MESSAGE_DELETE_BULK', async (client, d) => {
+  const data = d as GatewayMessageDeleteBulkDispatchData;
+  for (const id of data.ids ?? []) {
+    client._removeMessageFromCache(data.channel_id, id);
+  }
+  client.emit(Events.MessageDeleteBulk, data);
+});
+
+handlers.set('GUILD_BAN_ADD', async (client, d) => {
+  const data = d as GatewayGuildBanAddDispatchData;
+  const banData: APIBan & { guild_id?: string } = {
+    user: data.user,
+    reason: data.reason ?? null,
+    guild_id: data.guild_id,
+  };
+  const ban = new GuildBan(client, banData, data.guild_id);
+  client.emit(Events.GuildBanAdd, ban);
+});
+
+handlers.set('GUILD_BAN_REMOVE', async (client, d) => {
+  const data = d as GatewayGuildBanRemoveDispatchData;
+  const ban = new GuildBan(client, { ...data, reason: null }, data.guild_id);
+  client.emit(Events.GuildBanRemove, ban);
+});
+
+handlers.set('GUILD_EMOJIS_UPDATE', async (client, d) => {
+  const data = d as {
+    guild_id: string;
+    emojis: Array<{ id: string; name?: string; animated?: boolean }>;
+  };
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) {
+    guild.emojis.clear();
+    for (const e of data.emojis ?? []) {
+      if (!e.id || e.name == null) continue;
+      guild.emojis.set(
+        e.id,
+        new GuildEmoji(
+          client,
+          { id: e.id, name: e.name, animated: e.animated ?? false, guild_id: guild.id },
+          guild.id,
+        ),
+      );
+    }
+  }
+  client.emit(Events.GuildEmojisUpdate, d);
+});
+
+handlers.set('GUILD_STICKERS_UPDATE', async (client, d) => {
+  client.emit(Events.GuildStickersUpdate, d);
+});
+
+handlers.set('GUILD_INTEGRATIONS_UPDATE', async (client, d) => {
+  client.emit(Events.GuildIntegrationsUpdate, d);
+});
+
+handlers.set('GUILD_ROLE_CREATE', async (client, d) => {
+  const data = d as GatewayGuildRoleCreateDispatchData;
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) {
+    guild.roles.set(data.role.id, new Role(client, data.role, guild.id));
+  }
+  client.emit(Events.GuildRoleCreate, data);
+});
+
+handlers.set('GUILD_ROLE_UPDATE', async (client, d) => {
+  const data = d as GatewayGuildRoleUpdateDispatchData;
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) {
+    const existing = guild.roles.get(data.role.id);
+    if (existing) {
+      existing._patch(data.role);
+    } else {
+      guild.roles.set(data.role.id, new Role(client, data.role, guild.id));
+    }
+  }
+  client.emit(Events.GuildRoleUpdate, data);
+});
+
+handlers.set('GUILD_ROLE_DELETE', async (client, d) => {
+  const data = d as GatewayGuildRoleDeleteDispatchData;
+  const guild = client.guilds.get(data.guild_id);
+  if (guild) guild.roles.delete(data.role_id);
+  client.emit(Events.GuildRoleDelete, data);
+});
+
+handlers.set('GUILD_SCHEDULED_EVENT_CREATE', async (client, d) => {
+  client.emit(Events.GuildScheduledEventCreate, d);
+});
+
+handlers.set('GUILD_SCHEDULED_EVENT_UPDATE', async (client, d) => {
+  client.emit(Events.GuildScheduledEventUpdate, d);
+});
+
+handlers.set('GUILD_SCHEDULED_EVENT_DELETE', async (client, d) => {
+  client.emit(Events.GuildScheduledEventDelete, d);
+});
+
+handlers.set('CHANNEL_PINS_UPDATE', async (client, d) => {
+  client.emit(Events.ChannelPinsUpdate, d);
+});
+
+handlers.set('INVITE_CREATE', async (client, d) => {
+  const data = normalizeInviteCreatePayload(client, d as GatewayInviteCreateDispatchData);
+  if (!data) {
+    client.emit(
+      Events.Debug,
+      '[Gateway] INVITE_CREATE payload had no invite code (documented as possibly empty)',
+    );
+    return;
+  }
+
+  client.emit(
+    Events.Debug,
+    `[Gateway] INVITE_CREATE code=${data.code} guild=${data.guild.id} channel=${data.channel.id}`,
+  );
+  client.emit(Events.InviteCreate, new Invite(client, data));
+});
+
+handlers.set('INVITE_DELETE', async (client, d) => {
+  client.emit(Events.InviteDelete, d as GatewayInviteDeleteDispatchData);
+});
+
+handlers.set('TYPING_START', async (client, d) => {
+  client.emit(Events.TypingStart, d as GatewayTypingStartDispatchData);
+});
+
+handlers.set('USER_UPDATE', async (client, d) => {
+  const data = d as GatewayUserUpdateDispatchData;
+  if (client.user?.id === data.id) {
+    client.user!._patch(data);
+  }
+  client.emit(Events.UserUpdate, data);
+});
+
+handlers.set('PRESENCE_UPDATE', async (client, d) => {
+  client.emit(Events.PresenceUpdate, d);
+});
+
+handlers.set('WEBHOOKS_UPDATE', async (client, d) => {
+  client.emit(Events.WebhooksUpdate, d);
+});
+
+handlers.set('RESUMED', async (client) => {
+  client.emit(Events.Resumed);
+});
+
+/** Registry of gateway dispatch event handlers. Add handlers via set() for extensibility. */
+export const eventHandlers = handlers;

package/core/packages/fluxer-core/src/client/GuildManager.ts

@@ -0,0 +1,79 @@
+import { Collection } from '@erinjs/collection';
+import { APIGuild, Routes } from '@erinjs/types';
+import { Client } from './Client.js';
+import { Guild } from '../structures/Guild.js';
+
+/**
+ * Manages guilds with fetch.
+ * Extends Collection so you can use .get(), .set(), .filter(), etc.
+ */
+export class GuildManager extends Collection<string, Guild> {
+  private readonly maxSize: number;
+
+  constructor(private readonly client: Client) {
+    super();
+    this.maxSize = client.options?.cache?.guilds ?? 0;
+  }
+
+  override set(key: string, value: Guild): this {
+    if (this.maxSize > 0 && this.size >= this.maxSize && !this.has(key)) {
+      const firstKey = this.keys().next().value;
+      if (firstKey !== undefined) this.delete(firstKey);
+    }
+    return super.set(key, value);
+  }
+
+  /**
+   * Get a guild from cache or fetch from the API if not present.
+   * Convenience helper to avoid repeating `client.guilds.get(id) ?? (await client.guilds.fetch(id))`.
+   * @param guildId - Snowflake of the guild
+   * @returns The guild, or null if not found
+   * @example
+   * const guild = await client.guilds.resolve(message.guildId);
+   * if (guild) console.log(guild.name);
+   */
+  async resolve(guildId: string): Promise<Guild | null> {
+    return this.get(guildId) ?? this.fetch(guildId);
+  }
+
+  /**
+   * Create a guild. POST /guilds.
+   * @param options - name (required), icon (base64), empty_features
+   * @returns The created guild
+   */
+  async create(options: {
+    name: string;
+    icon?: string | null;
+    empty_features?: boolean;
+  }): Promise<Guild> {
+    const data = await this.client.rest.post<APIGuild>(Routes.guilds(), {
+      body: options,
+      auth: true,
+    });
+    const guild = new Guild(this.client, data);
+    this.set(guild.id, guild);
+    return guild;
+  }
+
+  /**
+   * Fetch a guild by ID from the API (or return from cache if present).
+   * @param guildId - Snowflake of the guild
+   * @returns The guild, or null if not found
+   * @example
+   * const guild = await client.guilds.fetch(guildId);
+   * if (guild) console.log(guild.name);
+   */
+  async fetch(guildId: string): Promise<Guild | null> {
+    const cached = this.get(guildId);
+    if (cached) return cached;
+
+    try {
+      const data = await this.client.rest.get<APIGuild>(Routes.guild(guildId));
+      const guild = new Guild(this.client, data);
+      this.set(guild.id, guild);
+      return guild;
+    } catch {
+      return null;
+    }
+  }
+}

package/core/packages/fluxer-core/src/client/GuildMemberManager.ts

@@ -0,0 +1,91 @@
+import { Collection } from '@erinjs/collection';
+import { APIGuildMember, Routes } from '@erinjs/types';
+import { Guild } from '../structures/Guild.js';
+import { GuildMember } from '../structures/GuildMember.js';
+
+/**
+ * Manages guild members with a Collection-like API.
+ * Extends Collection so you can use .get(), .set(), .filter(), etc.
+ * Provides guild.members.me for Discord.js parity.
+ *
+ * @discordJsCompat https://discord.js.org/docs/packages/discord.js/main/GuildMemberManager
+ */
+export class GuildMemberManager extends Collection<string, GuildMember> {
+  constructor(private readonly guild: Guild) {
+    super();
+  }
+
+  /**
+   * Get a guild member from cache or fetch from the API if not present.
+   * Convenience helper to avoid repeating `guild.members.get(userId) ?? (await guild.fetchMember(userId))`.
+   * @param userId - Snowflake of the user
+   * @returns The guild member
+   * @throws FluxerError with MEMBER_NOT_FOUND if user is not in the guild (404)
+   * @example
+   * const member = await guild.members.resolve(userId);
+   * console.log(member.displayName);
+   */
+  async resolve(userId: string): Promise<GuildMember> {
+    return this.get(userId) ?? this.guild.fetchMember(userId);
+  }
+
+  /**
+   * The current bot user as a GuildMember in this guild.
+   * Returns null if the bot's member is not cached or client.user is null.
+   * Use fetchMe() to load the bot's member when not cached.
+   *
+   * @discordJsCompat https://discord.js.org/docs/packages/discord.js/main/GuildMemberManager
+   * @example
+   * const perms = guild.members.me?.permissions;
+   * if (perms?.has(PermissionFlags.BanMembers)) { ... }
+   */
+  get me(): GuildMember | null {
+    const userId = this.guild.client.user?.id;
+    return userId ? (this.get(userId) ?? null) : null;
+  }
+
+  /**
+   * Fetch the current bot user as a GuildMember in this guild.
+   * Caches the result in guild.members.
+   *
+   * @throws Error if client.user is null (client not ready)
+   * @example
+   * const me = await guild.members.fetchMe();
+   * console.log(me.displayName);
+   */
+  async fetchMe(): Promise<GuildMember> {
+    const userId = this.guild.client.user?.id;
+    if (!userId) {
+      throw new Error('Cannot fetch me: client.user is null (client not ready)');
+    }
+    return this.guild.fetchMember(userId);
+  }
+
+  /**
+   * Fetch guild members with pagination. GET /guilds/{id}/members.
+   * @param options - limit (1-1000), after (user ID for pagination)
+   * @returns Array of GuildMember objects (cached in guild.members)
+   */
+  async fetch(options?: { limit?: number; after?: string }): Promise<GuildMember[]> {
+    const params = new URLSearchParams();
+    if (options?.limit != null) params.set('limit', String(options.limit));
+    if (options?.after) params.set('after', options.after);
+    const qs = params.toString();
+    const url = Routes.guildMembers(this.guild.id) + (qs ? `?${qs}` : '');
+    const data = await this.guild.client.rest.get<
+      APIGuildMember[] | { members?: APIGuildMember[] }
+    >(url, { auth: true });
+    const list = Array.isArray(data) ? data : (data?.members ?? []);
+    const members: GuildMember[] = [];
+    for (const m of list) {
+      const member = new GuildMember(
+        this.guild.client,
+        { ...m, guild_id: this.guild.id },
+        this.guild,
+      );
+      this.set(member.id, member);
+      members.push(member);
+    }
+    return members;
+  }
+}

package/core/packages/fluxer-core/src/client/MessageManager.ts

@@ -0,0 +1,58 @@
+import { APIMessage, Routes } from '@erinjs/types';
+import { FluxerAPIError, RateLimitError } from '@erinjs/rest';
+import { FluxerError } from '../errors/FluxerError.js';
+import { ErrorCodes } from '../errors/ErrorCodes.js';
+import { Client } from './Client.js';
+import { Message } from '../structures/Message';
+
+/**
+ * Manages messages for a channel. Access via channel.messages.
+ * @example
+ * 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!' });
+ */
+export class MessageManager {
+  constructor(
+    private readonly client: Client,
+    private readonly 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 {
+    const data = this.client._getMessageCache(this.channelId)?.get(messageId);
+    return data ? new Message(this.client, data) : 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
+   */
+  async fetch(messageId: string): Promise<Message> {
+    try {
+      const data = await this.client.rest.get<APIMessage>(
+        Routes.channelMessage(this.channelId, messageId),
+      );
+      this.client._addMessageToCache(this.channelId, data);
+      return new Message(this.client, data);
+    } catch (err) {
+      if (err instanceof RateLimitError) throw err;
+      if (err instanceof FluxerAPIError && err.statusCode === 404) {
+        throw new FluxerError(`Message ${messageId} not found in channel ${this.channelId}`, {
+          code: ErrorCodes.MessageNotFound,
+          cause: err,
+        });
+      }
+      throw err instanceof FluxerError
+        ? err
+        : new FluxerError(String(err), { cause: err as Error });
+    }
+  }
+}