@bunker-community/plugin-sdk 0.0.0-stage → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/API_DOC.md ADDED
@@ -0,0 +1,589 @@
1
+ # Bunker Plugin Developer Guide and API Reference
2
+
3
+ SDK `@bunker-community/plugin-sdk` 0.1.7
4
+
5
+ This document is for people who want to write plugins (bots) for Bunker: what is required, how to upload, and which
6
+ functions are available.
7
+
8
+ ## Contents
9
+ 1. [What a plugin is and how it runs](#what-a-plugin-is-and-how-it-runs)
10
+ 2. [Requirements](#requirements)
11
+ 3. [Your first plugin: write, upload, run](#your-first-plugin-write-upload-run)
12
+ 4. [Testing while developing: connecting from your computer](#testing-while-developing-connecting-from-your-computer)
13
+ 5. [Lifecycle](#lifecycle)
14
+ 6. [API reference](#api-reference)
15
+ 7. [Publishing to the Store](#publishing-to-the-store)
16
+ 8. [Limits and error messages](#limits-and-error-messages)
17
+ 9. [FAQ](#faq)
18
+ 10. [Appendix A: Gateway protocol (other languages)](#appendix-a-gateway-protocol-other-languages)
19
+ 11. [Appendix B: Versions](#appendix-b-versions)
20
+
21
+ ---
22
+
23
+ ## What a plugin is and how it runs
24
+
25
+ A plugin is a small program added to Bunker servers: it replies to commands, listens to events (messages, voice
26
+ channels, members), stores data, plays music/radio in voice channels and shows its own window in the panel.
27
+
28
+ ```
29
+ you ── upload code ──▶ Bunker (restricted environment) ──▶ servers you added the plugin to
30
+ │
31
+ └─ only what the SDK offers (the permissions you were granted)
32
+ ```
33
+
34
+ - The code runs **on Bunker**, in a separate restricted environment per plugin. It has no internet or file access;
35
+ its only connection to the outside is the SDK.
36
+ - A plugin runs **only on servers it was added to** and only sees those servers' events. It never sees direct
37
+ messages (DMs).
38
+ - The server owner sees the requested **permissions** and approves them when adding the plugin.
39
+ - A new plugin is **unverified**: it can only be added to servers you manage, and it runs as soon as you upload it.
40
+ To make it public, have the Bunker team review it ([Publishing to the Store](#publishing-to-the-store)).
41
+
42
+ ---
43
+
44
+ ## Requirements
45
+
46
+ A plugin that doesn't follow these rules is rejected or won't run.
47
+
48
+ ### Files
49
+
50
+ | File | Required | Description |
51
+ |---|---|---|
52
+ | `bunker-plugin.json` | yes | Manifest: name, version, permissions (below). |
53
+ | Code file (`.mjs` / `.js`) | yes | **A single file**, ES module, ≤1 MB. |
54
+ | Window page (`.html`) | only if the manifest has `ui` | Single file; inline scripts and styles. |
55
+
56
+ ### Manifest: `bunker-plugin.json`
57
+
58
+ ```json
59
+ {
60
+ "name": "Dice Bot",
61
+ "version": "1.0.0",
62
+ "description": "Rolls dice: !roll 20",
63
+ "sdk": "0.1",
64
+ "permissions": ["events.messages", "chat.send"]
65
+ }
66
+ ```
67
+
68
+ | Field | Required | Rule |
69
+ |---|---|---|
70
+ | `name` | yes | Display name, at most 40 characters. The bot's name in messages (server admins can rename it on their server). |
71
+ | `version` | yes | `x.y.z` (e.g. `1.0.0`, `1.2.0-beta.1`). |
72
+ | `sdk` | yes | `"0.1"`. |
73
+ | `permissions` | yes | List of permissions; `[]` if you need none. |
74
+ | `description` | no | At most 300 characters; shown on Store cards and in server settings. |
75
+ | `details` | no | Long description, at most 4000 characters of plain text (a blank line starts a new paragraph). Shown when someone opens your plugin in the Store: what it does, how to use it, its commands. |
76
+ | `author` | no | At most 80 characters. |
77
+ | `ui` | no | Panel window ([Window](#window-ctxui)). |
78
+ | `id` | — | Don't set it: the plugin id (`ext-xxxxxxxx`) is assigned when you create the plugin on Bunker. |
79
+
80
+ ### Code
81
+
82
+ - **A single file.** You can't import other files; bundle the libraries you use into one file
83
+ ([First plugin](#your-first-plugin-write-upload-run), step 2).
84
+ - The file must `export default definePlugin({ setup(ctx) { … } })`.
85
+ - The only external import: `@bunker-community/plugin-sdk`.
86
+ - **Don't** call `connect()`; Bunker connects the plugin (connect is only for [testing on your computer](#testing-while-developing-connecting-from-your-computer)).
87
+
88
+ ### What the environment forbids
89
+
90
+ | Forbidden | Description |
91
+ |---|---|
92
+ | Internet | No `fetch`, `WebSocket`, `http`, `https`, `net`, `dns`… You can't call external APIs. |
93
+ | File system | No `fs`, `os`, `child_process`, `worker_threads`, `vm`. Use [Storage](#storage-ctxstorage) for persistent data. |
94
+ | Environment variables | Empty. There is nowhere to put secret keys (and no internet to use them anyway). |
95
+ | Resources | 128 MB memory; if the 1-minute CPU average exceeds 40% or it doesn't respond for 20 s (infinite loop), the plugin is killed and restarted. After 5 crashes in 10 minutes it stops. |
96
+
97
+ A plugin that needs the internet (weather, exchange rates…) can currently only run [on your own computer](#testing-while-developing-connecting-from-your-computer).
98
+
99
+ ### Permissions
100
+
101
+ Ask only for what you need; server owners won't add plugins that ask for too much, and the Store review rejects them.
102
+ An action without permission throws.
103
+
104
+ | Permission | Shown to the server owner | Unlocks |
105
+ |---|---|---|
106
+ | `events.messages` | Reads messages in text channels, replies to commands | `message.*` events, `ctx.command` |
107
+ | `chat.send` | Posts messages in text channels under its own name | `ctx.chat.send`, `c.reply` |
108
+ | `storage` | Stores its own data on Bunker | `ctx.storage` |
109
+ | `voice.speak` | Joins voice channels and plays audio | `ctx.voice` |
110
+ | `events.voice` | Sees who joins and leaves voice channels | `voice.*` events |
111
+ | `events.members` | Sees members joining and leaving the server | `member.*`, `guild.create/delete` |
112
+ | `events.channels` | Sees channels being created, changed and deleted | `channel.*` |
113
+ | `events.presence` | Sees whether members are online | `user.online/offline` |
114
+
115
+ `ctx.log`, `ctx.ui` and the `guild.install/uninstall` events need no permission. If an update **adds a new
116
+ permission**, the plugin stops on every server it is installed on until that server's owner approves it again.
117
+
118
+ ---
119
+
120
+ ## Your first plugin: write, upload, run
121
+
122
+ **1. Write two files.**
123
+
124
+ `bunker-plugin.json`
125
+ ```json
126
+ {
127
+ "name": "Dice Bot",
128
+ "version": "1.0.0",
129
+ "description": "Rolls dice: !roll 20",
130
+ "sdk": "0.1",
131
+ "permissions": ["events.messages", "chat.send"]
132
+ }
133
+ ```
134
+
135
+ `plugin.js`
136
+ ```js
137
+ import { definePlugin } from "@bunker-community/plugin-sdk";
138
+
139
+ export default definePlugin({
140
+ setup(ctx) {
141
+ ctx.command("roll", async (c) => {
142
+ const sides = Math.max(2, Math.min(1000, Number(c.args) || 6));
143
+ await c.reply(`${c.nick} rolled ${1 + Math.floor(Math.random() * sides)} (d${sides})`);
144
+ });
145
+ },
146
+ });
147
+ ```
148
+
149
+ **2. Bundle into one file.** If you use no libraries, `plugin.js` already is a single file; skip this step.
150
+ Otherwise (Node.js 22+):
151
+
152
+ ```bash
153
+ npm install @bunker-community/plugin-sdk
154
+ npx esbuild plugin.js --bundle --format=esm --platform=neutral --external:@bunker-community/plugin-sdk --outfile=bundle.mjs
155
+ ```
156
+
157
+ **3. Create it on Bunker and upload.**
158
+ 1. **Settings → Developer → New plugin**: type a name, **Create**. (Keep the token shown; you only need it for
159
+ testing from your computer.)
160
+ 2. On the plugin's row, **Upload code**: select the code file and `bunker-plugin.json` (plus the `.html` if it has
161
+ a window) together.
162
+ 3. **Run on Bunker**. The row shows "Connected (running on Bunker)".
163
+
164
+ **4. Add it to your server.** On your server: **Server settings → Plugins** (or the Plugin Store) → **Add** →
165
+ approve the permissions. Type `!roll 20` in a channel.
166
+
167
+ When you change the code, bundle again and **Upload new code**: the new code takes effect immediately.
168
+
169
+ ---
170
+
171
+ ## Testing while developing: connecting from your computer
172
+
173
+ Instead of uploading after every change, you can run the code on your computer and connect it to Bunker. The plugin
174
+ works on the same servers with the same permissions; only the code runs on your machine (and can use the internet).
175
+
176
+ ```bash
177
+ npm install @bunker-community/plugin-sdk
178
+ ```
179
+
180
+ `local.js` (with `"type": "module"` in `package.json`)
181
+ ```js
182
+ import { connect } from "@bunker-community/plugin-sdk";
183
+ import plugin from "./plugin.js";
184
+
185
+ connect(plugin, { token: process.env.BUNKER_TOKEN });
186
+ ```
187
+
188
+ ```bash
189
+ BUNKER_TOKEN=<token> node local.js
190
+ # PowerShell: $env:BUNKER_TOKEN="<token>"; node local.js
191
+ ```
192
+
193
+ - The token is shown **once** when you create the plugin under Settings → Developer; if you lose it, use
194
+ **Regenerate token**. Don't put it in code or share it.
195
+ - `connect` sends `bunker-plugin.json` and the window page from the folder to Bunker on every connect.
196
+ - While the plugin runs on Bunker you can't connect from your computer (code 4004); click **Stop** on its row first.
197
+ - While your code isn't running, the bot shows offline and commands get no reply.
198
+
199
+ ### `connect(plugin, options)`
200
+
201
+ | Option | Description |
202
+ |---|---|
203
+ | `token` | Required. The plugin's token. |
204
+ | `url` | Gateway address; default `wss://bunker.community/app/api/plugin/gateway`. |
205
+ | `manifest` | Manifest object; if omitted, `bunker-plugin.json` in `dir` is read. |
206
+ | `dir` | Folder of `bunker-plugin.json` and the window page (default: working directory). |
207
+ | `uiPage` | HTML of the window page (if omitted, the `ui.page` file is read). |
208
+ | `logger` | Connection logs (default `console`). |
209
+
210
+ Returns `{ ready: Promise<void>, connected: boolean, close(): Promise<void> }`. Reconnects by itself if the connection
211
+ drops (1 s → 30 s). Does not retry, and `ready` rejects, if the token is invalid, the plugin was disabled, the manifest
212
+ is invalid or the plugin is running on Bunker. This way you can't send raw PCM to voice channels (no `playPcm`);
213
+ `playMedia` and `playUrl` work.
214
+
215
+ ---
216
+
217
+ ## Lifecycle
218
+
219
+ ```js
220
+ export default definePlugin({
221
+ async setup(ctx) {
222
+ // Runs once when the plugin starts: set up commands and listeners here.
223
+ ctx.onUnload(async () => {
224
+ // On shutdown: stop timers, save state to storage if needed.
225
+ });
226
+ },
227
+ });
228
+ ```
229
+
230
+ - If `setup` throws, the plugin doesn't start (the reason shows under Settings → Developer).
231
+ - When the plugin stops (stop, new code, Bunker restart): listeners are released, voice sessions close, `onUnload`
232
+ runs. Storage still works inside `onUnload`; at most 3 s in total.
233
+ - **Error budget:** if your listeners throw 10 errors within 60 s, the plugin stops itself. Catch your errors.
234
+ - After the plugin stops, every call on the old `ctx` throws `plugin is off`.
235
+
236
+ ---
237
+
238
+ ## API reference
239
+
240
+ ### `definePlugin(definition)`
241
+
242
+ ```ts
243
+ definePlugin({ setup(ctx: PluginContext): void | Promise<void> }): PluginDefinition
244
+ ```
245
+ Returns the definition as is (a typing helper). This is the code file's `export default`.
246
+
247
+ ### `PluginContext` (ctx)
248
+
249
+ | Member | Permission | Description |
250
+ |---|---|---|
251
+ | `ctx.manifest` | — | Validated manifest (read-only). |
252
+ | `ctx.log.info/warn/error(message, extra?)` | — | Logging (the error line under Settings → Developer and Bunker's logs). |
253
+ | `ctx.on(event, fn)` | per event | Listen to an event; the returned function stops listening. |
254
+ | `ctx.command(name, fn)` | `events.messages` | `!name` command; the returned function removes it. |
255
+ | `ctx.chat.send(channel, text)` | `chat.send` | Message to a text channel. |
256
+ | `ctx.storage` | `storage` | Persistent key-value storage. |
257
+ | `ctx.serverLang(gid)` | — | The server's language, `Promise<"en" \| "tr">` (Server settings → Language). |
258
+ | `ctx.voice.join(cid)` / `ctx.voice.session(cid)` | `voice.speak` | Voice channel session. |
259
+ | `ctx.voice.channelOf(uid)` | `voice.speak` or `events.voice` | Which voice channel a user is in: `Promise<{ gid, cid } \| null>` (null if not in a voice channel of a server you were added to). |
260
+ | `ctx.ui.setState(...)` / `ctx.ui.onAction(fn)` / `ctx.ui.send(...)` | — (manifest `ui`) | Panel window. |
261
+ | `ctx.onUnload(fn)` | — | Cleanup on shutdown. |
262
+
263
+ Event data is a copy; changing it doesn't affect Bunker.
264
+
265
+ ### Events: `ctx.on(event, fn)`
266
+
267
+ ```js
268
+ ctx.on("member.join", (e) => ctx.log.info("new member", { gid: e.gid, uid: e.uid }));
269
+ ```
270
+
271
+ | Event | Data | Permission |
272
+ |---|---|---|
273
+ | `message.create` | `{ scope: "text", gid, chan, m: PluginMessage }` | `events.messages` |
274
+ | `message.edit` | `{ scope, gid, chan, m }` | `events.messages` |
275
+ | `message.delete` | `{ scope, gid, chan, id, by }` | `events.messages` |
276
+ | `message.react` | `{ scope, gid, chan, id, uid, emoji, added }` | `events.messages` |
277
+ | `voice.join` / `voice.leave` | `{ gid, cid, uid, bot }` | `events.voice` |
278
+ | `voice.move` | `{ gid, cid, uid, bot, from }` | `events.voice` |
279
+ | `member.join` / `member.leave` | `{ gid, uid }` | `events.members` |
280
+ | `guild.create` / `guild.delete` | `{ gid, owner }` / `{ gid }` | `events.members` |
281
+ | `channel.create/update/delete` | `{ gid, kind: "text" \| "voice", id }` | `events.channels` |
282
+ | `user.online` / `user.offline` | `{ uid }` (if a member of a server you were added to) | `events.presence` |
283
+ | `guild.install` | `{ gid, by }`: the plugin was added to this server | — |
284
+ | `guild.uninstall` | `{ gid }`: removed, or the server was deleted; **delete that server's data here** | — |
285
+
286
+ ```ts
287
+ interface PluginMessage {
288
+ id: string; ts: number; uid: string; nick: string;
289
+ text: string; // raw text: mentions <@uid>, custom emoji <:name:id>
290
+ system: boolean; // system line such as "… pinned a message"
291
+ bot: boolean; // written by a bot/plugin (including yours: avoid reply loops)
292
+ attachments: number; // number of images/videos
293
+ replyTo?: string; edited?: number;
294
+ }
295
+ ```
296
+
297
+ Events arrive after Bunker has finished its work; a slow listener never blocks Bunker.
298
+
299
+ ### Commands: `ctx.command(name, fn)`
300
+
301
+ ```js
302
+ ctx.command("hello", (c) => c.reply(`Hello ${c.nick}!`));
303
+ ```
304
+
305
+ - Name: letters, digits, `_`, `-`; 1-32 characters; written without `!`; lowercased.
306
+ - Triggered only in text channels and only when a **human** writes it.
307
+ - Bunker's own commands (`!play`, `!skip`, `!rank`, `!bug`…) and names taken by another plugin can't be used.
308
+
309
+ ```ts
310
+ interface CommandCall {
311
+ gid: string; chan: string; uid: string; nick: string;
312
+ args: string; // text after the command
313
+ m: PluginMessage;
314
+ manage: boolean; // the writer has server settings permission on this server
315
+ lang: "en" | "tr"; // the server's language: write your reply in it
316
+ reply(text: string): Promise<void>; // to the same channel (needs chat.send)
317
+ }
318
+ ```
319
+
320
+ ### Messages: `ctx.chat.send(channel, text)`
321
+
322
+ ```js
323
+ const r = await ctx.chat.send(chanId, "Hello!"); // { id } | null
324
+ ```
325
+ Only to text channels of servers you were added to; shown under the bot's name with a BOT tag. At most 10 messages
326
+ per 10 s per server. Text at most 1800 characters (longer is cut). Mentions: `<@uid>`.
327
+
328
+ ### Storage: `ctx.storage`
329
+
330
+ ```js
331
+ await ctx.storage.set("config:" + gid, { lang: "en" });
332
+ const a = await ctx.storage.get("config:" + gid); // undefined if missing
333
+ await ctx.storage.delete("config:" + gid);
334
+ const keys = await ctx.storage.keys("config:");
335
+ ```
336
+
337
+ | Function | Returns |
338
+ |---|---|
339
+ | `get(key)` | value or `undefined` |
340
+ | `set(key, value)` | — (value must be JSON-serializable) |
341
+ | `delete(key)` | — |
342
+ | `keys(prefix?)` | `string[]` |
343
+
344
+ Private to the plugin, persistent. Values ≤64 KB, keys 1-200 characters, at most 10,000 keys. **One store** for all
345
+ servers: prefix per-server data with `gid` and delete it on `guild.uninstall`.
346
+
347
+ ### Voice: `ctx.voice`
348
+
349
+ ```js
350
+ const s = await ctx.voice.join(cid); // same session if already there
351
+ s.setVolume(30);
352
+ s.on("meta", (m) => ctx.log.info("playing: " + m.title));
353
+ s.on("error", (why, { silent }) => { if (!silent) ctx.log.warn(why); });
354
+ await s.playMedia("daft punk one more time");
355
+ ```
356
+
357
+ `ctx.voice.session(cid)` returns the open session (or `null`). The bot shows up as a separate member in the channel.
358
+
359
+ | `VoiceSession` | Description |
360
+ |---|---|
361
+ | `gid`, `cid`, `playing`, `paused`, `volume` (0-100), `connected` | State (read-only). |
362
+ | `playMedia(query, { seek? })` | YouTube / SoundCloud link, radio stream or search text. Track info arrives via the `meta` event. |
363
+ | `prefetch(query)` | Prepare the next track (faster transitions; valid for 30 min). |
364
+ | `playUrl(url, { seek? })` | Direct http(s) audio URL (radio, mp3). |
365
+ | `stop()`, `pause()`, `resume()`, `setVolume(v)` | Controls. |
366
+ | `leave()` | Leave the channel. |
367
+ | `on(event, fn)` | `started`, `ended`, `error(why, { silent })`, `meta(MediaMeta)`, `leave(why)`; the returned function unsubscribes. |
368
+
369
+ ```ts
370
+ interface MediaMeta { title: string; artist: string; duration: number /* s, 0 for live */; thumb: string; src: string; url: string }
371
+ ```
372
+ If `error` has `silent: true` (e.g. YouTube blocking), you don't need to show it to users. The session closes 60 s
373
+ after nobody is left in the channel, and immediately when the channel is deleted (`leave`). At most 12 plugin voice
374
+ sessions across Bunker at once.
375
+
376
+ ### Window: `ctx.ui`
377
+
378
+ A plugin can show an icon in the plugin group at the bottom left of the panel, and a window that opens on click.
379
+
380
+ ```json
381
+ "ui": { "title": "Dice", "icon": "gamepad", "page": "ui.html", "scope": "guild" }
382
+ ```
383
+
384
+ | Field | Description |
385
+ |---|---|
386
+ | `title` | Window title (≤40). |
387
+ | `icon` | Icon name (below); default `plug`. |
388
+ | `page` | The window page `.html` (select it too when uploading). |
389
+ | `scope` | `"guild"`: always visible on the server, state per server. `"voice"`: only while in one of that server's voice channels, state **per channel**. |
390
+
391
+ Icons: `music radio tv gamepad play pause skip shuffle list volume mic headphones monitor screen camera video live
392
+ clock bell crown smile message hash pin users user gear plug store compass shield key palette keyboard search check
393
+ info edit trash download sleep phone at`.
394
+
395
+ **Model: state down, actions up.** The page cannot connect anywhere by itself; all logic lives in the plugin.
396
+
397
+ ```
398
+ plugin ── ctx.ui.setState ──▶ panel ── {bunker:"state"} ──▶ page
399
+ plugin ◀── ctx.ui.onAction ── panel ◀── {bunker:"action"} ── page
400
+ ```
401
+
402
+ | Function | Description |
403
+ |---|---|
404
+ | `ctx.ui.setState({ gid, cid? }, state, { live? })` | Sends the state to everyone on that server (in that channel for scope `voice`); people opening it later get the latest state too. JSON, ≤32 KB. `live: true` → the icon lights up. `null` → clear. Kept in memory. |
405
+ | `ctx.ui.onAction(fn)` | `fn({ gid, cid?, uid, nick, name, data, manage, lang })` (`manage`: the user has server settings permission; `lang`: their panel language). Bunker checks the user is a member (and in the channel for scope `voice`); ≤10 per second per user, `data` ≤4 KB. Still validate `data`. |
406
+
407
+ ```js
408
+ ctx.ui.onAction(async (a) => {
409
+ if (a.name === "roll") ctx.ui.setState({ gid: a.gid }, { last: a.nick, result: 1 + Math.floor(Math.random() * 6) });
410
+ });
411
+ ```
412
+
413
+ Page (`ui.html`):
414
+ ```html
415
+ <!doctype html>
416
+ <meta charset="utf-8">
417
+ <style>
418
+ :root { --bg:#1e1f22; --text:#dbdee1; --accent:#6c6cff; }
419
+ body { margin:0; padding:16px; background:var(--bg); color:var(--text); font:14px system-ui; }
420
+ button { background:var(--accent); color:#fff; border:0; border-radius:6px; padding:8px 12px; }
421
+ </style>
422
+ <p id="t">…</p>
423
+ <button id="b">Roll</button>
424
+ <script>
425
+ const act = (name, data) => parent.postMessage({ bunker: "action", name, data }, "*");
426
+ addEventListener("message", (e) => {
427
+ const m = e.data;
428
+ if (e.source !== parent || m?.bunker !== "state") return;
429
+ for (const [k, v] of Object.entries(m.ctx.theme)) if (typeof v === "string") document.documentElement.style.setProperty("--" + k, v);
430
+ document.getElementById("t").textContent = m.state ? `${m.state.last}: ${m.state.result}` : "No rolls yet";
431
+ });
432
+ document.getElementById("b").onclick = () => act("roll");
433
+ parent.postMessage({ bunker: "ready" }, "*");
434
+ </script>
435
+ ```
436
+
437
+ | Direction | Message |
438
+ |---|---|
439
+ | page → panel | `{ bunker: "ready" }` · `{ bunker: "action", name, data? }` · `{ bunker: "close" }` |
440
+ | panel → page | `{ bunker: "state", state, ctx: { gid, cid, me: { uid, nick }, manage, age, lang, theme: { dark, bg, text, muted, accent, border, hover } } }` |
441
+
442
+ Plus `{ bunker: "message", data }`: data sent only to this user with `ctx.ui.send(uid, { gid, cid? }, data)` (e.g. the
443
+ result of an action, or an error). `ctx.manage`: whether the viewer has server settings permission (for showing
444
+ buttons only; check `UiAction.manage` in the plugin).
445
+
446
+ `ctx.lang`: the viewer's panel language (`"en"` or `"tr"`). The panel doesn't translate your page; pick your texts by it.
447
+
448
+ `ctx.age`: how many ms ago the plugin produced this state. The same state may be sent again (e.g. when the window is
449
+ reopened), so a page that shows elapsed time (a progress bar) should add `age` instead of assuming the state is fresh.
450
+
451
+ Page rules: opens in an isolated frame (no access to the panel's cookies or data); no network requests; a single file
452
+ with inline scripts and styles; images may be `https:` or `data:`; take colors from `ctx.theme`. **Forms don't submit**
453
+ in the isolated frame (the `submit` event never fires): don't rely on `<form onsubmit>`; handle the button's `click` and
454
+ the input's `keydown` (Enter) yourself.
455
+
456
+ ---
457
+
458
+ ## Publishing to the Store
459
+
460
+ An unverified plugin only runs on your servers and only you see it in the Store (with an "Unverified" tag). To let
461
+ everyone add it:
462
+
463
+ 1. Make sure it works well on your own server.
464
+ 2. Contact the Bunker team (support@bunker.community) with the plugin's name and id (`ext-…`).
465
+ 3. The team reviews the code. If approved, it becomes visible to everyone in the Store (verified).
466
+
467
+ The review checks: whether the requested permissions are really needed, whether the description is accurate, whether
468
+ there is misleading / harassing / spamming behavior, and whether the code is readable (deliberately obfuscated code is
469
+ rejected).
470
+
471
+ Once in the Store, **every new upload is reviewed too**; the previously approved version keeps running until the new
472
+ one is approved. Abusive plugins are disabled.
473
+
474
+ ---
475
+
476
+ ## Limits and error messages
477
+
478
+ | What | Limit |
479
+ |---|---|
480
+ | Code file | single file, ≤1 MB |
481
+ | Memory / CPU | 128 MB / 40% 1-minute average |
482
+ | Plugins per person | 5 |
483
+ | Plugins per server | 25 |
484
+ | Error budget | 10 errors in 60 s → plugin stops |
485
+ | `chat.send` | 10 messages per 10 s per server, ≤1800 characters |
486
+ | Storage | value ≤64 KB, ≤10,000 keys, key ≤200 characters |
487
+ | Window | state ≤32 KB; actions 10 per second per user, `data` ≤4 KB |
488
+ | Voice | 12 sessions across Bunker |
489
+ | Command name | 1-32 characters |
490
+
491
+ Common errors:
492
+
493
+ | Error | Cause |
494
+ |---|---|
495
+ | `… needs the "X" permission (bunker-plugin.json → permissions)` | Permission X is missing from the manifest. |
496
+ | `You can't write to this channel (the plugin is not added to this server).` | The channel is on a server the plugin wasn't added to. |
497
+ | `Too fast: at most 10 messages per 10 s to a server` | Message limit (per server). |
498
+ | `!x is a Bunker command and can't be taken` / `!x is registered by another plugin (…)` | Command name taken; pick another. |
499
+ | `value is at most 64 KB` / `state is at most 32 KB` | Value / state too large; split it. |
500
+ | `plugin is off` | The old `ctx` was used after the plugin stopped (stop timers in `onUnload`). |
501
+ | `A plugin hosted on Bunker cannot use this: …` | Forbidden module or action (internet, files…). |
502
+
503
+ ---
504
+
505
+ ## FAQ
506
+
507
+ **My plugin doesn't respond.** Is its row "Connected" under Settings → Developer? Is it added under Server settings →
508
+ Plugins, and is there a "needs new permission" warning? Is the command name right? The error line shows the reason.
509
+
510
+ **I need to call an external API.** Code running on Bunker can't reach the internet. Run it on your own computer /
511
+ server with `connect` ([testing section](#testing-while-developing-connecting-from-your-computer)); it can run that way permanently too.
512
+
513
+ **Can I use TypeScript?** Yes; esbuild compiles TypeScript while bundling. Types are included
514
+ (`import type { PluginContext } from "@bunker-community/plugin-sdk"`).
515
+
516
+ **How do I store per-user settings?** Put the server and user id in the key: `ctx.storage.set("config:" + gid + ":" + uid, …)`.
517
+
518
+ **I lost / leaked my token.** Settings → Developer → **Regenerate token**; the old one stops working immediately.
519
+
520
+ ---
521
+
522
+ ## Appendix A: Gateway protocol (other languages)
523
+
524
+ The SDK is for Node.js. To write a bot in another language (Python, Go…) that runs on your own machine, connect to
525
+ the gateway directly: WebSocket `wss://bunker.community/app/api/plugin/gateway`, JSON text messages, ≤320 KB per
526
+ message, ~30 calls per second.
527
+
528
+ **Hello** (first message, within 10 s) and reply:
529
+ ```json
530
+ { "op": "hello", "token": "ext-…", "sdk": "0.1.7", "manifest": { "name": "…", "version": "1.0.0", "sdk": "0.1", "permissions": [] }, "uiPage": "<!doctype html>…" }
531
+ { "op": "ready", "v": 1, "sdk": "0.1.6", "manifest": { "…": "…" }, "guilds": [{ "gid": "…", "name": "…" }] }
532
+ ```
533
+
534
+ **Call → result:**
535
+ ```json
536
+ { "op": "call", "id": 7, "method": "chat.send", "args": ["<channel>", "hello"] }
537
+ { "op": "result", "id": 7, "ok": true, "value": { "id": "<message>" } }
538
+ ```
539
+
540
+ | method | args | value |
541
+ |---|---|---|
542
+ | `subscribe` / `unsubscribe` | `[event]` (event names + `"ui.action"`) | — |
543
+ | `command` / `uncommand` | `[name]` | — |
544
+ | `chat.send` | `[channel, text]` | `{ id }` or `null` |
545
+ | `storage.get` | `[key]` | value or `null` |
546
+ | `storage.set` | `[key, value]` | — |
547
+ | `storage.delete` | `[key]` | — |
548
+ | `storage.keys` | `[prefix]` | `string[]` |
549
+ | `ui.setState` | `[{ gid, cid? }, state, { live? }]` | — |
550
+ | `voice.join` / `voice.session` | `[cid]` | session state |
551
+ | `voice.channelOf` | `[uid]` | `{ gid, cid }` or `null` |
552
+ | `ui.send` | `[uid, { gid, cid? }, data]` | — |
553
+ | `voice.call` | `[cid, action, args[]]` (`playUrl playMedia prefetch stop pause resume setVolume leave`) | session state |
554
+ | `log` | `["info" / "warn" / "error", message, extra?]` | — |
555
+ | `guilds` | `[]` | `[{ gid, name }]` |
556
+
557
+ Session state: `{ gid, cid, playing, paused, volume, connected }`.
558
+
559
+ **From the server:**
560
+ ```json
561
+ { "op": "event", "name": "member.join", "data": { "gid": "…", "uid": "…" } }
562
+ { "op": "command", "name": "roll", "call": { "gid": "…", "chan": "…", "uid": "…", "nick": "…", "args": "20", "m": { "…": "…" } } }
563
+ { "op": "voice", "cid": "…", "ev": "started", "args": [], "state": { "…": "…" } }
564
+ ```
565
+ To reply to a command, `chat.send` to `call.chan`. Subscriptions are dropped when the connection closes; send them
566
+ again after reconnecting.
567
+
568
+ **Close codes:** 4001 invalid / regenerated token · 4002 malformed message · 4003 plugin disabled or deleted · 4004
569
+ another connection with the same token, or the plugin is running on Bunker · 4005 invalid manifest (reason in
570
+ `reason`) · 4008 too fast or not reading messages. Reconnect on any other close.
571
+
572
+ ---
573
+
574
+ ## Appendix B: Versions
575
+
576
+ `sdk: "0.1"` in the manifest → works with 0.1.x. Fields are added, never removed; breaking changes bump the version.
577
+
578
+ | Version | Change |
579
+ |---|---|
580
+ | 0.1.7 | Languages: `CommandCall.lang`, `ctx.serverLang(gid)`, `UiAction.lang`, page `ctx.lang` |
581
+ | 0.1.6 | Manifest `details` (long description for the Store detail view) |
582
+ | 0.1.5 | `ctx.voice.channelOf`, `ctx.ui.send` (data to one user's window), `manage` in `CommandCall` / `UiAction` / page `ctx` |
583
+ | 0.1.4 | Uploading plugins to Bunker (hosting), connecting from your computer (`connect`) |
584
+ | 0.1.3 | `playMedia`, `prefetch`, `meta` event, `silent` in the `error` event |
585
+ | 0.1.2 | Voice (`voice.speak`) and panel window (`ui`) |
586
+ | 0.1.1 | `guild.install` / `guild.uninstall` events |
587
+ | 0.1.0 | Events, commands, storage, messages |
588
+
589
+ Examples: [github.com/bunker-community/plugin-sdk/tree/main/examples](https://github.com/bunker-community/plugin-sdk/tree/main/examples)
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bunker
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,40 @@
1
- # Temporary Holding Version
1
+ # Bunker Plugin SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@bunker-community/plugin-sdk)](https://www.npmjs.com/package/@bunker-community/plugin-sdk)
4
+
5
+ Write bots and plugins for [Bunker](https://bunker.community): commands, events, storage, voice (music/radio) and a
6
+ window in the Bunker panel. Write a file, upload it in Bunker, it runs.
7
+
8
+ **Developer guide and API reference:** [API_DOC.md](API_DOC.md) · [web](https://bunker.community/app/sdk/) · [PDF](docs/bunker-plugin-api.pdf)
9
+
10
+ ## Quick start
11
+
12
+ `bunker-plugin.json`
13
+ ```json
14
+ { "name": "Dice Bot", "version": "1.0.0", "sdk": "0.1", "permissions": ["events.messages", "chat.send"] }
15
+ ```
16
+
17
+ `plugin.js`
18
+ ```js
19
+ import { definePlugin } from "@bunker-community/plugin-sdk";
20
+
21
+ export default definePlugin({
22
+ setup(ctx) {
23
+ ctx.command("roll", (c) => c.reply(`${c.nick} rolled ${1 + Math.floor(Math.random() * 6)}`));
24
+ },
25
+ });
26
+ ```
27
+
28
+ 1. In Bunker: **Settings → Developer → New plugin**.
29
+ 2. **Upload code**: select `plugin.js` and `bunker-plugin.json`, then **Run on Bunker**.
30
+ 3. Add it to your server (Server settings → Plugins) and type `!roll`.
31
+
32
+ Plugins run in a restricted environment (no internet or file access, single file, only this SDK). To test from your
33
+ own computer instead, install the SDK (`npm install @bunker-community/plugin-sdk`) and use `connect(plugin, { token })`;
34
+ see the guide.
35
+
36
+ Examples: [examples/dice](examples/dice) (start here), `hello`, `radio`, `music` (Bunker's own plugins, same API).
37
+
38
+ ## License
39
+
40
+ MIT. This repository is published from the Bunker monorepo; issues and pull requests are welcome here.
@@ -0,0 +1,7 @@
1
+ import type { PluginDefinition } from "./types.ts";
2
+ export * from "./types.ts";
3
+ export * from "./manifest.ts";
4
+ export * from "./version.ts";
5
+ export * from "./remote.ts";
6
+ /** Type helper: returns the plugin definition as is */
7
+ export declare function definePlugin(def: PluginDefinition): PluginDefinition;
package/dist/index.js ADDED
@@ -0,0 +1,8 @@
1
+ export * from "./types.js";
2
+ export * from "./manifest.js";
3
+ export * from "./version.js";
4
+ export * from "./remote.js";
5
+ /** Type helper: returns the plugin definition as is */
6
+ export function definePlugin(def) {
7
+ return def;
8
+ }