@bunker-community/plugin-sdk 0.1.4 → 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 +40 -19
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/manifest.d.ts +2 -2
- package/dist/manifest.js +19 -18
- package/dist/remote.d.ts +12 -12
- package/dist/remote.js +20 -17
- package/dist/types.d.ts +93 -61
- package/dist/types.js +16 -16
- package/dist/version.d.ts +2 -2
- package/dist/version.js +2 -2
- package/package.json +1 -1
package/API_DOC.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Bunker Plugin Developer Guide and API Reference
|
|
2
2
|
|
|
3
|
-
SDK `@bunker-community/plugin-sdk` 0.1.
|
|
3
|
+
SDK `@bunker-community/plugin-sdk` 0.1.7
|
|
4
4
|
|
|
5
5
|
This document is for people who want to write plugins (bots) for Bunker: what is required, how to upload, and which
|
|
6
6
|
functions are available.
|
|
@@ -71,7 +71,8 @@ A plugin that doesn't follow these rules is rejected or won't run.
|
|
|
71
71
|
| `version` | yes | `x.y.z` (e.g. `1.0.0`, `1.2.0-beta.1`). |
|
|
72
72
|
| `sdk` | yes | `"0.1"`. |
|
|
73
73
|
| `permissions` | yes | List of permissions; `[]` if you need none. |
|
|
74
|
-
| `description` | no | At most 300 characters; shown
|
|
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. |
|
|
75
76
|
| `author` | no | At most 80 characters. |
|
|
76
77
|
| `ui` | no | Panel window ([Window](#window-ctxui)). |
|
|
77
78
|
| `id` | — | Don't set it: the plugin id (`ext-xxxxxxxx`) is assigned when you create the plugin on Bunker. |
|
|
@@ -230,7 +231,7 @@ export default definePlugin({
|
|
|
230
231
|
- When the plugin stops (stop, new code, Bunker restart): listeners are released, voice sessions close, `onUnload`
|
|
231
232
|
runs. Storage still works inside `onUnload`; at most 3 s in total.
|
|
232
233
|
- **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
|
|
234
|
+
- After the plugin stops, every call on the old `ctx` throws `plugin is off`.
|
|
234
235
|
|
|
235
236
|
---
|
|
236
237
|
|
|
@@ -253,8 +254,10 @@ Returns the definition as is (a typing helper). This is the code file's `export
|
|
|
253
254
|
| `ctx.command(name, fn)` | `events.messages` | `!name` command; the returned function removes it. |
|
|
254
255
|
| `ctx.chat.send(channel, text)` | `chat.send` | Message to a text channel. |
|
|
255
256
|
| `ctx.storage` | `storage` | Persistent key-value storage. |
|
|
257
|
+
| `ctx.serverLang(gid)` | — | The server's language, `Promise<"en" \| "tr">` (Server settings → Language). |
|
|
256
258
|
| `ctx.voice.join(cid)` / `ctx.voice.session(cid)` | `voice.speak` | Voice channel session. |
|
|
257
|
-
| `ctx.
|
|
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. |
|
|
258
261
|
| `ctx.onUnload(fn)` | — | Cleanup on shutdown. |
|
|
259
262
|
|
|
260
263
|
Event data is a copy; changing it doesn't affect Bunker.
|
|
@@ -308,6 +311,8 @@ interface CommandCall {
|
|
|
308
311
|
gid: string; chan: string; uid: string; nick: string;
|
|
309
312
|
args: string; // text after the command
|
|
310
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
|
|
311
316
|
reply(text: string): Promise<void>; // to the same channel (needs chat.send)
|
|
312
317
|
}
|
|
313
318
|
```
|
|
@@ -318,7 +323,7 @@ interface CommandCall {
|
|
|
318
323
|
const r = await ctx.chat.send(chanId, "Hello!"); // { id } | null
|
|
319
324
|
```
|
|
320
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
|
|
321
|
-
per 10 s. Text at most 1800 characters (longer is cut). Mentions: `<@uid>`.
|
|
326
|
+
per 10 s per server. Text at most 1800 characters (longer is cut). Mentions: `<@uid>`.
|
|
322
327
|
|
|
323
328
|
### Storage: `ctx.storage`
|
|
324
329
|
|
|
@@ -397,7 +402,7 @@ plugin ◀── ctx.ui.onAction ── panel ◀── {bunker:"action"} ──
|
|
|
397
402
|
| Function | Description |
|
|
398
403
|
|---|---|
|
|
399
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. |
|
|
400
|
-
| `ctx.ui.onAction(fn)` | `fn({ gid, cid?, uid, nick, name, data })
|
|
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`. |
|
|
401
406
|
|
|
402
407
|
```js
|
|
403
408
|
ctx.ui.onAction(async (a) => {
|
|
@@ -432,10 +437,21 @@ Page (`ui.html`):
|
|
|
432
437
|
| Direction | Message |
|
|
433
438
|
|---|---|
|
|
434
439
|
| 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 } } }` |
|
|
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.
|
|
436
450
|
|
|
437
451
|
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`.
|
|
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.
|
|
439
455
|
|
|
440
456
|
---
|
|
441
457
|
|
|
@@ -466,23 +482,23 @@ one is approved. Abusive plugins are disabled.
|
|
|
466
482
|
| Plugins per person | 5 |
|
|
467
483
|
| Plugins per server | 25 |
|
|
468
484
|
| Error budget | 10 errors in 60 s → plugin stops |
|
|
469
|
-
| `chat.send` | 10 messages per 10 s, ≤1800 characters |
|
|
485
|
+
| `chat.send` | 10 messages per 10 s per server, ≤1800 characters |
|
|
470
486
|
| Storage | value ≤64 KB, ≤10,000 keys, key ≤200 characters |
|
|
471
487
|
| Window | state ≤32 KB; actions 10 per second per user, `data` ≤4 KB |
|
|
472
488
|
| Voice | 12 sessions across Bunker |
|
|
473
489
|
| Command name | 1-32 characters |
|
|
474
490
|
|
|
475
|
-
Common errors
|
|
491
|
+
Common errors:
|
|
476
492
|
|
|
477
493
|
| Error | Cause |
|
|
478
494
|
|---|---|
|
|
479
|
-
| `…
|
|
480
|
-
| `
|
|
481
|
-
|
|
|
482
|
-
| `!x Bunker'
|
|
483
|
-
| `
|
|
484
|
-
| `plugin
|
|
485
|
-
| `Bunker
|
|
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…). |
|
|
486
502
|
|
|
487
503
|
---
|
|
488
504
|
|
|
@@ -511,8 +527,8 @@ message, ~30 calls per second.
|
|
|
511
527
|
|
|
512
528
|
**Hello** (first message, within 10 s) and reply:
|
|
513
529
|
```json
|
|
514
|
-
{ "op": "hello", "token": "ext-…", "sdk": "0.1.
|
|
515
|
-
{ "op": "ready", "v": 1, "sdk": "0.1.
|
|
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": "…" }] }
|
|
516
532
|
```
|
|
517
533
|
|
|
518
534
|
**Call → result:**
|
|
@@ -532,6 +548,8 @@ message, ~30 calls per second.
|
|
|
532
548
|
| `storage.keys` | `[prefix]` | `string[]` |
|
|
533
549
|
| `ui.setState` | `[{ gid, cid? }, state, { live? }]` | — |
|
|
534
550
|
| `voice.join` / `voice.session` | `[cid]` | session state |
|
|
551
|
+
| `voice.channelOf` | `[uid]` | `{ gid, cid }` or `null` |
|
|
552
|
+
| `ui.send` | `[uid, { gid, cid? }, data]` | — |
|
|
535
553
|
| `voice.call` | `[cid, action, args[]]` (`playUrl playMedia prefetch stop pause resume setVolume leave`) | session state |
|
|
536
554
|
| `log` | `["info" / "warn" / "error", message, extra?]` | — |
|
|
537
555
|
| `guilds` | `[]` | `[{ gid, name }]` |
|
|
@@ -559,6 +577,9 @@ another connection with the same token, or the plugin is running on Bunker · 40
|
|
|
559
577
|
|
|
560
578
|
| Version | Change |
|
|
561
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` |
|
|
562
583
|
| 0.1.4 | Uploading plugins to Bunker (hosting), connecting from your computer (`connect`) |
|
|
563
584
|
| 0.1.3 | `playMedia`, `prefetch`, `meta` event, `silent` in the `error` event |
|
|
564
585
|
| 0.1.2 | Voice (`voice.speak`) and panel window (`ui`) |
|
package/dist/index.d.ts
CHANGED
|
@@ -3,5 +3,5 @@ export * from "./types.ts";
|
|
|
3
3
|
export * from "./manifest.ts";
|
|
4
4
|
export * from "./version.ts";
|
|
5
5
|
export * from "./remote.ts";
|
|
6
|
-
/**
|
|
6
|
+
/** Type helper: returns the plugin definition as is */
|
|
7
7
|
export declare function definePlugin(def: PluginDefinition): PluginDefinition;
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@ export * from "./types.js";
|
|
|
2
2
|
export * from "./manifest.js";
|
|
3
3
|
export * from "./version.js";
|
|
4
4
|
export * from "./remote.js";
|
|
5
|
-
/**
|
|
5
|
+
/** Type helper: returns the plugin definition as is */
|
|
6
6
|
export function definePlugin(def) {
|
|
7
7
|
return def;
|
|
8
8
|
}
|
package/dist/manifest.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type PluginManifest } from "./types.ts";
|
|
2
2
|
export declare const MANIFEST_FILE = "bunker-plugin.json";
|
|
3
|
-
/** 2-28
|
|
3
|
+
/** 2-28 characters: the bot identity "BunkerPluginBot.<id>" stays at most 44 characters */
|
|
4
4
|
export declare const ID_RE: RegExp;
|
|
5
5
|
export type ManifestResult = {
|
|
6
6
|
ok: true;
|
|
@@ -10,5 +10,5 @@ export type ManifestResult = {
|
|
|
10
10
|
errors: string[];
|
|
11
11
|
};
|
|
12
12
|
export declare function validateManifest(raw: unknown): ManifestResult;
|
|
13
|
-
/**
|
|
13
|
+
/** Is the SDK version the manifest asks for compatible with this SDK ("0.1" -> 0.1.x; "1" -> 1.x). In 0.x a minor version counts as breaking too. */
|
|
14
14
|
export declare function sdkCompatible(want: string, have: string): boolean;
|
package/dist/manifest.js
CHANGED
|
@@ -1,78 +1,79 @@
|
|
|
1
|
-
/* bunker-plugin.json
|
|
1
|
+
/* bunker-plugin.json validation (dependency-free; the runtime and the developer tool use the same code) */
|
|
2
2
|
import { PERMISSIONS } from "./types.js";
|
|
3
3
|
export const MANIFEST_FILE = "bunker-plugin.json";
|
|
4
|
-
/** 2-28
|
|
4
|
+
/** 2-28 characters: the bot identity "BunkerPluginBot.<id>" stays at most 44 characters */
|
|
5
5
|
export const ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,26}[a-z0-9])$/;
|
|
6
6
|
const VERSION_RE = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
|
|
7
7
|
const SDK_RANGE_RE = /^\d+(?:\.\d+)?$/;
|
|
8
8
|
export function validateManifest(raw) {
|
|
9
9
|
const errors = [];
|
|
10
10
|
if (!raw || typeof raw !== "object" || Array.isArray(raw))
|
|
11
|
-
return { ok: false, errors: ["manifest
|
|
11
|
+
return { ok: false, errors: ["manifest must be a JSON object"] };
|
|
12
12
|
const o = raw;
|
|
13
13
|
const str = (k, max, required = true) => {
|
|
14
14
|
const v = o[k];
|
|
15
15
|
if (v === undefined && !required)
|
|
16
16
|
return undefined;
|
|
17
17
|
if (typeof v !== "string" || !v.trim()) {
|
|
18
|
-
errors.push(`${k}:
|
|
18
|
+
errors.push(`${k}: must be text`);
|
|
19
19
|
return undefined;
|
|
20
20
|
}
|
|
21
21
|
if (v.length > max)
|
|
22
|
-
errors.push(`${k}:
|
|
22
|
+
errors.push(`${k}: at most ${max} characters`);
|
|
23
23
|
return v.trim();
|
|
24
24
|
};
|
|
25
25
|
const id = str("id", 28);
|
|
26
26
|
if (id && !ID_RE.test(id))
|
|
27
|
-
errors.push("id:
|
|
27
|
+
errors.push("id: lowercase letters, digits and dashes (2-28 characters, not starting or ending with a dash)");
|
|
28
28
|
const name = str("name", 40);
|
|
29
29
|
const version = str("version", 32);
|
|
30
30
|
if (version && !VERSION_RE.test(version))
|
|
31
|
-
errors.push("version: x.y.z
|
|
31
|
+
errors.push("version: must be x.y.z");
|
|
32
32
|
const description = str("description", 300, false);
|
|
33
|
+
const details = str("details", 4000, false);
|
|
33
34
|
const author = str("author", 80, false);
|
|
34
35
|
const main = str("main", 120, false);
|
|
35
36
|
if (main && (main.startsWith("/") || main.includes("..") || main.includes("\\")))
|
|
36
|
-
errors.push("main:
|
|
37
|
+
errors.push("main: must be a relative path inside the plugin folder");
|
|
37
38
|
const sdk = str("sdk", 10);
|
|
38
39
|
if (sdk && !SDK_RANGE_RE.test(sdk))
|
|
39
|
-
errors.push('sdk: "0"
|
|
40
|
+
errors.push('sdk: a major version like "0" or "0.1"');
|
|
40
41
|
const perms = o.permissions;
|
|
41
42
|
let permissions = [];
|
|
42
43
|
if (!Array.isArray(perms))
|
|
43
|
-
errors.push("permissions:
|
|
44
|
+
errors.push("permissions: must be an array (can be empty)");
|
|
44
45
|
else {
|
|
45
46
|
for (const p of perms)
|
|
46
47
|
if (!PERMISSIONS.includes(p))
|
|
47
|
-
errors.push(`permissions:
|
|
48
|
+
errors.push(`permissions: unknown permission "${String(p)}"`);
|
|
48
49
|
permissions = [...new Set(perms)];
|
|
49
50
|
}
|
|
50
51
|
let ui;
|
|
51
52
|
if (o.ui !== undefined) {
|
|
52
53
|
const u = o.ui;
|
|
53
54
|
if (!u || typeof u !== "object" || Array.isArray(u))
|
|
54
|
-
errors.push("ui:
|
|
55
|
+
errors.push("ui: must be an object");
|
|
55
56
|
else {
|
|
56
57
|
const title = typeof u.title === "string" && u.title.trim() ? u.title.trim().slice(0, 40) : "";
|
|
57
58
|
const page = typeof u.page === "string" ? u.page.trim() : "";
|
|
58
59
|
const icon = u.icon === undefined ? undefined : typeof u.icon === "string" && /^[a-zA-Z]{1,24}$/.test(u.icon) ? u.icon : null;
|
|
59
60
|
if (!title)
|
|
60
|
-
errors.push("ui.title:
|
|
61
|
+
errors.push("ui.title: must be text");
|
|
61
62
|
if (!page || page.startsWith("/") || page.includes("..") || page.includes("\\") || !/\.html?$/i.test(page))
|
|
62
|
-
errors.push("ui.page:
|
|
63
|
+
errors.push("ui.page: must be an .html file in the plugin folder");
|
|
63
64
|
if (u.scope !== "voice" && u.scope !== "guild")
|
|
64
|
-
errors.push('ui.scope: "voice"
|
|
65
|
+
errors.push('ui.scope: "voice" or "guild"');
|
|
65
66
|
if (icon === null)
|
|
66
|
-
errors.push("ui.icon:
|
|
67
|
+
errors.push("ui.icon: an icon name made of letters");
|
|
67
68
|
if (title && page && icon !== null)
|
|
68
69
|
ui = { title, page, scope: u.scope, ...(icon ? { icon } : {}) };
|
|
69
70
|
}
|
|
70
71
|
}
|
|
71
72
|
if (errors.length)
|
|
72
73
|
return { ok: false, errors };
|
|
73
|
-
return { ok: true, manifest: { id: id, name: name, version: version, description, author, main: main ?? "src/index.ts", sdk: sdk, permissions, ...(ui ? { ui } : {}) } };
|
|
74
|
+
return { ok: true, manifest: { id: id, name: name, version: version, description, ...(details ? { details } : {}), author, main: main ?? "src/index.ts", sdk: sdk, permissions, ...(ui ? { ui } : {}) } };
|
|
74
75
|
}
|
|
75
|
-
/**
|
|
76
|
+
/** Is the SDK version the manifest asks for compatible with this SDK ("0.1" -> 0.1.x; "1" -> 1.x). In 0.x a minor version counts as breaking too. */
|
|
76
77
|
export function sdkCompatible(want, have) {
|
|
77
78
|
const [wMaj, wMin] = want.split(".").map(Number);
|
|
78
79
|
const [hMaj, hMin] = have.split(".").map(Number);
|
package/dist/remote.d.ts
CHANGED
|
@@ -1,32 +1,32 @@
|
|
|
1
1
|
import type { PluginDefinition, PluginManifest } from "./types.ts";
|
|
2
2
|
export declare const DEFAULT_GATEWAY = "wss://bunker.community/app/api/plugin/gateway";
|
|
3
3
|
export interface ConnectOptions {
|
|
4
|
-
/**
|
|
4
|
+
/** The token from Settings -> Developer */
|
|
5
5
|
token: string;
|
|
6
|
-
/**
|
|
6
|
+
/** Gateway address (default bunker.community) */
|
|
7
7
|
url?: string;
|
|
8
8
|
/**
|
|
9
|
-
* Manifest (bunker-plugin.json
|
|
10
|
-
* Bunker
|
|
9
|
+
* Manifest (the content of bunker-plugin.json). If not given, bunker-plugin.json in the `dir` folder is read; if that is missing too
|
|
10
|
+
* the manifest stored on Bunker is used. The id field is ignored (it is the key's plugin).
|
|
11
11
|
*/
|
|
12
12
|
manifest?: Partial<PluginManifest>;
|
|
13
|
-
/** bunker-plugin.json
|
|
13
|
+
/** Folder of bunker-plugin.json and the window page (default: the working directory) */
|
|
14
14
|
dir?: string;
|
|
15
|
-
/**
|
|
15
|
+
/** HTML of the window page (if not given, the manifest's ui.page file is read from `dir`) */
|
|
16
16
|
uiPage?: string;
|
|
17
17
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
18
|
+
* Connection (default: WebSocket(url)). For plugins hosted on Bunker the runtime provides its own channel;
|
|
19
|
+
* don't pass it normally.
|
|
20
20
|
*/
|
|
21
21
|
transport?: (url: string) => TransportLike;
|
|
22
|
-
/**
|
|
22
|
+
/** Logger (default console) */
|
|
23
23
|
logger?: {
|
|
24
24
|
info(...a: unknown[]): void;
|
|
25
25
|
warn(...a: unknown[]): void;
|
|
26
26
|
error(...a: unknown[]): void;
|
|
27
27
|
};
|
|
28
28
|
}
|
|
29
|
-
/** WebSocket
|
|
29
|
+
/** The part of WebSocket that is used */
|
|
30
30
|
export interface TransportLike {
|
|
31
31
|
onopen: ((e?: unknown) => void) | null;
|
|
32
32
|
onmessage: ((e: {
|
|
@@ -41,10 +41,10 @@ export interface TransportLike {
|
|
|
41
41
|
close(code?: number, reason?: string): void;
|
|
42
42
|
}
|
|
43
43
|
export interface Connection {
|
|
44
|
-
/**
|
|
44
|
+
/** The first connection was made and setup ran */
|
|
45
45
|
readonly ready: Promise<void>;
|
|
46
46
|
readonly connected: boolean;
|
|
47
|
-
/**
|
|
47
|
+
/** Close the connection, run the onUnload handlers */
|
|
48
48
|
close(): Promise<void>;
|
|
49
49
|
}
|
|
50
50
|
export declare function connect(def: PluginDefinition, opts: ConnectOptions): Connection;
|
package/dist/remote.js
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { SDK_VERSION as SDK } from "./version.js";
|
|
2
2
|
export const DEFAULT_GATEWAY = "wss://bunker.community/app/api/plugin/gateway";
|
|
3
|
-
/**
|
|
3
|
+
/** No retry if it closes with these codes */
|
|
4
4
|
const FATAL = {
|
|
5
|
-
4001: "
|
|
6
|
-
4003: "plugin Bunker
|
|
7
|
-
4004: "
|
|
8
|
-
4005: "manifest
|
|
5
|
+
4001: "invalid key",
|
|
6
|
+
4003: "plugin is off on Bunker",
|
|
7
|
+
4004: "another connection was opened with the same key",
|
|
8
|
+
4005: "invalid manifest",
|
|
9
9
|
};
|
|
10
10
|
export function connect(def, opts) {
|
|
11
11
|
const log = opts.logger ?? console;
|
|
@@ -29,14 +29,14 @@ export function connect(def, opts) {
|
|
|
29
29
|
ws.send(JSON.stringify(m)); };
|
|
30
30
|
function call(method, ...args) {
|
|
31
31
|
if (!ws || !open)
|
|
32
|
-
return Promise.reject(new Error("
|
|
32
|
+
return Promise.reject(new Error("not connected to Bunker"));
|
|
33
33
|
const id = ++seq;
|
|
34
34
|
return new Promise((resolve, reject) => {
|
|
35
35
|
pending.set(id, { resolve: resolve, reject });
|
|
36
36
|
raw({ op: "call", id, method, args });
|
|
37
37
|
});
|
|
38
38
|
}
|
|
39
|
-
/**
|
|
39
|
+
/** A call whose result wasn't awaited (error to the log) */
|
|
40
40
|
const fire = (method, ...args) => { call(method, ...args).catch((e) => log.warn(`[bunker] ${method}: ${e.message}`)); };
|
|
41
41
|
const safe = (where, fn) => {
|
|
42
42
|
try {
|
|
@@ -66,7 +66,7 @@ export function connect(def, opts) {
|
|
|
66
66
|
page = fs.readFileSync(path.join(dir, ui.page), "utf8");
|
|
67
67
|
}
|
|
68
68
|
catch (e) {
|
|
69
|
-
log.warn("[bunker] manifest/
|
|
69
|
+
log.warn("[bunker] could not read manifest/window:", e.message);
|
|
70
70
|
}
|
|
71
71
|
}
|
|
72
72
|
return { m, page };
|
|
@@ -103,7 +103,7 @@ export function connect(def, opts) {
|
|
|
103
103
|
command(name, fn) {
|
|
104
104
|
const n = String(name).replace(/^!/, "").toLocaleLowerCase("tr");
|
|
105
105
|
if (commands.has(n))
|
|
106
|
-
throw new Error(`!${n}
|
|
106
|
+
throw new Error(`!${n} is already registered`);
|
|
107
107
|
commands.set(n, fn);
|
|
108
108
|
if (open)
|
|
109
109
|
fire("command", n);
|
|
@@ -117,15 +117,18 @@ export function connect(def, opts) {
|
|
|
117
117
|
delete: (key) => call("storage.delete", key).then(() => { }),
|
|
118
118
|
keys: (prefix = "") => call("storage.keys", prefix),
|
|
119
119
|
},
|
|
120
|
+
serverLang: (gid) => call("serverLang", gid).then((v) => (v === "tr" ? "tr" : "en")),
|
|
120
121
|
voice: {
|
|
121
122
|
async join(cid) { return sessionFor(await call("voice.join", cid)); },
|
|
122
123
|
session(cid) { return sessions.get(cid) ?? null; },
|
|
124
|
+
channelOf: (uid) => call("voice.channelOf", uid),
|
|
123
125
|
},
|
|
124
126
|
ui: {
|
|
125
127
|
setState: (where, state, o) => fire("ui.setState", where, state, o ?? {}),
|
|
126
128
|
onAction(fn) {
|
|
127
129
|
return ctx.on("ui.action", fn);
|
|
128
130
|
},
|
|
131
|
+
send: (uid, where, data) => fire("ui.send", uid, where, data),
|
|
129
132
|
},
|
|
130
133
|
onUnload(fn) { unloaders.push(fn); },
|
|
131
134
|
};
|
|
@@ -150,7 +153,7 @@ export function connect(def, opts) {
|
|
|
150
153
|
case "ready":
|
|
151
154
|
manifest = m.manifest;
|
|
152
155
|
backoff = 1000;
|
|
153
|
-
log.info(`[bunker]
|
|
156
|
+
log.info(`[bunker] connected: ${manifest.name} (${manifest.id}), ${m.guilds?.length ?? 0} servers`);
|
|
154
157
|
if (!started) {
|
|
155
158
|
started = true;
|
|
156
159
|
Promise.resolve().then(() => def.setup(ctx)).then(() => readyResolve(), (e) => { log.error("[bunker] setup:", e); readyReject(e); });
|
|
@@ -177,7 +180,7 @@ export function connect(def, opts) {
|
|
|
177
180
|
const fn = commands.get(m.name);
|
|
178
181
|
const c = m.call;
|
|
179
182
|
if (fn)
|
|
180
|
-
safe("!" + m.name, () => fn({ ...c, reply: async (text) => { await call("chat.send", c.chan, text); } }));
|
|
183
|
+
safe("!" + m.name, () => fn({ ...c, lang: c.lang === "tr" ? "tr" : "en", reply: async (text) => { await call("chat.send", c.chan, text); } }));
|
|
181
184
|
return;
|
|
182
185
|
}
|
|
183
186
|
case "voice": {
|
|
@@ -207,23 +210,23 @@ export function connect(def, opts) {
|
|
|
207
210
|
open = false;
|
|
208
211
|
ws = null;
|
|
209
212
|
for (const p of pending.values())
|
|
210
|
-
p.reject(new Error("
|
|
213
|
+
p.reject(new Error("connection lost"));
|
|
211
214
|
pending.clear();
|
|
212
215
|
for (const s of sessions.values()) {
|
|
213
216
|
s.st = { ...s.st, connected: false, playing: false };
|
|
214
|
-
s.emit("leave", ["
|
|
217
|
+
s.emit("leave", ["connection lost"], safe);
|
|
215
218
|
}
|
|
216
219
|
sessions.clear();
|
|
217
220
|
if (closed)
|
|
218
221
|
return;
|
|
219
222
|
const fatal = FATAL[e.code];
|
|
220
223
|
if (fatal) {
|
|
221
|
-
log.error(`[bunker]
|
|
224
|
+
log.error(`[bunker] connection closed: ${fatal}${e.reason ? ` (${e.reason})` : ""}`);
|
|
222
225
|
closed = true;
|
|
223
226
|
readyReject(new Error(e.reason || fatal));
|
|
224
227
|
return;
|
|
225
228
|
}
|
|
226
|
-
log.warn(`[bunker]
|
|
229
|
+
log.warn(`[bunker] connection lost (${e.code}${e.reason ? " " + e.reason : ""}), retrying in ${Math.round(backoff / 1000)} s`);
|
|
227
230
|
setTimeout(() => void dial(), backoff);
|
|
228
231
|
backoff = Math.min(30_000, backoff * 2);
|
|
229
232
|
};
|
|
@@ -245,7 +248,7 @@ export function connect(def, opts) {
|
|
|
245
248
|
log.error("[bunker] onUnload:", e);
|
|
246
249
|
}
|
|
247
250
|
}
|
|
248
|
-
ws?.close(1000, "
|
|
251
|
+
ws?.close(1000, "turned off");
|
|
249
252
|
},
|
|
250
253
|
};
|
|
251
254
|
}
|
|
@@ -263,7 +266,7 @@ class RemoteSession {
|
|
|
263
266
|
do(method, ...args) { return this.call("voice.call", this.st.cid, method, args).then((st) => { if (st)
|
|
264
267
|
this.st = st; }); }
|
|
265
268
|
quiet(method, ...args) { this.do(method, ...args).catch(() => { }); }
|
|
266
|
-
playPcm() { throw new Error("playPcm
|
|
269
|
+
playPcm() { throw new Error("playPcm is not available for remote plugins (use playUrl / playMedia)"); }
|
|
267
270
|
playUrl(url, opts) { return this.do("playUrl", url, opts ?? {}); }
|
|
268
271
|
playMedia(query, opts) { return this.do("playMedia", query, opts ?? {}); }
|
|
269
272
|
prefetch(query) { this.quiet("prefetch", query); }
|
package/dist/types.d.ts
CHANGED
|
@@ -1,70 +1,73 @@
|
|
|
1
|
-
/**
|
|
1
|
+
/** Permissions a plugin can ask for. A call that needs a permission missing from the manifest throws. */
|
|
2
2
|
export type Permission =
|
|
3
|
-
/** message.*
|
|
3
|
+
/** message.* events + ctx.command */
|
|
4
4
|
"events.messages"
|
|
5
|
-
/** voice.*
|
|
5
|
+
/** voice.* events */
|
|
6
6
|
| "events.voice"
|
|
7
|
-
/** member.*, guild.*
|
|
7
|
+
/** member.*, guild.* events */
|
|
8
8
|
| "events.members"
|
|
9
|
-
/** channel.*
|
|
9
|
+
/** channel.* events */
|
|
10
10
|
| "events.channels"
|
|
11
11
|
/** user.online / user.offline */
|
|
12
12
|
| "events.presence"
|
|
13
|
-
/**
|
|
13
|
+
/** Writing to text channels under the plugin's own name */
|
|
14
14
|
| "chat.send"
|
|
15
|
-
/**
|
|
15
|
+
/** Key-value store private to the plugin */
|
|
16
16
|
| "storage"
|
|
17
|
-
/**
|
|
17
|
+
/** Joining voice channels and playing audio (ctx.voice) */
|
|
18
18
|
| "voice.speak";
|
|
19
19
|
export declare const PERMISSIONS: readonly Permission[];
|
|
20
|
-
/**
|
|
20
|
+
/** Description shown to the server owner when adding to a server (approval screen) */
|
|
21
21
|
export declare const PERMISSION_TEXT: Record<Permission, string>;
|
|
22
|
-
/**
|
|
22
|
+
/** The window the plugin shows in the panel (manifest "ui"). The page opens in an isolated frame (iframe, sandbox). */
|
|
23
23
|
export interface PluginUi {
|
|
24
|
-
/**
|
|
24
|
+
/** Window title */
|
|
25
25
|
title: string;
|
|
26
|
-
/**
|
|
26
|
+
/** Icon at the bottom left: one of the panel's icon names (e.g. "music", "radio", "tv"); "plug" otherwise */
|
|
27
27
|
icon?: string;
|
|
28
|
-
/**
|
|
28
|
+
/** Window page (relative to the plugin folder), e.g. "ui/index.html". A single file is recommended (inline script/style). */
|
|
29
29
|
page: string;
|
|
30
|
-
/** "voice":
|
|
30
|
+
/** "voice": only visible while in a voice channel of that server (state per channel); "guild": always on the server */
|
|
31
31
|
scope: "voice" | "guild";
|
|
32
32
|
}
|
|
33
33
|
/** bunker-plugin.json */
|
|
34
34
|
export interface PluginManifest {
|
|
35
|
-
/**
|
|
35
|
+
/** Lowercase letters, digits, dashes: 2-28 characters. The plugin's permanent identity (storage, settings, bot identity depend on it). */
|
|
36
36
|
id: string;
|
|
37
|
-
/**
|
|
37
|
+
/** Display name (also used as the bot name in messages) */
|
|
38
38
|
name: string;
|
|
39
|
-
/** Plugin
|
|
39
|
+
/** Plugin version (x.y.z) */
|
|
40
40
|
version: string;
|
|
41
|
+
/** Short description (at most 300 characters), shown on Store cards. */
|
|
41
42
|
description?: string;
|
|
43
|
+
/** Long description (at most 4000 characters, plain text; blank lines start a new paragraph), shown in the Store detail view. */
|
|
44
|
+
details?: string;
|
|
42
45
|
author?: string;
|
|
43
|
-
/**
|
|
46
|
+
/** Server-side entry file (relative to the plugin folder), default "src/index.ts" */
|
|
44
47
|
main?: string;
|
|
45
|
-
/**
|
|
48
|
+
/** Compatible SDK major version, e.g. "0" or "0.1" */
|
|
46
49
|
sdk: string;
|
|
47
50
|
permissions: Permission[];
|
|
48
|
-
/** Panel
|
|
51
|
+
/** Panel window (optional) */
|
|
49
52
|
ui?: PluginUi;
|
|
50
53
|
}
|
|
51
|
-
/**
|
|
54
|
+
/** The message as exposed to the plugin */
|
|
52
55
|
export interface PluginMessage {
|
|
53
56
|
id: string;
|
|
54
57
|
ts: number;
|
|
55
58
|
uid: string;
|
|
56
59
|
nick: string;
|
|
57
60
|
text: string;
|
|
58
|
-
/**
|
|
61
|
+
/** System line (like "... pinned") */
|
|
59
62
|
system: boolean;
|
|
60
|
-
/**
|
|
63
|
+
/** Written by a bot or plugin */
|
|
61
64
|
bot: boolean;
|
|
62
|
-
/**
|
|
65
|
+
/** Number of attachments (image/video) */
|
|
63
66
|
attachments: number;
|
|
64
67
|
replyTo?: string;
|
|
65
68
|
edited?: number;
|
|
66
69
|
}
|
|
67
|
-
/**
|
|
70
|
+
/** Text channel or direct message. Direct message events are currently NOT sent to plugins (privacy). */
|
|
68
71
|
export type MessageWhere = {
|
|
69
72
|
scope: "text";
|
|
70
73
|
gid: string;
|
|
@@ -134,31 +137,37 @@ export interface PluginEvents {
|
|
|
134
137
|
from: string;
|
|
135
138
|
};
|
|
136
139
|
"voice.leave": VoiceWhere;
|
|
137
|
-
/**
|
|
140
|
+
/** The plugin was added to this server (no permission needed) */
|
|
138
141
|
"guild.install": {
|
|
139
142
|
gid: string;
|
|
140
143
|
by: string;
|
|
141
144
|
};
|
|
142
|
-
/**
|
|
145
|
+
/** The plugin was removed from this server or the server was deleted (no permission needed); clean up your data for the server here */
|
|
143
146
|
"guild.uninstall": {
|
|
144
147
|
gid: string;
|
|
145
148
|
};
|
|
146
149
|
}
|
|
147
150
|
export type PluginEventName = keyof PluginEvents;
|
|
148
|
-
/**
|
|
151
|
+
/** Event -> required permission (null: no permission needed) */
|
|
149
152
|
export declare const EVENT_PERMISSION: Record<PluginEventName, Permission | null>;
|
|
150
153
|
export type Awaitable<T> = T | Promise<T>;
|
|
151
|
-
/**
|
|
154
|
+
/** Languages Bunker supports */
|
|
155
|
+
export type Lang = "en" | "tr";
|
|
156
|
+
/** A "!command args..." call (text channels only, when a human writes) */
|
|
152
157
|
export interface CommandCall {
|
|
153
158
|
gid: string;
|
|
154
159
|
chan: string;
|
|
155
|
-
/**
|
|
160
|
+
/** The writer */
|
|
156
161
|
uid: string;
|
|
157
162
|
nick: string;
|
|
158
|
-
/**
|
|
163
|
+
/** The text after the command (spaces trimmed) */
|
|
159
164
|
args: string;
|
|
160
165
|
m: PluginMessage;
|
|
161
|
-
/**
|
|
166
|
+
/** Does the writer have the server settings permission on this server (server.manage / admin) */
|
|
167
|
+
manage: boolean;
|
|
168
|
+
/** The server's language (Server settings -> Language). Write replies in it: chat messages are not translated per viewer. */
|
|
169
|
+
lang: Lang;
|
|
170
|
+
/** Reply in the same channel under the plugin's name (needs the chat.send permission) */
|
|
162
171
|
reply(text: string): Promise<void>;
|
|
163
172
|
}
|
|
164
173
|
export interface PluginLogger {
|
|
@@ -166,55 +175,55 @@ export interface PluginLogger {
|
|
|
166
175
|
warn(msg: string, ctx?: Record<string, unknown>): void;
|
|
167
176
|
error(msg: string, ctx?: Record<string, unknown>): void;
|
|
168
177
|
}
|
|
169
|
-
/**
|
|
178
|
+
/** Persistent store private to the plugin (JSON values, at most 64 KB; at most 10,000 keys per plugin) */
|
|
170
179
|
export interface PluginStorage {
|
|
171
180
|
get<T = unknown>(key: string): Promise<T | undefined>;
|
|
172
181
|
set(key: string, value: unknown): Promise<void>;
|
|
173
182
|
delete(key: string): Promise<void>;
|
|
174
183
|
keys(prefix?: string): Promise<string[]>;
|
|
175
184
|
}
|
|
176
|
-
/**
|
|
185
|
+
/** The plugin's session in a voice channel. Leaves on its own 60 s after no humans are left in the channel. */
|
|
177
186
|
export interface VoiceSession {
|
|
178
187
|
readonly gid: string;
|
|
179
188
|
readonly cid: string;
|
|
180
|
-
/**
|
|
189
|
+
/** Is audio flowing right now (true even if paused) */
|
|
181
190
|
readonly playing: boolean;
|
|
182
191
|
readonly paused: boolean;
|
|
183
192
|
/** 0-100 */
|
|
184
193
|
readonly volume: number;
|
|
185
|
-
/**
|
|
194
|
+
/** Is the session open (false after leaving; voice.join for a new session) */
|
|
186
195
|
readonly connected: boolean;
|
|
187
|
-
/** 48 kHz, stereo, 16
|
|
196
|
+
/** Play a 48 kHz, stereo, 16-bit (little-endian) raw PCM stream; stops what is playing */
|
|
188
197
|
playPcm(stream: AsyncIterable<Uint8Array>): void;
|
|
189
|
-
/** http(s)
|
|
198
|
+
/** Play an http(s) audio address (radio stream, mp3...); the core decodes it with ffmpeg. seek: seconds */
|
|
190
199
|
playUrl(url: string, opts?: {
|
|
191
200
|
seek?: number;
|
|
192
201
|
}): Promise<void>;
|
|
193
202
|
/**
|
|
194
|
-
*
|
|
195
|
-
*
|
|
203
|
+
* Play a song: a YouTube / SoundCloud link, a radio stream or a search text (searched on YouTube, SoundCloud if
|
|
204
|
+
* blocked). The core decodes it with yt-dlp; the info arrives with the "meta" event.
|
|
196
205
|
*/
|
|
197
206
|
playMedia(query: string, opts?: {
|
|
198
207
|
seek?: number;
|
|
199
208
|
}): Promise<void>;
|
|
200
|
-
/**
|
|
209
|
+
/** Decode the next one in advance (faster transition); valid for 30 min */
|
|
201
210
|
prefetch(query: string): void;
|
|
202
211
|
stop(): void;
|
|
203
212
|
pause(): void;
|
|
204
213
|
resume(): void;
|
|
205
214
|
setVolume(v: number): void;
|
|
206
|
-
/**
|
|
215
|
+
/** Leave the channel */
|
|
207
216
|
leave(): Promise<void>;
|
|
208
|
-
/** started:
|
|
217
|
+
/** started: the first audio went out; ended: the stream ended; error: could not play; leave: left the channel (reason) */
|
|
209
218
|
on(ev: "started" | "ended", fn: () => Awaitable<void>): () => void;
|
|
210
219
|
on(ev: "error", fn: (why: string, info: {
|
|
211
220
|
silent: boolean;
|
|
212
221
|
}) => Awaitable<void>): () => void;
|
|
213
222
|
on(ev: "leave", fn: (why: string) => Awaitable<void>): () => void;
|
|
214
|
-
/** playMedia:
|
|
223
|
+
/** playMedia: song info */
|
|
215
224
|
on(ev: "meta", fn: (m: MediaMeta) => Awaitable<void>): () => void;
|
|
216
225
|
}
|
|
217
|
-
/**
|
|
226
|
+
/** Info of the song playing via playMedia (silent errors: YouTube block etc., no need to show them to the user) */
|
|
218
227
|
export interface MediaMeta {
|
|
219
228
|
title: string;
|
|
220
229
|
artist: string;
|
|
@@ -223,21 +232,29 @@ export interface MediaMeta {
|
|
|
223
232
|
src: string;
|
|
224
233
|
url: string;
|
|
225
234
|
}
|
|
226
|
-
/**
|
|
235
|
+
/** An action in the panel window (the page sent { bunker: "action", name, data }) */
|
|
227
236
|
export interface UiAction {
|
|
228
237
|
gid: string;
|
|
229
|
-
/**
|
|
238
|
+
/** the voice channel the person is in if scope is "voice" */
|
|
230
239
|
cid?: string;
|
|
231
240
|
uid: string;
|
|
232
241
|
nick: string;
|
|
233
242
|
name: string;
|
|
234
243
|
data: unknown;
|
|
244
|
+
/** Does the person doing the action have the server settings permission on this server */
|
|
245
|
+
manage: boolean;
|
|
246
|
+
/** The person's panel language (for texts you send only to them with ctx.ui.send) */
|
|
247
|
+
lang: Lang;
|
|
235
248
|
}
|
|
236
249
|
/**
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
* panel ->
|
|
240
|
-
*
|
|
250
|
+
* Talking to the window page (window.postMessage):
|
|
251
|
+
* page -> panel: { bunker: "ready" } | { bunker: "action", name, data } | { bunker: "close" }
|
|
252
|
+
* panel -> page: { bunker: "state", state, ctx: { gid, cid, me: { uid, nick }, manage, age, lang, theme: { dark, bg, text, muted, accent, border, hover } } }
|
|
253
|
+
* | { bunker: "message", data } (only to this person, via ctx.ui.send)
|
|
254
|
+
* age: how many ms ago the state was produced (the same state may be sent again; a page counting time/progress adds it)
|
|
255
|
+
* manage: does the viewer have the server settings permission (display only; the real check is UiAction.manage)
|
|
256
|
+
* lang: the viewer's panel language ("en" | "tr"); the panel doesn't translate pages, so pick your texts by it
|
|
257
|
+
* The page can't make network requests (CSP); everything happens through state + actions.
|
|
241
258
|
*/
|
|
242
259
|
export type UiPageMessage = {
|
|
243
260
|
bunker: "ready";
|
|
@@ -251,27 +268,34 @@ export type UiPageMessage = {
|
|
|
251
268
|
export interface PluginContext {
|
|
252
269
|
readonly manifest: Readonly<PluginManifest>;
|
|
253
270
|
readonly log: PluginLogger;
|
|
254
|
-
/**
|
|
271
|
+
/** Listen to an event (needs the permission). The returned function stops listening; all are released when the plugin stops. */
|
|
255
272
|
on<K extends PluginEventName>(name: K, fn: (payload: PluginEvents[K]) => Awaitable<void>): () => void;
|
|
256
|
-
/** "!
|
|
273
|
+
/** A "!name" command (events.messages permission). The name is lowercased, written without "!". */
|
|
257
274
|
command(name: string, fn: (call: CommandCall) => Awaitable<void>): () => void;
|
|
258
275
|
readonly chat: {
|
|
259
|
-
/**
|
|
276
|
+
/** Message to a text channel under the plugin's name (chat.send). Can't write to a server the plugin isn't added to. */
|
|
260
277
|
send(chan: string, text: string): Promise<{
|
|
261
278
|
id: string;
|
|
262
279
|
} | null>;
|
|
263
280
|
};
|
|
264
281
|
readonly storage: PluginStorage;
|
|
282
|
+
/** A server's language (Server settings -> Language): write messages to that server in it. "en" if the plugin isn't added there. */
|
|
283
|
+
serverLang(gid: string): Promise<Lang>;
|
|
265
284
|
readonly voice: {
|
|
266
|
-
/**
|
|
285
|
+
/** Join a voice channel (voice.speak). The plugin must be added to that channel's server. Returns the same session if already there. */
|
|
267
286
|
join(cid: string): Promise<VoiceSession>;
|
|
268
|
-
/**
|
|
287
|
+
/** Open session (null if none) */
|
|
269
288
|
session(cid: string): VoiceSession | null;
|
|
289
|
+
/** The voice channel the person is in right now (voice.speak or events.voice). null if on a server the plugin isn't added to. */
|
|
290
|
+
channelOf(uid: string): Promise<{
|
|
291
|
+
gid: string;
|
|
292
|
+
cid: string;
|
|
293
|
+
} | null>;
|
|
270
294
|
};
|
|
271
295
|
readonly ui: {
|
|
272
296
|
/**
|
|
273
|
-
*
|
|
274
|
-
* cid
|
|
297
|
+
* The window's state (needs manifest "ui"): JSON, at most 32 KB. Goes live to everyone on the server (for scope "voice"
|
|
298
|
+
* cid is given, that channel's window). live: light up the icon at the bottom left (e.g. while playing). null = clear.
|
|
275
299
|
*/
|
|
276
300
|
setState(where: {
|
|
277
301
|
gid: string;
|
|
@@ -279,13 +303,21 @@ export interface PluginContext {
|
|
|
279
303
|
}, state: unknown, opts?: {
|
|
280
304
|
live?: boolean;
|
|
281
305
|
}): void;
|
|
282
|
-
/**
|
|
306
|
+
/** An action in the window */
|
|
283
307
|
onAction(fn: (a: UiAction) => Awaitable<void>): () => void;
|
|
308
|
+
/**
|
|
309
|
+
* Data to only one person's open window (goes to the page as { bunker: "message", data }): e.g. the reply to an
|
|
310
|
+
* action. JSON, at most 128 KB. Lost if the person doesn't have that window open.
|
|
311
|
+
*/
|
|
312
|
+
send(uid: string, where: {
|
|
313
|
+
gid: string;
|
|
314
|
+
cid?: string;
|
|
315
|
+
}, data: unknown): void;
|
|
284
316
|
};
|
|
285
|
-
/**
|
|
317
|
+
/** Cleanup to run when the plugin stops */
|
|
286
318
|
onUnload(fn: () => Awaitable<void>): void;
|
|
287
319
|
}
|
|
288
320
|
export interface PluginDefinition {
|
|
289
|
-
/**
|
|
321
|
+
/** Called once when the plugin starts. Set up listeners here. */
|
|
290
322
|
setup(ctx: PluginContext): Awaitable<void>;
|
|
291
323
|
}
|
package/dist/types.js
CHANGED
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
/*
|
|
2
|
-
* Bunker plugin API
|
|
2
|
+
* Public types of the Bunker plugin API.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* A plugin never sees the core's internal modules (chat.ts, voice.ts...): only the types here and
|
|
5
|
+
* the PluginContext the runtime provides. Event data is copied from the core; even if the plugin changes it
|
|
6
|
+
* the core is not affected.
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
8
|
+
* Backward compatibility: fields CAN be added, never removed/renamed. A breaking change bumps the major
|
|
9
|
+
* version of SDK_VERSION.
|
|
10
10
|
*/
|
|
11
11
|
export const PERMISSIONS = [
|
|
12
12
|
"events.messages", "events.voice", "events.members", "events.channels", "events.presence", "chat.send", "storage", "voice.speak",
|
|
13
13
|
];
|
|
14
|
-
/**
|
|
14
|
+
/** Description shown to the server owner when adding to a server (approval screen) */
|
|
15
15
|
export const PERMISSION_TEXT = {
|
|
16
|
-
"events.messages": "
|
|
17
|
-
"events.voice": "
|
|
18
|
-
"events.members": "
|
|
19
|
-
"events.channels": "
|
|
20
|
-
"events.presence": "
|
|
21
|
-
"chat.send": "
|
|
22
|
-
"storage": "
|
|
23
|
-
"voice.speak": "
|
|
16
|
+
"events.messages": "Reads messages in text channels and replies to commands",
|
|
17
|
+
"events.voice": "Sees who joins and leaves voice channels",
|
|
18
|
+
"events.members": "Sees members joining and leaving the server",
|
|
19
|
+
"events.channels": "Sees channels being created, changed and deleted",
|
|
20
|
+
"events.presence": "Sees whether members are online",
|
|
21
|
+
"chat.send": "Posts messages in text channels under its own name",
|
|
22
|
+
"storage": "Stores its own data on Bunker",
|
|
23
|
+
"voice.speak": "Joins voice channels and plays audio",
|
|
24
24
|
};
|
|
25
|
-
/**
|
|
25
|
+
/** Event -> required permission (null: no permission needed) */
|
|
26
26
|
export const EVENT_PERMISSION = {
|
|
27
27
|
"user.online": "events.presence",
|
|
28
28
|
"user.offline": "events.presence",
|
package/dist/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
/** SDK
|
|
2
|
-
export declare const SDK_VERSION = "0.1.
|
|
1
|
+
/** SDK version: the "sdk" field in the manifest is compared with this */
|
|
2
|
+
export declare const SDK_VERSION = "0.1.7";
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
/** SDK
|
|
2
|
-
export const SDK_VERSION = "0.1.
|
|
1
|
+
/** SDK version: the "sdk" field in the manifest is compared with this */
|
|
2
|
+
export const SDK_VERSION = "0.1.7";
|