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

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,568 @@
1
+ # Bunker Plugin Developer Guide and API Reference
2
+
3
+ SDK `@bunker-community/plugin-sdk` 0.1.4
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 in the Store and server settings. |
75
+ | `author` | no | At most 80 characters. |
76
+ | `ui` | no | Panel window ([Window](#window-ctxui)). |
77
+ | `id` | — | Don't set it: the plugin id (`ext-xxxxxxxx`) is assigned when you create the plugin on Bunker. |
78
+
79
+ ### Code
80
+
81
+ - **A single file.** You can't import other files; bundle the libraries you use into one file
82
+ ([First plugin](#your-first-plugin-write-upload-run), step 2).
83
+ - The file must `export default definePlugin({ setup(ctx) { … } })`.
84
+ - The only external import: `@bunker-community/plugin-sdk`.
85
+ - **Don't** call `connect()`; Bunker connects the plugin (connect is only for [testing on your computer](#testing-while-developing-connecting-from-your-computer)).
86
+
87
+ ### What the environment forbids
88
+
89
+ | Forbidden | Description |
90
+ |---|---|
91
+ | Internet | No `fetch`, `WebSocket`, `http`, `https`, `net`, `dns`… You can't call external APIs. |
92
+ | File system | No `fs`, `os`, `child_process`, `worker_threads`, `vm`. Use [Storage](#storage-ctxstorage) for persistent data. |
93
+ | Environment variables | Empty. There is nowhere to put secret keys (and no internet to use them anyway). |
94
+ | 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. |
95
+
96
+ A plugin that needs the internet (weather, exchange rates…) can currently only run [on your own computer](#testing-while-developing-connecting-from-your-computer).
97
+
98
+ ### Permissions
99
+
100
+ Ask only for what you need; server owners won't add plugins that ask for too much, and the Store review rejects them.
101
+ An action without permission throws.
102
+
103
+ | Permission | Shown to the server owner | Unlocks |
104
+ |---|---|---|
105
+ | `events.messages` | Reads messages in text channels, replies to commands | `message.*` events, `ctx.command` |
106
+ | `chat.send` | Posts messages in text channels under its own name | `ctx.chat.send`, `c.reply` |
107
+ | `storage` | Stores its own data on Bunker | `ctx.storage` |
108
+ | `voice.speak` | Joins voice channels and plays audio | `ctx.voice` |
109
+ | `events.voice` | Sees who joins and leaves voice channels | `voice.*` events |
110
+ | `events.members` | Sees members joining and leaving the server | `member.*`, `guild.create/delete` |
111
+ | `events.channels` | Sees channels being created, changed and deleted | `channel.*` |
112
+ | `events.presence` | Sees whether members are online | `user.online/offline` |
113
+
114
+ `ctx.log`, `ctx.ui` and the `guild.install/uninstall` events need no permission. If an update **adds a new
115
+ permission**, the plugin stops on every server it is installed on until that server's owner approves it again.
116
+
117
+ ---
118
+
119
+ ## Your first plugin: write, upload, run
120
+
121
+ **1. Write two files.**
122
+
123
+ `bunker-plugin.json`
124
+ ```json
125
+ {
126
+ "name": "Dice Bot",
127
+ "version": "1.0.0",
128
+ "description": "Rolls dice: !roll 20",
129
+ "sdk": "0.1",
130
+ "permissions": ["events.messages", "chat.send"]
131
+ }
132
+ ```
133
+
134
+ `plugin.js`
135
+ ```js
136
+ import { definePlugin } from "@bunker-community/plugin-sdk";
137
+
138
+ export default definePlugin({
139
+ setup(ctx) {
140
+ ctx.command("roll", async (c) => {
141
+ const sides = Math.max(2, Math.min(1000, Number(c.args) || 6));
142
+ await c.reply(`${c.nick} rolled ${1 + Math.floor(Math.random() * sides)} (d${sides})`);
143
+ });
144
+ },
145
+ });
146
+ ```
147
+
148
+ **2. Bundle into one file.** If you use no libraries, `plugin.js` already is a single file; skip this step.
149
+ Otherwise (Node.js 22+):
150
+
151
+ ```bash
152
+ npm install @bunker-community/plugin-sdk
153
+ npx esbuild plugin.js --bundle --format=esm --platform=neutral --external:@bunker-community/plugin-sdk --outfile=bundle.mjs
154
+ ```
155
+
156
+ **3. Create it on Bunker and upload.**
157
+ 1. **Settings → Developer → New plugin**: type a name, **Create**. (Keep the token shown; you only need it for
158
+ testing from your computer.)
159
+ 2. On the plugin's row, **Upload code**: select the code file and `bunker-plugin.json` (plus the `.html` if it has
160
+ a window) together.
161
+ 3. **Run on Bunker**. The row shows "Connected (running on Bunker)".
162
+
163
+ **4. Add it to your server.** On your server: **Server settings → Plugins** (or the Plugin Store) → **Add** →
164
+ approve the permissions. Type `!roll 20` in a channel.
165
+
166
+ When you change the code, bundle again and **Upload new code**: the new code takes effect immediately.
167
+
168
+ ---
169
+
170
+ ## Testing while developing: connecting from your computer
171
+
172
+ Instead of uploading after every change, you can run the code on your computer and connect it to Bunker. The plugin
173
+ works on the same servers with the same permissions; only the code runs on your machine (and can use the internet).
174
+
175
+ ```bash
176
+ npm install @bunker-community/plugin-sdk
177
+ ```
178
+
179
+ `local.js` (with `"type": "module"` in `package.json`)
180
+ ```js
181
+ import { connect } from "@bunker-community/plugin-sdk";
182
+ import plugin from "./plugin.js";
183
+
184
+ connect(plugin, { token: process.env.BUNKER_TOKEN });
185
+ ```
186
+
187
+ ```bash
188
+ BUNKER_TOKEN=<token> node local.js
189
+ # PowerShell: $env:BUNKER_TOKEN="<token>"; node local.js
190
+ ```
191
+
192
+ - The token is shown **once** when you create the plugin under Settings → Developer; if you lose it, use
193
+ **Regenerate token**. Don't put it in code or share it.
194
+ - `connect` sends `bunker-plugin.json` and the window page from the folder to Bunker on every connect.
195
+ - While the plugin runs on Bunker you can't connect from your computer (code 4004); click **Stop** on its row first.
196
+ - While your code isn't running, the bot shows offline and commands get no reply.
197
+
198
+ ### `connect(plugin, options)`
199
+
200
+ | Option | Description |
201
+ |---|---|
202
+ | `token` | Required. The plugin's token. |
203
+ | `url` | Gateway address; default `wss://bunker.community/app/api/plugin/gateway`. |
204
+ | `manifest` | Manifest object; if omitted, `bunker-plugin.json` in `dir` is read. |
205
+ | `dir` | Folder of `bunker-plugin.json` and the window page (default: working directory). |
206
+ | `uiPage` | HTML of the window page (if omitted, the `ui.page` file is read). |
207
+ | `logger` | Connection logs (default `console`). |
208
+
209
+ Returns `{ ready: Promise<void>, connected: boolean, close(): Promise<void> }`. Reconnects by itself if the connection
210
+ drops (1 s → 30 s). Does not retry, and `ready` rejects, if the token is invalid, the plugin was disabled, the manifest
211
+ is invalid or the plugin is running on Bunker. This way you can't send raw PCM to voice channels (no `playPcm`);
212
+ `playMedia` and `playUrl` work.
213
+
214
+ ---
215
+
216
+ ## Lifecycle
217
+
218
+ ```js
219
+ export default definePlugin({
220
+ async setup(ctx) {
221
+ // Runs once when the plugin starts: set up commands and listeners here.
222
+ ctx.onUnload(async () => {
223
+ // On shutdown: stop timers, save state to storage if needed.
224
+ });
225
+ },
226
+ });
227
+ ```
228
+
229
+ - If `setup` throws, the plugin doesn't start (the reason shows under Settings → Developer).
230
+ - When the plugin stops (stop, new code, Bunker restart): listeners are released, voice sessions close, `onUnload`
231
+ runs. Storage still works inside `onUnload`; at most 3 s in total.
232
+ - **Error budget:** if your listeners throw 10 errors within 60 s, the plugin stops itself. Catch your errors.
233
+ - After the plugin stops, every call on the old `ctx` throws `plugin kapalı` ("plugin closed").
234
+
235
+ ---
236
+
237
+ ## API reference
238
+
239
+ ### `definePlugin(definition)`
240
+
241
+ ```ts
242
+ definePlugin({ setup(ctx: PluginContext): void | Promise<void> }): PluginDefinition
243
+ ```
244
+ Returns the definition as is (a typing helper). This is the code file's `export default`.
245
+
246
+ ### `PluginContext` (ctx)
247
+
248
+ | Member | Permission | Description |
249
+ |---|---|---|
250
+ | `ctx.manifest` | — | Validated manifest (read-only). |
251
+ | `ctx.log.info/warn/error(message, extra?)` | — | Logging (the error line under Settings → Developer and Bunker's logs). |
252
+ | `ctx.on(event, fn)` | per event | Listen to an event; the returned function stops listening. |
253
+ | `ctx.command(name, fn)` | `events.messages` | `!name` command; the returned function removes it. |
254
+ | `ctx.chat.send(channel, text)` | `chat.send` | Message to a text channel. |
255
+ | `ctx.storage` | `storage` | Persistent key-value storage. |
256
+ | `ctx.voice.join(cid)` / `ctx.voice.session(cid)` | `voice.speak` | Voice channel session. |
257
+ | `ctx.ui.setState(...)` / `ctx.ui.onAction(fn)` | — (manifest `ui`) | Panel window. |
258
+ | `ctx.onUnload(fn)` | — | Cleanup on shutdown. |
259
+
260
+ Event data is a copy; changing it doesn't affect Bunker.
261
+
262
+ ### Events: `ctx.on(event, fn)`
263
+
264
+ ```js
265
+ ctx.on("member.join", (e) => ctx.log.info("new member", { gid: e.gid, uid: e.uid }));
266
+ ```
267
+
268
+ | Event | Data | Permission |
269
+ |---|---|---|
270
+ | `message.create` | `{ scope: "text", gid, chan, m: PluginMessage }` | `events.messages` |
271
+ | `message.edit` | `{ scope, gid, chan, m }` | `events.messages` |
272
+ | `message.delete` | `{ scope, gid, chan, id, by }` | `events.messages` |
273
+ | `message.react` | `{ scope, gid, chan, id, uid, emoji, added }` | `events.messages` |
274
+ | `voice.join` / `voice.leave` | `{ gid, cid, uid, bot }` | `events.voice` |
275
+ | `voice.move` | `{ gid, cid, uid, bot, from }` | `events.voice` |
276
+ | `member.join` / `member.leave` | `{ gid, uid }` | `events.members` |
277
+ | `guild.create` / `guild.delete` | `{ gid, owner }` / `{ gid }` | `events.members` |
278
+ | `channel.create/update/delete` | `{ gid, kind: "text" \| "voice", id }` | `events.channels` |
279
+ | `user.online` / `user.offline` | `{ uid }` (if a member of a server you were added to) | `events.presence` |
280
+ | `guild.install` | `{ gid, by }`: the plugin was added to this server | — |
281
+ | `guild.uninstall` | `{ gid }`: removed, or the server was deleted; **delete that server's data here** | — |
282
+
283
+ ```ts
284
+ interface PluginMessage {
285
+ id: string; ts: number; uid: string; nick: string;
286
+ text: string; // raw text: mentions <@uid>, custom emoji <:name:id>
287
+ system: boolean; // system line such as "… pinned a message"
288
+ bot: boolean; // written by a bot/plugin (including yours: avoid reply loops)
289
+ attachments: number; // number of images/videos
290
+ replyTo?: string; edited?: number;
291
+ }
292
+ ```
293
+
294
+ Events arrive after Bunker has finished its work; a slow listener never blocks Bunker.
295
+
296
+ ### Commands: `ctx.command(name, fn)`
297
+
298
+ ```js
299
+ ctx.command("hello", (c) => c.reply(`Hello ${c.nick}!`));
300
+ ```
301
+
302
+ - Name: letters, digits, `_`, `-`; 1-32 characters; written without `!`; lowercased.
303
+ - Triggered only in text channels and only when a **human** writes it.
304
+ - Bunker's own commands (`!play`, `!skip`, `!rank`, `!bug`…) and names taken by another plugin can't be used.
305
+
306
+ ```ts
307
+ interface CommandCall {
308
+ gid: string; chan: string; uid: string; nick: string;
309
+ args: string; // text after the command
310
+ m: PluginMessage;
311
+ reply(text: string): Promise<void>; // to the same channel (needs chat.send)
312
+ }
313
+ ```
314
+
315
+ ### Messages: `ctx.chat.send(channel, text)`
316
+
317
+ ```js
318
+ const r = await ctx.chat.send(chanId, "Hello!"); // { id } | null
319
+ ```
320
+ Only to text channels of servers you were added to; shown under the bot's name with a BOT tag. At most 10 messages
321
+ per 10 s. Text at most 1800 characters (longer is cut). Mentions: `<@uid>`.
322
+
323
+ ### Storage: `ctx.storage`
324
+
325
+ ```js
326
+ await ctx.storage.set("config:" + gid, { lang: "en" });
327
+ const a = await ctx.storage.get("config:" + gid); // undefined if missing
328
+ await ctx.storage.delete("config:" + gid);
329
+ const keys = await ctx.storage.keys("config:");
330
+ ```
331
+
332
+ | Function | Returns |
333
+ |---|---|
334
+ | `get(key)` | value or `undefined` |
335
+ | `set(key, value)` | — (value must be JSON-serializable) |
336
+ | `delete(key)` | — |
337
+ | `keys(prefix?)` | `string[]` |
338
+
339
+ Private to the plugin, persistent. Values ≤64 KB, keys 1-200 characters, at most 10,000 keys. **One store** for all
340
+ servers: prefix per-server data with `gid` and delete it on `guild.uninstall`.
341
+
342
+ ### Voice: `ctx.voice`
343
+
344
+ ```js
345
+ const s = await ctx.voice.join(cid); // same session if already there
346
+ s.setVolume(30);
347
+ s.on("meta", (m) => ctx.log.info("playing: " + m.title));
348
+ s.on("error", (why, { silent }) => { if (!silent) ctx.log.warn(why); });
349
+ await s.playMedia("daft punk one more time");
350
+ ```
351
+
352
+ `ctx.voice.session(cid)` returns the open session (or `null`). The bot shows up as a separate member in the channel.
353
+
354
+ | `VoiceSession` | Description |
355
+ |---|---|
356
+ | `gid`, `cid`, `playing`, `paused`, `volume` (0-100), `connected` | State (read-only). |
357
+ | `playMedia(query, { seek? })` | YouTube / SoundCloud link, radio stream or search text. Track info arrives via the `meta` event. |
358
+ | `prefetch(query)` | Prepare the next track (faster transitions; valid for 30 min). |
359
+ | `playUrl(url, { seek? })` | Direct http(s) audio URL (radio, mp3). |
360
+ | `stop()`, `pause()`, `resume()`, `setVolume(v)` | Controls. |
361
+ | `leave()` | Leave the channel. |
362
+ | `on(event, fn)` | `started`, `ended`, `error(why, { silent })`, `meta(MediaMeta)`, `leave(why)`; the returned function unsubscribes. |
363
+
364
+ ```ts
365
+ interface MediaMeta { title: string; artist: string; duration: number /* s, 0 for live */; thumb: string; src: string; url: string }
366
+ ```
367
+ If `error` has `silent: true` (e.g. YouTube blocking), you don't need to show it to users. The session closes 60 s
368
+ after nobody is left in the channel, and immediately when the channel is deleted (`leave`). At most 12 plugin voice
369
+ sessions across Bunker at once.
370
+
371
+ ### Window: `ctx.ui`
372
+
373
+ A plugin can show an icon in the plugin group at the bottom left of the panel, and a window that opens on click.
374
+
375
+ ```json
376
+ "ui": { "title": "Dice", "icon": "gamepad", "page": "ui.html", "scope": "guild" }
377
+ ```
378
+
379
+ | Field | Description |
380
+ |---|---|
381
+ | `title` | Window title (≤40). |
382
+ | `icon` | Icon name (below); default `plug`. |
383
+ | `page` | The window page `.html` (select it too when uploading). |
384
+ | `scope` | `"guild"`: always visible on the server, state per server. `"voice"`: only while in one of that server's voice channels, state **per channel**. |
385
+
386
+ Icons: `music radio tv gamepad play pause skip shuffle list volume mic headphones monitor screen camera video live
387
+ clock bell crown smile message hash pin users user gear plug store compass shield key palette keyboard search check
388
+ info edit trash download sleep phone at`.
389
+
390
+ **Model: state down, actions up.** The page cannot connect anywhere by itself; all logic lives in the plugin.
391
+
392
+ ```
393
+ plugin ── ctx.ui.setState ──▶ panel ── {bunker:"state"} ──▶ page
394
+ plugin ◀── ctx.ui.onAction ── panel ◀── {bunker:"action"} ── page
395
+ ```
396
+
397
+ | Function | Description |
398
+ |---|---|
399
+ | `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. |
400
+ | `ctx.ui.onAction(fn)` | `fn({ gid, cid?, uid, nick, name, data })`. 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`. |
401
+
402
+ ```js
403
+ ctx.ui.onAction(async (a) => {
404
+ if (a.name === "roll") ctx.ui.setState({ gid: a.gid }, { last: a.nick, result: 1 + Math.floor(Math.random() * 6) });
405
+ });
406
+ ```
407
+
408
+ Page (`ui.html`):
409
+ ```html
410
+ <!doctype html>
411
+ <meta charset="utf-8">
412
+ <style>
413
+ :root { --bg:#1e1f22; --text:#dbdee1; --accent:#6c6cff; }
414
+ body { margin:0; padding:16px; background:var(--bg); color:var(--text); font:14px system-ui; }
415
+ button { background:var(--accent); color:#fff; border:0; border-radius:6px; padding:8px 12px; }
416
+ </style>
417
+ <p id="t">…</p>
418
+ <button id="b">Roll</button>
419
+ <script>
420
+ const act = (name, data) => parent.postMessage({ bunker: "action", name, data }, "*");
421
+ addEventListener("message", (e) => {
422
+ const m = e.data;
423
+ if (e.source !== parent || m?.bunker !== "state") return;
424
+ for (const [k, v] of Object.entries(m.ctx.theme)) if (typeof v === "string") document.documentElement.style.setProperty("--" + k, v);
425
+ document.getElementById("t").textContent = m.state ? `${m.state.last}: ${m.state.result}` : "No rolls yet";
426
+ });
427
+ document.getElementById("b").onclick = () => act("roll");
428
+ parent.postMessage({ bunker: "ready" }, "*");
429
+ </script>
430
+ ```
431
+
432
+ | Direction | Message |
433
+ |---|---|
434
+ | page → panel | `{ bunker: "ready" }` · `{ bunker: "action", name, data? }` · `{ bunker: "close" }` |
435
+ | panel → page | `{ bunker: "state", state, ctx: { gid, cid, me: { uid, nick }, theme: { dark, bg, text, muted, accent, border, hover } } }` |
436
+
437
+ Page rules: opens in an isolated frame (no access to the panel's cookies or data); no network requests; a single file
438
+ with inline scripts and styles; images may be `https:` or `data:`; take colors from `ctx.theme`.
439
+
440
+ ---
441
+
442
+ ## Publishing to the Store
443
+
444
+ An unverified plugin only runs on your servers and only you see it in the Store (with an "Unverified" tag). To let
445
+ everyone add it:
446
+
447
+ 1. Make sure it works well on your own server.
448
+ 2. Contact the Bunker team (support@bunker.community) with the plugin's name and id (`ext-…`).
449
+ 3. The team reviews the code. If approved, it becomes visible to everyone in the Store (verified).
450
+
451
+ The review checks: whether the requested permissions are really needed, whether the description is accurate, whether
452
+ there is misleading / harassing / spamming behavior, and whether the code is readable (deliberately obfuscated code is
453
+ rejected).
454
+
455
+ Once in the Store, **every new upload is reviewed too**; the previously approved version keeps running until the new
456
+ one is approved. Abusive plugins are disabled.
457
+
458
+ ---
459
+
460
+ ## Limits and error messages
461
+
462
+ | What | Limit |
463
+ |---|---|
464
+ | Code file | single file, ≤1 MB |
465
+ | Memory / CPU | 128 MB / 40% 1-minute average |
466
+ | Plugins per person | 5 |
467
+ | Plugins per server | 25 |
468
+ | Error budget | 10 errors in 60 s → plugin stops |
469
+ | `chat.send` | 10 messages per 10 s, ≤1800 characters |
470
+ | Storage | value ≤64 KB, ≤10,000 keys, key ≤200 characters |
471
+ | Window | state ≤32 KB; actions 10 per second per user, `data` ≤4 KB |
472
+ | Voice | 12 sessions across Bunker |
473
+ | Command name | 1-32 characters |
474
+
475
+ Common errors (messages are currently in Turkish):
476
+
477
+ | Error | Cause |
478
+ |---|---|
479
+ | `… için "X" izni gerekli` | Permission X is missing from the manifest. |
480
+ | `Bu kanala yazamazsın (plugin bu sunucuya ekli değil).` | The channel is on a server the plugin wasn't added to. |
481
+ | `Çok hızlı: 10 sn'de en fazla 10 mesaj` | Message limit. |
482
+ | `!x Bunker'ın kendi komutu, alınamaz` / `başka bir plugin'de kayıtlı` | Command name taken; pick another. |
483
+ | `değer en fazla 64 KB` / `durum en fazla 32 KB` | Value / state too large; split it. |
484
+ | `plugin kapalı` | The old `ctx` was used after the plugin stopped (stop timers in `onUnload`). |
485
+ | `Bunker'da barındırılan plugin bunu kullanamaz: …` | Forbidden module or action (internet, files…). |
486
+
487
+ ---
488
+
489
+ ## FAQ
490
+
491
+ **My plugin doesn't respond.** Is its row "Connected" under Settings → Developer? Is it added under Server settings →
492
+ Plugins, and is there a "needs new permission" warning? Is the command name right? The error line shows the reason.
493
+
494
+ **I need to call an external API.** Code running on Bunker can't reach the internet. Run it on your own computer /
495
+ server with `connect` ([testing section](#testing-while-developing-connecting-from-your-computer)); it can run that way permanently too.
496
+
497
+ **Can I use TypeScript?** Yes; esbuild compiles TypeScript while bundling. Types are included
498
+ (`import type { PluginContext } from "@bunker-community/plugin-sdk"`).
499
+
500
+ **How do I store per-user settings?** Put the server and user id in the key: `ctx.storage.set("config:" + gid + ":" + uid, …)`.
501
+
502
+ **I lost / leaked my token.** Settings → Developer → **Regenerate token**; the old one stops working immediately.
503
+
504
+ ---
505
+
506
+ ## Appendix A: Gateway protocol (other languages)
507
+
508
+ The SDK is for Node.js. To write a bot in another language (Python, Go…) that runs on your own machine, connect to
509
+ the gateway directly: WebSocket `wss://bunker.community/app/api/plugin/gateway`, JSON text messages, ≤320 KB per
510
+ message, ~30 calls per second.
511
+
512
+ **Hello** (first message, within 10 s) and reply:
513
+ ```json
514
+ { "op": "hello", "token": "ext-…", "sdk": "0.1.4", "manifest": { "name": "…", "version": "1.0.0", "sdk": "0.1", "permissions": [] }, "uiPage": "<!doctype html>…" }
515
+ { "op": "ready", "v": 1, "sdk": "0.1.4", "manifest": { "…": "…" }, "guilds": [{ "gid": "…", "name": "…" }] }
516
+ ```
517
+
518
+ **Call → result:**
519
+ ```json
520
+ { "op": "call", "id": 7, "method": "chat.send", "args": ["<channel>", "hello"] }
521
+ { "op": "result", "id": 7, "ok": true, "value": { "id": "<message>" } }
522
+ ```
523
+
524
+ | method | args | value |
525
+ |---|---|---|
526
+ | `subscribe` / `unsubscribe` | `[event]` (event names + `"ui.action"`) | — |
527
+ | `command` / `uncommand` | `[name]` | — |
528
+ | `chat.send` | `[channel, text]` | `{ id }` or `null` |
529
+ | `storage.get` | `[key]` | value or `null` |
530
+ | `storage.set` | `[key, value]` | — |
531
+ | `storage.delete` | `[key]` | — |
532
+ | `storage.keys` | `[prefix]` | `string[]` |
533
+ | `ui.setState` | `[{ gid, cid? }, state, { live? }]` | — |
534
+ | `voice.join` / `voice.session` | `[cid]` | session state |
535
+ | `voice.call` | `[cid, action, args[]]` (`playUrl playMedia prefetch stop pause resume setVolume leave`) | session state |
536
+ | `log` | `["info" / "warn" / "error", message, extra?]` | — |
537
+ | `guilds` | `[]` | `[{ gid, name }]` |
538
+
539
+ Session state: `{ gid, cid, playing, paused, volume, connected }`.
540
+
541
+ **From the server:**
542
+ ```json
543
+ { "op": "event", "name": "member.join", "data": { "gid": "…", "uid": "…" } }
544
+ { "op": "command", "name": "roll", "call": { "gid": "…", "chan": "…", "uid": "…", "nick": "…", "args": "20", "m": { "…": "…" } } }
545
+ { "op": "voice", "cid": "…", "ev": "started", "args": [], "state": { "…": "…" } }
546
+ ```
547
+ To reply to a command, `chat.send` to `call.chan`. Subscriptions are dropped when the connection closes; send them
548
+ again after reconnecting.
549
+
550
+ **Close codes:** 4001 invalid / regenerated token · 4002 malformed message · 4003 plugin disabled or deleted · 4004
551
+ another connection with the same token, or the plugin is running on Bunker · 4005 invalid manifest (reason in
552
+ `reason`) · 4008 too fast or not reading messages. Reconnect on any other close.
553
+
554
+ ---
555
+
556
+ ## Appendix B: Versions
557
+
558
+ `sdk: "0.1"` in the manifest → works with 0.1.x. Fields are added, never removed; breaking changes bump the version.
559
+
560
+ | Version | Change |
561
+ |---|---|
562
+ | 0.1.4 | Uploading plugins to Bunker (hosting), connecting from your computer (`connect`) |
563
+ | 0.1.3 | `playMedia`, `prefetch`, `meta` event, `silent` in the `error` event |
564
+ | 0.1.2 | Voice (`voice.speak`) and panel window (`ui`) |
565
+ | 0.1.1 | `guild.install` / `guild.uninstall` events |
566
+ | 0.1.0 | Events, commands, storage, messages |
567
+
568
+ 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
+ /** Tip yardimcisi: plugin tanimini oldugu gibi dondurur */
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
+ /** Tip yardimcisi: plugin tanimini oldugu gibi dondurur */
6
+ export function definePlugin(def) {
7
+ return def;
8
+ }
@@ -0,0 +1,14 @@
1
+ import { type PluginManifest } from "./types.ts";
2
+ export declare const MANIFEST_FILE = "bunker-plugin.json";
3
+ /** 2-28 karakter: bot kimligi "BunkerPluginBot.<id>" en fazla 44 karakter olsun */
4
+ export declare const ID_RE: RegExp;
5
+ export type ManifestResult = {
6
+ ok: true;
7
+ manifest: PluginManifest;
8
+ } | {
9
+ ok: false;
10
+ errors: string[];
11
+ };
12
+ export declare function validateManifest(raw: unknown): ManifestResult;
13
+ /** Manifest'in istedigi SDK surumu bu SDK ile uyumlu mu ("0.1" -> 0.1.x; "1" -> 1.x). 0.x'te ara surum de kirici sayilir. */
14
+ export declare function sdkCompatible(want: string, have: string): boolean;