kira-arts 1.3.1 โ 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 +63 -44
- package/dist/index.cjs +3638 -3914
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +479 -455
- 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 +19 -12
- package/dist/index.d.ts +0 -595
- package/dist/index.js +0 -4126
- package/dist/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,23 +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://
|
|
6
|
-
|
|
7
|
-
> ๐ง **Heads up:** the documentation is currently hosted at `kira-arts.chocofactory.dev`. This will move to a dedicated, more formal custom domain/branding in an upcoming release โ the link above will be kept up to date when that happens.
|
|
5
|
+
**๐ Full documentation, live examples, and a Playground: [documentation](https://guide.worddevs.dev/docs/kira-arts)**
|
|
8
6
|
|
|
9
7
|
[](https://www.npmjs.com/package/kira-arts)
|
|
10
8
|
[](https://www.npmjs.com/package/kira-arts)
|
|
11
9
|
[](https://packagephobia.com/result?p=kira-arts)
|
|
12
10
|
[](./LICENSE)
|
|
13
11
|
[](https://www.npmjs.com/package/kira-arts)
|
|
14
|
-
[](./dist/index.d.
|
|
12
|
+
[](./dist/index.d.cts)
|
|
15
13
|
[](https://www.typescriptlang.org/)
|
|
16
14
|
[](https://github.com/worddevs/kira-arts/actions/workflows/tests.yml)
|
|
17
15
|
[](https://github.com/worddevs/kira-arts/actions/workflows/release.yml)
|
|
18
16
|
[](https://github.com/worddevs/kira-arts/stargazers)
|
|
19
|
-
[](https://github.com/worddevs/kira-arts/graphs/contributors)
|
|
17
|
+
[](https://github.com/worddevs/kira-arts/commits/main)
|
|
21
18
|
[](https://github.com/worddevs/kira-arts/commits/main)
|
|
22
19
|
[](https://github.com/worddevs/kira-arts/issues)
|
|
23
20
|
[](./CONTRIBUTING.md)
|
|
@@ -25,10 +22,13 @@ A TypeScript library for generating Discord-style visual cards โ profiles, wel
|
|
|
25
22
|
|
|
26
23
|
## โจ Features
|
|
27
24
|
|
|
28
|
-
- ๐ผ๏ธ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility),
|
|
29
|
-
- ๐ต Now Playing card ships with adapters for moonlink.js, Lavalink-based clients, discord-player, and distube
|
|
30
|
-
- ๐จ 8 built-in themes, Nitro/role-color aware borders, and up to 4-color custom gradients
|
|
31
|
-
- ๐งพ 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
|
|
32
32
|
|
|
33
33
|
## ๐ฆ Installation
|
|
34
34
|
|
|
@@ -47,52 +47,71 @@ bun add kira-arts
|
|
|
47
47
|
import { Client, GatewayIntentBits } from "discord.js";
|
|
48
48
|
import { setClient, profileImage, toAttachment } from "kira-arts";
|
|
49
49
|
|
|
50
|
-
const client = new Client({
|
|
50
|
+
const client = new Client({
|
|
51
|
+
intents: [
|
|
52
|
+
GatewayIntentBits.Guilds,
|
|
53
|
+
GatewayIntentBits.GuildMessages,
|
|
54
|
+
GatewayIntentBits.MessageContent,
|
|
55
|
+
],
|
|
56
|
+
});
|
|
51
57
|
|
|
52
58
|
client.once("clientReady", () => {
|
|
53
59
|
setClient(client); // ๐ required before generating any card
|
|
54
60
|
});
|
|
55
61
|
|
|
56
|
-
client.on("
|
|
57
|
-
if (
|
|
62
|
+
client.on("messageCreate", async (message) => {
|
|
63
|
+
if (message.author.bot || message.content !== "!card") return;
|
|
58
64
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
badgesFrame: true,
|
|
66
|
-
});
|
|
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
|
+
});
|
|
67
71
|
|
|
68
|
-
|
|
69
|
-
}
|
|
72
|
+
await message.reply({ files: [toAttachment(buffer, "profile", "png")] });
|
|
70
73
|
});
|
|
71
74
|
|
|
72
75
|
client.login(process.env.TOKEN);
|
|
73
76
|
```
|
|
74
77
|
|
|
75
|
-
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)**.
|
|
76
79
|
|
|
77
80
|
## ๐ Cards at a glance
|
|
78
81
|
|
|
79
|
-
| Card
|
|
80
|
-
|
|
|
81
|
-
| Profile
|
|
82
|
-
| Welcome
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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.
|
|
96
115
|
|
|
97
116
|
## ๐ License
|
|
98
117
|
|
|
@@ -102,7 +121,7 @@ Copyright ยฉ [worddevs](https://github.com/worddevs)
|
|
|
102
121
|
|
|
103
122
|
## ๐ Links
|
|
104
123
|
|
|
105
|
-
- ๐ **Documentation:** https://
|
|
124
|
+
- ๐ **Documentation:** https://guide.worddevs.dev/docs/kira-arts
|
|
106
125
|
- ๐ฆ **NPM:** https://www.npmjs.com/package/kira-arts
|
|
107
126
|
- ๐ป **Repository:** https://github.com/worddevs/kira-arts
|
|
108
127
|
- ๐ **Issues:** https://github.com/worddevs/kira-arts/issues
|
|
@@ -115,5 +134,5 @@ Copyright ยฉ [worddevs](https://github.com/worddevs)
|
|
|
115
134
|
</p>
|
|
116
135
|
|
|
117
136
|
<p align="center">
|
|
118
|
-
<sub>Built with TypeScript
|
|
137
|
+
<sub>Built with TypeScript, designed for performance.</sub>
|
|
119
138
|
</p>
|