novaapp-sdk 1.3.1 → 1.3.2

package/README.md

@@ -1,14 +1,977 @@
-# nova-bot-sdk
+# novaapp-sdk
 
 Official SDK for building bots on the [Nova](https://novachatapp.com) platform.
 
+> **Current version: 1.3.0**
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Routing handlers](#routing-handlers)
+- [Rich wrappers](#rich-wrappers)
+- [API reference](#api-reference)
+- [Fluent builders](#fluent-builders)
+- [Utilities](#utilities)
+- [Events](#events)
+- [WebSocket helpers](#websocket-helpers)
+- [Examples](#examples)
+
+---
+
 ## Installation
 
 ```bash
-npm install nova-bot-sdk
+npm install novaapp-sdk
+```
+
+---
+
+## Quick start
+
+```ts
+import { NovaClient, EmbedBuilder } from 'novaapp-sdk'
+
+const client = new NovaClient({ token: process.env.NOVA_BOT_TOKEN! })
+
+client.on('ready', async (bot) => {
+  console.log(`Logged in as ${bot.botUser.username}`)
+
+  await client.commands.setSlash([
+    { name: 'ping', description: 'Check if the bot is alive' },
+  ])
+})
+
+// Slash command routing
+client.command('ping', async (interaction) => {
+  await interaction.reply('Pong! 🏓')
+})
+
+// Button routing
+client.button('confirm', async (interaction) => {
+  await interaction.replyEphemeral('Confirmed!')
+})
+
+// Modal submission routing
+client.modal('report_modal', async (interaction) => {
+  const reason = interaction.modalData['reason']
+  await interaction.replyEphemeral(`Report received: ${reason}`)
+})
+
+await client.connect()
+```
+
+---
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `token` | `string` | **required** | Your bot token (`nova_bot_...`) |
+| `baseUrl` | `string` | `https://novachatapp.com` | Override for self-hosted Nova servers |
+
+---
+
+## Routing handlers
+
+Instead of handling everything inside `interactionCreate`, use the built-in router:
+
+```ts
+// /slash and !prefix commands
+client.command('ban', async (interaction) => {
+  const userId = interaction.options.getUser('user', true)
+  const reason = interaction.options.getString('reason') ?? 'No reason given'
+  await client.members.ban(interaction.serverId!, userId, reason)
+  await interaction.reply(`✅ Banned <@${userId}>`)
+})
+
+// Button clicks
+client.button('delete_confirm', async (interaction) => {
+  await interaction.replyEphemeral('Deleted.')
+})
+
+// Select menus
+client.selectMenu('colour_pick', async (interaction) => {
+  const chosen = interaction.values[0]
+  await interaction.reply(`You picked: ${chosen}`)
+})
+
+// Modal submissions
+client.modal('feedback_modal', async (interaction) => {
+  const text = interaction.modalData['feedback']
+  await interaction.replyEphemeral(`Thanks: ${text}`)
+})
+```
+
+---
+
+## Rich wrappers
+
+### `NovaInteraction`
+
+Returned by every interaction event and routing handler.
+
+```ts
+client.on('interactionCreate', async (interaction) => {
+  interaction.id           // string
+  interaction.type         // 'SLASH_COMMAND' | 'BUTTON_CLICK' | 'SELECT_MENU' | 'MODAL_SUBMIT' | …
+  interaction.commandName  // string | null
+  interaction.customId     // string | null  (buttons / selects / modals)
+  interaction.userId       // string
+  interaction.channelId    // string
+  interaction.serverId     // string | null
+  interaction.values       // string[]  (select menu choices)
+  interaction.modalData    // Record<string, string>  (modal submitted values)
+
+  // Type guards
+  interaction.isSlashCommand()
+  interaction.isPrefixCommand()
+  interaction.isCommand()       // slash OR prefix
+  interaction.isButton()
+  interaction.isSelectMenu()
+  interaction.isModalSubmit()
+  interaction.isAutocomplete()
+  interaction.isContextMenu()
+
+  // Typed option accessor
+  const userId = interaction.options.getUser('user', true)
+  const reason = interaction.options.getString('reason') ?? 'No reason'
+  const count  = interaction.options.getInteger('count')  // number | null
+
+  // Actions
+  await interaction.reply('Hello!')
+  await interaction.reply({ content: 'Hi', ephemeral: true, embed: { title: 'Stats' } })
+  await interaction.replyEphemeral('Only you can see this.')
+  await interaction.defer()            // acknowledge — shows loading state
+  await interaction.editReply('Done!') // edit after defer()
+
+  // Open a modal and await its submission
+  const submitted = await interaction.openModal(
+    new ModalBuilder()
+      .setTitle('Report')
+      .setCustomId('report')
+      .addField(new TextInputBuilder().setCustomId('reason').setLabel('Reason').setRequired(true))
+  )
+  if (submitted) {
+    await submitted.replyEphemeral(`Received: ${submitted.modalData['reason']}`)
+  }
+})
+```
+
+### `NovaMessage`
+
+Returned by `messageCreate` / `messageUpdate` events and message fetch calls.
+
+```ts
+client.on('messageCreate', async (msg) => {
+  msg.id          // string
+  msg.content     // string
+  msg.channelId   // string
+  msg.author      // { id, username, displayName, avatar, isBot }
+  msg.embed       // Embed | null
+  msg.components  // MessageComponent[]
+  msg.attachments // Attachment[]
+  msg.reactions   // Reaction[]
+  msg.replyToId   // string | null
+  msg.createdAt   // Date
+  msg.editedAt    // Date | null
+
+  msg.isFromBot()
+  msg.hasEmbed()
+  msg.hasComponents()
+  msg.isEdited()
+
+  await msg.reply('Got it!')
+  await msg.edit('Updated')
+  await msg.delete()
+  await msg.pin()
+  await msg.unpin()
+  await msg.react('👍')
+  await msg.removeReaction('👍')
+  const fresh = await msg.fetch()
+
+  console.log(msg.url)  // '/channels/<id>/messages/<id>'
+})
+```
+
+### `NovaChannel`
+
+Returned by `client.fetchChannel()` and `client.fetchChannels()`.
+
+```ts
+const channel = await client.fetchChannel('channel-id')
+
+channel.id        // string
+channel.name      // string
+channel.type      // 'TEXT' | 'VOICE' | 'ANNOUNCEMENT' | 'FORUM' | 'STAGE'
+channel.serverId  // string | null
+channel.topic     // string | null
+channel.position  // number
+channel.slowMode  // number (seconds; 0 = disabled)
+channel.createdAt // Date
+
+channel.isText()
+channel.isVoice()
+channel.isAnnouncement()
+channel.isForum()
+channel.isStage()
+channel.hasSlowMode()
+
+await channel.send('Hello!')
+await channel.send({ content: 'Hi', embed: { title: 'News' } })
+const messages = await channel.fetchMessages({ limit: 50 })
+const pins     = await channel.fetchPins()
+await channel.startTyping()
+const updated  = await channel.edit({ topic: 'New topic', slowMode: 5 })
+await channel.delete()
 ```
 
-## Quick Start
+### `NovaMember`
+
+Returned by `client.fetchMember()` and `client.fetchMembers()`.
+
+```ts
+const member = await client.fetchMember('server-id', 'user-id')
+
+member.userId       // string
+member.serverId     // string
+member.username     // string
+member.displayName  // string
+member.avatar       // string | null
+member.role         // 'OWNER' | 'ADMIN' | 'MEMBER'
+member.status       // 'ONLINE' | 'IDLE' | 'DND' | 'OFFLINE'
+member.isBot        // boolean
+member.joinedAt     // Date
+
+member.isOwner()
+member.isAdmin()          // ADMIN *or* OWNER
+member.isRegularMember()
+member.isOnline()
+member.isIdle()
+member.isDND()
+member.isOffline()
+
+await member.kick()
+await member.ban('Spamming')
+await member.dm('Welcome!')
+await member.addRole('role-id')
+await member.removeRole('role-id')
+```
+
+---
+
+## API reference
+
+### `client.messages`
+
+```ts
+await client.messages.send(channelId, { content: 'Hi!' })
+await client.messages.send(channelId, { embed: { title: 'Report', color: '#5865F2' } })
+await client.messages.send(channelId, {
+  content: 'Pick one:',
+  components: [
+    { type: 'button', customId: 'yes', label: 'Yes', style: 'success' },
+    { type: 'button', customId: 'no',  label: 'No',  style: 'danger'  },
+  ],
+})
+
+await client.messages.edit(messageId, { content: 'Updated' })
+await client.messages.delete(messageId)
+
+const msg      = await client.messages.fetchOne(messageId)
+const messages = await client.messages.fetch(channelId, { limit: 50, before: cursorId })
+const pins     = await client.messages.fetchPinned(channelId)
+
+await client.messages.pin(messageId)
+await client.messages.unpin(messageId)
+await client.messages.typing(channelId)
+
+await client.messages.addReaction(messageId, '👍')
+await client.messages.removeReaction(messageId, '👍')
+const reactions = await client.messages.fetchReactions(messageId)
+```
+
+### `client.channels`
+
+```ts
+const channels = await client.channels.list(serverId)
+const channel  = await client.channels.fetch(channelId)
+
+const newChan = await client.channels.create(serverId, {
+  name: 'announcements', type: 'ANNOUNCEMENT', topic: 'Official news',
+})
+
+await client.channels.edit(channelId, { topic: 'New topic', slowMode: 10 })
+await client.channels.delete(channelId)
+
+const messages = await client.channels.fetchMessages(channelId, { limit: 20 })
+const pins     = await client.channels.fetchPins(channelId)
+await client.channels.startTyping(channelId)
+```
+
+Rich wrapper shortcuts (return `NovaChannel`):
+
+```ts
+const channel  = await client.fetchChannel(channelId)
+const channels = await client.fetchChannels(serverId)
+const textOnly = channels.filter(c => c.isText())
+```
+
+### `client.reactions`
+
+```ts
+await client.reactions.add(messageId, '🎉')
+await client.reactions.remove(messageId, '🎉')
+await client.reactions.removeAll(messageId)          // requires messages.manage
+await client.reactions.removeEmoji(messageId, '🎉')  // all of one emoji
+
+const all    = await client.reactions.fetch(messageId)
+// [{ emoji: '🎉', count: 3, users: [{ id, username, displayName, avatar }] }, …]
+
+const detail = await client.reactions.fetchEmoji(messageId, '🎉')
+// { emoji: '🎉', count: 3, users: […] }
+```
+
+### `client.members`
+
+```ts
+const members = await client.members.list(serverId, { limit: 100 })
+await client.members.kick(serverId, userId)
+await client.members.ban(serverId, userId, 'Reason')
+await client.members.unban(serverId, userId)
+
+const bans = await client.members.listBans(serverId)
+// [{ userId, username, displayName, avatar, reason, bannedAt, moderatorId }]
+
+await client.members.dm(userId, 'Hello!')
+await client.members.dm(userId, { content: 'Hi', embed: { title: 'Welcome' } })
+
+await client.members.addRole(serverId, userId, roleId)
+await client.members.removeRole(serverId, userId, roleId)
+```
+
+Rich wrapper shortcuts (return `NovaMember`):
+
+```ts
+const member  = await client.fetchMember(serverId, userId)
+const members = await client.fetchMembers(serverId)
+const bots    = members.filter(m => m.isBot)
+```
+
+### `client.servers`
+
+```ts
+const servers = await client.servers.list()
+const roles   = await client.servers.listRoles(serverId)
+// [{ id, name, color, position, serverId, hoist, createdAt }]
+```
+
+### `client.commands`
+
+```ts
+await client.commands.setSlash([
+  { name: 'ban', description: 'Ban a user', options: [
+    { name: 'user',   description: 'User to ban', type: 'USER',   required: true  },
+    { name: 'reason', description: 'Reason',      type: 'STRING', required: false },
+  ]},
+])
+const slash = await client.commands.getSlash()
+await client.commands.deleteSlash('ban')
+
+await client.commands.setPrefix([{ prefix: '!', name: 'help', description: 'Show help' }])
+const prefix = await client.commands.getPrefix()
+await client.commands.deletePrefix('!', 'help')
+
+await client.commands.setContext([
+  { name: 'Report message', target: 'MESSAGE' },
+  { name: 'View profile',   target: 'USER'    },
+])
+```
+
+### `client.interactions`
+
+```ts
+await client.interactions.ack(interaction.id)            // acknowledge (show loading)
+await client.interactions.respond(interaction.id, { content: 'Done!', ephemeral: true })
+
+// Open a modal (low-level)
+await client.interactions.respond(interaction.id, {
+  modal: {
+    title: 'Report', customId: 'report_modal',
+    fields: [{ customId: 'reason', label: 'Reason', type: 'paragraph', required: true }],
+  },
+})
+
+const pending = await client.interactions.poll({ limit: 20 })
+```
+
+### `client.permissions`
+
+```ts
+const result = await client.permissions.get({
+  serverId:  'server-id',
+  channelId: 'channel-id', // optional
+  roleId:    'role-id',    // optional
+})
+result.permissions // merged Record<string, boolean>
+result.records     // raw permission records
+```
+
+### `client.cron()` — recurring tasks
+
+```ts
+const cancel = client.cron(60_000, async () => {
+  const msgs = await client.messages.fetch(channelId, { limit: 1 })
+  console.log('Latest:', msgs[0]?.content)
+})
+
+cancel() // stop the task
+```
+
+### `client.setStatus()`
+
+```ts
+client.setStatus('ONLINE')   // default
+client.setStatus('IDLE')     // away
+client.setStatus('DND')      // Do Not Disturb
+client.setStatus('OFFLINE')  // appear offline
+```
+
+### `client.waitFor()` — event fence
+
+```ts
+// Wait for a message in a specific channel (default 30 s timeout)
+const msg = await client.waitFor(
+  'messageCreate',
+  (m) => m.channelId === channelId,
+)
+
+// Wait for a button click, throw after 60 s
+const click = await client.waitFor(
+  'interactionCreate',
+  (i) => i.isButton() && i.customId === 'confirm',
+  60_000,
+)
+```
+
+---
+
+## Fluent builders
+
+### `EmbedBuilder`
+
+```ts
+const embed = new EmbedBuilder()
+  .setTitle('Server stats')
+  .setDescription('All systems operational.')
+  .setColor('#5865F2')
+  .setThumbnail('https://example.com/logo.png')
+  .addField('Members', '1,234', true)
+  .addField('Online',  '456',   true)
+  .setFooter('Updated just now')
+  .setTimestamp()
+  .toJSON()
+
+await client.messages.send(channelId, { embed })
+```
+
+### `ButtonBuilder` + `ActionRowBuilder`
+
+```ts
+const row = new ActionRowBuilder()
+  .addComponent(
+    new ButtonBuilder().setCustomId('yes').setLabel('Yes').setStyle('success').toJSON()
+  )
+  .addComponent(
+    new ButtonBuilder().setCustomId('no').setLabel('No').setStyle('danger').toJSON()
+  )
+  .toJSON()
+
+await client.messages.send(channelId, { content: 'Confirm?', components: [row] })
+```
+
+### `SelectMenuBuilder`
+
+```ts
+const row = new ActionRowBuilder()
+  .addComponent(
+    new SelectMenuBuilder()
+      .setCustomId('colour_pick')
+      .setPlaceholder('Choose a colour')
+      .addOption({ label: 'Red',   value: 'red'   })
+      .addOption({ label: 'Blue',  value: 'blue'  })
+      .addOption({ label: 'Green', value: 'green' })
+      .toJSON()
+  )
+  .toJSON()
+
+await client.messages.send(channelId, { content: 'Pick:', components: [row] })
+```
+
+### `ModalBuilder` + `TextInputBuilder`
+
+```ts
+const modal = new ModalBuilder()
+  .setTitle('Submit a report')
+  .setCustomId('report_modal')
+  .addField(
+    new TextInputBuilder()
+      .setCustomId('subject')
+      .setLabel('Subject')
+      .setStyle('short')
+      .setRequired(true)
+      .setMaxLength(100)
+  )
+  .addField(
+    new TextInputBuilder()
+      .setCustomId('description')
+      .setLabel('Description')
+      .setStyle('paragraph')
+      .setRequired(true)
+  )
+
+const submitted = await interaction.openModal(modal)
+if (submitted) {
+  const subject = submitted.modalData['subject']
+  const desc    = submitted.modalData['description']
+  await submitted.replyEphemeral(`Filed: ${subject}`)
+}
+```
+
+### `SlashCommandBuilder`
+
+```ts
+const cmd = new SlashCommandBuilder()
+  .setName('kick')
+  .setDescription('Kick a member')
+  .addOption(
+    new SlashCommandOptionBuilder()
+      .setName('user').setDescription('Member to kick').setType('USER').setRequired(true)
+  )
+  .toJSON()
+
+await client.commands.setSlash([cmd])
+```
+
+### `PollBuilder`
+
+```ts
+const poll = new PollBuilder()
+  .setQuestion('Best programming language?')
+  .addOption({ id: 'ts', label: 'TypeScript', emoji: '💙' })
+  .addOption({ id: 'rs', label: 'Rust',       emoji: '🦀' })
+  .addOption({ id: 'py', label: 'Python',     emoji: '🐍' })
+  .setMultipleChoice(false)
+  .toJSON()
+
+await client.messages.send(channelId, { content: 'Vote below!', ...poll })
+```
+
+### `MessageBuilder`
+
+Compose content, embeds, and components fluently:
+
+```ts
+const msg = new MessageBuilder()
+  .setContent('New announcement!')
+  .setEmbed(
+    new EmbedBuilder()
+      .setTitle('v2.0 Released')
+      .setDescription('Check the changelog for details.')
+      .setColor('#57F287')
+      .toJSON()
+  )
+  .addRow(
+    new ActionRowBuilder()
+      .addComponent(
+        new ButtonBuilder().setCustomId('changelog').setLabel('View changelog').setStyle('primary').toJSON()
+      )
+      .toJSON()
+  )
+  .build()
+
+await client.messages.send(channelId, msg)
+```
+
+---
+
+## Utilities
+
+### `Collection<K, V>`
+
+A supercharged `Map` with array-style helpers:
+
+```ts
+const col = new Collection<string, User>()
+col.set('1', { id: '1', name: 'Alice' })
+col.set('2', { id: '2', name: 'Bob'   })
+
+col.first()                        // { id: '1', name: 'Alice' }
+col.last()                         // { id: '2', name: 'Bob' }
+col.random()                       // random value
+col.find(v => v.name === 'Bob')    // { id: '2', … }
+col.filter(v => v.name.length > 3) // Collection with Alice
+col.map(v => v.name)               // ['Alice', 'Bob']
+col.some(v => v.name === 'Alice')  // true
+col.every(v => v.id.length > 0)    // true
+col.toArray()                      // [{ … }, { … }]
+```
+
+### `Paginator<T>`
+
+Cursor-based async paginator for any list API:
+
+```ts
+const paginator = new Paginator(async (cursor) => {
+  const messages = await client.messages.fetch(channelId, {
+    limit: 50, before: cursor ?? undefined,
+  })
+  return { items: messages, cursor: messages.at(-1)?.id ?? null }
+})
+
+// Async iteration
+for await (const msg of paginator) {
+  console.log(msg.content)
+}
+
+// Collect everything at once
+const all = await paginator.fetchAll()
+
+// Collect first N
+const first200 = await paginator.fetchN(200)
+
+// Reset and iterate again from the start
+paginator.reset()
+```
+
+### `PermissionsBitfield`
+
+Work with Nova bot permissions as a typed bitfield:
+
+```ts
+import { PermissionsBitfield, Permissions } from 'novaapp-sdk'
+
+const perms = new PermissionsBitfield({
+  [Permissions.MESSAGES_READ]:  true,
+  [Permissions.MESSAGES_WRITE]: true,
+})
+
+perms.has(Permissions.MESSAGES_READ)    // true
+perms.has(Permissions.CHANNELS_MANAGE)  // false
+perms.hasAll(Permissions.MESSAGES_READ, Permissions.MESSAGES_WRITE) // true
+perms.hasAny(Permissions.CHANNELS_MANAGE, Permissions.SERVERS_MANAGE) // false
+perms.missing(Permissions.MESSAGES_MANAGE, Permissions.MEMBERS_BAN)
+// ['messages.manage', 'members.ban']
+
+const extended   = perms.grant(Permissions.CHANNELS_MANAGE)
+const restricted = perms.deny(Permissions.MESSAGES_WRITE)
+const merged     = serverPerms.merge(channelOverrides)
+
+perms.toArray() // ['messages.read', 'messages.write']
+```
+
+Available constants in `Permissions`:
+
+| Constant | Value |
+|---|---|
+| `MESSAGES_READ` | `'messages.read'` |
+| `MESSAGES_WRITE` | `'messages.write'` |
+| `MESSAGES_MANAGE` | `'messages.manage'` |
+| `CHANNELS_MANAGE` | `'channels.manage'` |
+| `MEMBERS_KICK` | `'members.kick'` |
+| `MEMBERS_BAN` | `'members.ban'` |
+| `MEMBERS_ROLES` | `'members.roles'` |
+| `SERVERS_MANAGE` | `'servers.manage'` |
+
+### `CooldownManager`
+
+Per-user / per-command cooldown tracking:
+
+```ts
+const cooldowns = new CooldownManager()
+
+client.command('daily', async (interaction) => {
+  if (cooldowns.isOnCooldown(interaction.userId, 'daily', 86_400_000)) {
+    const remaining = cooldowns.getRemaining(interaction.userId, 'daily', 86_400_000)
+    await interaction.replyEphemeral(`Try again in ${formatDuration(remaining)}.`)
+    return
+  }
+  cooldowns.set(interaction.userId, 'daily')
+  await interaction.reply('Here is your daily reward!')
+})
+```
+
+### `Logger`
+
+Coloured, namespaced console logger:
+
+```ts
+const log = new Logger('ModBot')
+
+log.info('Bot started')
+log.success('Command registered: ban')
+log.warn('Rate limit approaching')
+log.error('Failed to ban user', err)
+log.debug('Payload', interaction.toJSON())
+```
+
+### Time utilities
+
+```ts
+import {
+  sleep, withTimeout,
+  formatDuration, formatRelative,
+  parseTimestamp, countdown,
+} from 'novaapp-sdk'
+
+await sleep(2_000)                          // wait 2 s
+const data = await withTimeout(fetch(), 5_000) // throw if > 5 s
+
+formatDuration(90_000)          // '1m 30s'
+formatDuration(3_661_000)       // '1h 1m 1s'
+
+formatRelative(Date.now() - 4_000)       // 'just now'
+formatRelative(Date.now() - 90_000)      // '1 minute ago'
+formatRelative(Date.now() + 60_000)      // 'in 1 minute'
+formatRelative(Date.now() - 86_400_000)  // 'yesterday'
+
+parseTimestamp('2026-01-01T00:00:00Z')   // Date
+parseTimestamp(null)                     // null
+
+const { days, hours, minutes, seconds } = countdown(new Date('2027-01-01'))
+```
+
+---
+
+## Events
+
+```ts
+// Connection
+client.on('ready',      (bot)    => console.log('Ready!', bot.botUser.username))
+client.on('disconnect', (reason) => console.log('Disconnected:', reason))
+client.on('error',      (err)    => console.error(err))
+
+// Interactions
+client.on('interactionCreate', (interaction) => { /* NovaInteraction */ })
+
+// Messages
+client.on('messageCreate', (msg)  => { /* NovaMessage */ })
+client.on('messageUpdate', (msg)  => { /* NovaMessage */ })
+client.on('messageDelete', (data) => { /* { id, channelId } */ })
+client.on('messagePinned', (data) => { /* { messageId, channelId, pinnedBy } */ })
+
+// Reactions
+client.on('reactionAdd',    (data) => { /* { messageId, channelId, userId, emoji } */ })
+client.on('reactionRemove', (data) => { /* { messageId, channelId, userId, emoji } */ })
+
+// Members
+client.on('memberAdd',      (data) => { /* { serverId, userId, username } */ })
+client.on('memberRemove',   (data) => { /* { serverId, userId } */ })
+client.on('memberUpdate',   (data) => { /* { serverId, userId } */ })
+client.on('memberBanned',   (data) => { /* { userId, serverId, moderatorId, reason } */ })
+client.on('memberUnbanned', (data) => { /* { userId, serverId } */ })
+client.on('typingStart',    (data) => { /* { channelId, userId } */ })
+
+// Channels
+client.on('channelCreate', (channel) => { /* Channel */ })
+client.on('channelUpdate', (channel) => { /* Channel */ })
+client.on('channelDelete', (data)    => { /* { id, serverId } */ })
+
+// Roles
+client.on('roleCreate', (data) => { /* { id, name, color, serverId, position, hoist, createdAt } */ })
+client.on('roleDelete', (data) => { /* { id, serverId } */ })
+
+// Voice
+client.on('voiceJoin',  (data) => { /* { userId, channelId, serverId } */ })
+client.on('voiceLeave', (data) => { /* { userId, channelId, serverId } */ })
+
+// Raw event stream
+client.on('event', (event) => {
+  console.log(event.type, event.data, event.timestamp)
+})
+```
+
+### Raw event types
+
+| `event.type` | Fires when |
+|---|---|
+| `message.created` | A message is sent |
+| `message.edited` | A message is edited |
+| `message.deleted` | A message is deleted |
+| `message.reaction_added` | A reaction is added |
+| `message.reaction_removed` | A reaction is removed |
+| `message.pinned` | A message is pinned |
+| `user.joined_server` | A user joins a server |
+| `user.left_server` | A user leaves a server |
+| `user.updated_profile` | A user updates their profile |
+| `user.banned` | A user is banned |
+| `user.unbanned` | A user is unbanned |
+| `user.role_added` | A user receives a role |
+| `user.role_removed` | A role is removed from a user |
+| `user.started_typing` | A user starts typing |
+| `user.voice_joined` | A user joins a voice channel |
+| `user.voice_left` | A user leaves a voice channel |
+| `interaction.slash_command` | A slash command is used |
+| `interaction.button_click` | A button is clicked |
+| `interaction.select_menu` | A select menu is used |
+| `interaction.modal_submit` | A modal is submitted |
+| `interaction.autocomplete` | An autocomplete request fires |
+| `server.updated` | Server settings change |
+| `channel.created` | A channel is created |
+| `channel.deleted` | A channel is deleted |
+| `channel.updated` | A channel is updated |
+| `role.created` | A role is created |
+| `role.deleted` | A role is deleted |
+
+---
+
+## WebSocket helpers
+
+```ts
+// Send a message via WebSocket (lower latency than HTTP)
+client.wsSend(channelId, 'Hello!')
+
+// Typing indicators
+client.wsTypingStart(channelId)
+client.wsTypingStop(channelId)
+```
+
+---
+
+## Examples
+
+### Moderation bot
+
+```ts
+import { NovaClient, EmbedBuilder, CooldownManager, Logger } from 'novaapp-sdk'
+
+const client    = new NovaClient({ token: process.env.NOVA_BOT_TOKEN! })
+const log       = new Logger('ModBot')
+const cooldowns = new CooldownManager()
+
+client.on('ready', async (bot) => {
+  log.success(`Logged in as ${bot.botUser.username}`)
+
+  await client.commands.setSlash([
+    {
+      name: 'ban',
+      description: 'Ban a user from the server',
+      options: [
+        { name: 'user',   type: 'USER',   description: 'User to ban',    required: true  },
+        { name: 'reason', type: 'STRING', description: 'Reason for ban', required: false },
+      ],
+    },
+  ])
+})
+
+client.command('ban', async (interaction) => {
+  if (cooldowns.isOnCooldown(interaction.userId, 'ban', 3_000)) {
+    await interaction.replyEphemeral('Slow down!')
+    return
+  }
+  cooldowns.set(interaction.userId, 'ban')
+
+  const userId = interaction.options.getUser('user', true)
+  const reason = interaction.options.getString('reason') ?? 'No reason provided'
+
+  try {
+    await client.members.ban(interaction.serverId!, userId, reason)
+    await interaction.reply({
+      embed: new EmbedBuilder()
+        .setTitle('🔨 User banned')
+        .setDescription(`<@${userId}> was banned.\n**Reason:** ${reason}`)
+        .setColor('#FF4444')
+        .setTimestamp()
+        .toJSON(),
+    })
+  } catch (err) {
+    log.error('Ban failed', err)
+    await interaction.replyEphemeral(`❌ Failed: ${(err as Error).message}`)
+  }
+})
+
+client.on('memberBanned', ({ userId, serverId, reason }) => {
+  log.warn(`${userId} banned from ${serverId} — ${reason ?? 'no reason'}`)
+})
+
+client.on('error', (err) => log.error('Gateway error', err))
+await client.connect()
+```
+
+### Multi-step modal form
+
+```ts
+client.command('report', async (interaction) => {
+  const submitted = await interaction.openModal(
+    new ModalBuilder()
+      .setTitle('Submit a report')
+      .setCustomId('report_modal')
+      .addField(
+        new TextInputBuilder().setCustomId('subject').setLabel('Subject').setStyle('short').setRequired(true)
+      )
+      .addField(
+        new TextInputBuilder().setCustomId('details').setLabel('Details').setStyle('paragraph').setRequired(true)
+      )
+  )
+
+  if (!submitted) { await interaction.replyEphemeral('Cancelled.'); return }
+
+  await client.messages.send(logChannelId, {
+    embed: new EmbedBuilder()
+      .setTitle(`📋 ${submitted.modalData['subject']}`)
+      .setDescription(submitted.modalData['details'])
+      .addField('From', `<@${interaction.userId}>`, true)
+      .setTimestamp()
+      .toJSON(),
+  })
+
+  await submitted.replyEphemeral('Your report has been submitted.')
+})
+```
+
+### Paginate all messages in a channel
+
+```ts
+import { Paginator, formatRelative } from 'novaapp-sdk'
+
+const paginator = new Paginator(async (cursor) => {
+  const messages = await client.messages.fetch(channelId, {
+    limit: 100, before: cursor ?? undefined,
+  })
+  return { items: messages, cursor: messages.at(-1)?.id ?? null }
+})
+
+let total = 0
+for await (const msg of paginator) {
+  console.log(`[${formatRelative(msg.createdAt)}] ${msg.author.username}: ${msg.content}`)
+  total++
+}
+console.log(`Scanned ${total} messages`)
+```
+
+---
+
+## Self-hosted deployments
+
+```ts
+const client = new NovaClient({
+  token:   'nova_bot_...',
+  baseUrl: 'https://my-nova-server.example.com',
+})
+```
+
+---
+
+## Rate limits
+
+The Nova API enforces a limit of **50 requests/second** per bot. The SDK surfaces a `429` error if exceeded. Use `sleep()` and exponential back-off for bulk operations.
+
+---
+
+## License
+
+MIT
 
 ```ts
 import { NovaClient } from 'nova-bot-sdk'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novaapp-sdk",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Official SDK for building bots on the Nova platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",