privage.js 0.21.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Privage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,503 @@
+# privage.js
+
+The official SDK for building [Privage](https://privage.xyz) bots. It wraps the
+bot gateway so you write simple, familiar event handlers instead of raw
+WebSocket + opcodes.
+
+Full documentation: [privage.xyz/docs](https://privage.xyz/docs)
+
+> Feature-complete: messages (incl. threads), embeds and file attachments,
+> buttons, select menus, slash commands, modals, ephemeral replies, polls,
+> reactions, members/roles/moderation, presence, webhooks, collectors, a
+> self-maintaining name cache, and auto reconnect + resume — all typed.
+> Bot DMs are the one remaining backend-gated feature.
+
+## Install
+
+```bash
+npm install privage.js
+```
+
+## Quick start
+
+```ts
+import { Client, Intents } from 'privage.js';
+
+const client = new Client({ intents: [Intents.Messages] });
+
+client.on('ready', ({ user }) => console.log(`Logged in as ${user.username}`));
+
+client.on('messageCreate', async (msg) => {
+  if (msg.author.bot) return;              // loop guard
+  if (msg.content === '!ping') await msg.reply('pong');
+});
+
+client.login(process.env.PRIVAGE_BOT_TOKEN);
+```
+
+Create a bot in the Privage app (**User Settings → Bots**) and copy the
+token — it's shown once, at creation. Add the bot to a server from the same
+panel (needs **Manage Server** in the target). Full walkthrough:
+[Create a bot](https://privage.xyz/docs/create-a-bot).
+
+## Configuration
+
+The client connects to Privage production by default — no URLs needed.
+Overrides are for self-hosted or local-dev backends:
+
+```ts
+new Client({
+  intents: [Intents.Messages],
+  api: 'http://localhost:3001',          // default: $PRIVAGE_API or https://api.privage.xyz
+  ws: 'ws://localhost:4000/socket',      // default: $PRIVAGE_WS, derived from a custom `api`, or wss://ws.privage.xyz/socket
+  debug: false,                          // emit raw wire frames on the `debug` event
+});
+```
+
+## Intents
+
+Declare only what you handle. **Omitting intents entirely means you receive
+everything** — the SDK warns when you do.
+
+| Intent | Delivers |
+|--------|----------|
+| `Intents.Messages` | messages (including in-thread replies), edits, deletes, pins, polls, tip jars |
+| `Intents.Reactions` | reaction updates |
+| `Intents.Typing` | typing start/stop |
+| `Intents.Members` | member joins/leaves/updates, roles, nicknames |
+| `Intents.Moderation` | bans, kicks, timeouts |
+| `Intents.Servers` | channel/role/emoji/config structure changes |
+| `Intents.Interactions` | button clicks, select menus, slash commands, modal submits — delivered bot-direct |
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `ready` | `{ user }` — fired once, after the first connect |
+| `messageCreate` | `Message` |
+| `messageUpdate` | `Message` |
+| `messageDelete` | `{ id, channelId, serverId }` |
+| `messageDeleteBulk` | `{ ids, channelId, serverId }` |
+| `reactionUpdate` | `{ messageId, channelId, reactions }` — full snapshot |
+| `reactionAdd` | `{ messageId, channelId, emoji, userId }` — a specific user reacted |
+| `reactionRemove` | `{ messageId, channelId, emoji, userId }` |
+| `memberJoin` | `Member` |
+| `memberLeave` | `{ userId, serverId }` |
+| `roleAdd` / `roleRemove` | `{ serverId, userId, roleId }` |
+| `memberUpdate` | `{ serverId, userId, displayName?, avatarUrl?, nickname? }` |
+| `memberBan` / `memberUnban` | `{ serverId, userId, username, displayName }` |
+| `memberTimeout` | `{ serverId, userId, until, moderatorId, reason }` |
+| `memberUntimeout` | `{ serverId, userId }` |
+| `messagePin` / `messageUnpin` | `{ messageId, channelId }` |
+| `typingStart` / `typingStop` | `{ userId, channelId }` |
+| `channelCreate` / `channelUpdate` | `Channel` |
+| `channelDelete` | `{ channelId, serverId }` |
+| `roleCreate` / `roleUpdate` | `Role` |
+| `roleDelete` | `{ roleId, serverId }` |
+| `pollVote` | `{ pollId, messageId, voterId, optionIdx, totalVotes }` |
+| `pollClose` | `{ pollId, messageId, totalVotes }` |
+| `interaction` | `Interaction` — button click, select choice, slash command, or modal submit (discriminate with `.kind`) |
+| `connectionError` | `PrivageConnectionError` — recoverable; the SDK is reconnecting |
+| `warn` | `string` |
+| `debug` | `string` (only when `debug: true`) |
+
+## Reconnect & resume (automatic)
+
+You don't handle any of this. On a dropped connection the client reconnects
+with backoff, then **resumes** the event stream (replaying anything buffered
+while you were away) and, if the gap is too large for the buffer, transparently
+**REST-catches-up** the missed events — all deduplicated. Your handlers just
+keep firing; there is no "you missed events" state to manage. If a gap is too
+large even for catchup, you get a one-off `warn` suggesting a REST re-fetch.
+
+## Sending
+
+```ts
+await msg.reply('pong');                 // reply (threads via reply_to)
+msg.reference;                           // reply/forward/pin pointer (+preview), null otherwise
+msg.replyToId;                           // compat alias: reference.messageId for replies
+await msg.channel.send('hi');            // plain send
+await msg.channel.send({ content: 'rich', embeds: [ /* ... */ ] });  // embeds are bot-only
+
+await client.send(channelId, 'hi');      // send to any channel by id — no server id needed
+await client.channels.get(channelId)?.send('hi');  // same, via the cache
+```
+
+In-thread replies arrive as normal `messageCreate` events (with the thread as
+`channelId`), so a bot sees thread messages without any extra setup.
+
+## Embeds & attachments
+
+Build rich embeds with `EmbedBuilder` — pass builders straight into
+`embeds`, no `.toJSON()` call needed — and upload files with
+`AttachmentBuilder` (a path, `Buffer`, or `Blob`):
+
+```ts
+import { EmbedBuilder, AttachmentBuilder } from 'privage.js';
+
+await msg.channel.send({
+  embeds: [
+    new EmbedBuilder()
+      .setTitle('Deploy finished')
+      .setColor(0x35b9e8)                    // or '#35b9e8'
+      .addFields({ name: 'Duration', value: '42s', inline: true })
+      .setTimestamp(),
+  ],
+});
+
+await msg.channel.send({
+  content: "this week's report",
+  files: [new AttachmentBuilder('./report.pdf')],  // or Buffer/Blob + { name: '...' }
+});
+
+// Spoiler attachments render blurred until the viewer reveals them:
+await msg.channel.send({
+  files: [new AttachmentBuilder('./ending.png').setSpoiler()],
+});
+```
+
+Limits mirror the server (10 embeds/message — title ≤256, description ≤4096,
+≤25 fields; 10 files, 25 MB each) and the builders throw at build time where
+the server would silently truncate or drop. A message can carry embeds
+**or** attachments, not both (v1). The client renders one image slot per
+embed — `setThumbnail` wins over `setImage` if both are set.
+
+## Components & interactions
+
+Attach buttons and select menus to messages and handle every interaction —
+clicks, selections, slash commands, modal submits — as one `interaction`
+event, discriminated by `kind`. No message reading required
+(`Intents.Interactions` is delivered bot-direct, and covers all kinds):
+
+```ts
+import { Client, Intents, ButtonBuilder, SelectMenuBuilder, ActionRowBuilder } from 'privage.js';
+
+const client = new Client({ intents: [Intents.Interactions] });
+
+await client.send(channelId, {
+  content: 'Ticket #42',
+  components: [
+    new ActionRowBuilder().addButtons(
+      new ButtonBuilder().setStyle('primary').setLabel('Claim').setCustomId('ticket:claim:42'),
+      new ButtonBuilder().setStyle('link').setLabel('Logs').setURL('https://logs.example.com/42'),
+    ),
+    new ActionRowBuilder().addSelect(
+      new SelectMenuBuilder().setCustomId('ticket:severity').setPlaceholder('Severity')
+        .addOptions({ label: 'Low', value: 'low' }, { label: 'High', value: 'high' }),
+    ),
+  ],
+});
+
+client.on('interaction', async (interaction) => {
+  if (interaction.kind === 'select' && interaction.customId === 'ticket:severity') {
+    await interaction.reply({ content: `Severity set to ${interaction.values![0]}`, ephemeral: true });
+  }
+  if (interaction.customId === 'ticket:claim:42') {
+    await interaction.update({ content: `Ticket #42 — claimed by <@${interaction.user.id}>`, components: [] });
+  }
+});
+```
+
+Respond within 5 minutes with exactly one terminal callback —
+`interaction.update(...)` (edit the original; invalid for slash commands,
+which have no source message) or `interaction.reply(...)` — optionally after
+`interaction.defer()` (extends to 15 min). **Ephemeral replies**
+(`reply({ ..., ephemeral: true })`) are visible only to the interacting user
+and never persisted — great for confirmations and errors; valid for every
+kind. Selected values arrive on `interaction.values` (selects only).
+
+Limits: 5 rows/message; a row holds either ≤5 buttons or exactly one select
+(≤25 interactive components/message); label ≤80, `custom_id` ≤100 and unique
+per message; select options ≤25 with unique values. Link buttons take a URL
+and fire no event. Components can't share a message with file attachments
+(v1). `editMessage(id, { components })` replaces a message's rows (e.g.
+disable a panel).
+
+## Slash commands
+
+Register the bot's whole command set with a bulk overwrite (validated
+locally against the same grammar the server enforces), and handle
+invocations as `interaction` events with `kind: 'command'`:
+
+```ts
+await client.commands.set([
+  {
+    name: 'ticket',                       // ^[a-z0-9_-]{1,32}$
+    description: 'Open a support ticket', // ≤100 chars
+    options: [
+      { type: 'string', name: 'subject', description: 'What broke', required: true },
+      { type: 'integer', name: 'severity', description: 'How bad',
+        choices: [{ name: 'Low', value: 1 }, { name: 'High', value: 3 }] },
+    ],
+  },
+]);
+
+client.on('interaction', async (interaction) => {
+  if (interaction.kind !== 'command' || interaction.command?.name !== 'ticket') return;
+  const subject = interaction.command.getOption<string>('subject');
+  await interaction.reply({ content: `Ticket opened: ${subject}`, ephemeral: true });
+});
+```
+
+`client.commands.fetch()` lists the registered set; `set([])` clears it
+(`set` replaces the whole registry each time — 5/60s rate limit). Option
+types: `string | integer | number | boolean | user | channel | role`
+(user/channel/role values arrive as id strings); required options must
+precede optional ones; ≤50 commands, ≤10 options each, choices (≤25) only on
+string/integer/number. Command interactions carry no source message —
+respond with `reply(...)` (normal or ephemeral), never `update(...)`.
+
+## Modals
+
+Open a form in response to a button/select/command interaction; the
+submission comes back as a fresh `interaction` with `kind: 'modal_submit'`:
+
+```ts
+import { ModalBuilder, TextInputBuilder } from 'privage.js';
+
+client.on('interaction', async (interaction) => {
+  if (interaction.kind === 'button' && interaction.customId === 'ticket:open') {
+    await interaction.showModal(
+      new ModalBuilder().setTitle('Open a ticket').setCustomId('ticket-modal').addFields(
+        new TextInputBuilder().setCustomId('subject').setLabel('Subject').setStyle('short'),
+        new TextInputBuilder().setCustomId('details').setLabel('Details').setStyle('paragraph').setRequired(false),
+      ),
+    );
+  }
+  if (interaction.kind === 'modal_submit' && interaction.customId === 'ticket-modal') {
+    await interaction.reply({ content: `Got it: ${interaction.getField('subject')}`, ephemeral: true });
+  }
+});
+```
+
+`showModal(...)` is only valid from a *pending* interaction, once — not
+after `defer()`, not in response to a modal submit (the SDK throws
+client-side before the server would 400), and it does not extend the
+5-minute window. The submission is a brand-new interaction with a fresh
+window: read values via `interaction.getField(customId)` (or the raw
+`interaction.fields`), then `reply(...)` / `defer()` — `update(...)` works
+only when the modal was opened from a message component. Limits: title and
+labels ≤45, 1–5 fields, `short` inputs cap at 1024 chars, `paragraph` at
+4000.
+
+## Reactions, editing & fetching
+
+```ts
+await msg.react('👍');                    // add a reaction
+await msg.removeReaction('👍');           // remove the bot's own
+await msg.edit('updated text');           // edit the bot's own message
+await msg.pin(); await msg.unpin();
+
+const recent  = await client.fetchMessages(channelId, { limit: 50 });  // Message[]
+const members = await server.fetchMembers();  // Member[]
+const roles   = await server.fetchRoles();    // Role[] — e.g. roles.find(r => r.name === 'Mods')
+await msg.member.setNickname('New Nick');     // null to clear
+```
+
+REST calls automatically back off and retry on a 429 (up to 3 attempts,
+respecting `retryAfter`).
+
+## Presence
+
+Set the bot's own status and rich-presence activity (shown on its profile
+and in member lists):
+
+```ts
+import { ActivityType } from 'privage.js';
+
+await client.setStatus('online');   // 'online' | 'idle' | 'dnd' | 'offline'
+await client.setActivity({ type: ActivityType.Watching, name: 'the mod queue' });
+await client.clearActivity();
+```
+
+Activities are validated server-side (`name` required, ≤128 chars; optional
+`details`, `state`, `timestamps`) and activity updates are rate-limited
+(~10/min). Bots can **set** presence but do not **receive** presence events
+(the `presence` intent is a no-op for bots in v1).
+
+## Polls
+
+Create polls (the SDK already receives `pollVote` / `pollClose` events):
+
+```ts
+await client.createPoll(channelId, {
+  question: 'Ship it?',
+  options: ['Yes', 'No', 'Needs work'],   // 2–6 unique, ≤200 chars each
+  deadline: Date.now() + 24 * 3600e3,     // required, within 7 days
+});
+await client.closePoll(pollId);            // creator or MANAGE_MESSAGES
+```
+
+## Awaiting replies (collectors)
+
+The standard confirmation/wizard building block — collect matching
+`messageCreate`s until a count or time limit:
+
+```ts
+await msg.reply('Really ban them? Reply `yes` within 30s.');
+const [answer] = await client.awaitMessages({
+  channelId: msg.channelId,
+  filter: (m) => m.author.id === msg.author.id && m.content === 'yes',
+  timeMs: 30_000,
+});
+if (answer) await msg.member?.ban({ reason: 'confirmed' });
+
+// or the event form:
+const collector = client.createMessageCollector({ channelId, max: 5, timeMs: 60_000 });
+collector.on('collect', (m) => console.log(m.content));
+collector.on('end', (all, reason) => console.log(`${all.length} collected (${reason})`));
+```
+
+## Mentions & formatting
+
+Mention syntax on the wire is `<@userId>` / `<@&roleId>` / `<#channelId>`:
+
+```ts
+import { userMention, channelMention, bold, codeBlock } from 'privage.js';
+
+await client.send(channelId, `${userMention(userId)} check ${channelMention(logsChannelId)} — ${bold('3 new alerts')}`);
+```
+
+`@everyone` / `@here` work as plain text (broadcast mentions are
+rate-limited server-side).
+
+## Webhooks
+
+Bots with `MANAGE_WEBHOOKS` can provision channel webhooks:
+
+```ts
+const { webhook, token } = await client.createWebhook(channelId, { name: 'Deploys' });
+await client.fetchChannelWebhooks(channelId);
+await client.editWebhook(webhook.id, { name: 'CI' });
+await client.rotateWebhookToken(webhook.id);   // old token dies immediately
+await client.deleteWebhook(webhook.id);
+```
+
+## Servers & channels
+
+The SDK maintains a server/channel name cache for you — no per-message REST
+calls needed:
+
+```ts
+client.on('messageCreate', (msg) => {
+  console.log(`[${msg.server?.name ?? 'DM'} / #${msg.channel.name}] ${msg.content}`);
+});
+
+client.channels.get(channelId);  // Channel | undefined
+client.servers.get(serverId);    // Server | undefined
+```
+
+The cache is **hydrated on connect** (`GET /servers`, then each server's
+channel list in the background — `ready` never waits on it) and **lazily
+filled on a cache miss** (a channel not yet seen resolves itself in the
+background so the *next* message in it has a name). `msg.channel.name` is
+`null` until resolved; `msg.channel.send(...)` always works regardless.
+
+**Live updates (renames, new/deleted channels, server renames/deletes)
+require `Intents.Servers`** — without it, the cache still hydrates on connect
+and lazily fills on miss, but won't reflect changes made after that until the
+next miss.
+
+## Managing roles
+
+A bot with `MANAGE_ROLES` can grant/remove roles — the target role must sit
+**below the bot's highest role**, and its permissions must be delegatable by
+the bot (a 403 → `PrivagePermissionError` otherwise):
+
+```ts
+// respond to "!role" by giving the author a role
+client.on('messageCreate', async (msg) => {
+  if (msg.author.bot || !msg.member) return;      // member is null in DMs
+  if (msg.content === '!role') await msg.member.addRole(ROLE_ID);
+});
+
+await msg.member.removeRole(ROLE_ID);
+await client.addRole(serverId, userId, roleId);   // anyone, anywhere
+```
+
+`memberJoin` gives you a `Member` with the same helpers — handy for auto-roles:
+
+```ts
+client.on('memberJoin', (m) => { if (!m.bot) m.addRole(WELCOME_ROLE_ID); });
+```
+
+## Moderation
+
+Every mod action is on the `Member` (and mirrored on `Client`). Each needs the
+matching permission (`KICK_MEMBERS` / `BAN_MEMBERS` / `TIMEOUT_MEMBERS` /
+`MANAGE_MESSAGES`) and the bot must outrank the target:
+
+```ts
+await msg.member.kick({ reason: 'spam' });
+await msg.member.ban({ reason: 'raid', deleteHistory: true });
+await msg.member.timeout({ durationSeconds: 600, reason: 'cool off' });  // or { until: new Date(...) }
+await msg.member.removeTimeout();
+await msg.delete();                       // delete the offending message
+
+// server-level / general form:
+await client.unban(serverId, userId);
+await client.kick(serverId, userId);
+await client.deleteMessage(messageId);
+```
+
+## Migrating from discord.js
+
+The SDK is deliberately discord.js-shaped, and ships compat constants so
+common idioms port verbatim:
+
+```ts
+import { Events, Colors, ButtonStyle, TextInputStyle, SlashCommandBuilder } from 'privage.js';
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (interaction.isChatInputCommand()) {
+    await interaction.deferReply();       // alias of defer()
+    const result = await slowWork();
+    await interaction.editReply(result);  // alias of reply() — the deferred response IS the reply
+  }
+});
+
+// Ready-state accessors match discord.js (true once ready fires, across reconnects):
+if (client.isReady()) console.log(`up since ${client.readyAt} (${client.uptime}ms)`);
+
+await client.commands.set([
+  new SlashCommandBuilder()
+    .setName('ticket')
+    .setDescription('Open a support ticket')
+    .addStringOption(o => o.setName('subject').setDescription('What broke').setRequired(true)),
+]);
+
+new EmbedBuilder().setColor(Colors.Blurple).setAuthor({ name: 'CI', iconURL: '...' });
+// Colors.Blurple is an alias of Colors.Privage (brand purple) — ported bots go on-brand automatically.
+new ButtonBuilder().setStyle(ButtonStyle.Primary).setLabel('Go').setCustomId('go');
+```
+
+The honest differences: intents are coarser and semantically different (no
+`GatewayIntentBits` alias on purpose — read the [intents docs](https://privage.xyz/docs/bot/reference/intents);
+interaction-driven bots need no message intent at all), the token goes to
+`login(token)` not the constructor, presence is `client.setStatus`/
+`client.setActivity` (not `client.user.setActivity`), embeds/components
+can't share a message with file attachments, interactions are not replayed
+after reconnects, and there's no sharding (the collapsed pipe scales
+without it). Full guide:
+[Migrating from discord.js](https://privage.xyz/docs/bot/guides/migrating-from-discordjs).
+
+## Errors
+
+`PrivageAuthError` (bad/rotated token — `login()` rejects, no retry; also
+thrown from any REST call on a mid-session 401), `PrivageRateLimitError`
+(`.retryAfter` ms), `PrivagePermissionError` (missing permission / kicked —
+thrown from `reply`/`send`), `PrivageConnectionError` (emitted as
+`connectionError` for gateway drops while the SDK auto-reconnects, and
+thrown from REST calls that fail at the network level — those are not
+retried). Full guide: [Error handling](https://privage.xyz/docs/guides/error-handling).
+
+## Roadmap
+
+- ✅ Messages (incl. threads), reactions (+ granular add/remove), edits, deletes, polls
+- ✅ Members, roles, nicknames; kick / ban / timeout moderation
+- ✅ Reply / send, edit, pin, react; fetch messages / members / roles
+- ✅ Server & channel name cache; auto reconnect + resume + REST catchup; 429 retry
+- ✅ Interactions: buttons, select menus, slash commands, modals, ephemeral replies
+- ⏳ Bot DMs (pending gateway support)
+
+See `docs/bot-gateway-protocol.md` in the backend for the underlying wire spec.