@stoatx/client 0.6.4 → 0.8.0
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/README.md +3 -113
- package/dist/index.cjs +448 -17
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +185 -5
- package/dist/index.d.ts +185 -5
- package/dist/index.js +453 -18
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -5,127 +5,17 @@ A high-performance, fully-typed, and memory-efficient client library for the Sto
|
|
|
5
5
|
[](https://www.npmjs.com/package/@stoatx/client)
|
|
6
6
|
[](https://www.typescriptlang.org/)
|
|
7
7
|
|
|
8
|
-
`@stoatx/client` provides a robust object-oriented wrapper around Stoat's REST and WebSocket APIs. It features an intelligent caching system, automatic memory sweeping, and strict event typings to make building bots as frictionless as possible.
|
|
9
|
-
|
|
10
8
|
## Features
|
|
11
9
|
|
|
12
10
|
- **Strictly Typed:** 100% TypeScript with highly accurate generic types for events and structures.
|
|
13
11
|
- **Smart Caching:** Built on a unified `BaseManager` architecture that guarantees reference stability (no duplicate objects in memory).
|
|
14
12
|
- **Automatic Memory Management:** Includes a built-in `SweeperManager` to prevent memory leaks in long-running applications.
|
|
15
13
|
- **Extensible:** Designed to seamlessly integrate with higher-level command frameworks like the Stoatx Handler.
|
|
14
|
+
- **Self-hosting support:** Natively supports custom Stoat instances via root API discovery.
|
|
16
15
|
- **Modern Node:** Pure ESM and CommonJS support built with `tsup`.
|
|
17
16
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
# Using pnpm (Recommended)
|
|
22
|
-
pnpm add @stoatx/client
|
|
23
|
-
|
|
24
|
-
# Using npm
|
|
25
|
-
npm install @stoatx/client
|
|
26
|
-
|
|
27
|
-
# Using yarn
|
|
28
|
-
yarn add @stoatx/client
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Quick Start
|
|
32
|
-
|
|
33
|
-
```typescript
|
|
34
|
-
import { Client } from "@stoatx/client";
|
|
35
|
-
|
|
36
|
-
// Initialize the client
|
|
37
|
-
const client = new Client({
|
|
38
|
-
sweepers: {
|
|
39
|
-
messages: {
|
|
40
|
-
lifetime: 3600000, // 1 hour
|
|
41
|
-
interval: 600000, // 10 minutes
|
|
42
|
-
},
|
|
43
|
-
},
|
|
44
|
-
});
|
|
45
|
-
|
|
46
|
-
// Listen to events
|
|
47
|
-
client.on("ready", async () => {
|
|
48
|
-
const me = await client.users.fetchMe();
|
|
49
|
-
console.log(`Logged in successfully as ${me.username}!`);
|
|
50
|
-
});
|
|
51
|
-
|
|
52
|
-
client.on("messageCreate", async (message) => {
|
|
53
|
-
if (message.author.bot) return;
|
|
54
|
-
|
|
55
|
-
if (message.content === "!ping") {
|
|
56
|
-
await message.channel.send("Pong! 🏓");
|
|
57
|
-
}
|
|
58
|
-
});
|
|
59
|
-
|
|
60
|
-
// Connect to Stoat
|
|
61
|
-
client.login("YOUR_BOT_TOKEN");
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
##️ Architecture & Managers
|
|
65
|
-
|
|
66
|
-
`@stoatx/client` organizes data using a predictable **Manager** hierarchy. Managers handle fetching, caching, and editing structures.
|
|
67
|
-
|
|
68
|
-
### Global Managers
|
|
69
|
-
|
|
70
|
-
Accessible directly on the `client`, managing data across the entire bot:
|
|
71
|
-
|
|
72
|
-
- `client.users` (Fetches and caches users)
|
|
73
|
-
- `client.servers` (Fetches and caches servers)
|
|
74
|
-
- `client.channels` (The global cache for all channel types)
|
|
75
|
-
|
|
76
|
-
### Scoped Managers
|
|
77
|
-
|
|
78
|
-
Accessible on specific structures (like `Server` or `Channel`), managing localized data:
|
|
79
|
-
|
|
80
|
-
- `server.members` (Manages members within a specific server)
|
|
81
|
-
- `server.roles` (Manages roles for a server)
|
|
82
|
-
- `server.channels` (A virtual manager filtering the global channel cache)
|
|
83
|
-
- `channel.messages` (Manages messages within a specific channel)
|
|
84
|
-
|
|
85
|
-
### Example: Editing a Server and Sending a Message
|
|
86
|
-
|
|
87
|
-
```typescript
|
|
88
|
-
// Fetch a server and edit its name
|
|
89
|
-
const server = await client.servers.fetch("SERVER_ID");
|
|
90
|
-
await server.edit({ name: "My Awesome Server" });
|
|
91
|
-
|
|
92
|
-
// Find a specific channel and send an embed
|
|
93
|
-
const channel = server.channels.cache.get("CHANNEL_ID");
|
|
94
|
-
if (channel && channel.isText()) {
|
|
95
|
-
await channel.send({
|
|
96
|
-
content: "Welcome to the new server!",
|
|
97
|
-
embeds: [{ title: "Update", description: "Name changed successfully." }],
|
|
98
|
-
});
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
## Building Command Handlers
|
|
103
|
-
|
|
104
|
-
While you can use `@stoatx/client` directly, it truly shines when paired with a command handler. Because the events are strictly typed using generics, you can easily build type-safe event registries.
|
|
105
|
-
We recommend using the `Stoatx` for a seamless experience, but you can also create your own custom command handler leveraging the client's event system.
|
|
106
|
-
|
|
107
|
-
```typescript
|
|
108
|
-
// Example of event listening
|
|
109
|
-
import type { ClientEvents } from "@stoatx/client";
|
|
110
|
-
|
|
111
|
-
function registerEvent<K ClientEvents extends keyof>(
|
|
112
|
-
client: Client,
|
|
113
|
-
event: K,
|
|
114
|
-
handler: (...args: ClientEvents[K]) => void
|
|
115
|
-
) {
|
|
116
|
-
client.on(event, handler);
|
|
117
|
-
}
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
## Contributing
|
|
121
|
-
|
|
122
|
-
Contributions are welcome! If you're using this library and find a bug or want to add a feature from the Revolt API, feel free to open a Pull Request.
|
|
123
|
-
|
|
124
|
-
1. Clone the repository.
|
|
125
|
-
2. Run `pnpm install`.
|
|
126
|
-
3. Make your changes in `packages/client`.
|
|
127
|
-
4. Run `pnpm build` to ensure `tsup` compiles your changes correctly.
|
|
17
|
+
For installation instructions, guides, and API references, visit the **[Stoatx Documentation](https://stoatx-ts.github.io/stoatx/)**.
|
|
128
18
|
|
|
129
19
|
## License
|
|
130
20
|
|
|
131
|
-
MIT © [Stoatx / Stoatx Team]
|
|
21
|
+
MIT © [Stoatx / Stoatx Team]
|