@raven_app/raven.js 0.0.0-stage → 1.0.2

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@raven_app/raven.js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "SDK for building Raven bots on https://ravenapp.xyz (REST /api/v1 + live gateway, polling fallback)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://ravenapp.xyz",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --platform=node --packages=external --format=esm --outfile=dist/index.mjs && esbuild src/index.js --bundle --platform=node --packages=external --format=cjs --outfile=dist/index.cjs",
+    "prepublishOnly": "npm test && npm run build",
+    "test": "node test.js",
+    "example:ping": "node examples/ping.js",
+    "example:stats": "node examples/stats.js",
+    "example:gateway": "node examples/gateway-bot.js",
+    "example:showcase": "node examples/showcase-bot.js",
+    "example:ethan": "node examples/ethan.js",
+    "example:cooldowns": "node examples/redis-cooldown-store.js"
+  },
+  "keywords": [
+    "raven",
+    "ravenapp",
+    "bot",
+    "sdk",
+    "chat"
+  ],
+  "author": "andre5338",
+  "license": "ISC"
+}

package/types/index.d.ts

@@ -0,0 +1,586 @@
+export const DEFAULT_BASE_URL: string
+
+export interface ClientOptions {
+  token: string // `rvb_...`
+  timeoutMs?: number
+  retryOn429?: boolean
+  ethanKey?: string // `rve_...` (EthanPlus/Pro key for client.ethan)
+}
+
+export type EthanPersonality = "friendly" | "objective" | "humorous" | "neutral" | "grumpy"
+
+export interface EthanChatOptions {
+  message?: string
+  input?: string // alias for message
+  prompt?: string // alias for message
+  personality?: EthanPersonality | string // default "neutral"
+  reasoning?: boolean
+  temperature?: number // 0-100
+}
+
+export interface EthanChatResult {
+  reply: string
+  thinking: string
+  model: string
+  plan: string | null
+  raw: unknown
+}
+
+export const ETHAN_MODEL: string
+export const ETHAN_PERSONALITIES: string[]
+export const ETHAN_MESSAGE_MAX: number
+export const ETHAN_KEY_PREFIX: string
+export function assertPersonality(personality: unknown): string
+export function assertEthanMessage(message: unknown): string
+export function assertTemperature(temperature: unknown): number | undefined
+
+export class EthanClient {
+  constructor(options: { key: string; timeoutMs?: number; retryOn429?: boolean })
+  key: string
+  request(method: string, path: string, opts?: { query?: Record<string, unknown>; body?: unknown }): Promise<unknown>
+  models(): Promise<{ models: Array<{ id: string; name: string; via: string | null; raw: unknown }>; raw: unknown }>
+  chat(message: string | EthanChatOptions, opts?: EthanChatOptions): Promise<EthanChatResult>
+  ask(message: string | EthanChatOptions, opts?: EthanChatOptions): Promise<EthanChatResult>
+}
+
+export function createEthanClient(options: ConstructorParameters<typeof EthanClient>[0]): EthanClient
+
+export type BotStatus = "online" | "idle" | "dnd"
+
+export interface BotSelf {
+  id: string
+  username: string
+  avatar: string | null
+  applicationId: string
+  scopes: string[]
+  bot: boolean
+  status?: string
+  statusLocked?: boolean
+  raw: unknown
+}
+
+export interface Guild {
+  id: string
+  name: string
+  description?: string
+  icon: string | null
+  ownerId: string
+  memberCount: number
+  verified?: boolean
+  raw: unknown
+}
+
+export interface GuildStats {
+  guildId: string
+  memberCount: number
+  [key: string]: unknown
+}
+
+export interface Channel {
+  id: string
+  name: string
+  type: string // "text" | "voice" | ...
+  position: number
+  parentId: string | null
+  raw: unknown
+}
+
+export interface ChannelDetail extends Channel {
+  guildId?: string
+  topic: string
+  icon: string
+}
+
+export interface ChannelCreateOptions {
+  name: string
+  type?: "text" | "voice" | string // default "text"
+  parentId?: string | null // category id
+  topic?: string // max 1024 chars
+}
+
+export interface ChannelUpdateOptions {
+  name?: string
+  type?: "text" | "voice" | string
+  topic?: string
+  parentId?: string | null // "" or null = no category
+  position?: number
+}
+
+export interface ChannelReorderItem {
+  id: string
+  position?: number
+  parentId?: string | null
+}
+
+export interface DmConversation {
+  channelId: string
+  counter: number
+  unread: number
+  lastMessageAt: Date | null
+  other: { id: string; username: string; displayName: string | null; avatar: string | null }
+  raw?: unknown
+}
+
+export interface DmMessage {
+  id: string
+  channelId: string
+  authorId: string
+  content: string
+  counter?: number
+  createdAt: Date
+  editedAt?: Date | null
+  raw?: unknown
+}
+
+export interface DmFetchOptions {
+  limit?: number // 1-100, default 50
+  before?: number // enc counter cursor
+}
+
+export const CHANNEL_TYPES: string[]
+export function assertChannelType(type: unknown): string
+export function assertChannelName(name: unknown): string
+
+export interface Role {
+  id: string
+  name: string
+  color: string
+  hoist: boolean
+  mentionable: boolean
+  position: number
+  permissions: number
+  managed: boolean
+  raw: unknown
+}
+
+export interface RoleCreateOptions {
+  name: string
+  color?: string // "#RRGGBB"
+  hoist?: boolean
+  mentionable?: boolean
+  permissions?: number // bitfield, masked to 0x1fff
+  position?: number
+}
+
+export interface RoleUpdateOptions {
+  name?: string
+  color?: string
+  hoist?: boolean
+  mentionable?: boolean
+  permissions?: number
+  position?: number
+}
+
+export interface MemberRoles {
+  userId: string
+  roleIds: string[]
+  raw?: unknown
+}
+
+export interface Member {
+  id: string
+  username: string
+  displayName: string | null
+  avatar: string | null
+  tag: string
+  bio: string
+  badges: string[]
+  createdAt: Date | null
+  joinedAt: Date | null
+  roleIds: string[]
+  isOwner: boolean
+  isBot: boolean
+  raw?: unknown
+}
+
+export interface MemberListOptions {
+  limit?: number // 1-100, default 50
+  after?: string // userId cursor
+}
+
+export interface MemberListResult {
+  members: Member[]
+  hasMore: boolean
+  raw: unknown
+}
+
+export interface BanOptions {
+  reason?: string // max 256 chars
+  duration?: number | string // seconds or "10m"/"1h"/"7d"/"1w"/"permanent"
+  durationSec?: number | string
+}
+
+export interface BanResult {
+  userId?: string
+  reason: string
+  expiresAt?: Date | null
+  duration: string
+  [key: string]: unknown
+}
+
+export interface BanEntry {
+  userId: string
+  reason: string
+  bannedBy: string | null
+  bannedAt: Date | null
+  expiresAt: Date | null
+}
+
+export interface HierarchyCheck {
+  ok: boolean
+  reason: string | null
+}
+
+export const PERMISSIONS: Record<string, number>
+export const PERMISSION_MASK: number
+export const DEFAULT_EVERYONE_PERMS: number
+export const DEFAULT_ADMIN_PERMS: number
+export function normalizeRole(r: unknown): Role
+export function getHighestRole(roles: Role[], roleIds: string[], isOwner?: boolean): Role | null
+export function getMemberPermissions(roles: Role[], roleIds: string[], isOwner?: boolean): number
+export function hasPermission(roles: Role[], roleIds: string[], permission: number, isOwner?: boolean): boolean
+export function canManageRole(actorRoles: Role[], actorRoleIds: string[], targetRole: Role, opts?: { actorIsOwner?: boolean }): HierarchyCheck
+export function canAssignRole(actorRoles: Role[], actorRoleIds: string[], role: Role, opts?: { actorIsOwner?: boolean }): HierarchyCheck
+export function canModerate(actorRoles: Role[], actorRoleIds: string[], targetRoleIds: string[], opts?: { actorIsOwner?: boolean; targetIsOwner?: boolean; self?: boolean }): HierarchyCheck
+export function sortRoles(roles: Role[]): Role[]
+export function assertRoleName(name: unknown): string
+export function assertRoleColor(color: unknown): string | undefined
+export function assertRolePermissions(permissions: unknown): number | undefined
+
+export interface Message {
+  id: string
+  channelId: string
+  guildId?: string
+  authorId: string
+  isBot?: boolean
+  botId?: string | null
+  content: string
+  createdAt: Date
+  editedAt?: Date | null
+  raw?: unknown
+}
+
+export interface FetchMessagesResult {
+  messages: Message[]
+  hasMore: boolean
+  raw: unknown
+}
+
+export interface OAuthInfo {
+  clientId: string
+  username: string
+  scopes: string[]
+  authorizeUrl: string
+  installed: boolean | null
+  raw: unknown
+}
+
+export interface PollOptions {
+  channelId?: string | string[]
+  channelIds?: string | string[]
+  channels?: string | string[]
+  pollInterval?: number // ms, min 1000, default 3000
+  limit?: number // 1-100, default 25
+  emitHistory?: boolean
+  ignoreBots?: boolean
+  selfAuthorId?: string | null
+  signal?: AbortSignal | null
+  onError?: ((err: Error) => void) | null
+}
+
+export class MessagePoller {
+  on(event: "message", cb: (m: Message) => void): this
+  on(event: "error" | "stopped", cb: (e?: unknown) => void): this
+  start(): Promise<this>
+  stop(): this
+}
+
+export const GATEWAY_EVENTS: string[]
+export interface GatewayReadyInfo {
+  sessionId: string | null
+  bot: BotSelf | null
+  guilds: string[]
+}
+export class RavenGateway {
+  constructor(client: RavenClient, options?: { token?: string; identifyTimeoutMs?: number })
+  connected: boolean
+  sessionId: string | null
+  on(event: "ready", cb: (info: GatewayReadyInfo) => void): this
+  on(event: "message:new" | "message:update", cb: (m: Message) => void): this
+  on(event: "message:delete", cb: (d: { id: string; channelId: string; guildId?: string }) => void): this
+  on(event: "guildCreate" | "guildRemove", cb: (d: { guildId?: string; [key: string]: unknown }) => void): this
+  on(event: "roleCreate" | "roleUpdate" | "roleDelete", cb: (d: { guildId?: string; role?: Role; [key: string]: unknown }) => void): this
+  on(event: "rolesReordered", cb: (d: { guildId?: string; roles?: Role[]; [key: string]: unknown }) => void): this
+  on(event: "memberRolesUpdate", cb: (d: MemberRoles & { guildId?: string; [key: string]: unknown }) => void): this
+  on(event: "memberJoin", cb: (d: { guildId?: string; member?: Member; [key: string]: unknown }) => void): this
+  on(event: "memberLeave", cb: (d: { guildId?: string; userId?: string; [key: string]: unknown }) => void): this
+  on(event: "memberBan" | "memberUnban", cb: (d: { guildId?: string; userId?: string; reason?: string; [key: string]: unknown }) => void): this
+  on(event: "channelCreate" | "channelUpdate", cb: (d: { guildId?: string; channel?: ChannelDetail; [key: string]: unknown }) => void): this
+  on(event: "channelDelete", cb: (d: { guildId?: string; channelId?: string; [key: string]: unknown }) => void): this
+  on(event: "channelsReordered", cb: (d: { guildId?: string; channels?: ChannelDetail[]; [key: string]: unknown }) => void): this
+  on(event: "dmCreate", cb: (d: { channelId?: string; [key: string]: unknown }) => void): this
+  on(event: "dmMessage", cb: (d: DmMessage & { channelId: string; [key: string]: unknown }) => void): this
+  on(event: "dmMessageUpdate", cb: (d: DmMessage & { channelId: string; [key: string]: unknown }) => void): this
+  on(event: "dmMessageDelete", cb: (d: { id: string; channelId: string; [key: string]: unknown }) => void): this
+  on(event: "commandError", cb: (err: Error, ctx: CommandContext) => void): this
+  on(event: "*", cb: (event: string, ...args: unknown[]) => void): this
+  on(event: "dispatch", cb: (env: { op: string; t: string; s: number; d: unknown }) => void): this
+  on(event: string, cb: (...args: unknown[]) => void): this
+  once(event: string, cb: (...args: unknown[]) => void): this
+  off(event: string, cb: (...args: unknown[]) => void): this
+  connect(): Promise<GatewayReadyInfo>
+  send(channelId: string, content: string | { content: string; replyTo?: string; reply_to?: string }): Promise<Message>
+  reply(channelId: string, messageId: string, content: string): Promise<Message>
+  edit(channelId: string, messageId: string, content: string): Promise<Message>
+  delete(channelId: string, messageId: string): Promise<{ id: string }>
+  listRoles(guildId: string): Promise<Role[]>
+  getRole(guildId: string, roleId: string): Promise<Role>
+  createRole(guildId: string, opts: RoleCreateOptions): Promise<Role>
+  updateRole(guildId: string, roleId: string, patch: RoleUpdateOptions): Promise<Role | Role[]>
+  deleteRole(guildId: string, roleId: string): Promise<{ id: string }>
+  reorderRoles(guildId: string, orderedIds: string[]): Promise<Role[]>
+  memberRoles(guildId: string, userId: string): Promise<MemberRoles>
+  setMemberRoles(guildId: string, userId: string, roleIds: string[]): Promise<MemberRoles>
+  listMembers(guildId: string, opts?: MemberListOptions): Promise<MemberListResult>
+  getMember(guildId: string, userId: string): Promise<Member>
+  kick(guildId: string, userId: string, reason?: string | { reason?: string }): Promise<{ id: string }>
+  ban(guildId: string, userId: string, opts?: BanOptions | string): Promise<BanResult>
+  unban(guildId: string, userId: string): Promise<{ id: string }>
+  bans(guildId: string): Promise<{ bans: BanEntry[]; bannedUserIds: string[] }>
+  getChannel(channelId: string): Promise<ChannelDetail>
+  createChannel(guildId: string, opts: ChannelCreateOptions): Promise<ChannelDetail>
+  updateChannel(channelId: string, patch: ChannelUpdateOptions): Promise<ChannelDetail>
+  deleteChannel(channelId: string): Promise<{ id: string }>
+  reorderChannels(guildId: string, items: ChannelReorderItem[]): Promise<ChannelDetail[]>
+  listDms(): Promise<{ conversations: DmConversation[] }>
+  openDm(userId: string): Promise<DmConversation>
+  fetchDm(channelId: string, opts?: DmFetchOptions): Promise<{ messages: DmMessage[]; hasMore: boolean }>
+  sendDm(channelId: string, content: string): Promise<DmMessage>
+  editDm(channelId: string, messageId: string, content: string): Promise<DmMessage>
+  deleteDm(channelId: string, messageId: string): Promise<{ id: string }>
+  readDm(channelId: string): Promise<{ ok: boolean }>
+  setStatus(status: BotStatus | string | null): Promise<{ status: string; locked: boolean }>
+  sync(): Promise<{ guilds: string[]; channels: number }>
+  disconnect(): this
+  attachPoller(poller: MessagePoller): this
+}
+
+export interface CommandContext {
+  message: Message
+  content: string
+  args: string[]
+  rawArgs: string
+  command: string
+  authorId: string
+  channelId: string
+  guildId?: string
+  user: { id: string; [key: string]: unknown } | unknown
+  guild: { id: string } | null
+  channel: { id: string } | null
+  reply(content: string): Promise<Message>
+  send(content: string): Promise<Message>
+  delete(): Promise<{ id: string }>
+}
+
+export interface CommandOptions {
+  description?: string
+  usage?: string
+  aliases?: string | string[]
+  alias?: string | string[]
+  cooldown?: number
+}
+
+export interface HelpOptions {
+  prefix?: boolean | string
+  descriptions?: boolean
+  command?: string
+}
+
+export interface CooldownStore {
+  get(key: string): number | string | null | Promise<number | string | null>
+  set(key: string, expiresAt: number, ttlMs: number): void | Promise<void>
+}
+
+export class MemoryCooldownStore implements CooldownStore {
+  constructor(options?: { maxKeys?: number })
+  get(key: string): number | null
+  set(key: string, expiresAt: number): void
+  readonly size: number
+}
+
+export class CommandHandler {
+  constructor(options?: { prefix?: string; ignoreBots?: boolean; cooldownStore?: CooldownStore; onUnknown?: (ctx: CommandContext) => void | Promise<void>; onError?: (err: Error, ctx: CommandContext) => void | Promise<void>; onCooldown?: (ctx: CommandContext, waitSeconds: number) => void | Promise<void> })
+  command(name: string, fn: (ctx: CommandContext) => void | Promise<void>, opts?: CommandOptions): this
+  resolve(name: string): string | null
+  suggestCommand(name: string): string | null
+  parse(content: string): { name: string; args: string[]; raw: string } | null
+  handle(client: RavenClient, message: Message): Promise<boolean>
+  attach(client: RavenClient, channelIds: string | string[], pollOptions?: PollOptions): Promise<{ poller: MessagePoller; stop: () => void }>
+  help(options?: HelpOptions): string
+  helpText(): string
+}
+
+export function createCommandHandler(options?: ConstructorParameters<typeof CommandHandler>[0]): CommandHandler
+
+export interface BotOptions {
+  token: string // `rvb_...`
+  prefix?: string // default "!"
+  status?: BotStatus | string | null // startup status, null = server-managed
+  testGuild?: string // test area server (or RAVEN_TEST_GUILD env): errors land in #bot-test / #test / first text channel
+  testChannel?: string // explicit bug channel (or RAVEN_TEST_CHANNEL env): wins over testGuild resolution
+  timeoutMs?: number
+  retryOn429?: boolean
+  log?: boolean | ((...args: unknown[]) => void)
+  debug?: boolean
+  cooldownStore?: CooldownStore
+}
+
+export interface BotStartInfo {
+  bot: BotSelf | null
+  guilds: string[]
+  channels: number
+}
+
+export class RavenBot {
+  constructor(options: BotOptions)
+  client: RavenClient
+  commands: CommandHandler
+  errors: { format(err: unknown, opts?: { color?: boolean }): string; suggest(input: unknown, candidates: unknown[]): Suggestion | null }
+  started: boolean
+  debug: boolean
+  testChannelId: string | null
+  command(name: string, fn: (ctx: CommandContext) => void | Promise<void>, opts?: CommandOptions): this
+  on(event: string, fn: (...args: unknown[]) => void): this
+  once(event: string, fn: (...args: unknown[]) => void): this
+  off(event: string, fn: (...args: unknown[]) => void): this
+  start(): Promise<BotStartInfo>
+  stop(): this
+  info(): { bot: BotSelf | null; guilds: string[] }
+}
+
+export function createBot(options: BotOptions): RavenBot
+
+export class RavenClient {
+  constructor(options: ClientOptions)
+  token: string
+  ethanKey: string | null
+  ethan: EthanClient
+  me: {
+    get(): Promise<BotSelf>
+    setStatus(status: BotStatus | string | null): Promise<{ status: string; locked: boolean; shown: string; raw: unknown }>
+  }
+  guilds: {
+    list(): Promise<Guild[]>
+    get(guildId: string): Promise<Guild>
+    stats(guildId: string): Promise<GuildStats>
+  }
+  channels: {
+    list(guildId: string): Promise<Channel[]>
+    get(channelId: string): Promise<ChannelDetail>
+    create(guildId: string, opts: ChannelCreateOptions): Promise<ChannelDetail>
+    update(channelId: string, patch: ChannelUpdateOptions): Promise<ChannelDetail>
+    delete(channelId: string): Promise<{ id: string }>
+    reorder(guildId: string, items: ChannelReorderItem[]): Promise<ChannelDetail[]>
+  }
+  dms: {
+    list(): Promise<{ conversations: DmConversation[]; raw: unknown }>
+    open(userId: string): Promise<DmConversation>
+    fetch(channelId: string, opts?: DmFetchOptions): Promise<{ messages: DmMessage[]; hasMore: boolean; raw: unknown }>
+    fetchAll(channelId: string, opts?: { max?: number; pageSize?: number }): Promise<DmMessage[]>
+    send(channelId: string, content: string): Promise<DmMessage>
+    edit(channelId: string, messageId: string, content: string): Promise<DmMessage>
+    delete(channelId: string, messageId: string): Promise<{ id: string; raw: unknown }>
+    read(channelId: string): Promise<{ ok: boolean; raw: unknown }>
+  }
+  roles: {
+    list(guildId: string): Promise<Role[]>
+    get(guildId: string, roleId: string): Promise<Role>
+    create(guildId: string, opts: RoleCreateOptions): Promise<Role>
+    update(guildId: string, roleId: string, patch: RoleUpdateOptions): Promise<Role | Role[]>
+    delete(guildId: string, roleId: string): Promise<{ id: string }>
+    reorder(guildId: string, orderedIds: string[]): Promise<Role[]>
+    memberRoles(guildId: string, userId: string): Promise<MemberRoles>
+    setMemberRoles(guildId: string, userId: string, roleIds: string[]): Promise<MemberRoles>
+    addMemberRole(guildId: string, userId: string, roleId: string): Promise<MemberRoles>
+    removeMemberRole(guildId: string, userId: string, roleId: string): Promise<MemberRoles>
+    highestOf(roles: Role[], roleIds: string[], isOwner?: boolean): Role | null
+    highestPosition(roles: Role[], roleIds: string[], isOwner?: boolean): number
+    memberPermissions(roles: Role[], roleIds: string[], isOwner?: boolean): number
+    hasPermission(roles: Role[], roleIds: string[], permission: number, isOwner?: boolean): boolean
+    canManage(roles: Role[], actorRoleIds: string[], targetRole: Role, opts?: { actorIsOwner?: boolean }): HierarchyCheck
+    canAssign(roles: Role[], actorRoleIds: string[], role: Role, opts?: { actorIsOwner?: boolean }): HierarchyCheck
+    canModerate(roles: Role[], actorRoleIds: string[], targetRoleIds: string[], opts?: { actorIsOwner?: boolean; targetIsOwner?: boolean; self?: boolean }): HierarchyCheck
+  }
+  members: {
+    list(guildId: string, opts?: MemberListOptions): Promise<MemberListResult>
+    get(guildId: string, userId: string): Promise<Member>
+    kick(guildId: string, userId: string, reason?: string | { reason?: string }): Promise<{ id: string; raw: unknown }>
+    ban(guildId: string, userId: string, opts?: BanOptions | string): Promise<BanResult>
+    unban(guildId: string, userId: string): Promise<{ id: string; raw: unknown }>
+    bans(guildId: string): Promise<{ bans: BanEntry[]; bannedUserIds: string[]; raw: unknown }>
+  }
+  messages: {
+    send(channelId: string, content: string | { content: string; replyTo?: string; reply_to?: string }): Promise<Message>
+    reply(channelId: string, messageId: string, content: string): Promise<Message>
+    edit(channelId: string, messageId: string, content: string): Promise<Message>
+    delete(channelId: string, messageId: string): Promise<{ id: string }>
+    fetch(channelId: string, opts?: { limit?: number; before?: string }): Promise<FetchMessagesResult>
+    fetchAll(channelId: string, opts?: { max?: number; pageSize?: number }): Promise<Message[]>
+  }
+  oauth: { info(guildId?: string): Promise<OAuthInfo> }
+  gateway: RavenGateway
+  request(method: string, path: string, opts?: { query?: Record<string, unknown>; body?: unknown }): Promise<unknown>
+  onMessage(callback: (m: Message) => void | Promise<void>, opts: PollOptions): Promise<MessagePoller>
+  discoverTextChannels(): Promise<Array<{ guild: Guild; channel: Channel }>>
+  createCommands(options?: ConstructorParameters<typeof CommandHandler>[0]): CommandHandler
+}
+
+export function createClient(options: ClientOptions): RavenClient
+
+export class RavenError extends Error {
+  status: number
+  code: string
+  details: unknown
+  retryAfter: number | null
+  endpoint?: string | null
+  suggestion?: string
+  suggestions?: string[]
+  suggestionsHint?: string
+  validTitle?: string
+  valid?: string[]
+  received?: string
+  expected?: string
+  example?: string
+  hints?: string[]
+  docs?: string
+}
+export class RavenAPIError extends RavenError { endpoint: string | null }
+export class RavenAuthError extends RavenAPIError {}
+export class RavenPermissionError extends RavenAPIError {}
+export class RavenRateLimitError extends RavenAPIError {}
+export class RavenValidationError extends RavenAPIError {}
+export class RavenNotFoundError extends RavenAPIError {}
+export class AuthenticationError extends RavenError {}
+export class MissingScopeError extends RavenError { scope: string }
+export class NotInstalledError extends RavenError {}
+export class NotFoundError extends RavenError {}
+export class ValidationError extends RavenError {}
+export class RateLimitedError extends RavenError {}
+export class GatewayNotAvailableError extends RavenError {}
+
+export function sanitizeContent(s: unknown): string
+export function escapeContent(s: unknown): string
+export function isBotAuthorId(id: unknown): boolean
+export function toCamel(obj: unknown): unknown
+export function parseMentions(content: unknown): { userIds: string[]; everyone: boolean; here: boolean }
+
+export interface Suggestion { value: string; distance: number; confidence: number }
+export function editDistance(a: unknown, b: unknown): number
+export function suggest(input: unknown, candidates: unknown[], options?: { limit?: number }): Suggestion | null
+export function suggestAll(input: unknown, candidates: unknown[], options?: { limit?: number }): Suggestion[]
+export function withSuggestions<T extends object>(target: T, label: string): T
+export function formatError(err: unknown, options?: { color?: boolean; baseDir?: string; file?: string; line?: number; column?: number }): string
+export function markDiff(received: unknown, suggested: unknown): string | null
+export function unknownOption(args: { option: string; valid: string[]; label?: string }): RavenError
+export function invalidChoice(args: { label: string; received: string; valid: string[]; validTitle?: string }): RavenError
+export function missingArgument(args: { label: string; param: string; example?: string }): RavenError