@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 +589 -0
- package/LICENSE +21 -0
- package/README.md +39 -2
- package/dist/index.d.ts +7 -0
- package/dist/index.js +8 -0
- package/dist/manifest.d.ts +14 -0
- package/dist/manifest.js +85 -0
- package/dist/remote.d.ts +50 -0
- package/dist/remote.js +291 -0
- package/dist/types.d.ts +323 -0
- package/dist/types.js +45 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/package.json +46 -4
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/** Permissions a plugin can ask for. A call that needs a permission missing from the manifest throws. */
|
|
2
|
+
export type Permission =
|
|
3
|
+
/** message.* events + ctx.command */
|
|
4
|
+
"events.messages"
|
|
5
|
+
/** voice.* events */
|
|
6
|
+
| "events.voice"
|
|
7
|
+
/** member.*, guild.* events */
|
|
8
|
+
| "events.members"
|
|
9
|
+
/** channel.* events */
|
|
10
|
+
| "events.channels"
|
|
11
|
+
/** user.online / user.offline */
|
|
12
|
+
| "events.presence"
|
|
13
|
+
/** Writing to text channels under the plugin's own name */
|
|
14
|
+
| "chat.send"
|
|
15
|
+
/** Key-value store private to the plugin */
|
|
16
|
+
| "storage"
|
|
17
|
+
/** Joining voice channels and playing audio (ctx.voice) */
|
|
18
|
+
| "voice.speak";
|
|
19
|
+
export declare const PERMISSIONS: readonly Permission[];
|
|
20
|
+
/** Description shown to the server owner when adding to a server (approval screen) */
|
|
21
|
+
export declare const PERMISSION_TEXT: Record<Permission, string>;
|
|
22
|
+
/** The window the plugin shows in the panel (manifest "ui"). The page opens in an isolated frame (iframe, sandbox). */
|
|
23
|
+
export interface PluginUi {
|
|
24
|
+
/** Window title */
|
|
25
|
+
title: string;
|
|
26
|
+
/** Icon at the bottom left: one of the panel's icon names (e.g. "music", "radio", "tv"); "plug" otherwise */
|
|
27
|
+
icon?: string;
|
|
28
|
+
/** Window page (relative to the plugin folder), e.g. "ui/index.html". A single file is recommended (inline script/style). */
|
|
29
|
+
page: string;
|
|
30
|
+
/** "voice": only visible while in a voice channel of that server (state per channel); "guild": always on the server */
|
|
31
|
+
scope: "voice" | "guild";
|
|
32
|
+
}
|
|
33
|
+
/** bunker-plugin.json */
|
|
34
|
+
export interface PluginManifest {
|
|
35
|
+
/** Lowercase letters, digits, dashes: 2-28 characters. The plugin's permanent identity (storage, settings, bot identity depend on it). */
|
|
36
|
+
id: string;
|
|
37
|
+
/** Display name (also used as the bot name in messages) */
|
|
38
|
+
name: string;
|
|
39
|
+
/** Plugin version (x.y.z) */
|
|
40
|
+
version: string;
|
|
41
|
+
/** Short description (at most 300 characters), shown on Store cards. */
|
|
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;
|
|
45
|
+
author?: string;
|
|
46
|
+
/** Server-side entry file (relative to the plugin folder), default "src/index.ts" */
|
|
47
|
+
main?: string;
|
|
48
|
+
/** Compatible SDK major version, e.g. "0" or "0.1" */
|
|
49
|
+
sdk: string;
|
|
50
|
+
permissions: Permission[];
|
|
51
|
+
/** Panel window (optional) */
|
|
52
|
+
ui?: PluginUi;
|
|
53
|
+
}
|
|
54
|
+
/** The message as exposed to the plugin */
|
|
55
|
+
export interface PluginMessage {
|
|
56
|
+
id: string;
|
|
57
|
+
ts: number;
|
|
58
|
+
uid: string;
|
|
59
|
+
nick: string;
|
|
60
|
+
text: string;
|
|
61
|
+
/** System line (like "... pinned") */
|
|
62
|
+
system: boolean;
|
|
63
|
+
/** Written by a bot or plugin */
|
|
64
|
+
bot: boolean;
|
|
65
|
+
/** Number of attachments (image/video) */
|
|
66
|
+
attachments: number;
|
|
67
|
+
replyTo?: string;
|
|
68
|
+
edited?: number;
|
|
69
|
+
}
|
|
70
|
+
/** Text channel or direct message. Direct message events are currently NOT sent to plugins (privacy). */
|
|
71
|
+
export type MessageWhere = {
|
|
72
|
+
scope: "text";
|
|
73
|
+
gid: string;
|
|
74
|
+
chan: string;
|
|
75
|
+
};
|
|
76
|
+
export type VoiceWhere = {
|
|
77
|
+
gid: string;
|
|
78
|
+
cid: string;
|
|
79
|
+
uid: string;
|
|
80
|
+
bot: boolean;
|
|
81
|
+
};
|
|
82
|
+
export interface PluginEvents {
|
|
83
|
+
"user.online": {
|
|
84
|
+
uid: string;
|
|
85
|
+
};
|
|
86
|
+
"user.offline": {
|
|
87
|
+
uid: string;
|
|
88
|
+
};
|
|
89
|
+
"guild.create": {
|
|
90
|
+
gid: string;
|
|
91
|
+
owner: string;
|
|
92
|
+
};
|
|
93
|
+
"guild.delete": {
|
|
94
|
+
gid: string;
|
|
95
|
+
};
|
|
96
|
+
"member.join": {
|
|
97
|
+
gid: string;
|
|
98
|
+
uid: string;
|
|
99
|
+
};
|
|
100
|
+
"member.leave": {
|
|
101
|
+
gid: string;
|
|
102
|
+
uid: string;
|
|
103
|
+
};
|
|
104
|
+
"channel.create": {
|
|
105
|
+
gid: string;
|
|
106
|
+
kind: "text" | "voice";
|
|
107
|
+
id: string;
|
|
108
|
+
};
|
|
109
|
+
"channel.update": {
|
|
110
|
+
gid: string;
|
|
111
|
+
kind: "text" | "voice";
|
|
112
|
+
id: string;
|
|
113
|
+
};
|
|
114
|
+
"channel.delete": {
|
|
115
|
+
gid: string;
|
|
116
|
+
kind: "text" | "voice";
|
|
117
|
+
id: string;
|
|
118
|
+
};
|
|
119
|
+
"message.create": MessageWhere & {
|
|
120
|
+
m: PluginMessage;
|
|
121
|
+
};
|
|
122
|
+
"message.edit": MessageWhere & {
|
|
123
|
+
m: PluginMessage;
|
|
124
|
+
};
|
|
125
|
+
"message.delete": MessageWhere & {
|
|
126
|
+
id: string;
|
|
127
|
+
by: string;
|
|
128
|
+
};
|
|
129
|
+
"message.react": MessageWhere & {
|
|
130
|
+
id: string;
|
|
131
|
+
uid: string;
|
|
132
|
+
emoji: string;
|
|
133
|
+
added: boolean;
|
|
134
|
+
};
|
|
135
|
+
"voice.join": VoiceWhere;
|
|
136
|
+
"voice.move": VoiceWhere & {
|
|
137
|
+
from: string;
|
|
138
|
+
};
|
|
139
|
+
"voice.leave": VoiceWhere;
|
|
140
|
+
/** The plugin was added to this server (no permission needed) */
|
|
141
|
+
"guild.install": {
|
|
142
|
+
gid: string;
|
|
143
|
+
by: string;
|
|
144
|
+
};
|
|
145
|
+
/** The plugin was removed from this server or the server was deleted (no permission needed); clean up your data for the server here */
|
|
146
|
+
"guild.uninstall": {
|
|
147
|
+
gid: string;
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
export type PluginEventName = keyof PluginEvents;
|
|
151
|
+
/** Event -> required permission (null: no permission needed) */
|
|
152
|
+
export declare const EVENT_PERMISSION: Record<PluginEventName, Permission | null>;
|
|
153
|
+
export type Awaitable<T> = T | Promise<T>;
|
|
154
|
+
/** Languages Bunker supports */
|
|
155
|
+
export type Lang = "en" | "tr";
|
|
156
|
+
/** A "!command args..." call (text channels only, when a human writes) */
|
|
157
|
+
export interface CommandCall {
|
|
158
|
+
gid: string;
|
|
159
|
+
chan: string;
|
|
160
|
+
/** The writer */
|
|
161
|
+
uid: string;
|
|
162
|
+
nick: string;
|
|
163
|
+
/** The text after the command (spaces trimmed) */
|
|
164
|
+
args: string;
|
|
165
|
+
m: PluginMessage;
|
|
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) */
|
|
171
|
+
reply(text: string): Promise<void>;
|
|
172
|
+
}
|
|
173
|
+
export interface PluginLogger {
|
|
174
|
+
info(msg: string, ctx?: Record<string, unknown>): void;
|
|
175
|
+
warn(msg: string, ctx?: Record<string, unknown>): void;
|
|
176
|
+
error(msg: string, ctx?: Record<string, unknown>): void;
|
|
177
|
+
}
|
|
178
|
+
/** Persistent store private to the plugin (JSON values, at most 64 KB; at most 10,000 keys per plugin) */
|
|
179
|
+
export interface PluginStorage {
|
|
180
|
+
get<T = unknown>(key: string): Promise<T | undefined>;
|
|
181
|
+
set(key: string, value: unknown): Promise<void>;
|
|
182
|
+
delete(key: string): Promise<void>;
|
|
183
|
+
keys(prefix?: string): Promise<string[]>;
|
|
184
|
+
}
|
|
185
|
+
/** The plugin's session in a voice channel. Leaves on its own 60 s after no humans are left in the channel. */
|
|
186
|
+
export interface VoiceSession {
|
|
187
|
+
readonly gid: string;
|
|
188
|
+
readonly cid: string;
|
|
189
|
+
/** Is audio flowing right now (true even if paused) */
|
|
190
|
+
readonly playing: boolean;
|
|
191
|
+
readonly paused: boolean;
|
|
192
|
+
/** 0-100 */
|
|
193
|
+
readonly volume: number;
|
|
194
|
+
/** Is the session open (false after leaving; voice.join for a new session) */
|
|
195
|
+
readonly connected: boolean;
|
|
196
|
+
/** Play a 48 kHz, stereo, 16-bit (little-endian) raw PCM stream; stops what is playing */
|
|
197
|
+
playPcm(stream: AsyncIterable<Uint8Array>): void;
|
|
198
|
+
/** Play an http(s) audio address (radio stream, mp3...); the core decodes it with ffmpeg. seek: seconds */
|
|
199
|
+
playUrl(url: string, opts?: {
|
|
200
|
+
seek?: number;
|
|
201
|
+
}): Promise<void>;
|
|
202
|
+
/**
|
|
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.
|
|
205
|
+
*/
|
|
206
|
+
playMedia(query: string, opts?: {
|
|
207
|
+
seek?: number;
|
|
208
|
+
}): Promise<void>;
|
|
209
|
+
/** Decode the next one in advance (faster transition); valid for 30 min */
|
|
210
|
+
prefetch(query: string): void;
|
|
211
|
+
stop(): void;
|
|
212
|
+
pause(): void;
|
|
213
|
+
resume(): void;
|
|
214
|
+
setVolume(v: number): void;
|
|
215
|
+
/** Leave the channel */
|
|
216
|
+
leave(): Promise<void>;
|
|
217
|
+
/** started: the first audio went out; ended: the stream ended; error: could not play; leave: left the channel (reason) */
|
|
218
|
+
on(ev: "started" | "ended", fn: () => Awaitable<void>): () => void;
|
|
219
|
+
on(ev: "error", fn: (why: string, info: {
|
|
220
|
+
silent: boolean;
|
|
221
|
+
}) => Awaitable<void>): () => void;
|
|
222
|
+
on(ev: "leave", fn: (why: string) => Awaitable<void>): () => void;
|
|
223
|
+
/** playMedia: song info */
|
|
224
|
+
on(ev: "meta", fn: (m: MediaMeta) => Awaitable<void>): () => void;
|
|
225
|
+
}
|
|
226
|
+
/** Info of the song playing via playMedia (silent errors: YouTube block etc., no need to show them to the user) */
|
|
227
|
+
export interface MediaMeta {
|
|
228
|
+
title: string;
|
|
229
|
+
artist: string;
|
|
230
|
+
duration: number;
|
|
231
|
+
thumb: string;
|
|
232
|
+
src: string;
|
|
233
|
+
url: string;
|
|
234
|
+
}
|
|
235
|
+
/** An action in the panel window (the page sent { bunker: "action", name, data }) */
|
|
236
|
+
export interface UiAction {
|
|
237
|
+
gid: string;
|
|
238
|
+
/** the voice channel the person is in if scope is "voice" */
|
|
239
|
+
cid?: string;
|
|
240
|
+
uid: string;
|
|
241
|
+
nick: string;
|
|
242
|
+
name: string;
|
|
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;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
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.
|
|
258
|
+
*/
|
|
259
|
+
export type UiPageMessage = {
|
|
260
|
+
bunker: "ready";
|
|
261
|
+
} | {
|
|
262
|
+
bunker: "action";
|
|
263
|
+
name: string;
|
|
264
|
+
data?: unknown;
|
|
265
|
+
} | {
|
|
266
|
+
bunker: "close";
|
|
267
|
+
};
|
|
268
|
+
export interface PluginContext {
|
|
269
|
+
readonly manifest: Readonly<PluginManifest>;
|
|
270
|
+
readonly log: PluginLogger;
|
|
271
|
+
/** Listen to an event (needs the permission). The returned function stops listening; all are released when the plugin stops. */
|
|
272
|
+
on<K extends PluginEventName>(name: K, fn: (payload: PluginEvents[K]) => Awaitable<void>): () => void;
|
|
273
|
+
/** A "!name" command (events.messages permission). The name is lowercased, written without "!". */
|
|
274
|
+
command(name: string, fn: (call: CommandCall) => Awaitable<void>): () => void;
|
|
275
|
+
readonly chat: {
|
|
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. */
|
|
277
|
+
send(chan: string, text: string): Promise<{
|
|
278
|
+
id: string;
|
|
279
|
+
} | null>;
|
|
280
|
+
};
|
|
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>;
|
|
284
|
+
readonly voice: {
|
|
285
|
+
/** Join a voice channel (voice.speak). The plugin must be added to that channel's server. Returns the same session if already there. */
|
|
286
|
+
join(cid: string): Promise<VoiceSession>;
|
|
287
|
+
/** Open session (null if none) */
|
|
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>;
|
|
294
|
+
};
|
|
295
|
+
readonly ui: {
|
|
296
|
+
/**
|
|
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.
|
|
299
|
+
*/
|
|
300
|
+
setState(where: {
|
|
301
|
+
gid: string;
|
|
302
|
+
cid?: string;
|
|
303
|
+
}, state: unknown, opts?: {
|
|
304
|
+
live?: boolean;
|
|
305
|
+
}): void;
|
|
306
|
+
/** An action in the window */
|
|
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;
|
|
316
|
+
};
|
|
317
|
+
/** Cleanup to run when the plugin stops */
|
|
318
|
+
onUnload(fn: () => Awaitable<void>): void;
|
|
319
|
+
}
|
|
320
|
+
export interface PluginDefinition {
|
|
321
|
+
/** Called once when the plugin starts. Set up listeners here. */
|
|
322
|
+
setup(ctx: PluginContext): Awaitable<void>;
|
|
323
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Public types of the Bunker plugin API.
|
|
3
|
+
*
|
|
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
|
+
*
|
|
8
|
+
* Backward compatibility: fields CAN be added, never removed/renamed. A breaking change bumps the major
|
|
9
|
+
* version of SDK_VERSION.
|
|
10
|
+
*/
|
|
11
|
+
export const PERMISSIONS = [
|
|
12
|
+
"events.messages", "events.voice", "events.members", "events.channels", "events.presence", "chat.send", "storage", "voice.speak",
|
|
13
|
+
];
|
|
14
|
+
/** Description shown to the server owner when adding to a server (approval screen) */
|
|
15
|
+
export const PERMISSION_TEXT = {
|
|
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
|
+
};
|
|
25
|
+
/** Event -> required permission (null: no permission needed) */
|
|
26
|
+
export const EVENT_PERMISSION = {
|
|
27
|
+
"user.online": "events.presence",
|
|
28
|
+
"user.offline": "events.presence",
|
|
29
|
+
"guild.create": "events.members",
|
|
30
|
+
"guild.delete": "events.members",
|
|
31
|
+
"member.join": "events.members",
|
|
32
|
+
"member.leave": "events.members",
|
|
33
|
+
"channel.create": "events.channels",
|
|
34
|
+
"channel.update": "events.channels",
|
|
35
|
+
"channel.delete": "events.channels",
|
|
36
|
+
"message.create": "events.messages",
|
|
37
|
+
"message.edit": "events.messages",
|
|
38
|
+
"message.delete": "events.messages",
|
|
39
|
+
"message.react": "events.messages",
|
|
40
|
+
"voice.join": "events.voice",
|
|
41
|
+
"voice.move": "events.voice",
|
|
42
|
+
"voice.leave": "events.voice",
|
|
43
|
+
"guild.install": null,
|
|
44
|
+
"guild.uninstall": null,
|
|
45
|
+
};
|
package/dist/version.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bunker-community/plugin-sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.7",
|
|
4
|
+
"description": "SDK for Bunker plugins and bots: types, manifest validation and the remote plugin client (connect).",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"bunker",
|
|
7
|
+
"bot",
|
|
8
|
+
"plugin",
|
|
9
|
+
"sdk",
|
|
10
|
+
"voice",
|
|
11
|
+
"chat"
|
|
12
|
+
],
|
|
13
|
+
"homepage": "https://bunker.community/app/sdk/",
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/bunker-community/plugin-sdk.git"
|
|
17
|
+
},
|
|
18
|
+
"bugs": {
|
|
19
|
+
"url": "https://github.com/bunker-community/plugin-sdk/issues"
|
|
20
|
+
},
|
|
21
|
+
"license": "MIT",
|
|
22
|
+
"author": "Bunker",
|
|
23
|
+
"type": "module",
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=22"
|
|
26
|
+
},
|
|
27
|
+
"exports": {
|
|
28
|
+
".": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"default": "./dist/index.js"
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"types": "./dist/index.d.ts",
|
|
34
|
+
"files": [
|
|
35
|
+
"dist",
|
|
36
|
+
"API_DOC.md",
|
|
37
|
+
"README.md",
|
|
38
|
+
"LICENSE"
|
|
39
|
+
],
|
|
40
|
+
"scripts": {
|
|
41
|
+
"build": "tsc -p tsconfig.json",
|
|
42
|
+
"prepublishOnly": "npm run build"
|
|
43
|
+
},
|
|
44
|
+
"devDependencies": {
|
|
45
|
+
"@types/node": "^22.10.0",
|
|
46
|
+
"typescript": "^5.7.0"
|
|
47
|
+
}
|
|
48
|
+
}
|