@erinjs/core 1.0.0

package/core/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - 'packages/*'
+  - 'examples'
+  - 'apps/*'

package/core/scripts/generate-ai-rag.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * Generate RAG index for Fluxer AI bot.
+ * Chunks main.json + guides.json, embeds via OpenRouter, writes rag-index.json.
+ * Run after generate-docs. Requires OPENROUTER_API_KEY (in .env or environment).
+ */
+
+import { config } from 'dotenv';
+import { resolve, dirname } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+config({ path: resolve(__dirname, '../.env'), quiet: true });
+const root = resolve(__dirname, '..');
+const DOCS_DIR = resolve(root, 'apps/docs/public/docs/latest');
+const RAG_INDEX_PATH = resolve(DOCS_DIR, 'rag-index.json');
+const OR_EMBED_ENDPOINT = 'https://openrouter.ai/api/v1/embeddings';
+const EMBED_MODEL = 'openai/text-embedding-3-small';
+const BATCH_SIZE = 25;
+const BATCH_DELAY_MS = 500;
+
+interface RagChunk {
+  id: string;
+  type: string;
+  source: string;
+  text: string;
+  meta: { slug?: string; url?: string };
+  embedding?: number[];
+}
+
+function formatMethodSig(m: {
+  name: string;
+  params?: Array<{ name: string; type: string }>;
+  returns?: string;
+}): string {
+  const params = m.params?.map((p) => `${p.name}: ${p.type}`).join(', ') ?? '';
+  const ret = m.returns ? ` -> ${m.returns}` : '';
+  return `${m.name}(${params})${ret}`;
+}
+
+function chunkMainJson(main: {
+  classes?: Array<{
+    name: string;
+    description?: string;
+    properties?: Array<{ name: string; type: string }>;
+    methods?: Array<{
+      name: string;
+      params?: Array<{ name: string; type: string }>;
+      returns?: string;
+      description?: string;
+    }>;
+  }>;
+  interfaces?: Array<{
+    name: string;
+    description?: string;
+    properties?: Array<{ name: string; type: string }>;
+  }>;
+  enums?: Array<{
+    name: string;
+    members?: Array<{ name: string; value?: string }>;
+  }>;
+}): RagChunk[] {
+  const chunks: RagChunk[] = [];
+
+  for (const c of main.classes ?? []) {
+    const parts: string[] = [];
+    parts.push(`Class: ${c.name}`);
+    if (c.description) parts.push(`Description: ${c.description}`);
+    if (c.properties?.length) {
+      parts.push(`Properties: ${c.properties.map((p) => `${p.name}: ${p.type}`).join(', ')}`);
+    }
+    if (c.methods?.length) {
+      const methodStrs = c.methods.map((m) => {
+        const sig = formatMethodSig(m);
+        return m.description ? `${sig} — ${m.description}` : sig;
+      });
+      parts.push(`Methods: ${methodStrs.join('; ')}`);
+    }
+    chunks.push({
+      id: `class-${c.name}`,
+      type: 'class',
+      source: 'main',
+      text: parts.join('\n'),
+      meta: { url: `/docs/classes/${c.name}` },
+    });
+  }
+
+  for (const i of main.interfaces ?? []) {
+    const parts: string[] = [];
+    parts.push(`Interface: ${i.name}`);
+    if (i.description) parts.push(`Description: ${i.description}`);
+    if (i.properties?.length) {
+      parts.push(`Properties: ${i.properties.map((p) => `${p.name}: ${p.type}`).join(', ')}`);
+    }
+    chunks.push({
+      id: `interface-${i.name}`,
+      type: 'interface',
+      source: 'main',
+      text: parts.join('\n'),
+      meta: { url: `/docs/typedefs/${i.name}` },
+    });
+  }
+
+  for (const e of main.enums ?? []) {
+    const members =
+      e.members?.map((m) => `${m.name}${m.value != null ? `=${m.value}` : ''}`).join(', ') ?? '';
+    chunks.push({
+      id: `enum-${e.name}`,
+      type: 'enum',
+      source: 'main',
+      text: `Enum: ${e.name}\nMembers: ${members}`,
+      meta: { url: `/docs/typedefs/${e.name}` },
+    });
+  }
+
+  return chunks;
+}
+
+function chunkGuidesJson(
+  guides: Array<{
+    slug: string;
+    title: string;
+    description?: string;
+    sections?: Array<{
+      title?: string;
+      description?: string;
+      code?: string;
+      language?: string;
+    }>;
+  }>,
+): RagChunk[] {
+  const chunks: RagChunk[] = [];
+
+  for (const g of guides) {
+    const sections = g.sections ?? [];
+    for (let i = 0; i < sections.length; i++) {
+      const s = sections[i];
+      const parts: string[] = [];
+      parts.push(`Guide: ${g.title} (${g.slug})`);
+      if (s.title) parts.push(`Section: ${s.title}`);
+      if (s.description) parts.push(s.description);
+      if (s.code) parts.push(`\n\`\`\`${s.language ?? 'js'}\n${s.code}\n\`\`\``);
+      const text = parts.join('\n');
+      if (!text.trim()) continue;
+      chunks.push({
+        id: `guide-${g.slug}-${i}`,
+        type: 'guide',
+        source: 'guides',
+        text,
+        meta: { slug: g.slug, url: `/guides/${g.slug}` },
+      });
+    }
+  }
+
+  return chunks;
+}
+
+async function embedBatch(texts: string[], apiKey: string): Promise<number[][]> {
+  const res = await fetch(OR_EMBED_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: EMBED_MODEL,
+      input: texts,
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Embeddings API ${res.status}: ${err.slice(0, 300)}`);
+  }
+
+  const data = (await res.json()) as { data: Array<{ embedding: number[] }> };
+  return data.data.map((d) => d.embedding);
+}
+
+async function main(): Promise<void> {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error('[generate-ai-rag] OPENROUTER_API_KEY is required');
+    process.exit(1);
+  }
+
+  const mainPath = resolve(DOCS_DIR, 'main.json');
+  const guidesPath = resolve(DOCS_DIR, 'guides.json');
+
+  if (!existsSync(mainPath)) {
+    console.error('[generate-ai-rag] main.json not found. Run: pnpm run generate:docs');
+    process.exit(1);
+  }
+  if (!existsSync(guidesPath)) {
+    console.error('[generate-ai-rag] guides.json not found. Run: pnpm run generate:docs');
+    process.exit(1);
+  }
+
+  const main = JSON.parse(readFileSync(mainPath, 'utf-8'));
+  const guides = JSON.parse(readFileSync(guidesPath, 'utf-8'));
+
+  const mainChunks = chunkMainJson(main);
+  const guideChunks = chunkGuidesJson(guides);
+  const allChunks = [...mainChunks, ...guideChunks];
+
+  console.log(
+    `[generate-ai-rag] Chunked ${mainChunks.length} from main.json, ${guideChunks.length} from guides.json`,
+  );
+
+  for (let i = 0; i < allChunks.length; i += BATCH_SIZE) {
+    const batch = allChunks.slice(i, i + BATCH_SIZE);
+    const texts = batch.map((c) => c.text);
+    const embeddings = await embedBatch(texts, apiKey);
+    for (let j = 0; j < batch.length; j++) {
+      batch[j].embedding = embeddings[j];
+    }
+    console.log(
+      `[generate-ai-rag] Embedded ${Math.min(i + BATCH_SIZE, allChunks.length)}/${allChunks.length}`,
+    );
+    if (i + BATCH_SIZE < allChunks.length) {
+      await new Promise((r) => setTimeout(r, BATCH_DELAY_MS));
+    }
+  }
+
+  mkdirSync(DOCS_DIR, { recursive: true });
+  const output = {
+    model: EMBED_MODEL,
+    dimensions: allChunks[0]?.embedding?.length ?? 1536,
+    generatedAt: Date.now(),
+    chunks: allChunks,
+  };
+  writeFileSync(RAG_INDEX_PATH, JSON.stringify(output), 'utf-8');
+  console.log(`[generate-ai-rag] Wrote ${RAG_INDEX_PATH}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/core/scripts/generate-docs.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Generate combined API documentation JSON from all SDK packages.
+ * Output: apps/docs/public/docs/main.json (single file)
+ */
+
+import { resolve, dirname } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, readdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { generateDocs } from '@erinjs/docgen';
+import { DocOutput } from '@erinjs/docgen';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+
+const PACKAGES: { id: string; name: string; pkgPath: string }[] = [
+  { id: 'core', name: '@erinjs/core', pkgPath: 'packages/fluxer-core' },
+  { id: 'builders', name: '@erinjs/builders', pkgPath: 'packages/builders' },
+  { id: 'rest', name: '@erinjs/rest', pkgPath: 'packages/rest' },
+  { id: 'ws', name: '@erinjs/ws', pkgPath: 'packages/ws' },
+  { id: 'voice', name: '@erinjs/voice', pkgPath: 'packages/voice' },
+  { id: 'util', name: '@erinjs/util', pkgPath: 'packages/util' },
+  { id: 'collection', name: '@erinjs/collection', pkgPath: 'packages/collection' },
+  { id: 'types', name: '@erinjs/types', pkgPath: 'packages/types' },
+];
+
+const DOCS_DIR = resolve(root, 'apps/docs-vitepress/api-data');
+
+function getVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf-8'));
+    return pkg.version ?? '1.1.0';
+  } catch {
+    return '1.1.0';
+  }
+}
+
+async function main(): Promise<void> {
+  const allClasses: DocOutput['classes'] = [];
+  const allInterfaces: DocOutput['interfaces'] = [];
+  const allEnums: DocOutput['enums'] = [];
+  const packages = new Set<string>();
+
+  const seen = new Set<string>();
+
+  for (const pkg of PACKAGES) {
+    try {
+      const pkgRoot = resolve(root, pkg.pkgPath);
+      const tsconfigPath = resolve(pkgRoot, 'tsconfig.json');
+      const outDir = resolve(root, 'apps/docs-vitepress/api-data');
+      const tempFile = resolve(outDir, `_temp_${pkg.id}.json`);
+
+      generateDocs({
+        entryPoints: ['src/index.ts'],
+        tsconfigPath,
+        packageName: pkg.name,
+        outFile: tempFile,
+        repoRoot: root,
+      });
+
+      const data = JSON.parse(readFileSync(tempFile, 'utf-8')) as DocOutput;
+      unlinkSync(tempFile);
+
+      for (const c of data.classes ?? []) {
+        if (!seen.has(`class:${c.name}`)) {
+          seen.add(`class:${c.name}`);
+          allClasses.push({ ...c, package: pkg.name });
+          packages.add(pkg.name);
+        }
+      }
+      for (const i of data.interfaces ?? []) {
+        if (!seen.has(`interface:${i.name}`)) {
+          seen.add(`interface:${i.name}`);
+          allInterfaces.push({ ...i, package: pkg.name });
+          packages.add(pkg.name);
+        }
+      }
+      for (const e of data.enums ?? []) {
+        if (!seen.has(`enum:${e.name}`)) {
+          seen.add(`enum:${e.name}`);
+          allEnums.push({ ...e, package: pkg.name });
+          packages.add(pkg.name);
+        }
+      }
+      console.log(`[generate-docs] ${pkg.name}`);
+    } catch (err) {
+      console.error(`[generate-docs] Failed for ${pkg.name}:`, err);
+      throw err;
+    }
+  }
+
+  allClasses.sort((a, b) => a.name.localeCompare(b.name));
+  allInterfaces.sort((a, b) => a.name.localeCompare(b.name));
+  allEnums.sort((a, b) => a.name.localeCompare(b.name));
+
+  const version = getVersion();
+  const combined: DocOutput = {
+    meta: { generator: 'fluxer-docgen', version: '1', date: Date.now() },
+    package: '@erinjs/core',
+    version,
+    packages: Array.from(packages).sort(),
+    classes: allClasses,
+    interfaces: allInterfaces,
+    enums: allEnums,
+  };
+
+  const jsonStr = JSON.stringify(combined, null, 2);
+
+  // Write to versioned path: docs/v1.0.6/main.json (separate file per version)
+  const versionedDir = resolve(DOCS_DIR, `v${version}`);
+  mkdirSync(versionedDir, { recursive: true });
+  const versionedFile = resolve(versionedDir, 'main.json');
+  writeFileSync(versionedFile, jsonStr, 'utf-8');
+  console.log(`[generate-docs] Versioned -> ${versionedFile}`);
+
+  // Also write to docs/latest/main.json for the "latest" alias (avoids extra redirect)
+  const latestDir = resolve(DOCS_DIR, 'latest');
+  mkdirSync(latestDir, { recursive: true });
+  writeFileSync(resolve(latestDir, 'main.json'), jsonStr, 'utf-8');
+  console.log(`[generate-docs] Latest -> ${latestDir}/main.json`);
+
+  // versions.json — derive from actual v* folders so we never lose older versions
+  const versionsPath = resolve(DOCS_DIR, 'versions.json');
+  const dirEntries = readdirSync(DOCS_DIR, { withFileTypes: true });
+  const versionDirs = dirEntries
+    .filter((e) => e.isDirectory() && /^v\d+\.\d+\.\d+$/.test(e.name))
+    .map((e) => e.name.slice(1)); // strip leading "v"
+  const hasCurrent = versionDirs.includes(version);
+  const allVersions = hasCurrent
+    ? [...new Set([version, ...versionDirs])]
+    : [version, ...versionDirs];
+  allVersions.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  const versionsData = { versions: allVersions, latest: version };
+  writeFileSync(versionsPath, JSON.stringify(versionsData, null, 2), 'utf-8');
+  console.log(`[generate-docs] Versions -> ${versionsPath} (${allVersions.length} versions)`);
+
+  console.log('[generate-docs] Done');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/core/scripts/generate-emoji-shortcodes.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Generate shortcode→unicode map from Discord's emoji data (anyascii/discord-emojis).
+ * Fluxer is Discord-compatible, so we use Discord's official shortcodes.
+ * Run: pnpm exec tsx scripts/generate-emoji-shortcodes.ts
+ *
+ * Source: https://github.com/anyascii/discord-emojis
+ * Format: { "emojis": [ { "names": ["arrow_backward"], "surrogates": "⬅️" }, ... ] }
+ */
+import { writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+const cwd = process.cwd();
+const repoRoot =
+  basename(cwd) === 'util' && basename(dirname(cwd)) === 'packages' ? join(cwd, '../..') : cwd;
+const utilPath = join(repoRoot, 'packages/util');
+
+const DISCORD_EMOJIS_URL =
+  'https://raw.githubusercontent.com/anyascii/discord-emojis/master/discord-emojis.json';
+
+async function fetchDiscordEmojis(): Promise<{
+  emojis: Array<{ names: string[]; surrogates: string }>;
+}> {
+  const res = await fetch(DISCORD_EMOJIS_URL);
+  if (!res.ok) throw new Error(`Failed to fetch discord-emojis: ${res.status}`);
+  return res.json();
+}
+
+async function main() {
+  const data = await fetchDiscordEmojis();
+  const map: Record<string, string> = {};
+
+  for (const entry of data.emojis) {
+    const { names, surrogates } = entry;
+    if (!Array.isArray(names) || !surrogates) continue;
+    for (const name of names) {
+      const normalized = String(name).replace(/\s+/g, '_').trim().toLowerCase();
+      if (normalized.length < 2 || !/^[\w_]+$/.test(normalized)) continue;
+      map[normalized] = surrogates;
+    }
+  }
+
+  const output = `/**
+ * Auto-generated from Discord's emoji data (anyascii/discord-emojis).
+ * Run: pnpm exec tsx scripts/generate-emoji-shortcodes.ts
+ */
+export const UNICODE_EMOJI_SHORTCODES: Record<string, string> = ${JSON.stringify(map, null, 0)};
+`;
+
+  const outPath = join(utilPath, 'src/emojiShortcodes.generated.ts');
+  writeFileSync(outPath, output, 'utf8');
+  console.log(`Wrote ${outPath} (${Object.keys(map).length} shortcodes)`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/core/scripts/generate-types.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Generate TypeScript types from OpenAPI spec.
+ * Will be implemented in types-package phase.
+ */
+console.log('Type generation - see packages/types');

package/core/scripts/publish-ordered.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Publish erin.js community packages in dependency order with a delay between each
+ * to avoid npm 409 (packument not fully processed).
+ *
+ * Run from repo root:
+ *   node scripts/publish-ordered.js
+ *   node scripts/publish-ordered.js --delay=15
+ *   node scripts/publish-ordered.js --otp=123456
+ *
+ * Prereqs: pnpm install, pnpm run build, and npm login (or token).
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// Dependency order: no internal deps first, then dependents
+const PACKAGES = [
+  '@erinjs/types',
+  '@erinjs/util',
+  '@erinjs/collection',
+  '@erinjs/rest',
+  '@erinjs/ws',
+  '@erinjs/builders',
+  '@erinjs/core',
+  '@erinjs/voice',
+];
+
+const args = process.argv.slice(2);
+const delaySec = parseInt(args.find((a) => a.startsWith('--delay='))?.split('=')[1] || '1', 10);
+const otp = args.find((a) => a.startsWith('--otp='));
+const otpArg = otp ? ` ${otp}` : '';
+
+function run(cmd, opts = {}) {
+  execSync(cmd, { stdio: 'inherit', shell: true, cwd: ROOT, ...opts });
+}
+
+console.log('Installing (ensures workspace links are used)...');
+run('pnpm install');
+console.log('Building...');
+run('pnpm run build');
+
+console.log(`\nPublishing in order with ${delaySec}s delay between each.\n`);
+
+for (let i = 0; i < PACKAGES.length; i++) {
+  const pkg = PACKAGES[i];
+  console.log(`[${i + 1}/${PACKAGES.length}] ${pkg}`);
+  try {
+    run(`pnpm --filter "${pkg}" publish --no-git-checks${otpArg}`);
+  } catch (e) {
+    console.error(`Publish failed for ${pkg}`);
+    process.exit(1);
+  }
+  if (i < PACKAGES.length - 1) {
+    console.log(`Waiting ${delaySec}s...\n`);
+    const deadline = Date.now() + delaySec * 1000;
+    while (Date.now() < deadline) {}
+  }
+}
+
+console.log('\nAll packages published.');

package/core/scripts/test-cjs-require.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Test that all published erin.js community packages can be required as CJS without throwing.
+ * Catches issues when packages fail to load via require().
+ *
+ * Run from repo root after build:
+ *   node scripts/test-cjs-require.mjs
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const PACKAGES = [
+  '@erinjs/types',
+  '@erinjs/util',
+  '@erinjs/collection',
+  '@erinjs/rest',
+  '@erinjs/ws',
+  '@erinjs/builders',
+  '@erinjs/core',
+  '@erinjs/voice',
+];
+
+function main() {
+  const failed = [];
+  for (const pkg of PACKAGES) {
+    try {
+      require(pkg);
+      console.log(`✓ ${pkg}`);
+    } catch (err) {
+      console.error(`✗ ${pkg}:`, err.message);
+      failed.push({ pkg, err });
+    }
+  }
+  if (failed.length > 0) {
+    console.error('\nCJS require test failed for:', failed.map((f) => f.pkg).join(', '));
+    process.exit(1);
+  }
+  console.log(`\nAll ${PACKAGES.length} packages load as CJS successfully.`);
+}
+
+main();

package/core/scripts/test-esm-imports.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Test that all published erin.js community packages can be imported as ESM without throwing.
+ * Catches issues like "Dynamic require of X is not supported" when bundled CJS
+ * code gets loaded in ESM context.
+ *
+ * Run from repo root after build:
+ *   node scripts/test-esm-imports.mjs
+ *
+ * Must run as ESM (this file is .mjs).
+ */
+
+const PACKAGES = [
+  '@erinjs/types',
+  '@erinjs/util',
+  '@erinjs/collection',
+  '@erinjs/rest',
+  '@erinjs/ws',
+  '@erinjs/builders',
+  '@erinjs/core',
+  '@erinjs/voice',
+];
+
+async function main() {
+  const failed = [];
+  for (const pkg of PACKAGES) {
+    try {
+      await import(pkg);
+      console.log(`✓ ${pkg}`);
+    } catch (err) {
+      console.error(`✗ ${pkg}:`, err.message);
+      failed.push({ pkg, err });
+    }
+  }
+  if (failed.length > 0) {
+    console.error('\nESM import test failed for:', failed.map((f) => f.pkg).join(', '));
+    process.exit(1);
+  }
+  console.log(`\nAll ${PACKAGES.length} packages load as ESM successfully.`);
+}
+
+main();