@erinjs/core 1.0.0

package/core/apps/docs-vitepress/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "erinjs-docs",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "node --import tsx/esm scripts/generate-api.ts api-data/latest/main.json && vitepress build",
+    "preview": "vitepress preview",
+    "generate-api": "node --import tsx/esm scripts/generate-api.ts api-data/latest/main.json",
+    "migrate-guides": "node --import tsx/esm scripts/migrate-guides.ts ../docs/public/docs/latest/guides.json"
+  },
+  "dependencies": {
+    "vitepress": "^1.6.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0"
+  }
+}

package/core/apps/docs-vitepress/public/CNAME

@@ -0,0 +1 @@
+erin.js.org

package/core/apps/docs-vitepress/scripts/generate-api.ts

@@ -0,0 +1,243 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ---- Types ----------------------------------------------------------------
+
+interface Param {
+  name: string
+  type: string
+  optional: boolean
+  description?: string
+}
+
+interface Method {
+  name: string
+  params: Param[]
+  returns: string
+  description?: string
+  async: boolean
+  source?: { file: string; line: number; path?: string }
+}
+
+interface Property {
+  name: string
+  type: string
+  readonly: boolean
+  optional: boolean
+  description?: string
+}
+
+interface ApiClass {
+  name: string
+  description?: string
+  constructor?: { params: Param[] }
+  properties: Property[]
+  methods: Method[]
+  package: string
+  source?: { file: string; line: number; path?: string }
+}
+
+interface ApiInterface {
+  name: string
+  description?: string
+  properties: Property[]
+  package: string
+  source?: { file: string; line: number; path?: string }
+}
+
+interface EnumMember {
+  name: string
+  value: string
+}
+
+interface ApiEnum {
+  name: string
+  description?: string
+  members: EnumMember[]
+  package: string
+  source?: { file: string; line: number; path?: string }
+}
+
+interface MainJson {
+  meta: { version: string; date: number }
+  package: string
+  version: string
+  packages: string[]
+  classes: ApiClass[]
+  interfaces: ApiInterface[]
+  enums: ApiEnum[]
+}
+
+// ---- Helpers ---------------------------------------------------------------
+
+function escapeType(type: string): string {
+  // Used inside <code> HTML tags in markdown table cells.
+  // & must come first to avoid double-escaping.
+  // < and > use HTML entities so the browser renders them correctly.
+  // | must be \| so markdown-it's escapedSplit() strips the backslash
+  // and keeps | as literal cell content instead of a column separator.
+  return type
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\|/g, '\\|')
+}
+
+function fixBranding(text: string): string {
+  return text
+    .replace(/@fluxerjs\//g, '@erinjs/')
+    .replace(/\bFluxerError\b/g, 'ErinError')
+    .replace(/\bFluxer\b/g, 'erin.js')
+}
+
+function renderPropertiesTable(properties: Property[]): string {
+  if (properties.length === 0) return '_None_\n'
+  const header = '| Name | Type | Readonly | Optional | Description |'
+  const divider = '| --- | --- | --- | --- | --- |'
+  const rows = properties.map(p =>
+    `| \`${p.name}\` | <code>${escapeType(p.type)}</code> | ${p.readonly ? 'Yes' : 'No'} | ${p.optional ? 'Yes' : 'No'} | ${fixBranding(p.description ?? '')} |`
+  )
+  return [header, divider, ...rows].join('\n') + '\n'
+}
+
+function renderParamsTable(params: Param[]): string {
+  if (params.length === 0) return '_None_\n'
+  const header = '| Name | Type | Optional | Description |'
+  const divider = '| --- | --- | --- | --- |'
+  const rows = params.map(p =>
+    `| \`${p.name}\` | <code>${escapeType(p.type)}</code> | ${p.optional ? 'Yes' : 'No'} | ${fixBranding(p.description ?? '')} |`
+  )
+  return [header, divider, ...rows].join('\n') + '\n'
+}
+
+function renderMethod(method: Method): string {
+  const asyncTag = method.async ? ' `async`' : ''
+  const parts = [`### \`${method.name}()\`${asyncTag}\n`]
+  if (method.description) parts.push(`${fixBranding(method.description)}\n`)
+  parts.push(`**Returns:** <code>${escapeType(method.returns)}</code>\n`)
+  parts.push('**Parameters:**\n')
+  parts.push(renderParamsTable(method.params))
+  return parts.join('\n')
+}
+
+// ---- Generators ------------------------------------------------------------
+
+function generateClassPage(cls: ApiClass): string {
+  const parts: string[] = [`# ${fixBranding(cls.name)}\n`]
+  if (cls.package) parts.push(`**Package:** \`${cls.package.replace('@fluxerjs/', '@erinjs/')}\`\n`)
+  if (cls.description) parts.push(`${fixBranding(cls.description)}\n`)
+
+  if (cls.constructor && cls.constructor.params?.length > 0) {
+    parts.push('## Constructor\n')
+    parts.push(renderParamsTable(cls.constructor.params))
+  }
+
+  parts.push('## Properties\n')
+  parts.push(renderPropertiesTable(cls.properties))
+
+  if (cls.methods.length > 0) {
+    parts.push('## Methods\n')
+    parts.push(cls.methods.map(renderMethod).join('\n---\n\n'))
+  }
+
+  return parts.join('\n')
+}
+
+function generateInterfacePage(iface: ApiInterface): string {
+  const parts: string[] = [`# ${fixBranding(iface.name)}\n`]
+  if (iface.package) parts.push(`**Package:** \`${iface.package.replace('@fluxerjs/', '@erinjs/')}\`\n`)
+  if (iface.description) parts.push(`${fixBranding(iface.description)}\n`)
+  parts.push('## Properties\n')
+  parts.push(renderPropertiesTable(iface.properties))
+  return parts.join('\n')
+}
+
+function generateEnumPage(en: ApiEnum): string {
+  const parts: string[] = [`# ${fixBranding(en.name)}\n`]
+  if (en.package) parts.push(`**Package:** \`${en.package.replace('@fluxerjs/', '@erinjs/')}\`\n`)
+  if (en.description) parts.push(`${fixBranding(en.description)}\n`)
+  parts.push('## Members\n')
+  const header = '| Name | Value |'
+  const divider = '| --- | --- |'
+  const rows = en.members.map(m => `| \`${m.name}\` | \`${m.value}\` |`)
+  parts.push([header, divider, ...rows].join('\n') + '\n')
+  return parts.join('\n')
+}
+
+function generateIndex(names: string[], section: string, basePath: string): string {
+  const links = names.map(name => `- [${fixBranding(name)}](${basePath}/${name})`).join('\n')
+  return `# ${section}\n\n${links}\n`
+}
+
+// ---- Filename deduplication (case-insensitive, for cross-platform Rollup compat) ---
+
+function makeUniqueSlug(name: string, seen: Map<string, number>): string {
+  const key = name.toLowerCase()
+  const count = seen.get(key) ?? 0
+  seen.set(key, count + 1)
+  return count === 0 ? name : `${name}-${count + 1}`
+}
+
+// ---- Main ------------------------------------------------------------------
+
+const inputPath = process.argv[2]
+if (!inputPath) {
+  console.error('Usage: generate-api.ts <path-to-main.json>')
+  process.exit(1)
+}
+
+const data: MainJson = JSON.parse(readFileSync(inputPath, 'utf8'))
+const apiDir = join(__dirname, '../v/latest/api')
+
+const classesDir = join(apiDir, 'classes')
+const interfacesDir = join(apiDir, 'interfaces')
+const enumsDir = join(apiDir, 'enums')
+// Clean stale files from previous runs before writing fresh output
+rmSync(apiDir, { recursive: true, force: true })
+mkdirSync(classesDir, { recursive: true })
+mkdirSync(interfacesDir, { recursive: true })
+mkdirSync(enumsDir, { recursive: true })
+
+const classSeen = new Map<string, number>()
+const classSlugs: Array<{ name: string; slug: string }> = []
+for (const cls of data.classes) {
+  const slug = makeUniqueSlug(cls.name, classSeen)
+  classSlugs.push({ name: cls.name, slug })
+  writeFileSync(join(classesDir, `${slug}.md`), generateClassPage(cls), 'utf8')
+}
+writeFileSync(
+  join(classesDir, 'index.md'),
+  generateIndex(classSlugs.map(c => c.slug), 'Classes', '/v/latest/api/classes'),
+  'utf8'
+)
+
+const ifaceSeen = new Map<string, number>()
+const ifaceSlugs: Array<{ name: string; slug: string }> = []
+for (const iface of data.interfaces) {
+  const slug = makeUniqueSlug(iface.name, ifaceSeen)
+  ifaceSlugs.push({ name: iface.name, slug })
+  writeFileSync(join(interfacesDir, `${slug}.md`), generateInterfacePage(iface), 'utf8')
+}
+writeFileSync(
+  join(interfacesDir, 'index.md'),
+  generateIndex(ifaceSlugs.map(i => i.slug), 'Interfaces', '/v/latest/api/interfaces'),
+  'utf8'
+)
+
+const enumSeen = new Map<string, number>()
+const enumSlugs: Array<{ name: string; slug: string }> = []
+for (const en of data.enums) {
+  const slug = makeUniqueSlug(en.name, enumSeen)
+  enumSlugs.push({ name: en.name, slug })
+  writeFileSync(join(enumsDir, `${slug}.md`), generateEnumPage(en), 'utf8')
+}
+writeFileSync(
+  join(enumsDir, 'index.md'),
+  generateIndex(enumSlugs.map(e => e.slug), 'Enums', '/v/latest/api/enums'),
+  'utf8'
+)
+
+console.log(`Generated ${data.classes.length} classes, ${data.interfaces.length} interfaces, ${data.enums.length} enums`)

package/core/apps/docs-vitepress/scripts/migrate-guides.ts

@@ -0,0 +1,129 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+interface GuideTable {
+  headers: string[]
+  rows: string[][]
+  codeColumns?: number[]
+}
+
+interface GuideSection {
+  title?: string
+  description?: string
+  code?: string
+  language?: string
+  table?: GuideTable
+  tip?: string
+  alternateCode?: { label: string; code: string; language?: string }
+  discordJsCompat?: boolean | string
+}
+
+interface Guide {
+  id: string
+  slug: string
+  title: string
+  description: string
+  category: string
+  sections: GuideSection[]
+}
+
+const inputPath = process.argv[2]
+if (!inputPath) {
+  console.error('Usage: migrate-guides.ts <path-to-guides.json>')
+  process.exit(1)
+}
+
+const guides: Guide[] = JSON.parse(readFileSync(inputPath, 'utf8'))
+const outDir = join(__dirname, '../docs/v/latest/guides')
+mkdirSync(outDir, { recursive: true })
+
+function escapeMarkdown(str: string): string {
+  return str
+    .replace(/@fluxerjs\//g, '@erinjs/')
+    .replace(/fluxerjs/gi, 'erinjs')
+    .replace(/Fluxer\.js/g, 'erin.js')
+    .replace(/Fluxer SDK/g, 'erin.js SDK')
+    .replace(/Fluxer API/g, 'erin.js API')
+    .replace(/FluxerError/g, 'ErinError')
+    .replace(/\bFluxer\b/g, 'erin.js')
+    .replace(/FLUXER_BOT_TOKEN/g, 'ERIN_BOT_TOKEN')
+    .replace(/FLUXER_SUPPRESS_DEPRECATION/g, 'ERIN_SUPPRESS_DEPRECATION')
+}
+
+function renderTable(table: GuideTable): string {
+  const codeColumns = table.codeColumns ?? []
+  const header = `| ${table.headers.join(' | ')} |`
+  const divider = `| ${table.headers.map(() => '---').join(' | ')} |`
+  const rows = table.rows.map(row =>
+    `| ${row.map((cell, i) => (codeColumns.includes(i) ? `\`${cell}\`` : cell)).join(' | ')} |`
+  )
+  return [header, divider, ...rows].join('\n')
+}
+
+function renderSection(section: GuideSection): string {
+  const parts: string[] = []
+
+  if (section.title) {
+    parts.push(`## ${escapeMarkdown(section.title)}\n`)
+  }
+
+  if (section.discordJsCompat) {
+    const rawLink = typeof section.discordJsCompat === 'string' ? section.discordJsCompat : ''
+    // Remap old /docs/classes/ and /docs/typedefs/ paths to new VitePress structure
+    const link = rawLink
+      .replace(/^\/docs\/classes\//, '/v/latest/api/classes/')
+      .replace(/^\/docs\/typedefs\//, '/v/latest/api/interfaces/')
+    if (link) {
+      parts.push(`::: info Discord.js Compatible\nSee [API reference](${link}) for full details.\n:::\n`)
+    } else {
+      parts.push(`::: info Discord.js Compatible\nThis API follows Discord.js conventions.\n:::\n`)
+    }
+  }
+
+  if (section.description) {
+    parts.push(`${escapeMarkdown(section.description)}\n`)
+  }
+
+  if (section.tip) {
+    parts.push(`::: tip\n${escapeMarkdown(section.tip)}\n:::\n`)
+  }
+
+  if (section.table) {
+    parts.push(renderTable(section.table) + '\n')
+  }
+
+  if (section.code) {
+    const lang = section.language ?? 'javascript'
+    const codeFixed = escapeMarkdown(section.code)
+
+    if (section.alternateCode) {
+      const altLang = section.alternateCode.language ?? 'javascript'
+      const altCode = escapeMarkdown(section.alternateCode.code)
+      parts.push(
+        `::: code-group\n\`\`\`${lang} [Default]\n${codeFixed}\n\`\`\`\n\`\`\`${altLang} [${section.alternateCode.label}]\n${altCode}\n\`\`\`\n:::\n`
+      )
+    } else {
+      parts.push(`\`\`\`${lang}\n${codeFixed}\n\`\`\`\n`)
+    }
+  }
+
+  return parts.join('\n')
+}
+
+for (const guide of guides) {
+  const lines: string[] = [
+    `# ${escapeMarkdown(guide.title)}\n`,
+    `${escapeMarkdown(guide.description)}\n`,
+    ...guide.sections.map(renderSection),
+  ]
+
+  const content = lines.join('\n')
+  const outPath = join(outDir, `${guide.slug}.md`)
+  writeFileSync(outPath, content, 'utf8')
+  console.log(`wrote ${outPath}`)
+}
+
+console.log(`\nMigrated ${guides.length} guides to ${outDir}`)

package/core/apps/docs-vitepress/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["scripts/**/*", ".vitepress/**/*"]
+}

package/core/apps/docs-vitepress/v/latest/guides/attachments-by-url.md

@@ -0,0 +1,57 @@
+# File Attachments by URL
+
+Attach files by passing a URL instead of buffer data. The SDK fetches the URL and uploads it as a normal attachment.
+
+## Using a URL
+
+Pass { name, url } in the files array. The SDK fetches the URL (30s timeout), validates it with URL.canParse(), and uploads the result. Works with channel.send(), message.reply(), message.send(), webhook.send(), and client.channels.send().
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!attachurl') {
+    await message.reply({
+      content: 'Image from URL:',
+      files: [
+        {
+          name: 'image.png',
+          url: 'https://example.com/image.png',
+        },
+      ],
+    });
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Mixing buffers and URLs
+
+You can combine file data and URLs in the same message. Order is preserved; attachments metadata id matches the file index.
+
+```javascript
+await message.reply({
+  content: 'Two files:',
+  files: [
+    { name: 'local.txt', data: Buffer.from('Hello') },
+    { name: 'remote.png', url: 'https://example.com/logo.png' },
+  ],
+});
+```
+
+## Optional filename override
+
+Use filename to control the displayed attachment name independently from the local name used during upload.
+
+```javascript
+files: [
+  {
+    name: 'fetched-image.png',
+    url: 'https://example.com/image.jpg',
+    filename: 'custom-display.png',
+  },
+]
+```

package/core/apps/docs-vitepress/v/latest/guides/attachments.md

@@ -0,0 +1,62 @@
+# File Attachments
+
+Upload files with messages and set attachment metadata (title, description, flags for spoiler, animated, explicit).
+
+## Basic File Upload
+
+Pass files in your send options. Each file needs a name and data (Buffer, Blob, Uint8Array). Use with message.reply(), message.send(), or channel.send().
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+import { readFileSync } from 'fs';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!file') {
+    const data = Buffer.from('Hello from erin.js!', 'utf-8');
+    await message.reply({
+      content: 'Here is a file:',
+      files: [{ name: 'hello.txt', data }],
+    });
+  }
+});
+```
+
+## Attachment Metadata
+
+When using files, you can pass attachments to set metadata per file: filename, title, description, and flags. The id in each attachment matches the file index (0, 1, 2...).
+
+```javascript
+import { MessageAttachmentFlags } from '@erinjs/core';
+
+await message.reply({
+  content: 'Spoiler image:',
+  files: [{ name: 'secret.png', data: imageBuffer }],
+  attachments: [
+    {
+      id: 0,
+      filename: 'secret.png',
+      title: 'Hidden image',
+      flags: MessageAttachmentFlags.IS_SPOILER,
+    },
+  ],
+});
+```
+
+## Attachment Flags
+
+MessageAttachmentFlags: IS_SPOILER (8) blurs until clicked, CONTAINS_EXPLICIT_MEDIA (16) for explicit content, IS_ANIMATED (32) for GIFs and animated WebP. Combine with bitwise OR.
+
+```javascript
+import { MessageAttachmentFlags } from '@erinjs/core';
+
+// Spoiler (blurred until clicked)
+flags: MessageAttachmentFlags.IS_SPOILER
+
+// Animated image (GIF, animated WebP)
+flags: MessageAttachmentFlags.IS_ANIMATED
+
+// Combine flags
+flags: MessageAttachmentFlags.IS_SPOILER | MessageAttachmentFlags.IS_ANIMATED
+```

package/core/apps/docs-vitepress/v/latest/guides/basic-bot.md

@@ -0,0 +1,49 @@
+# Basic Bot
+
+A minimal bot that responds to !ping with Pong. See examples/first-steps-bot.js for !hello, !avatar, !embed, !perms.
+
+::: tip
+You can also use client.events for chainable, typed handlers with better autocomplete.
+:::
+
+::: code-group
+```javascript [Default]
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => console.log('Ready!'));
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!ping') {
+    await message.reply('Pong!');
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+```javascript [client.events]
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client
+  .events.Ready(() => console.log('Ready!'))
+  .events.MessageCreate(async (message) => {
+    if (message.content === '!ping') await message.reply('Pong!');
+  });
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+:::
+
+## Common mistakes
+
+Always await message.reply() to avoid unhandled promise rejections. Use intents: 0 (erin.js does not support intents yet). Set ERIN_SUPPRESS_DEPRECATION=1 to silence deprecation warnings.
+
+```javascript
+// ❌ BAD — unhandled rejection if reply fails
+message.reply('Pong!');
+
+// ✅ GOOD
+await message.reply('Pong!');
+```