lunibee 0.1.6 → 0.1.8
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/LICENSE +21 -21
- package/README.md +223 -223
- package/dist/builders/commands.d.ts +39 -0
- package/dist/builders/components.d.ts +37 -12
- package/dist/builders/embed.d.ts +3 -1
- package/dist/builders/index.d.ts +2 -2
- package/dist/builders/index.js +192 -29
- package/dist/builders/index.js.map +9 -7
- package/dist/collection/index.d.ts +30 -0
- package/dist/collection/index.js +79 -5
- package/dist/collection/index.js.map +4 -4
- package/dist/core/events.d.ts +88 -2
- package/dist/core/index.d.ts +46 -85
- package/dist/core/index.js +2395 -789
- package/dist/core/index.js.map +44 -22
- package/dist/core/permissions.d.ts +112 -53
- package/dist/formatters/index.d.ts +43 -3
- package/dist/formatters/index.js +64 -1
- package/dist/formatters/index.js.map +3 -3
- package/dist/handlers/index.js.map +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +3783 -1009
- package/dist/index.js.map +63 -38
- package/dist/managers/emoji.d.ts +38 -0
- package/dist/managers/guild-resources.d.ts +109 -0
- package/dist/managers/guild.d.ts +117 -1
- package/dist/managers/index.d.ts +37 -1
- package/dist/managers/index.js +1125 -81
- package/dist/managers/index.js.map +25 -20
- package/dist/rest/decoder.d.ts +23 -0
- package/dist/rest/errors.d.ts +20 -0
- package/dist/rest/index.d.ts +119 -25
- package/dist/rest/index.js +676 -204
- package/dist/rest/index.js.map +14 -6
- package/dist/rest/limiter.d.ts +42 -0
- package/dist/rest/redis.d.ts +54 -0
- package/dist/rest/route.d.ts +31 -0
- package/dist/rest/routes.d.ts +24 -0
- package/dist/rest/scheduler.d.ts +42 -0
- package/dist/rest/store.d.ts +67 -0
- package/dist/rest/transport.d.ts +40 -0
- package/dist/rest/webhook.d.ts +2 -2
- package/dist/sharding/bus.d.ts +31 -0
- package/dist/sharding/cluster.d.ts +71 -0
- package/dist/sharding/index.d.ts +18 -2
- package/dist/sharding/index.js +1202 -317
- package/dist/sharding/index.js.map +18 -7
- package/dist/structures/audit-log.d.ts +26 -0
- package/dist/structures/base.d.ts +40 -0
- package/dist/structures/channels.d.ts +56 -0
- package/dist/structures/index.d.ts +30 -1
- package/dist/structures/index.js +963 -87
- package/dist/structures/index.js.map +17 -10
- package/dist/structures/interactions.d.ts +12 -52
- package/dist/structures/options.d.ts +55 -0
- package/dist/structures/resources.d.ts +194 -6
- package/dist/types/gateway-events.d.ts +132 -0
- package/dist/types/gateway.d.ts +181 -0
- package/dist/types/index.d.ts +78 -263
- package/dist/types/index.js +44 -2
- package/dist/types/index.js.map +5 -4
- package/dist/utils/index.js.map +2 -2
- package/dist/voice/index.d.ts +116 -0
- package/dist/voice/index.js +261 -10
- package/dist/voice/index.js.map +3 -3
- package/dist/ws/close-codes.d.ts +23 -0
- package/dist/ws/decoder.d.ts +58 -0
- package/dist/ws/heartbeat.d.ts +87 -0
- package/dist/ws/index.d.ts +24 -32
- package/dist/ws/index.js +920 -318
- package/dist/ws/index.js.map +15 -5
- package/dist/ws/opcodes.d.ts +14 -0
- package/dist/ws/protocol.d.ts +110 -0
- package/dist/ws/reconnect.d.ts +108 -0
- package/dist/ws/send-budget.d.ts +17 -0
- package/dist/ws/session.d.ts +100 -0
- package/dist/ws/state.d.ts +27 -0
- package/dist/ws/transport.d.ts +80 -0
- package/package.json +23 -22
- package/dist/structures/permissions.d.ts +0 -73
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Ekretos
|
|
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.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ekretos
|
|
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,223 +1,223 @@
|
|
|
1
|
-
# Lunibee 🐝
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/lunibee)
|
|
4
|
-
[](https://www.npmjs.com/package/lunibee)
|
|
5
|
-
[](https://discord.gg/SSADgyBpgw)
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/lunibee)
|
|
8
|
-
|
|
9
|
-
A lightweight, Bun-first Discord API library for TypeScript.
|
|
10
|
-
|
|
11
|
-
## Requirements
|
|
12
|
-
|
|
13
|
-
- [Bun](https://bun.sh/) for the supported runtime and package manager
|
|
14
|
-
- TypeScript for typed application development
|
|
15
|
-
- A Discord bot token for connecting to Discord
|
|
16
|
-
|
|
17
|
-
## Installation
|
|
18
|
-
|
|
19
|
-
For repository development:
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
bun install
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
For application usage, install the published `lunibee` package when a release is available:
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
bun add lunibee
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Documentation
|
|
32
|
-
|
|
33
|
-
Full documentation, practical guides, and API references are available at **[lunibee.js.org](https://lunibee.js.org)**.
|
|
34
|
-
|
|
35
|
-
## Getting started
|
|
36
|
-
|
|
37
|
-
```ts
|
|
38
|
-
import { Client, GatewayIntentBits } from "lunibee";
|
|
39
|
-
|
|
40
|
-
const client = new Client({
|
|
41
|
-
token: process.env.DISCORD_TOKEN!,
|
|
42
|
-
intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages
|
|
43
|
-
});
|
|
44
|
-
|
|
45
|
-
client.on("ready", user => {
|
|
46
|
-
console.log(`Ready as ${user.username}`);
|
|
47
|
-
});
|
|
48
|
-
|
|
49
|
-
client.on("messageCreate", message => {
|
|
50
|
-
console.log(message.content);
|
|
51
|
-
});
|
|
52
|
-
|
|
53
|
-
await client.login();
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Destroy the client when the application is shutting down:
|
|
57
|
-
|
|
58
|
-
```ts
|
|
59
|
-
client.destroy();
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Client
|
|
63
|
-
|
|
64
|
-
`Client` is the main application entry point. It coordinates the REST transport, resource managers, Gateway, event dispatch, interactions, and lifecycle state.
|
|
65
|
-
|
|
66
|
-
### Lifecycle
|
|
67
|
-
|
|
68
|
-
```text
|
|
69
|
-
idle → connecting → ready
|
|
70
|
-
↑ ↓
|
|
71
|
-
└──── reconnect ──┘
|
|
72
|
-
|
|
73
|
-
ready → destroyed
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Useful APIs include:
|
|
77
|
-
|
|
78
|
-
- `client.login()` — authenticate and connect to Discord.
|
|
79
|
-
- `client.isReady()` — type guard for a ready client.
|
|
80
|
-
- `client.destroy()` — close the Gateway and clear client-managed resources.
|
|
81
|
-
- `client.rest` — access the REST transport.
|
|
82
|
-
- `client.users`, `client.guilds`, `client.channels` — resource managers.
|
|
83
|
-
|
|
84
|
-
## Gateway
|
|
85
|
-
|
|
86
|
-
The Gateway package implements the Discord WebSocket lifecycle:
|
|
87
|
-
|
|
88
|
-
```text
|
|
89
|
-
CONNECT → HELLO → IDENTIFY/RESUME → READY → DISPATCH
|
|
90
|
-
↘ HEARTBEAT / ACK
|
|
91
|
-
↓
|
|
92
|
-
RECONNECT
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
The Gateway tracks sequence numbers and sessions, handles Discord resume URLs, heartbeat acknowledgement timeouts, invalid sessions, server reconnect requests, and stale/zombie connections.
|
|
96
|
-
|
|
97
|
-
```ts
|
|
98
|
-
import { Gateway } from "@lunibee/ws";
|
|
99
|
-
|
|
100
|
-
const gateway = new Gateway({
|
|
101
|
-
token: process.env.DISCORD_TOKEN!,
|
|
102
|
-
intents: 513
|
|
103
|
-
});
|
|
104
|
-
|
|
105
|
-
await gateway.connect();
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
## REST
|
|
109
|
-
|
|
110
|
-
The REST client supports Discord bucket-aware rate limiting and retries. It consumes Discord's rate-limit headers including bucket identifiers, remaining requests, reset information, and `Retry-After`.
|
|
111
|
-
|
|
112
|
-
Requests accept an `AbortSignal`:
|
|
113
|
-
|
|
114
|
-
```ts
|
|
115
|
-
const controller = new AbortController();
|
|
116
|
-
|
|
117
|
-
const request = client.rest.get("/users/@me", {
|
|
118
|
-
signal: controller.signal
|
|
119
|
-
});
|
|
120
|
-
|
|
121
|
-
controller.abort();
|
|
122
|
-
await request;
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
`RESTError` includes HTTP status, Discord error code, method, path, and the raw error payload when available.
|
|
126
|
-
|
|
127
|
-
## Structures and caching
|
|
128
|
-
|
|
129
|
-
Resource managers maintain canonical instances by Discord resource ID. Re-resolving an already cached resource returns the same structure instance, allowing identity-sensitive application code to remain consistent.
|
|
130
|
-
|
|
131
|
-
REST-created and Gateway-updated resources are routed through manager cache mutation APIs so the same resource is not represented by unrelated structure instances.
|
|
132
|
-
|
|
133
|
-
## Permissions
|
|
134
|
-
|
|
135
|
-
`
|
|
136
|
-
|
|
137
|
-
```ts
|
|
138
|
-
if (member.permissions.has(
|
|
139
|
-
// permitted
|
|
140
|
-
}
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
Multiple permissions can be checked together, and immutable `add()` / `remove()` operations return a new bitfield.
|
|
144
|
-
|
|
145
|
-
## Interactions
|
|
146
|
-
|
|
147
|
-
Interactions expose an ergonomic acknowledgement lifecycle:
|
|
148
|
-
|
|
149
|
-
```ts
|
|
150
|
-
if (interaction.isChatInputCommand()) {
|
|
151
|
-
await interaction.deferReply();
|
|
152
|
-
await interaction.editReply({ content: "Done!" });
|
|
153
|
-
await interaction.followUp({ content: "Follow-up" });
|
|
154
|
-
}
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
Available lifecycle methods include `reply()`, `deferReply()`, `editReply()`, `deleteReply()`, and `followUp()`.
|
|
158
|
-
|
|
159
|
-
## Builders
|
|
160
|
-
|
|
161
|
-
Lunibee provides strict builders for Discord payloads (Discord.js V2 compatible), including:
|
|
162
|
-
|
|
163
|
-
- `ActionRowBuilder`
|
|
164
|
-
- `ButtonBuilder`
|
|
165
|
-
- `
|
|
166
|
-
- `EmbedBuilder`
|
|
167
|
-
- `ModalBuilder`
|
|
168
|
-
- `TextInputBuilder`
|
|
169
|
-
|
|
170
|
-
Builders validate Discord limits before serialization and expose typed `toJSON()` payloads.
|
|
171
|
-
|
|
172
|
-
## Sharding
|
|
173
|
-
|
|
174
|
-
`@lunibee/sharding` manages multiple Gateway connections and supports explicit shard counts or Discord's recommended shard count.
|
|
175
|
-
|
|
176
|
-
```ts
|
|
177
|
-
import { ShardManager } from "@lunibee/sharding";
|
|
178
|
-
|
|
179
|
-
const shards = new ShardManager({
|
|
180
|
-
token: process.env.DISCORD_TOKEN!,
|
|
181
|
-
intents: 513,
|
|
182
|
-
shardCount: "auto"
|
|
183
|
-
});
|
|
184
|
-
|
|
185
|
-
await shards.connect();
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
Call `destroy()` during shutdown. The manager releases its Gateway instances and can initialize a fresh shard set on a later `connect()`.
|
|
189
|
-
|
|
190
|
-
## Package layout
|
|
191
|
-
|
|
192
|
-
The monorepo is organized into focused packages:
|
|
193
|
-
|
|
194
|
-
| Package | Responsibility |
|
|
195
|
-
| --- | --- |
|
|
196
|
-
| `@lunibee/types` | Discord API and shared TypeScript types |
|
|
197
|
-
| `@lunibee/structures` | Discord resource and interaction structures |
|
|
198
|
-
| `@lunibee/managers` | Resource caches and REST-backed managers |
|
|
199
|
-
| `@lunibee/rest` | HTTP transport, routes, rate limits, retries |
|
|
200
|
-
| `@lunibee/ws` | Discord Gateway connection |
|
|
201
|
-
| `@lunibee/core` | Main client and high-level orchestration |
|
|
202
|
-
| `@lunibee/builders` | Typed Discord payload builders |
|
|
203
|
-
| `@lunibee/sharding` | Multi-Gateway shard management |
|
|
204
|
-
| `lunibee` | End-user package entry point |
|
|
205
|
-
|
|
206
|
-
## Development
|
|
207
|
-
|
|
208
|
-
Run the repository's checks before submitting changes:
|
|
209
|
-
|
|
210
|
-
```bash
|
|
211
|
-
bun install
|
|
212
|
-
bunx tsc --noEmit
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
## Documentation & API Reference
|
|
216
|
-
|
|
217
|
-
The full, official API reference and practical guides are available at **[lunibee.js.org](https://lunibee.js.org)**.
|
|
218
|
-
|
|
219
|
-
The source remains the authoritative API surface while Lunibee is pre-1.0. Public exports are intentionally split by responsibility so applications can import either the high-level `lunibee` package or individual packages when appropriate.
|
|
220
|
-
|
|
221
|
-
## Status
|
|
222
|
-
|
|
223
|
-
Lunibee is in active development and the API may change before the first stable release.
|
|
1
|
+
# Lunibee 🐝
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/lunibee)
|
|
4
|
+
[](https://www.npmjs.com/package/lunibee)
|
|
5
|
+
[](https://discord.gg/SSADgyBpgw)
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/lunibee)
|
|
8
|
+
|
|
9
|
+
A lightweight, Bun-first Discord API library for TypeScript.
|
|
10
|
+
|
|
11
|
+
## Requirements
|
|
12
|
+
|
|
13
|
+
- [Bun](https://bun.sh/) for the supported runtime and package manager
|
|
14
|
+
- TypeScript for typed application development
|
|
15
|
+
- A Discord bot token for connecting to Discord
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
For repository development:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
bun install
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
For application usage, install the published `lunibee` package when a release is available:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
bun add lunibee
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Documentation
|
|
32
|
+
|
|
33
|
+
Full documentation, practical guides, and API references are available at **[lunibee.js.org](https://lunibee.js.org)**.
|
|
34
|
+
|
|
35
|
+
## Getting started
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { Client, GatewayIntentBits } from "lunibee";
|
|
39
|
+
|
|
40
|
+
const client = new Client({
|
|
41
|
+
token: process.env.DISCORD_TOKEN!,
|
|
42
|
+
intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
client.on("ready", user => {
|
|
46
|
+
console.log(`Ready as ${user.username}`);
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
client.on("messageCreate", message => {
|
|
50
|
+
console.log(message.content);
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
await client.login();
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Destroy the client when the application is shutting down:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
client.destroy();
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Client
|
|
63
|
+
|
|
64
|
+
`Client` is the main application entry point. It coordinates the REST transport, resource managers, Gateway, event dispatch, interactions, and lifecycle state.
|
|
65
|
+
|
|
66
|
+
### Lifecycle
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
idle → connecting → ready
|
|
70
|
+
↑ ↓
|
|
71
|
+
└──── reconnect ──┘
|
|
72
|
+
|
|
73
|
+
ready → destroyed
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Useful APIs include:
|
|
77
|
+
|
|
78
|
+
- `client.login()` — authenticate and connect to Discord.
|
|
79
|
+
- `client.isReady()` — type guard for a ready client.
|
|
80
|
+
- `client.destroy()` — close the Gateway and clear client-managed resources.
|
|
81
|
+
- `client.rest` — access the REST transport.
|
|
82
|
+
- `client.users`, `client.guilds`, `client.channels` — resource managers.
|
|
83
|
+
|
|
84
|
+
## Gateway
|
|
85
|
+
|
|
86
|
+
The Gateway package implements the Discord WebSocket lifecycle:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
CONNECT → HELLO → IDENTIFY/RESUME → READY → DISPATCH
|
|
90
|
+
↘ HEARTBEAT / ACK
|
|
91
|
+
↓
|
|
92
|
+
RECONNECT
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The Gateway tracks sequence numbers and sessions, handles Discord resume URLs, heartbeat acknowledgement timeouts, invalid sessions, server reconnect requests, and stale/zombie connections.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import { Gateway } from "@lunibee/ws";
|
|
99
|
+
|
|
100
|
+
const gateway = new Gateway({
|
|
101
|
+
token: process.env.DISCORD_TOKEN!,
|
|
102
|
+
intents: 513
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
await gateway.connect();
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## REST
|
|
109
|
+
|
|
110
|
+
The REST client supports Discord bucket-aware rate limiting and retries. It consumes Discord's rate-limit headers including bucket identifiers, remaining requests, reset information, and `Retry-After`.
|
|
111
|
+
|
|
112
|
+
Requests accept an `AbortSignal`:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
const controller = new AbortController();
|
|
116
|
+
|
|
117
|
+
const request = client.rest.get("/users/@me", {
|
|
118
|
+
signal: controller.signal
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
controller.abort();
|
|
122
|
+
await request;
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`RESTError` includes HTTP status, Discord error code, method, path, and the raw error payload when available.
|
|
126
|
+
|
|
127
|
+
## Structures and caching
|
|
128
|
+
|
|
129
|
+
Resource managers maintain canonical instances by Discord resource ID. Re-resolving an already cached resource returns the same structure instance, allowing identity-sensitive application code to remain consistent.
|
|
130
|
+
|
|
131
|
+
REST-created and Gateway-updated resources are routed through manager cache mutation APIs so the same resource is not represented by unrelated structure instances.
|
|
132
|
+
|
|
133
|
+
## Permissions
|
|
134
|
+
|
|
135
|
+
`PermissionSet` provides named and raw permission checks:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
if (member.permissions.has(Permission.manageMessages)) {
|
|
139
|
+
// permitted
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Multiple permissions can be checked together, and immutable `add()` / `remove()` operations return a new bitfield.
|
|
144
|
+
|
|
145
|
+
## Interactions
|
|
146
|
+
|
|
147
|
+
Interactions expose an ergonomic acknowledgement lifecycle:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
if (interaction.isChatInputCommand()) {
|
|
151
|
+
await interaction.deferReply();
|
|
152
|
+
await interaction.editReply({ content: "Done!" });
|
|
153
|
+
await interaction.followUp({ content: "Follow-up" });
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Available lifecycle methods include `reply()`, `deferReply()`, `editReply()`, `deleteReply()`, and `followUp()`.
|
|
158
|
+
|
|
159
|
+
## Builders
|
|
160
|
+
|
|
161
|
+
Lunibee provides strict builders for Discord payloads (Discord.js V2 compatible), including:
|
|
162
|
+
|
|
163
|
+
- `ActionRowBuilder`
|
|
164
|
+
- `ButtonBuilder`
|
|
165
|
+
- `StringSelectBuilder`
|
|
166
|
+
- `EmbedBuilder`
|
|
167
|
+
- `ModalBuilder`
|
|
168
|
+
- `TextInputBuilder`
|
|
169
|
+
|
|
170
|
+
Builders validate Discord limits before serialization and expose typed `toJSON()` payloads.
|
|
171
|
+
|
|
172
|
+
## Sharding
|
|
173
|
+
|
|
174
|
+
`@lunibee/sharding` manages multiple Gateway connections and supports explicit shard counts or Discord's recommended shard count.
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import { ShardManager } from "@lunibee/sharding";
|
|
178
|
+
|
|
179
|
+
const shards = new ShardManager({
|
|
180
|
+
token: process.env.DISCORD_TOKEN!,
|
|
181
|
+
intents: 513,
|
|
182
|
+
shardCount: "auto"
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
await shards.connect();
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Call `destroy()` during shutdown. The manager releases its Gateway instances and can initialize a fresh shard set on a later `connect()`.
|
|
189
|
+
|
|
190
|
+
## Package layout
|
|
191
|
+
|
|
192
|
+
The monorepo is organized into focused packages:
|
|
193
|
+
|
|
194
|
+
| Package | Responsibility |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `@lunibee/types` | Discord API and shared TypeScript types |
|
|
197
|
+
| `@lunibee/structures` | Discord resource and interaction structures |
|
|
198
|
+
| `@lunibee/managers` | Resource caches and REST-backed managers |
|
|
199
|
+
| `@lunibee/rest` | HTTP transport, routes, rate limits, retries |
|
|
200
|
+
| `@lunibee/ws` | Discord Gateway connection |
|
|
201
|
+
| `@lunibee/core` | Main client and high-level orchestration |
|
|
202
|
+
| `@lunibee/builders` | Typed Discord payload builders |
|
|
203
|
+
| `@lunibee/sharding` | Multi-Gateway shard management |
|
|
204
|
+
| `lunibee` | End-user package entry point |
|
|
205
|
+
|
|
206
|
+
## Development
|
|
207
|
+
|
|
208
|
+
Run the repository's checks before submitting changes:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
bun install
|
|
212
|
+
bunx tsc --noEmit
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## Documentation & API Reference
|
|
216
|
+
|
|
217
|
+
The full, official API reference and practical guides are available at **[lunibee.js.org](https://lunibee.js.org)**.
|
|
218
|
+
|
|
219
|
+
The source remains the authoritative API surface while Lunibee is pre-1.0. Public exports are intentionally split by responsibility so applications can import either the high-level `lunibee` package or individual packages when appropriate.
|
|
220
|
+
|
|
221
|
+
## Status
|
|
222
|
+
|
|
223
|
+
Lunibee is in active development and the API may change before the first stable release.
|
|
@@ -116,3 +116,42 @@ export declare class NumberOptionBuilder extends CommandOptionBuilder {
|
|
|
116
116
|
/** Creates a subcommand group. */ constructor();
|
|
117
117
|
/** Adds a subcommand to this group. */ addSubcommand(configure: (option: SubcommandBuilder) => SubcommandBuilder): this;
|
|
118
118
|
}
|
|
119
|
+
/** Builder for application commands that appear in right-click context menus.
|
|
120
|
+
* Discord.js-familiar: `new ContextMenuCommandBuilder().setName("x").setType(2)`. */
|
|
121
|
+
export declare class ContextMenuCommandBuilder {
|
|
122
|
+
protected readonly data: Record<string, unknown>;
|
|
123
|
+
constructor(type?: 2 | 3);
|
|
124
|
+
/** Sets the command type: 2 = USER, 3 = MESSAGE. @throws {RangeError} For any other type. */
|
|
125
|
+
setType(type: 2 | 3): this;
|
|
126
|
+
/** Sets the command name (shown in the right-click menu).
|
|
127
|
+
* Unlike CHAT_INPUT commands, USER (type 2) and MESSAGE (type 3) context-menu
|
|
128
|
+
* command names may contain uppercase letters and spaces, so no lowercase/charset
|
|
129
|
+
* validation is applied here — only Discord's 1-32 length limit and a non-empty
|
|
130
|
+
* (non-whitespace) requirement are enforced.
|
|
131
|
+
* @param name Display name; 1-32 characters, mixed case and spaces allowed.
|
|
132
|
+
* @throws {RangeError} If the name is empty/whitespace-only or exceeds 32 characters.
|
|
133
|
+
*/
|
|
134
|
+
setName(name: string): this;
|
|
135
|
+
/** Sets default member permissions required to see this command. */
|
|
136
|
+
setDefaultMemberPermissions(permissions: bigint | number | string | null): this;
|
|
137
|
+
/** Sets whether the command is available in direct messages. */
|
|
138
|
+
setDMPermission(enabled: boolean): this;
|
|
139
|
+
/** Sets command integration types. */
|
|
140
|
+
setIntegrationTypes(...types: number[]): this;
|
|
141
|
+
/** Serializes the command payload for the Discord API. */
|
|
142
|
+
toJSON(): Record<string, unknown>;
|
|
143
|
+
}
|
|
144
|
+
/** Builds a User context menu command (appears when right-clicking a user, type 2).
|
|
145
|
+
* @example
|
|
146
|
+
* new UserCommandBuilder().setName("View Profile").toJSON()
|
|
147
|
+
*/
|
|
148
|
+
export declare class UserCommandBuilder extends ContextMenuCommandBuilder {
|
|
149
|
+
constructor();
|
|
150
|
+
}
|
|
151
|
+
/** Builds a Message context menu command (appears when right-clicking a message, type 3).
|
|
152
|
+
* @example
|
|
153
|
+
* new MessageCommandBuilder().setName("Translate Message").toJSON()
|
|
154
|
+
*/
|
|
155
|
+
export declare class MessageCommandBuilder extends ContextMenuCommandBuilder {
|
|
156
|
+
constructor();
|
|
157
|
+
}
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { ButtonStyle } from "@lunibee/types";
|
|
2
|
+
export { ButtonStyle };
|
|
1
3
|
/** Component type constants exposed by Lunibee. */
|
|
2
4
|
export declare const ComponentType: {
|
|
3
5
|
readonly ActionRow: 1;
|
|
@@ -17,13 +19,6 @@ export declare const ComponentType: {
|
|
|
17
19
|
readonly ContentInventoryEntry: 16;
|
|
18
20
|
readonly Container: 17;
|
|
19
21
|
};
|
|
20
|
-
export declare const ButtonStyle: {
|
|
21
|
-
readonly Primary: 1;
|
|
22
|
-
readonly Secondary: 2;
|
|
23
|
-
readonly Success: 3;
|
|
24
|
-
readonly Danger: 4;
|
|
25
|
-
readonly Link: 5;
|
|
26
|
-
};
|
|
27
22
|
export declare const TextInputStyle: {
|
|
28
23
|
readonly Short: 1;
|
|
29
24
|
readonly Paragraph: 2;
|
|
@@ -35,7 +30,7 @@ export interface APIComponentEmoji {
|
|
|
35
30
|
}
|
|
36
31
|
export interface APIButtonComponent {
|
|
37
32
|
type: typeof ComponentType.Button;
|
|
38
|
-
style: 1 | 2 | 3 | 4 | 5;
|
|
33
|
+
style: 1 | 2 | 3 | 4 | 5 | 6;
|
|
39
34
|
custom_id?: string;
|
|
40
35
|
label?: string;
|
|
41
36
|
emoji?: APIComponentEmoji;
|
|
@@ -67,6 +62,7 @@ export interface APIEntitySelectComponent {
|
|
|
67
62
|
max_values?: number;
|
|
68
63
|
required?: boolean;
|
|
69
64
|
disabled?: boolean;
|
|
65
|
+
default_values?: APISelectDefaultValue[];
|
|
70
66
|
}
|
|
71
67
|
export interface APITextInputComponent {
|
|
72
68
|
type: typeof ComponentType.TextInput;
|
|
@@ -108,6 +104,11 @@ export interface APIMediaGalleryComponent {
|
|
|
108
104
|
};
|
|
109
105
|
}[];
|
|
110
106
|
}
|
|
107
|
+
/** Default values accepted by an auto-populated entity select. */
|
|
108
|
+
export interface APISelectDefaultValue {
|
|
109
|
+
id: string;
|
|
110
|
+
type: "user" | "role" | "channel";
|
|
111
|
+
}
|
|
111
112
|
export interface APIFileComponent {
|
|
112
113
|
type: typeof ComponentType.File;
|
|
113
114
|
file: {
|
|
@@ -126,6 +127,8 @@ export interface APIThumbnailComponent {
|
|
|
126
127
|
proxy_url?: string;
|
|
127
128
|
width?: number;
|
|
128
129
|
height?: number;
|
|
130
|
+
description?: string;
|
|
131
|
+
spoiler?: boolean;
|
|
129
132
|
}
|
|
130
133
|
export interface APIContentInventoryEntryComponent {
|
|
131
134
|
type: typeof ComponentType.ContentInventoryEntry;
|
|
@@ -135,6 +138,7 @@ export interface APIContainerComponent {
|
|
|
135
138
|
type: typeof ComponentType.Container;
|
|
136
139
|
components: APIComponent[];
|
|
137
140
|
accent_color?: number;
|
|
141
|
+
spoiler?: boolean;
|
|
138
142
|
}
|
|
139
143
|
export type APIComponent = APIActionRowComponent | APIButtonComponent | APIStringSelectComponent | APIEntitySelectComponent | APITextInputComponent | APISectionComponent | APITextDisplayComponent | APIThumbnailComponent | APIMediaGalleryComponent | APIFileComponent | APISeparatorComponent | APIContentInventoryEntryComponent | APIContainerComponent;
|
|
140
144
|
export declare class ActionRowBuilder<T extends {
|
|
@@ -177,10 +181,7 @@ export declare class EntitySelectBuilder {
|
|
|
177
181
|
setMaxValues(value: number): this;
|
|
178
182
|
setRequired(value?: boolean): this;
|
|
179
183
|
setDisabled(value?: boolean): this;
|
|
180
|
-
setDefaultValues(...values:
|
|
181
|
-
id: string;
|
|
182
|
-
type: "user" | "role" | "channel";
|
|
183
|
-
}[]): this;
|
|
184
|
+
setDefaultValues(...values: APISelectDefaultValue[]): this;
|
|
184
185
|
toJSON(): APIEntitySelectComponent;
|
|
185
186
|
}
|
|
186
187
|
export declare class ModalBuilder {
|
|
@@ -210,6 +211,8 @@ export declare class ContainerBuilder {
|
|
|
210
211
|
toJSON(): APIComponent;
|
|
211
212
|
}[]): this;
|
|
212
213
|
setAccentColor(color: number): this;
|
|
214
|
+
/** Marks the whole container as a spoiler (blurred until clicked). */
|
|
215
|
+
setSpoiler(spoiler?: boolean): this;
|
|
213
216
|
toJSON(): APIContainerComponent;
|
|
214
217
|
}
|
|
215
218
|
export declare class SectionBuilder {
|
|
@@ -250,6 +253,10 @@ export declare class SeparatorBuilder {
|
|
|
250
253
|
export declare class ThumbnailBuilder {
|
|
251
254
|
#private;
|
|
252
255
|
setUrl(url: string): this;
|
|
256
|
+
/** Sets the thumbnail's alt-text description. */
|
|
257
|
+
setDescription(description: string): this;
|
|
258
|
+
/** Marks the thumbnail as a spoiler (blurred until clicked). */
|
|
259
|
+
setSpoiler(spoiler?: boolean): this;
|
|
253
260
|
toJSON(): APIThumbnailComponent;
|
|
254
261
|
}
|
|
255
262
|
export declare class ContentInventoryEntryBuilder {
|
|
@@ -257,3 +264,21 @@ export declare class ContentInventoryEntryBuilder {
|
|
|
257
264
|
setId(id: string): this;
|
|
258
265
|
toJSON(): APIContentInventoryEntryComponent;
|
|
259
266
|
}
|
|
267
|
+
/** Discord.js-familiar alias for {@link StringSelectBuilder}. */
|
|
268
|
+
export { StringSelectBuilder as StringSelectMenuBuilder };
|
|
269
|
+
/** User select menu builder (Discord.js-familiar). */
|
|
270
|
+
export declare class UserSelectMenuBuilder extends EntitySelectBuilder {
|
|
271
|
+
constructor();
|
|
272
|
+
}
|
|
273
|
+
/** Role select menu builder (Discord.js-familiar). */
|
|
274
|
+
export declare class RoleSelectMenuBuilder extends EntitySelectBuilder {
|
|
275
|
+
constructor();
|
|
276
|
+
}
|
|
277
|
+
/** Mentionable select menu builder (Discord.js-familiar). */
|
|
278
|
+
export declare class MentionableSelectMenuBuilder extends EntitySelectBuilder {
|
|
279
|
+
constructor();
|
|
280
|
+
}
|
|
281
|
+
/** Channel select menu builder (Discord.js-familiar). */
|
|
282
|
+
export declare class ChannelSelectMenuBuilder extends EntitySelectBuilder {
|
|
283
|
+
constructor();
|
|
284
|
+
}
|
package/dist/builders/embed.d.ts
CHANGED
|
@@ -48,7 +48,9 @@ export declare class EmbedBuilder {
|
|
|
48
48
|
/** Sets the image URL. @param value Image URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ setImage(value: {
|
|
49
49
|
url: string;
|
|
50
50
|
} | string): this;
|
|
51
|
-
/** Adds embed fields.
|
|
51
|
+
/** Adds embed fields. Accepts both the spread form `addFields(a, b)` and the
|
|
52
|
+
* single-array form `addFields([a, b])` for discord.js `RestOrArray` parity.
|
|
53
|
+
* @param fields Field payloads, spread or as a single array. @returns This builder. @throws {RangeError} If the 25-field limit is exceeded. */ addFields(...fields: EmbedField[] | [EmbedField[]]): this;
|
|
52
54
|
setFields(fields: EmbedField[]): this;
|
|
53
55
|
/** Replaces fields starting at an index. @param index Start index. @param deleteCount Number of fields to remove. @param fields Replacement fields. @returns This builder. @throws {RangeError} If arguments are invalid or the 25-field limit is exceeded. */ spliceFields(index: number, deleteCount: number, ...fields: EmbedField[]): this;
|
|
54
56
|
/** Removes all embed fields. @returns This builder. */ clearFields(): this;
|
package/dist/builders/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { EmbedBuilder } from "./embed.js";
|
|
2
2
|
export type { EmbedField } from "./embed.js";
|
|
3
|
-
export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, EntitySelectBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, } from "./components.js";
|
|
4
|
-
export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, } from "./commands.js";
|
|
3
|
+
export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, StringSelectMenuBuilder, EntitySelectBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, MentionableSelectMenuBuilder, ChannelSelectMenuBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, } from "./components.js";
|
|
4
|
+
export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, UserCommandBuilder, MessageCommandBuilder, ContextMenuCommandBuilder, } from "./commands.js";
|
|
5
5
|
export { AttachmentBuilder, type AttachmentData } from "./attachment.js";
|