novaapp-sdk 1.0.0

package/README.md

@@ -0,0 +1,329 @@
+# nova-bot-sdk
+
+Official SDK for building bots on the [Nova](https://nova.chat) platform.
+
+## Installation
+
+```bash
+npm install nova-bot-sdk
+```
+
+## Quick Start
+
+```ts
+import { NovaClient } from 'nova-bot-sdk'
+
+const client = new NovaClient({ token: 'nova_bot_your_token_here' })
+
+client.on('ready', (bot) => {
+  console.log(`Logged in as ${bot.botUser.username}`)
+})
+
+client.on('interactionCreate', async (interaction) => {
+  if (interaction.commandName === 'ping') {
+    await client.interactions.respond(interaction.id, { content: 'Pong! 🏓' })
+  }
+})
+
+// Register commands once at startup
+await client.connect()
+
+await client.commands.setSlash([
+  { name: 'ping', description: 'Check if the bot is alive' },
+])
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `token` | `string` | **required** | Your bot token (`nova_bot_...`) |
+| `baseUrl` | `string` | `https://api.nova.chat` | Override for self-hosted deployments |
+
+## API Reference
+
+### `client.messages`
+
+```ts
+// Send a message
+await client.messages.send(channelId, { content: 'Hello!' })
+
+// Send with embed
+await client.messages.send(channelId, {
+  embed: {
+    title: 'Report',
+    description: 'All systems operational.',
+    color: 0x5865f2,
+  },
+})
+
+// Send with action buttons
+await client.messages.send(channelId, {
+  content: 'Confirm action?',
+  components: [
+    { type: 'button', customId: 'confirm', label: 'Confirm', style: 'success' },
+    { type: 'button', customId: 'cancel',  label: 'Cancel',  style: 'danger'  },
+  ],
+})
+
+// Edit a message
+await client.messages.edit(messageId, { content: 'Updated!' })
+
+// Delete a message
+await client.messages.delete(messageId)
+
+// Fetch recent messages
+const messages = await client.messages.fetch(channelId, { limit: 50 })
+
+// Show typing indicator
+await client.messages.typing(channelId)
+```
+
+### `client.commands`
+
+```ts
+// Slash commands
+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' },
+  ]},
+])
+const slash = await client.commands.getSlash()
+await client.commands.deleteSlash('ban')
+
+// Prefix commands  
+await client.commands.setPrefix([
+  { prefix: '!', name: 'help',  description: 'Show help' },
+  { prefix: '!', name: 'stats', description: 'Show bot stats' },
+])
+const prefix = await client.commands.getPrefix()
+await client.commands.deletePrefix('!', 'help')
+
+// Context menu commands (right-click)
+await client.commands.setContext([
+  { name: 'Report message', target: 'MESSAGE' },
+  { name: 'View profile',   target: 'USER'    },
+])
+```
+
+### `client.interactions`
+
+```ts
+client.on('interactionCreate', async (interaction) => {
+  // Acknowledge immediately (shows loading state)
+  await client.interactions.ack(interaction.id)
+
+  // Do your work...
+  const result = await doExpensiveWork()
+
+  // Respond with result
+  await client.interactions.respond(interaction.id, {
+    content: result,
+    ephemeral: true, // only visible to the user who triggered it
+  })
+})
+
+// Poll for pending interactions (HTTP polling mode, no WebSocket)
+const pending = await client.interactions.poll({ limit: 20 })
+```
+
+### `client.members`
+
+```ts
+// List server members
+const members = await client.members.list(serverId, { limit: 100 })
+
+// Kick a member (cannot kick OWNER or ADMIN)
+await client.members.kick(serverId, userId)
+
+// Ban a member
+await client.members.ban(serverId, userId, 'Spamming')
+```
+
+### `client.servers`
+
+```ts
+// List all servers the bot is in
+const servers = await client.servers.list()
+console.log(`Active in ${servers.length} servers`)
+```
+
+## 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('Error:', err.message))
+
+// Interactions
+client.on('interactionCreate', (interaction) => { /* ... */ })
+
+// Messages (convenience events)
+client.on('messageCreate', (data) => { /* ... */ })
+client.on('messageUpdate', (data) => { /* ... */ })
+client.on('messageDelete', (data) => { /* ... */ })
+client.on('reactionAdd',   (data) => { /* ... */ })
+client.on('reactionRemove',(data) => { /* ... */ })
+
+// Members
+client.on('memberAdd',    (data) => { /* ... */ })
+client.on('memberRemove', (data) => { /* ... */ })
+client.on('typingStart',  (data) => { /* ... */ })
+
+// All raw events
+client.on('event', (event) => {
+  console.log(event.type, event.data, event.timestamp)
+})
+```
+
+### All event types
+
+| Event type | Fired when |
+|---|---|
+| `message.created` | A message is sent in a server the bot is in |
+| `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 item is chosen |
+| `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
+
+For ultra-low-latency message sending without an HTTP round-trip:
+
+```ts
+// Send via WebSocket (fire and forget)
+client.wsSend(channelId, 'Hello!')
+
+// Typing indicators via WebSocket
+client.wsTypingStart(channelId)
+client.wsTypingStop(channelId)
+```
+
+## Full example — Moderation bot
+
+```ts
+import { NovaClient } from 'nova-bot-sdk'
+
+const client = new NovaClient({ token: process.env.NOVA_BOT_TOKEN! })
+
+client.on('ready', async (bot) => {
+  console.log(`[${bot.botUser.username}] Ready!`)
+
+  await client.commands.setSlash([
+    {
+      name: 'ban',
+      description: 'Ban a user from the server',
+      options: [
+        { name: 'user',   description: 'User to ban',    type: 'USER',   required: true  },
+        { name: 'reason', description: 'Reason for ban', type: 'STRING', required: false },
+      ],
+    },
+    {
+      name: 'warn',
+      description: 'Warn a user',
+      options: [
+        { name: 'user',    description: 'User to warn',  type: 'USER',   required: true },
+        { name: 'message', description: 'Warning message', type: 'STRING', required: true },
+      ],
+    },
+  ])
+})
+
+client.on('interactionCreate', async (interaction) => {
+  if (interaction.commandName === 'ban') {
+    await client.interactions.ack(interaction.id)
+
+    const data = interaction.data as { options?: Array<{ name: string; value: string }> }
+    const userId = data.options?.find((o) => o.name === 'user')?.value
+    const reason = data.options?.find((o) => o.name === 'reason')?.value ?? 'No reason provided'
+
+    if (!userId || !interaction.serverId) {
+      await client.interactions.respond(interaction.id, {
+        content: '❌ Missing user or server context.',
+        ephemeral: true,
+      })
+      return
+    }
+
+    try {
+      await client.members.ban(interaction.serverId, userId, reason)
+      await client.interactions.respond(interaction.id, {
+        embed: {
+          title: '🔨 User banned',
+          description: `<@${userId}> was banned. Reason: ${reason}`,
+          color: 0xff4444,
+        },
+      })
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      await client.interactions.respond(interaction.id, {
+        content: `❌ Failed to ban: ${message}`,
+        ephemeral: true,
+      })
+    }
+  }
+
+  if (interaction.commandName === 'warn') {
+    const data = interaction.data as { options?: Array<{ name: string; value: string }> }
+    const userId = data.options?.find((o) => o.name === 'user')?.value
+    const message = data.options?.find((o) => o.name === 'message')?.value
+
+    await client.interactions.respond(interaction.id, {
+      embed: {
+        title: '⚠️ Warning issued',
+        description: `<@${userId}> — ${message}`,
+        color: 0xffa500,
+      },
+    })
+  }
+})
+
+client.on('error', (err) => {
+  console.error('[Bot]', err.message)
+})
+
+client.connect().then(() => console.log('Connected to Nova gateway'))
+```
+
+## Self-hosted deployments
+
+If you're running your own Nova server, pass the base URL:
+
+```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 will surface a `429` error if you exceed this. Build in exponential back-off for batch operations.
+
+## License
+
+MIT