@erinjs/core 1.0.0

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

@@ -0,0 +1,122 @@
+import { Collection } from '@erinjs/collection';
+import { Routes } from '@erinjs/types';
+import { APIUserPartial, APIProfileResponse, APIGuildMember } from '@erinjs/types';
+import { Client } from './Client.js';
+import { User } from '../structures/User.js';
+import { GuildMember } from '../structures/GuildMember.js';
+
+/** Result of {@link UsersManager.fetchWithProfile}. */
+export interface FetchedUserWithProfile {
+  /** The user (cached in client.users). */
+  user: User;
+  /** Raw user data from GET /users/{id}. */
+  userData: APIUserPartial;
+  /** Global profile (bio, pronouns, mutual guilds, etc.). Null if unavailable. */
+  globalProfile: APIProfileResponse | null;
+  /** Server-specific profile when guildId was provided. Null if unavailable. */
+  serverProfile: APIProfileResponse | null;
+  /** Guild member when guildId was provided and user is in the guild. Null otherwise. */
+  member: GuildMember | null;
+  /** Raw member data when member exists (for premium_since, etc.). */
+  memberData: (APIGuildMember & { user: { id: string } }) | null;
+}
+
+/**
+ * Manages users with fetch and profile helpers.
+ * Extends Collection so you can use .get(), .set(), .filter(), etc.
+ */
+export class UsersManager extends Collection<string, User> {
+  private readonly maxSize: number;
+
+  constructor(private readonly client: Client) {
+    super();
+    this.maxSize = client.options?.cache?.users ?? 0;
+  }
+
+  override set(key: string, value: User): 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);
+  }
+
+  /**
+   * Fetch a user by ID from the API.
+   * Updates cache if user already exists.
+   * @param userId - Snowflake of the user
+   * @returns The user
+   * @throws FluxerError (or REST error) if user not found
+   * @example
+   * const user = await client.users.fetch(userId);
+   * console.log(user.username);
+   */
+  async fetch(userId: string): Promise<User> {
+    const data = await this.client.rest.get<APIUserPartial>(Routes.user(userId));
+    return this.client.getOrCreateUser(data);
+  }
+
+  /**
+   * Fetch a user with full profile and optional guild context.
+   * Returns user, global profile, server profile (when guildId), and member (when guildId).
+   * Ideal for userinfo commands.
+   * @param userId - Snowflake of the user
+   * @param options - Optional guildId for server profile and member data
+   * @returns User, raw data, profiles, and member (when in guild)
+   * @throws FluxerError (or REST error) if user not found
+   * @example
+   * const { user, globalProfile, serverProfile, member } = await client.users.fetchWithProfile(
+   *   userId,
+   *   { guildId: message.guildId ?? undefined },
+   * );
+   */
+  async fetchWithProfile(
+    userId: string,
+    options?: { guildId?: string | null },
+  ): Promise<FetchedUserWithProfile> {
+    const guildId = options?.guildId ?? undefined;
+
+    const [userData, globalProfileData, serverProfileData, memberData] = await Promise.all([
+      this.client.rest.get<APIUserPartial>(Routes.user(userId)),
+      this.client.rest.get(Routes.userProfile(userId)).catch((): APIProfileResponse | null => null),
+      guildId
+        ? this.client.rest
+            .get(Routes.userProfile(userId, guildId))
+            .catch((): APIProfileResponse | null => null)
+        : Promise.resolve(null),
+      guildId
+        ? this.client.rest
+            .get<APIGuildMember & { user: { id: string } }>(Routes.guildMember(guildId, userId))
+            .catch((): null => null)
+        : Promise.resolve(null),
+    ]);
+
+    const user = this.client.getOrCreateUser(userData);
+    const globalProfile =
+      globalProfileData && typeof globalProfileData === 'object'
+        ? (globalProfileData as APIProfileResponse)
+        : null;
+    const serverProfile =
+      serverProfileData && typeof serverProfileData === 'object'
+        ? (serverProfileData as APIProfileResponse)
+        : null;
+
+    let member: GuildMember | null = null;
+    if (memberData && guildId) {
+      const guild = this.client.guilds.get(guildId) ?? (await this.client.guilds.fetch(guildId));
+      if (guild) {
+        member = new GuildMember(this.client, { ...memberData, guild_id: guildId }, guild);
+        guild.members.set(member.id, member);
+      }
+    }
+
+    return {
+      user,
+      userData,
+      globalProfile,
+      serverProfile,
+      member,
+      memberData: memberData as (APIGuildMember & { user: { id: string } }) | null,
+    };
+  }
+}

package/core/packages/fluxer-core/src/errors/ErrorCodes.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCodes } from './ErrorCodes.js';
+
+describe('ErrorCodes', () => {
+  it('has expected error codes', () => {
+    expect(ErrorCodes.ClientNotReady).toBe('CLIENT_NOT_READY');
+    expect(ErrorCodes.ChannelNotFound).toBe('CHANNEL_NOT_FOUND');
+    expect(ErrorCodes.GuildNotFound).toBe('GUILD_NOT_FOUND');
+    expect(ErrorCodes.EmojiNotFound).toBe('EMOJI_NOT_FOUND');
+  });
+
+  it('has all required codes', () => {
+    const codes = Object.values(ErrorCodes);
+    expect(codes).toContain('CLIENT_NOT_READY');
+    expect(codes).toContain('INVALID_TOKEN');
+    expect(codes).toContain('CHANNEL_NOT_FOUND');
+    expect(codes).toContain('MESSAGE_NOT_FOUND');
+  });
+});

package/core/packages/fluxer-core/src/errors/ErrorCodes.ts

@@ -0,0 +1,12 @@
+export const ErrorCodes = {
+  ClientNotReady: 'CLIENT_NOT_READY',
+  InvalidToken: 'INVALID_TOKEN',
+  AlreadyLoggedIn: 'ALREADY_LOGGED_IN',
+  ChannelNotFound: 'CHANNEL_NOT_FOUND',
+  MessageNotFound: 'MESSAGE_NOT_FOUND',
+  GuildNotFound: 'GUILD_NOT_FOUND',
+  MemberNotFound: 'MEMBER_NOT_FOUND',
+  RoleNotFound: 'ROLE_NOT_FOUND',
+  EmojiNotInGuild: 'EMOJI_NOT_IN_GUILD',
+  EmojiNotFound: 'EMOJI_NOT_FOUND',
+} as const;

package/core/packages/fluxer-core/src/errors/FluxerError.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { FluxerError } from './FluxerError.js';
+import { ErrorCodes } from './ErrorCodes.js';
+
+describe('FluxerError', () => {
+  it('creates error with message', () => {
+    const err = new FluxerError('Something went wrong');
+    expect(err.message).toBe('Something went wrong');
+    expect(err.name).toBe('FluxerError');
+  });
+
+  it('accepts code option', () => {
+    const err = new FluxerError('Not found', { code: ErrorCodes.ChannelNotFound });
+    expect(err.code).toBe(ErrorCodes.ChannelNotFound);
+  });
+
+  it('accepts cause option', () => {
+    const cause = new Error('Original error');
+    const err = new FluxerError('Wrapped', { cause });
+    expect(err.cause).toBe(cause);
+  });
+
+  it('chains code and cause', () => {
+    const cause = new Error('API 404');
+    const err = new FluxerError('Channel not found', {
+      code: ErrorCodes.ChannelNotFound,
+      cause,
+    });
+    expect(err.code).toBe(ErrorCodes.ChannelNotFound);
+    expect(err.cause).toBe(cause);
+  });
+});

package/core/packages/fluxer-core/src/errors/FluxerError.ts

@@ -0,0 +1,15 @@
+export interface FluxerErrorOptions {
+  code?: string;
+  cause?: Error;
+}
+
+export class FluxerError extends Error {
+  readonly code?: string;
+
+  constructor(message: string, options?: FluxerErrorOptions) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.name = 'FluxerError';
+    this.code = options?.code;
+    Object.setPrototypeOf(this, FluxerError.prototype);
+  }
+}

package/core/packages/fluxer-core/src/index.ts

@@ -0,0 +1,85 @@
+export { Client, type ClientEvents, type ClientEventMethods } from './client/Client.js';
+export { ChannelManager } from './client/ChannelManager.js';
+export { GuildMemberManager } from './client/GuildMemberManager.js';
+export { UsersManager, type FetchedUserWithProfile } from './client/UsersManager.js';
+export { MessageManager } from './client/MessageManager.js';
+export { ClientUser } from './client/ClientUser.js';
+export { Base } from './structures/Base.js';
+export { User } from './structures/User.js';
+export { Guild } from './structures/Guild.js';
+export {
+  Channel,
+  GuildChannel,
+  TextChannel,
+  VoiceChannel,
+  CategoryChannel,
+  LinkChannel,
+  DMChannel,
+} from './structures/Channel.js';
+export {
+  Message,
+  type MessageEditOptions,
+  type MessageSendOptions,
+  type ReplyOptions,
+} from './structures/Message.js';
+export type { PartialMessage } from './structures/PartialMessage.js';
+export { MessageReaction } from './structures/MessageReaction.js';
+export { Webhook, type WebhookSendOptions } from './structures/Webhook.js';
+export { GuildMember } from './structures/GuildMember.js';
+export {
+  GuildMemberRoleManager,
+  type RoleResolvable,
+} from './structures/GuildMemberRoleManager.js';
+export { Role } from './structures/Role.js';
+export { Invite } from './structures/Invite.js';
+export { GuildBan } from './structures/GuildBan.js';
+export { GuildEmoji } from './structures/GuildEmoji.js';
+export { GuildSticker } from './structures/GuildSticker.js';
+export { Events } from './util/Events.js';
+export {
+  MessageCollector,
+  type MessageCollectorOptions,
+  type MessageCollectorEndReason,
+} from './util/MessageCollector.js';
+export {
+  ReactionCollector,
+  type ReactionCollectorOptions,
+  type ReactionCollectorEndReason,
+  type CollectedReaction,
+} from './util/ReactionCollector.js';
+export { FluxerError, type FluxerErrorOptions } from './errors/FluxerError.js';
+export { ErrorCodes } from './errors/ErrorCodes.js';
+
+// Re-export builders for convenience
+export { EmbedBuilder, MessagePayload, AttachmentBuilder } from '@erinjs/builders';
+
+// Re-export Routes, GatewayOpcodes, MessageAttachmentFlags for REST/gateway API calls
+export { Routes, GatewayOpcodes, MessageAttachmentFlags } from '@erinjs/types';
+
+// Re-export Tenor URL resolver and mention parsers for embeds and moderation
+export { resolveTenorToImageUrl, parseUserMention, parsePrefixCommand } from '@erinjs/util';
+
+// Re-export permission helpers for role/member permission checks
+export {
+  PermissionsBitField,
+  PermissionFlags,
+  resolvePermissionsToBitfield,
+  UserFlagsBitField,
+  UserFlagsBits,
+  type PermissionString,
+  type PermissionResolvable,
+  type UserFlagsString,
+  type UserFlagsResolvable,
+} from '@erinjs/util';
+
+// CDN URL helpers for avatars, banners, etc. (works with raw API data or User objects)
+export { CDN_URL, STATIC_CDN_URL } from './util/Constants.js';
+export {
+  cdnAvatarURL,
+  cdnDisplayAvatarURL,
+  cdnBannerURL,
+  cdnMemberAvatarURL,
+  cdnMemberBannerURL,
+  cdnDefaultAvatarURL,
+} from './util/cdn.js';
+export type { CdnUrlOptions } from './util/cdn.js';

package/core/packages/fluxer-core/src/structures/Base.ts

@@ -0,0 +1,7 @@
+import { Client } from '../client/Client.js';
+
+/** Base class for all Fluxer structures. Provides the client reference. */
+export abstract class Base {
+  /** The client instance this structure belongs to. */
+  abstract readonly client: Client;
+}