@erinjs/core 1.0.0

package/core/packages/fluxer-core/src/util/messageUtils.ts

@@ -0,0 +1,119 @@
+import { APIEmbed } from '@erinjs/types';
+import { EmbedBuilder } from '@erinjs/builders';
+
+/** Resolved file data (after URL fetch). Used internally by REST layer. */
+export 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. */
+export type MessageFileData =
+  | {
+      name: string;
+      data: Blob | ArrayBuffer | Uint8Array | Buffer;
+      filename?: string;
+    }
+  | {
+      name: string;
+      url: string;
+      filename?: string;
+    };
+
+const FILE_FETCH_TIMEOUT_MS = 30_000;
+
+/** Resolve files: fetch URLs to buffers, pass through data as-is. */
+export async function resolveMessageFiles(
+  files: MessageFileData[],
+): Promise<ResolvedMessageFile[]> {
+  const result: ResolvedMessageFile[] = [];
+  for (let i = 0; i < files.length; i++) {
+    const f = files[i]!;
+    const filename = f.filename ?? f.name;
+    if ('url' in f && f.url) {
+      if (!URL.canParse(f.url)) {
+        throw new Error(`Invalid file URL at index ${i}: ${f.url}`);
+      }
+      const res = await fetch(f.url, {
+        signal: AbortSignal.timeout(FILE_FETCH_TIMEOUT_MS),
+      });
+      if (!res.ok) {
+        throw new Error(`Failed to fetch file from ${f.url}: ${res.status} ${res.statusText}`);
+      }
+      const data = await res.arrayBuffer();
+      result.push({ name: f.name, data, filename });
+    } else if ('data' in f && f.data != null) {
+      result.push({ name: f.name, data: f.data, filename });
+    } else {
+      throw new Error(`File at index ${i} must have either "data" or "url"`);
+    }
+  }
+  return result;
+}
+
+/** Attachment metadata for file uploads (id matches FormData index). */
+export interface MessageAttachmentMeta {
+  id: number;
+  filename: string;
+  title?: string | null;
+  description?: string | null;
+  /** MessageAttachmentFlags: IS_SPOILER (8), CONTAINS_EXPLICIT_MEDIA (16), IS_ANIMATED (32) */
+  flags?: number;
+}
+
+/** 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().
+ */
+export type MessageSendOptions = {
+  content?: string;
+  /** EmbedBuilder instances are auto-converted; raw APIEmbed also supported. */
+  embeds?: (APIEmbed | EmbedBuilder)[];
+  /** File attachments. When present, request uses multipart/form-data. */
+  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). */
+export 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;
+}
+
+/** Build API-ready body from MessageSendOptions or text content (serializes EmbedBuilder to APIEmbed). */
+export function buildSendBody(options: string | MessageSendOptions): SendBodyResult {
+  const body = typeof options === 'string' ? { content: options } : options;
+  const result: SendBodyResult = {};
+  if (body.content !== undefined) result.content = body.content;
+  if (body.embeds?.length) {
+    result.embeds = body.embeds.map((e) => (e instanceof EmbedBuilder ? e.toJSON() : e));
+  }
+  if (body.files?.length && body.attachments) {
+    result.attachments = body.attachments.map((a) => ({
+      id: a.id,
+      filename: a.filename,
+      ...(a.title != null && { title: a.title }),
+      ...(a.description != null && { description: a.description }),
+      ...(a.flags != null && { flags: a.flags }),
+    }));
+  } else if (body.files?.length) {
+    result.attachments = body.files.map((f, i) => ({
+      id: i,
+      filename: f.filename ?? f.name,
+    }));
+  }
+  if (body.flags !== undefined) result.flags = body.flags;
+  return result;
+}

package/core/packages/fluxer-core/src/util/permissions.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { computePermissions, hasPermission } from './permissions.js';
+import { OverwriteType } from '@erinjs/types';
+import { PermissionFlags } from '@erinjs/util';
+
+describe('hasPermission', () => {
+  it('returns true when Administrator is set (grants all permissions)', () => {
+    expect(hasPermission(PermissionFlags.Administrator, PermissionFlags.Administrator)).toBe(true);
+    expect(hasPermission(PermissionFlags.Administrator, PermissionFlags.SendMessages)).toBe(true);
+  });
+
+  it('returns true when specific permission is set', () => {
+    expect(hasPermission(PermissionFlags.SendMessages, PermissionFlags.SendMessages)).toBe(true);
+  });
+
+  it('returns false when permission not set', () => {
+    expect(hasPermission(0n, PermissionFlags.SendMessages)).toBe(false);
+    expect(hasPermission(0n, PermissionFlags.Administrator)).toBe(false);
+  });
+
+  it('returns false when Administrator not set but other permission is', () => {
+    expect(hasPermission(PermissionFlags.BanMembers, PermissionFlags.Administrator)).toBe(false);
+  });
+});
+
+describe('computePermissions', () => {
+  it('returns base permissions when no overwrites', () => {
+    const base = PermissionFlags.SendMessages | PermissionFlags.ViewChannel;
+    const perms = computePermissions(base, [], [], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(true);
+    expect(hasPermission(perms, PermissionFlags.ViewChannel)).toBe(true);
+    expect(hasPermission(perms, PermissionFlags.BanMembers)).toBe(false);
+  });
+
+  it('returns full permissions when owner (including high-bit Fluxer perms)', () => {
+    const perms = computePermissions(0n, [], [], 'user1', true);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(true);
+    expect(hasPermission(perms, PermissionFlags.BanMembers)).toBe(true);
+    expect(hasPermission(perms, BigInt(PermissionFlags.ManageRoles))).toBe(true);
+    expect(hasPermission(perms, BigInt(PermissionFlags.PinMessages))).toBe(true);
+    expect(hasPermission(perms, BigInt(PermissionFlags.BypassSlowmode))).toBe(true);
+  });
+
+  it('applies role deny overwrite', () => {
+    const base = PermissionFlags.SendMessages;
+    const overwrites = [{ id: 'role1', type: OverwriteType.Role, allow: '0', deny: '2048' }];
+    const perms = computePermissions(base, overwrites, ['role1'], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(false);
+  });
+
+  it('applies role allow overwrite', () => {
+    const base = 0n;
+    const overwrites = [{ id: 'role1', type: OverwriteType.Role, allow: '2048', deny: '0' }];
+    const perms = computePermissions(base, overwrites, ['role1'], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(true);
+  });
+
+  it('applies member overwrite', () => {
+    const base = 0n;
+    const overwrites = [{ id: 'user1', type: OverwriteType.Member, allow: '2048', deny: '0' }];
+    const perms = computePermissions(base, overwrites, [], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(true);
+  });
+
+  it('member overwrite can deny base permission', () => {
+    const base = PermissionFlags.SendMessages;
+    const overwrites = [{ id: 'user1', type: OverwriteType.Member, allow: '0', deny: '2048' }];
+    const perms = computePermissions(base, overwrites, [], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(false);
+  });
+
+  it('ignores overwrites that do not apply to member', () => {
+    const base = PermissionFlags.SendMessages;
+    const overwrites = [{ id: 'role99', type: OverwriteType.Role, allow: '0', deny: '2048' }];
+    const perms = computePermissions(base, overwrites, ['role1'], 'user1', false);
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(true);
+  });
+
+  it('applies both role and member overwrites (member overwrite wins for same permission)', () => {
+    const base = 0n;
+    const overwrites = [
+      { id: 'role1', type: OverwriteType.Role, allow: '2048', deny: '0' },
+      { id: 'user1', type: OverwriteType.Member, allow: '0', deny: '2048' },
+    ];
+    const perms = computePermissions(base, overwrites, ['role1'], 'user1', false);
+    // Member deny overwrites role allow
+    expect(hasPermission(perms, PermissionFlags.SendMessages)).toBe(false);
+  });
+
+  it('empty overwrites returns base unchanged', () => {
+    const base = 2048n;
+    const perms = computePermissions(base, [], [], 'user1', false);
+    expect(perms).toBe(base);
+  });
+});

package/core/packages/fluxer-core/src/util/permissions.ts

@@ -0,0 +1,43 @@
+import { OverwriteType, type APIChannelOverwrite } from '@erinjs/types';
+import { ALL_PERMISSIONS_BIGINT, PermissionFlags } from '@erinjs/util';
+
+/**
+ * Compute the effective permission bitfield for a member in a channel.
+ * Applies role permissions and channel overwrites.
+ * Guild owner always receives all permissions (matches Fluxer API behavior).
+ * @param basePermissions - Combined permissions from all member roles (guild base)
+ * @param overwrites - Channel permission overwrites
+ * @param memberRoles - Role IDs the member has
+ * @param memberId - Member user ID (for member-specific overwrites)
+ * @param isOwner - Whether the member is the guild owner (gets all permissions)
+ * @returns Effective permission bitfield as bigint
+ */
+export function computePermissions(
+  basePermissions: bigint,
+  overwrites: APIChannelOverwrite[],
+  memberRoles: string[],
+  memberId: string,
+  isOwner: boolean,
+): bigint {
+  if (isOwner) return ALL_PERMISSIONS_BIGINT;
+  let perms = basePermissions;
+  for (const overwrite of overwrites ?? []) {
+    const applies =
+      (overwrite.type === OverwriteType.Role && memberRoles.includes(overwrite.id)) ||
+      (overwrite.type === OverwriteType.Member && overwrite.id === memberId);
+    if (!applies) continue;
+    const allow = BigInt(overwrite.allow || '0');
+    const deny = BigInt(overwrite.deny || '0');
+    perms = (perms & ~deny) | allow;
+  }
+  return (perms & PermissionFlags.Administrator) !== 0n ? ALL_PERMISSIONS_BIGINT : perms;
+}
+
+/**
+ * Check if a permission bitfield has a specific permission.
+ * Administrator (bit 3) implies all permissions per Fluxer/Discord convention.
+ */
+export function hasPermission(bitfield: bigint, permission: bigint): boolean {
+  if ((bitfield & PermissionFlags.Administrator) !== 0n) return true;
+  return (bitfield & permission) !== 0n;
+}

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

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"]
+}

package/core/packages/fluxer-core/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  clean: true,
+});

package/core/packages/fluxer-core/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});

package/core/packages/rest/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@erinjs/rest",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.4",
+  "description": "REST client for the Fluxer API",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blstmo-abandoned-us-for-the-milk/core.git",
+    "directory": "packages/rest"
+  },
+  "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",
+    "api",
+    "rest",
+    "sdk",
+    "bot"
+  ],
+  "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 --passWithNoTests"
+  },
+  "dependencies": {
+    "@erinjs/types": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}

package/core/packages/rest/src/REST.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { REST } from './REST.js';
+import { Routes } from '@erinjs/types';
+
+describe('REST', () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('constructor and setToken', () => {
+    const rest = new REST();
+    expect(rest.token).toBeNull();
+    rest.setToken('abc123');
+    expect(rest.token).toBe('abc123');
+    rest.setToken(null);
+    expect(rest.token).toBeNull();
+  });
+
+  it('setToken returns this for chaining', () => {
+    const rest = new REST();
+    expect(rest.setToken('x')).toBe(rest);
+  });
+
+  it('get delegates to requestManager', async () => {
+    const rest = new REST();
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: () => Promise.resolve('{"id":"1"}'),
+      headers: new Headers(),
+    });
+    const result = await rest.get('/channels/1');
+    expect(result).toEqual({ id: '1' });
+  });
+
+  it('post sends body', async () => {
+    const rest = new REST();
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: () => Promise.resolve('{}'),
+      headers: new Headers(),
+    });
+    await rest.post('/channels', { body: { name: 'test' } });
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        method: 'POST',
+        body: '{"name":"test"}',
+      }),
+    );
+  });
+
+  it('Routes is exposed', () => {
+    expect(REST.Routes).toBe(Routes);
+  });
+});

package/core/packages/rest/src/REST.ts

@@ -0,0 +1,90 @@
+import { EventEmitter } from 'events';
+import { RequestManager } from './RequestManager.js';
+import { Routes } from '@erinjs/types';
+
+/** Options for the REST client. */
+export interface RESTOptions {
+  api?: string;
+  version?: string;
+  authPrefix?: 'Bot' | 'Bearer';
+  timeout?: number;
+  retries?: number;
+  userAgent?: string;
+}
+
+/** HTTP client for the Fluxer API. Used by Client internally. */
+export class REST extends EventEmitter {
+  private readonly requestManager: RequestManager;
+  private _token: string | null = null;
+
+  constructor(options: RESTOptions = {}) {
+    super();
+    this.requestManager = new RequestManager({
+      api: options.api ?? 'https://api.fluxer.app',
+      version: options.version ?? '1',
+      authPrefix: options.authPrefix ?? 'Bot',
+      timeout: options.timeout ?? 15000,
+      retries: options.retries ?? 3,
+      userAgent: options.userAgent ?? 'erin.js',
+    });
+  }
+
+  /** Set the bot token for authenticated requests. */
+  setToken(token: string | null): this {
+    this._token = token;
+    this.requestManager.setToken(token);
+    return this;
+  }
+
+  /** Current bot token, or null. */
+  get token(): string | null {
+    return this._token;
+  }
+
+  /** Send a GET request. */
+  async get<T>(route: string, options?: { auth?: boolean }): Promise<T> {
+    return this.requestManager.request<T>('GET', route, { auth: options?.auth });
+  }
+
+  /** Send a POST request. */
+  async post<T>(
+    route: string,
+    options?: {
+      body?: unknown;
+      auth?: boolean;
+      files?: Array<{ name: string; data: Blob | ArrayBuffer | Uint8Array; filename?: string }>;
+    },
+  ): Promise<T> {
+    return this.requestManager.request<T>('POST', route, {
+      body: options?.body,
+      auth: options?.auth,
+      files: options?.files,
+    });
+  }
+
+  /** Send a PATCH request. */
+  async patch<T>(route: string, options?: { body?: unknown; auth?: boolean }): Promise<T> {
+    return this.requestManager.request<T>('PATCH', route, {
+      body: options?.body,
+      auth: options?.auth,
+    });
+  }
+
+  /** Send a PUT request. */
+  async put<T>(route: string, options?: { body?: unknown; auth?: boolean }): Promise<T> {
+    return this.requestManager.request<T>('PUT', route, {
+      body: options?.body,
+      auth: options?.auth,
+    });
+  }
+
+  /** Send a DELETE request. */
+  async delete<T>(route: string, options?: { auth?: boolean }): Promise<T> {
+    return this.requestManager.request<T>('DELETE', route, { auth: options?.auth });
+  }
+
+  /** Route helpers (from @erinjs/types) for building paths. */
+  static get Routes(): typeof Routes {
+    return Routes;
+  }
+}

package/core/packages/rest/src/RateLimitManager.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RateLimitManager } from './RateLimitManager.js';
+
+describe('RateLimitManager', () => {
+  let manager: RateLimitManager;
+
+  beforeEach(() => {
+    manager = new RateLimitManager();
+  });
+
+  it('getBucket returns undefined for unknown route', () => {
+    expect(manager.getBucket('unknown')).toBeUndefined();
+  });
+
+  it('setBucket and getBucket', () => {
+    manager.setBucket('/channels/:id', 5, 3, Date.now() + 60000);
+    const bucket = manager.getBucket('/channels/:id');
+    expect(bucket).toEqual({ limit: 5, remaining: 3, resetAt: expect.any(Number) });
+  });
+
+  it('getWaitTime returns 0 when no limit', () => {
+    expect(manager.getWaitTime('any')).toBe(0);
+  });
+
+  it('getWaitTime returns wait when bucket exhausted', () => {
+    const resetAt = Date.now() + 5000;
+    manager.setBucket('route', 5, 0, resetAt);
+    const wait = manager.getWaitTime('route');
+    expect(wait).toBeGreaterThan(0);
+    expect(wait).toBeLessThanOrEqual(5000);
+  });
+
+  it('getWaitTime returns 0 when resetAt in past', () => {
+    manager.setBucket('route', 5, 0, Date.now() - 1000);
+    expect(manager.getWaitTime('route')).toBe(0);
+  });
+
+  it('setGlobalReset and getGlobalReset', () => {
+    const resetAt = Date.now() + 10000;
+    manager.setGlobalReset(resetAt);
+    expect(manager.getGlobalReset()).toBe(resetAt);
+  });
+
+  it('getWaitTime considers global reset', () => {
+    const resetAt = Date.now() + 3000;
+    manager.setGlobalReset(resetAt);
+    const wait = manager.getWaitTime('any-route');
+    expect(wait).toBeGreaterThan(0);
+  });
+
+  it('updateFromHeaders parses X-RateLimit headers', () => {
+    const resetSeconds = Math.floor(Date.now() / 1000) + 60;
+    const headers = new Headers({
+      'X-RateLimit-Limit': '5',
+      'X-RateLimit-Remaining': '2',
+      'X-RateLimit-Reset': String(resetSeconds),
+    });
+    manager.updateFromHeaders('/channels/123', headers);
+    const bucket = manager.getBucket('/channels/123');
+    expect(bucket?.limit).toBe(5);
+    expect(bucket?.remaining).toBe(2);
+  });
+
+  it('updateFromHeaders handles Retry-After', () => {
+    const headers = new Headers({ 'Retry-After': '10' });
+    manager.updateFromHeaders('/global', headers);
+    const bucket = manager.getBucket('/global');
+    expect(bucket?.limit).toBe(1);
+    expect(bucket?.remaining).toBe(0);
+  });
+});

package/core/packages/rest/src/RateLimitManager.ts

@@ -0,0 +1,60 @@
+/**
+ * Tracks rate limit state per bucket (route hash).
+ * Delays requests when limit is exceeded.
+ */
+export interface RateLimitState {
+  limit: number;
+  remaining: number;
+  resetAt: number;
+}
+
+export class RateLimitManager {
+  private buckets = new Map<string, RateLimitState>();
+  private globalResetAt = 0;
+
+  getBucket(route: string): RateLimitState | undefined {
+    return this.buckets.get(route);
+  }
+
+  setBucket(route: string, limit: number, remaining: number, resetAt: number): void {
+    this.buckets.set(route, { limit, remaining, resetAt });
+  }
+
+  setGlobalReset(resetAt: number): void {
+    this.globalResetAt = resetAt;
+  }
+
+  getGlobalReset(): number {
+    return this.globalResetAt;
+  }
+
+  /** Returns ms to wait before we can send again (0 if no wait). */
+  getWaitTime(route: string): number {
+    const now = Date.now();
+    const globalWait = this.globalResetAt > now ? this.globalResetAt - now : 0;
+    const bucket = this.buckets.get(route);
+    const bucketWait =
+      bucket && bucket.remaining <= 0 && bucket.resetAt > now ? bucket.resetAt - now : 0;
+    return Math.max(globalWait, bucketWait);
+  }
+
+  /** Parse rate limit headers and update state. */
+  updateFromHeaders(route: string, headers: Headers): void {
+    const limit = headers.get('X-RateLimit-Limit');
+    const remaining = headers.get('X-RateLimit-Remaining');
+    const reset = headers.get('X-RateLimit-Reset');
+    if (limit !== null && remaining !== null && reset !== null) {
+      const resetMs = parseInt(reset, 10);
+      if (!Number.isNaN(resetMs)) {
+        const resetAt = resetMs * 1000;
+        this.setBucket(route, parseInt(limit, 10), parseInt(remaining, 10), resetAt);
+      }
+    }
+    const retryAfter = headers.get('Retry-After');
+    if (retryAfter !== null) {
+      const sec = parseInt(retryAfter, 10);
+      const resetAt = Date.now() + (Number.isNaN(sec) ? 0 : sec * 1000);
+      this.setBucket(route, 1, 0, resetAt);
+    }
+  }
+}