@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 +568 -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 +84 -0
- package/dist/remote.d.ts +50 -0
- package/dist/remote.js +288 -0
- package/dist/types.d.ts +291 -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,291 @@
|
|
|
1
|
+
/** Plugin'in isteyebilecegi izinler. Manifest'te yazilmayan izin gerektiren cagri hata verir. */
|
|
2
|
+
export type Permission =
|
|
3
|
+
/** message.* olaylari + ctx.command */
|
|
4
|
+
"events.messages"
|
|
5
|
+
/** voice.* olaylari */
|
|
6
|
+
| "events.voice"
|
|
7
|
+
/** member.*, guild.* olaylari */
|
|
8
|
+
| "events.members"
|
|
9
|
+
/** channel.* olaylari */
|
|
10
|
+
| "events.channels"
|
|
11
|
+
/** user.online / user.offline */
|
|
12
|
+
| "events.presence"
|
|
13
|
+
/** Metin kanalina plugin'in kendi adiyla mesaj yazma */
|
|
14
|
+
| "chat.send"
|
|
15
|
+
/** Plugin'e ozel anahtar-deger deposu */
|
|
16
|
+
| "storage"
|
|
17
|
+
/** Ses kanalina katilip ses calma (ctx.voice) */
|
|
18
|
+
| "voice.speak";
|
|
19
|
+
export declare const PERMISSIONS: readonly Permission[];
|
|
20
|
+
/** Sunucuya eklerken sunucu sahibine gosterilen aciklama (onay ekrani) */
|
|
21
|
+
export declare const PERMISSION_TEXT: Record<Permission, string>;
|
|
22
|
+
/** Plugin'in panelde gosterdigi pencere (manifest "ui"). Sayfa izole bir cercevede (iframe, sandbox) acilir. */
|
|
23
|
+
export interface PluginUi {
|
|
24
|
+
/** Pencere basligi */
|
|
25
|
+
title: string;
|
|
26
|
+
/** Sol alttaki ikon: panelin ikon adlarindan biri (or. "music", "radio", "tv"); yoksa "plug" */
|
|
27
|
+
icon?: string;
|
|
28
|
+
/** Pencere sayfasi (plugin klasorune gore), or. "ui/index.html". Tek dosya olmasi onerilir (satir ici script/stil). */
|
|
29
|
+
page: string;
|
|
30
|
+
/** "voice": sadece o sunucunun bir ses kanalindayken gorunur (durum kanal basina); "guild": sunucuda her zaman */
|
|
31
|
+
scope: "voice" | "guild";
|
|
32
|
+
}
|
|
33
|
+
/** bunker-plugin.json */
|
|
34
|
+
export interface PluginManifest {
|
|
35
|
+
/** Kucuk harf, rakam, tire: 2-28 karakter. Plugin'in kalici kimligi (depo, ayarlar, bot kimligi buna bagli). */
|
|
36
|
+
id: string;
|
|
37
|
+
/** Gorunen ad (mesajlarda bot adi olarak da kullanilir) */
|
|
38
|
+
name: string;
|
|
39
|
+
/** Plugin surumu (x.y.z) */
|
|
40
|
+
version: string;
|
|
41
|
+
description?: string;
|
|
42
|
+
author?: string;
|
|
43
|
+
/** Sunucu tarafi giris dosyasi (plugin klasorune gore), varsayilan "src/index.ts" */
|
|
44
|
+
main?: string;
|
|
45
|
+
/** Uyumlu SDK ana surumu, or. "0" ya da "0.1" */
|
|
46
|
+
sdk: string;
|
|
47
|
+
permissions: Permission[];
|
|
48
|
+
/** Panel penceresi (istege bagli) */
|
|
49
|
+
ui?: PluginUi;
|
|
50
|
+
}
|
|
51
|
+
/** Mesajin plugin'e acilan hali */
|
|
52
|
+
export interface PluginMessage {
|
|
53
|
+
id: string;
|
|
54
|
+
ts: number;
|
|
55
|
+
uid: string;
|
|
56
|
+
nick: string;
|
|
57
|
+
text: string;
|
|
58
|
+
/** Sistem satiri ("... sabitledi" gibi) */
|
|
59
|
+
system: boolean;
|
|
60
|
+
/** Bot ya da plugin yazdi */
|
|
61
|
+
bot: boolean;
|
|
62
|
+
/** Ek sayisi (gorsel/video) */
|
|
63
|
+
attachments: number;
|
|
64
|
+
replyTo?: string;
|
|
65
|
+
edited?: number;
|
|
66
|
+
}
|
|
67
|
+
/** Metin kanali ya da ozel mesaj. Ozel mesaj olaylari plugin'lere su an GONDERILMEZ (gizlilik). */
|
|
68
|
+
export type MessageWhere = {
|
|
69
|
+
scope: "text";
|
|
70
|
+
gid: string;
|
|
71
|
+
chan: string;
|
|
72
|
+
};
|
|
73
|
+
export type VoiceWhere = {
|
|
74
|
+
gid: string;
|
|
75
|
+
cid: string;
|
|
76
|
+
uid: string;
|
|
77
|
+
bot: boolean;
|
|
78
|
+
};
|
|
79
|
+
export interface PluginEvents {
|
|
80
|
+
"user.online": {
|
|
81
|
+
uid: string;
|
|
82
|
+
};
|
|
83
|
+
"user.offline": {
|
|
84
|
+
uid: string;
|
|
85
|
+
};
|
|
86
|
+
"guild.create": {
|
|
87
|
+
gid: string;
|
|
88
|
+
owner: string;
|
|
89
|
+
};
|
|
90
|
+
"guild.delete": {
|
|
91
|
+
gid: string;
|
|
92
|
+
};
|
|
93
|
+
"member.join": {
|
|
94
|
+
gid: string;
|
|
95
|
+
uid: string;
|
|
96
|
+
};
|
|
97
|
+
"member.leave": {
|
|
98
|
+
gid: string;
|
|
99
|
+
uid: string;
|
|
100
|
+
};
|
|
101
|
+
"channel.create": {
|
|
102
|
+
gid: string;
|
|
103
|
+
kind: "text" | "voice";
|
|
104
|
+
id: string;
|
|
105
|
+
};
|
|
106
|
+
"channel.update": {
|
|
107
|
+
gid: string;
|
|
108
|
+
kind: "text" | "voice";
|
|
109
|
+
id: string;
|
|
110
|
+
};
|
|
111
|
+
"channel.delete": {
|
|
112
|
+
gid: string;
|
|
113
|
+
kind: "text" | "voice";
|
|
114
|
+
id: string;
|
|
115
|
+
};
|
|
116
|
+
"message.create": MessageWhere & {
|
|
117
|
+
m: PluginMessage;
|
|
118
|
+
};
|
|
119
|
+
"message.edit": MessageWhere & {
|
|
120
|
+
m: PluginMessage;
|
|
121
|
+
};
|
|
122
|
+
"message.delete": MessageWhere & {
|
|
123
|
+
id: string;
|
|
124
|
+
by: string;
|
|
125
|
+
};
|
|
126
|
+
"message.react": MessageWhere & {
|
|
127
|
+
id: string;
|
|
128
|
+
uid: string;
|
|
129
|
+
emoji: string;
|
|
130
|
+
added: boolean;
|
|
131
|
+
};
|
|
132
|
+
"voice.join": VoiceWhere;
|
|
133
|
+
"voice.move": VoiceWhere & {
|
|
134
|
+
from: string;
|
|
135
|
+
};
|
|
136
|
+
"voice.leave": VoiceWhere;
|
|
137
|
+
/** Plugin bu sunucuya eklendi (izin gerekmez) */
|
|
138
|
+
"guild.install": {
|
|
139
|
+
gid: string;
|
|
140
|
+
by: string;
|
|
141
|
+
};
|
|
142
|
+
/** Plugin bu sunucudan cikarildi ya da sunucu silindi (izin gerekmez); sunucuya ait verini burada temizle */
|
|
143
|
+
"guild.uninstall": {
|
|
144
|
+
gid: string;
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
export type PluginEventName = keyof PluginEvents;
|
|
148
|
+
/** Olay -> gereken izin (null: izin gerekmez) */
|
|
149
|
+
export declare const EVENT_PERMISSION: Record<PluginEventName, Permission | null>;
|
|
150
|
+
export type Awaitable<T> = T | Promise<T>;
|
|
151
|
+
/** "!komut arguman..." cagrisi (sadece metin kanallarinda, insan yazdiginda) */
|
|
152
|
+
export interface CommandCall {
|
|
153
|
+
gid: string;
|
|
154
|
+
chan: string;
|
|
155
|
+
/** Yazan */
|
|
156
|
+
uid: string;
|
|
157
|
+
nick: string;
|
|
158
|
+
/** Komuttan sonraki metin (bosluklar kirpilmis) */
|
|
159
|
+
args: string;
|
|
160
|
+
m: PluginMessage;
|
|
161
|
+
/** Ayni kanala plugin adiyla cevap (chat.send izni gerekir) */
|
|
162
|
+
reply(text: string): Promise<void>;
|
|
163
|
+
}
|
|
164
|
+
export interface PluginLogger {
|
|
165
|
+
info(msg: string, ctx?: Record<string, unknown>): void;
|
|
166
|
+
warn(msg: string, ctx?: Record<string, unknown>): void;
|
|
167
|
+
error(msg: string, ctx?: Record<string, unknown>): void;
|
|
168
|
+
}
|
|
169
|
+
/** Plugin'e ozel kalici depo (deger JSON, en fazla 64 KB; plugin basina en fazla 10 000 anahtar) */
|
|
170
|
+
export interface PluginStorage {
|
|
171
|
+
get<T = unknown>(key: string): Promise<T | undefined>;
|
|
172
|
+
set(key: string, value: unknown): Promise<void>;
|
|
173
|
+
delete(key: string): Promise<void>;
|
|
174
|
+
keys(prefix?: string): Promise<string[]>;
|
|
175
|
+
}
|
|
176
|
+
/** Plugin'in bir ses kanalindaki oturumu. Kanalda insan kalmazsa 60 sn sonra kendiliginden ayrilir. */
|
|
177
|
+
export interface VoiceSession {
|
|
178
|
+
readonly gid: string;
|
|
179
|
+
readonly cid: string;
|
|
180
|
+
/** Su an ses akiyor mu (duraklatilmis olsa da true) */
|
|
181
|
+
readonly playing: boolean;
|
|
182
|
+
readonly paused: boolean;
|
|
183
|
+
/** 0-100 */
|
|
184
|
+
readonly volume: number;
|
|
185
|
+
/** Oturum acik mi (ayrildiysa false; yeni oturum icin voice.join) */
|
|
186
|
+
readonly connected: boolean;
|
|
187
|
+
/** 48 kHz, stereo, 16 bit (little-endian) ham PCM akisini cal; caldigini durdurur */
|
|
188
|
+
playPcm(stream: AsyncIterable<Uint8Array>): void;
|
|
189
|
+
/** http(s) ses adresini cal (radyo yayini, mp3...); cekirdek ffmpeg ile cozer. seek: saniye */
|
|
190
|
+
playUrl(url: string, opts?: {
|
|
191
|
+
seek?: number;
|
|
192
|
+
}): Promise<void>;
|
|
193
|
+
/**
|
|
194
|
+
* Sarki cal: YouTube / SoundCloud baglantisi, radyo yayini ya da arama metni (YouTube'da aranir, engellenirse
|
|
195
|
+
* SoundCloud). Cekirdek yt-dlp ile cozer; bilgi "meta" olayiyla gelir.
|
|
196
|
+
*/
|
|
197
|
+
playMedia(query: string, opts?: {
|
|
198
|
+
seek?: number;
|
|
199
|
+
}): Promise<void>;
|
|
200
|
+
/** Siradakini onceden coz (gecis hizlansin); 30 dk gecerli */
|
|
201
|
+
prefetch(query: string): void;
|
|
202
|
+
stop(): void;
|
|
203
|
+
pause(): void;
|
|
204
|
+
resume(): void;
|
|
205
|
+
setVolume(v: number): void;
|
|
206
|
+
/** Kanaldan ayril */
|
|
207
|
+
leave(): Promise<void>;
|
|
208
|
+
/** started: ilk ses gitti; ended: akis bitti; error: calinamadi; leave: kanaldan ayrildi (neden) */
|
|
209
|
+
on(ev: "started" | "ended", fn: () => Awaitable<void>): () => void;
|
|
210
|
+
on(ev: "error", fn: (why: string, info: {
|
|
211
|
+
silent: boolean;
|
|
212
|
+
}) => Awaitable<void>): () => void;
|
|
213
|
+
on(ev: "leave", fn: (why: string) => Awaitable<void>): () => void;
|
|
214
|
+
/** playMedia: sarki bilgisi */
|
|
215
|
+
on(ev: "meta", fn: (m: MediaMeta) => Awaitable<void>): () => void;
|
|
216
|
+
}
|
|
217
|
+
/** playMedia ile calan sarkinin bilgisi (silent hatalar: YouTube engeli vb., kullaniciya gostermek sart degil) */
|
|
218
|
+
export interface MediaMeta {
|
|
219
|
+
title: string;
|
|
220
|
+
artist: string;
|
|
221
|
+
duration: number;
|
|
222
|
+
thumb: string;
|
|
223
|
+
src: string;
|
|
224
|
+
url: string;
|
|
225
|
+
}
|
|
226
|
+
/** Panel penceresinde yapilan islem (sayfa { bunker: "action", name, data } gonderdi) */
|
|
227
|
+
export interface UiAction {
|
|
228
|
+
gid: string;
|
|
229
|
+
/** scope "voice" ise kisinin bulundugu ses kanali */
|
|
230
|
+
cid?: string;
|
|
231
|
+
uid: string;
|
|
232
|
+
nick: string;
|
|
233
|
+
name: string;
|
|
234
|
+
data: unknown;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Pencere sayfasiyla konusma (window.postMessage):
|
|
238
|
+
* sayfa -> panel: { bunker: "ready" } | { bunker: "action", name, data } | { bunker: "close" }
|
|
239
|
+
* panel -> sayfa: { bunker: "state", state, ctx: { gid, cid, me: { uid, nick }, theme: { dark, bg, text, muted, accent, border, hover } } }
|
|
240
|
+
* Sayfa ag istegi yapamaz (CSP); her sey durum + islemlerle olur.
|
|
241
|
+
*/
|
|
242
|
+
export type UiPageMessage = {
|
|
243
|
+
bunker: "ready";
|
|
244
|
+
} | {
|
|
245
|
+
bunker: "action";
|
|
246
|
+
name: string;
|
|
247
|
+
data?: unknown;
|
|
248
|
+
} | {
|
|
249
|
+
bunker: "close";
|
|
250
|
+
};
|
|
251
|
+
export interface PluginContext {
|
|
252
|
+
readonly manifest: Readonly<PluginManifest>;
|
|
253
|
+
readonly log: PluginLogger;
|
|
254
|
+
/** Olay dinle (izin gerekir). Donen fonksiyon dinlemeyi birakir; plugin kapaninca hepsi kendiliginden birakilir. */
|
|
255
|
+
on<K extends PluginEventName>(name: K, fn: (payload: PluginEvents[K]) => Awaitable<void>): () => void;
|
|
256
|
+
/** "!ad" komutu (events.messages izni). Ad kucuk harfe cevrilir, "!" yazilmaz. */
|
|
257
|
+
command(name: string, fn: (call: CommandCall) => Awaitable<void>): () => void;
|
|
258
|
+
readonly chat: {
|
|
259
|
+
/** Metin kanalina plugin adiyla mesaj (chat.send). Plugin'in ekli olmadigi sunucuya yazamaz. */
|
|
260
|
+
send(chan: string, text: string): Promise<{
|
|
261
|
+
id: string;
|
|
262
|
+
} | null>;
|
|
263
|
+
};
|
|
264
|
+
readonly storage: PluginStorage;
|
|
265
|
+
readonly voice: {
|
|
266
|
+
/** Ses kanalina katil (voice.speak). Plugin bu kanalin sunucusuna ekli olmali. Zaten oradaysa ayni oturum doner. */
|
|
267
|
+
join(cid: string): Promise<VoiceSession>;
|
|
268
|
+
/** Acik oturum (yoksa null) */
|
|
269
|
+
session(cid: string): VoiceSession | null;
|
|
270
|
+
};
|
|
271
|
+
readonly ui: {
|
|
272
|
+
/**
|
|
273
|
+
* Pencerenin durumu (manifest "ui" gerekir): JSON, en fazla 32 KB. Sunucudaki herkese (scope "voice" ise
|
|
274
|
+
* cid verilir, o kanalin penceresi) anlik gider. live: sol alttaki ikon yansin (or. calarken). null = temizle.
|
|
275
|
+
*/
|
|
276
|
+
setState(where: {
|
|
277
|
+
gid: string;
|
|
278
|
+
cid?: string;
|
|
279
|
+
}, state: unknown, opts?: {
|
|
280
|
+
live?: boolean;
|
|
281
|
+
}): void;
|
|
282
|
+
/** Pencerede yapilan islem */
|
|
283
|
+
onAction(fn: (a: UiAction) => Awaitable<void>): () => void;
|
|
284
|
+
};
|
|
285
|
+
/** Plugin kapanirken calisacak temizlik */
|
|
286
|
+
onUnload(fn: () => Awaitable<void>): void;
|
|
287
|
+
}
|
|
288
|
+
export interface PluginDefinition {
|
|
289
|
+
/** Plugin acilinca bir kez cagrilir. Dinleyicileri burada kur. */
|
|
290
|
+
setup(ctx: PluginContext): Awaitable<void>;
|
|
291
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Bunker plugin API'sinin genel tipleri.
|
|
3
|
+
*
|
|
4
|
+
* Plugin cekirdegin ic modullerini (chat.ts, voice.ts...) hic gormez: sadece buradaki tipler ve
|
|
5
|
+
* calisma ortaminin verdigi PluginContext. Olay verileri cekirdekten kopyalanir; plugin degistirse de
|
|
6
|
+
* cekirdek etkilenmez.
|
|
7
|
+
*
|
|
8
|
+
* Geriye uyumluluk: alan EKLENEBILIR, silinmez/yeniden adlandirilmaz. Kiran degisiklik SDK_VERSION'in
|
|
9
|
+
* ana (major) surumunu artirir.
|
|
10
|
+
*/
|
|
11
|
+
export const PERMISSIONS = [
|
|
12
|
+
"events.messages", "events.voice", "events.members", "events.channels", "events.presence", "chat.send", "storage", "voice.speak",
|
|
13
|
+
];
|
|
14
|
+
/** Sunucuya eklerken sunucu sahibine gosterilen aciklama (onay ekrani) */
|
|
15
|
+
export const PERMISSION_TEXT = {
|
|
16
|
+
"events.messages": "Metin kanallarındaki mesajları okur, komutlara cevap verir",
|
|
17
|
+
"events.voice": "Ses kanallarına kimin girip çıktığını görür",
|
|
18
|
+
"events.members": "Sunucuya katılan ve ayrılan üyeleri görür",
|
|
19
|
+
"events.channels": "Kanalların açılmasını, değişmesini ve silinmesini görür",
|
|
20
|
+
"events.presence": "Üyelerin çevrimiçi olup olmadığını görür",
|
|
21
|
+
"chat.send": "Metin kanallarına kendi adıyla mesaj yazar",
|
|
22
|
+
"storage": "Kendi verilerini Bunker'da saklar",
|
|
23
|
+
"voice.speak": "Ses kanallarına katılır ve ses çalar",
|
|
24
|
+
};
|
|
25
|
+
/** Olay -> gereken izin (null: izin gerekmez) */
|
|
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.4",
|
|
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
|
+
}
|