@erinjs/core 1.0.0

package/core/packages/fluxer-core/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@erinjs/core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.4",
+  "description": "A fully-featured SDK for Fluxer bots",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blstmo-abandoned-us-for-the-milk/core.git",
+    "directory": "packages/fluxer-core"
+  },
+  "bugs": "https://github.com/blstmo-abandoned-us-for-the-milk/core/issues",
+  "homepage": "https://github.com/blstmo-abandoned-us-for-the-milk/core#readme",
+  "keywords": [
+    "fluxer",
+    "discord",
+    "sdk",
+    "bot",
+    "api"
+  ],
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --max-warnings 0 --config ../../eslint.config.js",
+    "lint:fix": "eslint src --fix --config ../../eslint.config.js",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@erinjs/rest": "workspace:*",
+    "@erinjs/ws": "workspace:*",
+    "@erinjs/builders": "workspace:*",
+    "@erinjs/collection": "workspace:*",
+    "@erinjs/util": "workspace:*",
+    "@erinjs/types": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

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

@@ -0,0 +1,143 @@
+import { Collection } from '@erinjs/collection';
+import { APIChannel, APIMessage, Routes } from '@erinjs/types';
+import { emitDeprecationWarning } from '@erinjs/util';
+import { FluxerAPIError, RateLimitError } from '@erinjs/rest';
+import { FluxerError } from '../errors/FluxerError.js';
+import { ErrorCodes } from '../errors/ErrorCodes.js';
+import { buildSendBody, resolveMessageFiles } from '../util/messageUtils.js';
+import { MessageSendOptions } from '../util/messageUtils.js';
+import { Client } from './Client.js';
+import { Channel, GuildChannel } from '../structures/Channel.js';
+import { Message } from '../structures/Message';
+
+/**
+ * Manages channels with fetch and send.
+ * Extends Collection so you can use .get(), .set(), .filter(), etc.
+ */
+export class ChannelManager extends Collection<string, Channel | GuildChannel> {
+  private readonly maxSize: number;
+
+  constructor(private readonly client: Client) {
+    super();
+    this.maxSize = client.options?.cache?.channels ?? 0;
+  }
+
+  override set(key: string, value: Channel): 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 channel from cache or fetch from the API if not present.
+   * Convenience helper to avoid repeating `client.channels.get(id) ?? (await client.channels.fetch(id))`.
+   * @param channelId - Snowflake of the channel
+   * @returns The channel
+   * @throws FluxerError with CHANNEL_NOT_FOUND if the channel does not exist
+   * @example
+   * const channel = await client.channels.resolve(message.channelId);
+   * if (channel?.isTextBased()) await channel.send('Hello!');
+   */
+  async resolve(channelId: string): Promise<Channel> {
+    return this.get(channelId) ?? this.fetch(channelId);
+  }
+
+  /**
+   * Fetch a channel by ID from the API (or return from cache if present).
+   * @param channelId - Snowflake of the channel
+   * @returns The channel
+   * @throws FluxerError with CHANNEL_NOT_FOUND if the channel does not exist
+   * @example
+   * const channel = await client.channels.fetch(channelId);
+   * if (channel?.isTextBased()) await channel.send('Hello!');
+   */
+  async fetch(channelId: string): Promise<Channel> {
+    const cached = this.get(channelId);
+    if (cached) return cached;
+
+    try {
+      const data = await this.client.rest.get<APIChannel>(Routes.channel(channelId));
+      const channel = Channel.fromOrCreate(this.client, data);
+      if (!channel) {
+        throw new FluxerError('Channel data invalid or unsupported type', {
+          code: ErrorCodes.ChannelNotFound,
+        });
+      }
+      this.set(channel.id, channel);
+      if ('guildId' in channel) {
+        const guild = this.client.guilds.get(channel.guildId);
+        if (guild) guild.channels.set(channel.id, channel);
+      }
+      return channel;
+    } catch (err) {
+      if (err instanceof RateLimitError) throw err;
+      if (err instanceof FluxerAPIError && err.statusCode === 404) {
+        throw new FluxerError(`Channel ${channelId} not found`, {
+          code: ErrorCodes.ChannelNotFound,
+          cause: err,
+        });
+      }
+      throw err instanceof FluxerError
+        ? err
+        : new FluxerError(String(err), { cause: err as Error });
+    }
+  }
+
+  /**
+   * Fetch a message by ID from the API.
+   * @param channelId - Snowflake of the channel
+   * @param messageId - Snowflake of the message
+   * @returns The message
+   * @throws FluxerError with MESSAGE_NOT_FOUND if the message does not exist
+   * @deprecated Use channel.messages.fetch(messageId). Prefer (await client.channels.resolve(channelId))?.messages?.fetch(messageId).
+   * @example
+   * const channel = await client.channels.resolve(channelId);
+   * const message = await channel?.messages?.fetch(messageId);
+   */
+  async fetchMessage(channelId: string, messageId: string): Promise<Message> {
+    emitDeprecationWarning(
+      'ChannelManager.fetchMessage()',
+      'Use channel.messages.fetch(messageId). Prefer (await client.channels.resolve(channelId))?.messages?.fetch(messageId).',
+    );
+    try {
+      const data = await this.client.rest.get<APIMessage>(
+        Routes.channelMessage(channelId, messageId),
+      );
+      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 ${channelId}`, {
+          code: ErrorCodes.MessageNotFound,
+          cause: err,
+        });
+      }
+      throw err instanceof FluxerError
+        ? err
+        : new FluxerError(String(err), { cause: err as Error });
+    }
+  }
+
+  /**
+   * Send a message to a channel by ID. Works even when the channel is not cached.
+   * Skips the fetch when you only need to send.
+   * @param channelId - Snowflake of the channel (text channel or DM)
+   * @param payload - Text content or object with content, embeds, and/or files
+   * @returns The created message
+   * @example
+   * await client.channels.send(logChannelId, 'User joined!');
+   * await client.channels.send(channelId, { embeds: [embed] });
+   * await client.channels.send(channelId, { content: 'Report', files: [{ name: 'log.txt', data }] });
+   */
+  async send(channelId: string, payload: string | MessageSendOptions): Promise<Message> {
+    const opts = typeof payload === 'string' ? { content: payload } : payload;
+    const body = buildSendBody(payload);
+    const files = opts.files?.length ? await resolveMessageFiles(opts.files) : undefined;
+    const postOptions = files?.length ? { body, files } : { body };
+    const data = await this.client.rest.post(Routes.channelMessages(channelId), postOptions);
+    this.client._addMessageToCache(channelId, data as APIMessage);
+    return new Message(this.client, data as APIMessage);
+  }
+}

package/core/packages/fluxer-core/src/client/Client.gateway.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Routes } from '@erinjs/types';
+import { Client } from './Client.js';
+import { Events } from '../util/Events.js';
+import { Invite } from '../structures/Invite.js';
+
+describe('Client gateway helpers and dispatch', () => {
+  let client: Client;
+
+  beforeEach(() => {
+    client = new Client();
+  });
+
+  it('fetchGatewayInfo() fetches gateway metadata from /gateway/bot', async () => {
+    const gatewayInfo = {
+      url: 'wss://gateway.fluxer.app',
+      shards: 2,
+      session_start_limit: {
+        total: 1000,
+        remaining: 999,
+        reset_after: 60000,
+        max_concurrency: 1,
+      },
+    };
+    const get = vi.spyOn(client.rest, 'get').mockResolvedValue(gatewayInfo);
+
+    const result = await client.fetchGatewayInfo();
+
+    expect(get).toHaveBeenCalledWith(Routes.gatewayBot());
+    expect(result).toEqual(gatewayInfo);
+  });
+
+  it('emits InviteCreate for partial INVITE_CREATE payloads and logs debug metadata', async () => {
+    const emit = vi.spyOn(client, 'emit');
+
+    await (
+      client as unknown as { handleDispatch: (payload: unknown) => Promise<void> }
+    ).handleDispatch({
+      op: 0,
+      t: 'INVITE_CREATE',
+      d: {
+        code: 'abc123',
+        guild_id: 'g1',
+        channel_id: 'c1',
+      },
+    });
+
+    const inviteCall = emit.mock.calls.find((call) => call[0] === Events.InviteCreate);
+    expect(inviteCall).toBeTruthy();
+    const invite = inviteCall?.[1] as Invite;
+    expect(invite).toBeInstanceOf(Invite);
+    expect(invite.code).toBe('abc123');
+    expect(invite.guild.id).toBe('g1');
+    expect(invite.channel.id).toBe('c1');
+
+    const debugCall = emit.mock.calls.find(
+      (call) => call[0] === Events.Debug && String(call[1]).includes('INVITE_CREATE code=abc123'),
+    );
+    expect(debugCall).toBeTruthy();
+  });
+
+  it('ignores malformed INVITE_CREATE payloads without code and logs debug message', async () => {
+    const emit = vi.spyOn(client, 'emit');
+
+    await (
+      client as unknown as { handleDispatch: (payload: unknown) => Promise<void> }
+    ).handleDispatch({
+      op: 0,
+      t: 'INVITE_CREATE',
+      d: {
+        guild_id: 'g1',
+        channel_id: 'c1',
+      },
+    });
+
+    expect(emit.mock.calls.some((call) => call[0] === Events.InviteCreate)).toBe(false);
+    const debugCall = emit.mock.calls.find(
+      (call) =>
+        call[0] === Events.Debug &&
+        String(call[1]).includes('INVITE_CREATE payload had no invite code'),
+    );
+    expect(debugCall).toBeTruthy();
+  });
+});

package/core/packages/fluxer-core/src/client/Client.resolveEmoji.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Client } from './Client.js';
+
+describe('Client.resolveEmoji', () => {
+  let client: Client;
+
+  beforeEach(() => {
+    client = new Client();
+    vi.spyOn(client.rest, 'get').mockResolvedValue([]);
+  });
+
+  it('resolves unicode shortcode :heart: to raw unicode (for URL encoding by route)', async () => {
+    const result = await client.resolveEmoji(':heart:');
+    expect(result).toBeTruthy();
+    expect(typeof result).toBe('string');
+    expect(result).not.toMatch(/^%.*%$/); // should NOT be pre-encoded
+    expect(client.rest.get).not.toHaveBeenCalled();
+  });
+
+  it('resolves object with id without guild lookup', async () => {
+    const result = await client.resolveEmoji({
+      name: 'custom',
+      id: '123456789012345678',
+    });
+    expect(result).toContain('custom');
+    expect(result).toContain('123456789012345678');
+  });
+
+  it('resolves name:id string format', async () => {
+    const result = await client.resolveEmoji('CustomEmoji:123456789012345678');
+    expect(result).toContain('CustomEmoji');
+    expect(result).toContain('123456789012345678');
+  });
+
+  it('resolves <:name:id> mention format', async () => {
+    const result = await client.resolveEmoji('<:custom:123456789012345678>');
+    expect(result).toContain('custom');
+    expect(result).toContain('123456789012345678');
+  });
+
+  it('returns raw unicode for direct unicode input', async () => {
+    const result = await client.resolveEmoji('❤');
+    expect(result).toBe('❤');
+  });
+});