kira-arts 1.3.0 โ 1.3.2
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 +87 -19
- package/dist/index.cjs +3647 -3836
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +513 -324
- package/dist/index.d.cts.map +1 -0
- package/dist/index.d.mts +619 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +3858 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +29 -22
- package/README.npm.md +0 -58
- package/dist/index.d.ts +0 -430
- package/dist/index.js +0 -4039
- package/dist/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,21 +1,20 @@
|
|
|
1
1
|
# kira-arts ๐
|
|
2
2
|
|
|
3
|
-
A TypeScript library for generating Discord-style visual cards โ profiles, welcome/leave events, level-ups, achievements, leaderboards, compatibility "ship" cards,
|
|
3
|
+
A TypeScript library for generating Discord-style visual cards โ profiles, welcome/leave events, level-ups, achievements, leaderboards, compatibility "ship" cards, now-playing music cards, and giveaways โ rendered natively for speed and zero runtime dependencies on a browser or headless Chromium.
|
|
4
4
|
|
|
5
|
-
**๐ Full documentation, live examples, and a Playground: [documentation](https://
|
|
5
|
+
**๐ Full documentation, live examples, and a Playground: [documentation](https://guide.worddevs.dev/docs/kira-arts)**
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/kira-arts)
|
|
8
8
|
[](https://www.npmjs.com/package/kira-arts)
|
|
9
9
|
[](https://packagephobia.com/result?p=kira-arts)
|
|
10
10
|
[](./LICENSE)
|
|
11
11
|
[](https://www.npmjs.com/package/kira-arts)
|
|
12
|
-
[](./dist/index.d.
|
|
12
|
+
[](./dist/index.d.cts)
|
|
13
13
|
[](https://www.typescriptlang.org/)
|
|
14
14
|
[](https://github.com/worddevs/kira-arts/actions/workflows/tests.yml)
|
|
15
15
|
[](https://github.com/worddevs/kira-arts/actions/workflows/release.yml)
|
|
16
16
|
[](https://github.com/worddevs/kira-arts/stargazers)
|
|
17
|
-
[](https://github.com/worddevs/kira-arts/graphs/contributors)
|
|
17
|
+
[](https://github.com/worddevs/kira-arts/commits/main)
|
|
19
18
|
[](https://github.com/worddevs/kira-arts/commits/main)
|
|
20
19
|
[](https://github.com/worddevs/kira-arts/issues)
|
|
21
20
|
[](./CONTRIBUTING.md)
|
|
@@ -23,10 +22,13 @@ A TypeScript library for generating Discord-style visual cards โ profiles, wel
|
|
|
23
22
|
|
|
24
23
|
## โจ Features
|
|
25
24
|
|
|
26
|
-
- ๐ผ๏ธ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility),
|
|
27
|
-
- ๐ต Now Playing card ships with adapters for moonlink.js, Lavalink-based clients, discord-player, and distube
|
|
28
|
-
- ๐จ 8 built-in themes, Nitro/role-color aware borders
|
|
29
|
-
- ๐งพ Output as `png`, `jpeg`, or `webp`, ready to use as a discord.js `AttachmentBuilder`
|
|
25
|
+
- ๐ผ๏ธ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility), Now Playing, and Giveaway cards
|
|
26
|
+
- ๐ต Now Playing card ships with adapters for moonlink.js, Lavalink-based clients (erela.js, Shoukaku, Kazagumo, Riffy, Magmastream, lavalink-client), discord-player, and distube
|
|
27
|
+
- ๐จ 8 built-in themes (`discord`, `midnight`, `sunset`, `neon`, `forest`, `sakura`, `monochrome`, `gold`), Nitro/role-color aware borders, and up to 4-color custom gradients
|
|
28
|
+
- ๐งพ Output as `png`, `jpeg`, or `webp`, ready to use as a discord.js `AttachmentBuilder` via `toAttachment()`
|
|
29
|
+
- โก Built-in, configurable in-memory cache for fetched user data (`setCacheOptions`, `clearCache`, `getCacheSize`)
|
|
30
|
+
- ๐ก๏ธ Typed error handling with `KiraError` and `KiraErrorCode`, instead of opaque runtime failures
|
|
31
|
+
- ๐ฆ Dual package: ESM and CommonJS builds, both with full type declarations, no extra config needed
|
|
30
32
|
|
|
31
33
|
## ๐ฆ Installation
|
|
32
34
|
|
|
@@ -45,26 +47,92 @@ bun add kira-arts
|
|
|
45
47
|
import { Client, GatewayIntentBits } from "discord.js";
|
|
46
48
|
import { setClient, profileImage, toAttachment } from "kira-arts";
|
|
47
49
|
|
|
48
|
-
const client = new Client({
|
|
50
|
+
const client = new Client({
|
|
51
|
+
intents: [
|
|
52
|
+
GatewayIntentBits.Guilds,
|
|
53
|
+
GatewayIntentBits.GuildMessages,
|
|
54
|
+
GatewayIntentBits.MessageContent,
|
|
55
|
+
],
|
|
56
|
+
});
|
|
49
57
|
|
|
50
|
-
client.once("
|
|
58
|
+
client.once("clientReady", () => {
|
|
51
59
|
setClient(client); // ๐ required before generating any card
|
|
52
60
|
});
|
|
53
61
|
|
|
54
|
-
client.
|
|
62
|
+
client.on("messageCreate", async (message) => {
|
|
63
|
+
if (message.author.bot || message.content !== "!card") return;
|
|
64
|
+
|
|
65
|
+
const buffer = await profileImage(message.author.id, {
|
|
66
|
+
guildId: message.guild?.id,
|
|
67
|
+
useRoleColor: true,
|
|
68
|
+
presenceStatus: message.member?.presence?.status,
|
|
69
|
+
badgesFrame: true,
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
await message.reply({ files: [toAttachment(buffer, "profile", "png")] });
|
|
73
|
+
});
|
|
55
74
|
|
|
56
|
-
|
|
57
|
-
await interaction.reply({ files: [toAttachment(buffer, "profile", "png")] });
|
|
75
|
+
client.login(process.env.TOKEN);
|
|
58
76
|
```
|
|
59
77
|
|
|
60
|
-
Every other card, the music adapters, theming, caching, error handling, and output options are documented with live examples at **[documentation](https://
|
|
78
|
+
Every other card, the music adapters, theming, caching, error handling, and output options are documented with live examples at **[documentation](https://guide.worddevs.dev/docs/kira-arts)**.
|
|
79
|
+
|
|
80
|
+
## ๐ Cards at a glance
|
|
81
|
+
|
|
82
|
+
| Card | Function | What it's for |
|
|
83
|
+
| ----------- | --------------------------------------------- | ------------------------------------------- |
|
|
84
|
+
| Profile | `profileImage(userId, options)` | Avatar, badges, nameplate, server tag, rank |
|
|
85
|
+
| Welcome | `welcomeImage(userId, guildName, options)` | Member join events |
|
|
86
|
+
| Leave | `leaveImage(userId, guildName, options)` | Member leave events |
|
|
87
|
+
| Level Up | `levelUpImage(userId, level, options)` | XP progress bar on level-up |
|
|
88
|
+
| Achievement | `achievementImage(userId, title, options)` | Unlockable achievements with rarity tiers |
|
|
89
|
+
| Leaderboard | `leaderboardImage(entries, options)` | Server ranking table |
|
|
90
|
+
| Ship | `shipImage(leftUserId, rightUserId, options)` | Compatibility between two users |
|
|
91
|
+
| Now Playing | `nowPlayingImage(track, options)` | Music player card with source detection |
|
|
92
|
+
| Giveaway | `giveawayImage(prize, options)` | Prize, host, entry count, winners on end |
|
|
93
|
+
|
|
94
|
+
## ๐ ๏ธ Utilities
|
|
95
|
+
|
|
96
|
+
| Function | What it's for |
|
|
97
|
+
| ----------------------------------------------- | ---------------------------------------------------------------------- |
|
|
98
|
+
| `setClient(client)` | Registers your discord.js client โ required before generating any card |
|
|
99
|
+
| `toAttachment(buffer, name, format)` | Wraps a card buffer into a discord.js `AttachmentBuilder` |
|
|
100
|
+
| `encodeCanvas(canvas, options)` | Encodes a raw canvas to `png` / `jpeg` / `webp` |
|
|
101
|
+
| `extensionForFormat(format)` | Returns the file extension for an `OutputFormat` |
|
|
102
|
+
| `setCacheOptions(options)` | Configures the internal user-data cache (enable, TTL) |
|
|
103
|
+
| `clearCache()` | Clears the internal user-data cache |
|
|
104
|
+
| `getCacheSize()` | Returns the number of entries currently cached |
|
|
105
|
+
| `computeCompatibility(leftUserId, rightUserId)` | Deterministic compatibility percentage for the Ship card |
|
|
106
|
+
| `pickShipMessage(percentage)` | Flavor text matching a compatibility percentage |
|
|
107
|
+
| `getThemePalette(theme)` | Resolves a `KiraThemeName` to its full color palette |
|
|
108
|
+
| `fromMoonlinkTrack(track)` | Adapter: moonlink.js track โ `NowPlayingTrack` |
|
|
109
|
+
| `fromLavalinkTrack(track)` | Adapter: Lavalink-based clients โ `NowPlayingTrack` |
|
|
110
|
+
| `fromDiscordPlayerTrack(track)` | Adapter: discord-player track โ `NowPlayingTrack` |
|
|
111
|
+
| `fromDistubeTrack(song)` | Adapter: distube song โ `NowPlayingTrack` |
|
|
112
|
+
| `extractRequesterId(track)` | Pulls the requester's user ID out of any supported track |
|
|
113
|
+
|
|
114
|
+
> `THEMES` (all 8 built-in palettes), `KiraError` / `KiraErrorCode`, and lower-level canvas/validation helpers (`loadImageSafe`, `hexToRgb`, `hexToRgba`, `drawGradientBorder`, `drawCoverImage`, `parseHex`, `decimalToHex`, `parseImg`, `parsePng`, `isString`, `isNumber`) are also exported for advanced use โ see the [documentation](https://guide.worddevs.dev/docs/kira-arts) for details.
|
|
61
115
|
|
|
62
116
|
## ๐ License
|
|
63
117
|
|
|
64
|
-
Apache-2.0
|
|
118
|
+
Kira-Arts is released under the **Apache-2.0 License**.
|
|
119
|
+
|
|
120
|
+
Copyright ยฉ [worddevs](https://github.com/worddevs)
|
|
65
121
|
|
|
66
122
|
## ๐ Links
|
|
67
123
|
|
|
68
|
-
- Documentation
|
|
69
|
-
-
|
|
70
|
-
-
|
|
124
|
+
- ๐ **Documentation:** https://guide.worddevs.dev/docs/kira-arts
|
|
125
|
+
- ๐ฆ **NPM:** https://www.npmjs.com/package/kira-arts
|
|
126
|
+
- ๐ป **Repository:** https://github.com/worddevs/kira-arts
|
|
127
|
+
- ๐ **Issues:** https://github.com/worddevs/kira-arts/issues
|
|
128
|
+
- ๐ **Contributing:** https://github.com/worddevs/kira-arts/blob/main/CONTRIBUTING.md
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
<p align="center">
|
|
133
|
+
Made with ๐ by <a href="https://github.com/worddevs">WordDevs</a>
|
|
134
|
+
</p>
|
|
135
|
+
|
|
136
|
+
<p align="center">
|
|
137
|
+
<sub>Built with TypeScript, designed for performance.</sub>
|
|
138
|
+
</p>
|