kira-arts 1.2.5 → 1.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 A TypeScript library for generating Discord-style visual cards — profiles, welcome/leave events, level-ups, achievements, leaderboards, compatibility "ship" cards, and now-playing music cards — all powered by `@napi-rs/canvas`.
 
+**📚 Full documentation, live examples, and a Playground: [documentation](https://kira-arts.chocofactory.dev/)**
+
 [![npm version](https://img.shields.io/npm/v/kira-arts.svg)](https://www.npmjs.com/package/kira-arts)
 [![npm downloads](https://img.shields.io/npm/dm/kira-arts.svg)](https://www.npmjs.com/package/kira-arts)
 [![install size](https://packagephobia.com/badge?p=kira-arts)](https://packagephobia.com/result?p=kira-arts)
@@ -21,26 +23,17 @@ A TypeScript library for generating Discord-style visual cards — profiles, wel
 
 ## ✨ Features
 
-- 🖼️ **Profile Card** — user profile with avatar, badges, nameplate, server tag, and rank.
-- 👋 **Welcome / Leave Card** — customizable join/leave event cards.
-- 📈 **Level Up Card** — level-up card with an XP progress bar.
-- 🏆 **Achievement Card** — achievement card with rarity (`common`, `rare`, `epic`, `legendary`).
-- 🏅 **Leaderboard Card** — ranking table with up to 15 entries.
-- 💘 **Ship Card** — compatibility card between two users.
-- 🎵 **Now Playing Card** — music player card with progress bar, source badge (YouTube, Spotify, SoundCloud, Twitch, Deezer, Apple Music, etc.), and live-stream support. Ships with adapters for moonlink.js, Lavalink-based clients, discord-player, and distube.
-- 🎨 **Built-in themes**: `discord`, `midnight`, `sunset`, `neon`, `forest`, `sakura`, `monochrome`, `gold`.
-- 🗃️ Configurable internal cache for user data.
-- 🧾 Output as `png`, `jpeg`, or `webp`, ready to use as a discord.js `AttachmentBuilder`.
+- 🖼️ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility), and Now Playing cards
+- 🎵 Now Playing card ships with adapters for moonlink.js, Lavalink-based clients, discord-player, and distube
+- 🎨 8 built-in themes, Nitro/role-color aware borders
+- 🧾 Output as `png`, `jpeg`, or `webp`, ready to use as a discord.js `AttachmentBuilder`
 
 ## 📦 Installation
 
-```cmd
+```bash
 npm install kira-arts
-
-pnpm add kira-arts
-
 yarn add kira-arts
-
+pnpm add kira-arts
 bun add kira-arts
 ```
 
@@ -48,11 +41,9 @@ bun add kira-arts
 
 ## 🚀 Quick usage
 
-Register your discord.js client **once** at startup:
-
 ```ts
 import { Client, GatewayIntentBits } from "discord.js";
-import { setClient } from "kira-arts";
+import { setClient, profileImage, toAttachment } from "kira-arts";
 
 const client = new Client({ intents: [GatewayIntentBits.Guilds] });
 
@@ -61,178 +52,12 @@ client.once("ready", () => {
 });
 
 client.login(process.env.TOKEN);
-```
-
-### Profile card
-
-```ts
-import { profileImage, toAttachment } from "kira-arts";
-
-const buffer = await profileImage(userId, {
-  guildId: interaction.guildId!,
-  useRoleColor: true,
-  theme: "discord",
-  presenceStatus: "online",
-});
-
-const attachment = toAttachment(buffer, "profile", "png");
-await interaction.reply({ files: [attachment] });
-```
-
-### Welcome / leave
-
-```ts
-import { welcomeImage, leaveImage } from "kira-arts";
-
-const buffer = await welcomeImage(userId, guild.name, {
-  memberCount: guild.memberCount,
-  theme: "sunset",
-});
-```
-
-### Level up
-
-```ts
-import { levelUpImage } from "kira-arts";
-
-const buffer = await levelUpImage(userId, 12, {
-  currentXp: 450,
-  requiredXp: 1000,
-  theme: "neon",
-});
-```
-
-### Achievement
-
-```ts
-import { achievementImage } from "kira-arts";
-
-const buffer = await achievementImage(userId, "First victory!", {
-  description: "Win your first ranked match.",
-  rarity: "epic",
-});
-```
-
-### Leaderboard
-
-```ts
-import { leaderboardImage } from "kira-arts";
-
-const buffer = await leaderboardImage(
-  [
-    { userId: "111", currentXp: 900, requiredXp: 1000, level: 20 },
-    { userId: "222", currentXp: 300, requiredXp: 800, level: 14 },
-  ],
-  { title: "Server Top", theme: "gold", maxEntries: 10 },
-);
-```
-
-### Ship (compatibility)
-
-```ts
-import { shipImage } from "kira-arts";
 
-const buffer = await shipImage(userIdA, userIdB, {
-  theme: "midnight",
-  showText: true,
-});
-```
-
-### Now playing
-
-```ts
-import { nowPlayingImage } from "kira-arts";
-
-const buffer = await nowPlayingImage(
-  {
-    title: "Blinding Lights",
-    author: "The Weeknd",
-    artworkUrl: track.artworkUrl,
-    duration: 200_040,
-    sourceName: "spotify",
-  },
-  {
-    position: 45_000,
-    requesterId: interaction.user.id,
-    guildId: interaction.guildId!,
-    theme: "midnight",
-  },
-);
-```
-
-For a livestream / radio, omit `duration` (or set it to `0`) and set `isStream: true` — the card shows a `LIVE` badge and a full progress bar instead of a position.
-
-#### Music library adapters
-
-You don't have to build the `track` object by hand. If you're using a supported player library, convert its track object directly:
-
-```ts
-import { nowPlayingImage, fromMoonlinkTrack, fromLavalinkTrack, fromDiscordPlayerTrack, fromDistubeTrack, extractRequesterId } from "kira-arts";
-
-// moonlink.js
-const buffer = await nowPlayingImage(fromMoonlinkTrack(player.current), {
-  requesterId: extractRequesterId(player.current),
-});
-
-// Lavalink-based clients (erela.js, Shoukaku, Kazagumo, Riffy, Magmastream, lavalink-client)
-const buffer = await nowPlayingImage(fromLavalinkTrack(track));
-
-// discord-player
-const buffer = await nowPlayingImage(fromDiscordPlayerTrack(queue.currentTrack));
-
-// distube
-const buffer = await nowPlayingImage(fromDistubeTrack(queue.songs[0]));
-```
-
-Each adapter is a plain duck-typed converter — kira-arts doesn't depend on any of these libraries, so any object with a matching shape works, including one you build yourself from a raw API response.
-
-## 🎨 Available themes
-
-```
-discord | midnight | sunset | neon | forest | sakura | monochrome | gold
-```
-
-Pass it as `theme` in any card's options, or use `getThemePalette(theme)` to get the raw palette.
-
-## 🗃️ Cache
-
-```ts
-import { setCacheOptions, clearCache, getCacheSize } from "kira-arts";
-
-setCacheOptions({ ttl: 60_000 }); // example, adjust to your actual options
-clearCache();
-console.log(getCacheSize());
-```
-
-## ⚠️ Error handling
-
-Every function throws a `KiraError` with a typed `code` (`KiraErrorCode`):
-
-```ts
-import { KiraError, KiraErrorCode } from "kira-arts";
-
-try {
-  await profileImage(userId);
-} catch (err) {
-  if (err instanceof KiraError && err.code === KiraErrorCode.Validation) {
-    // handle validation error
-  }
-}
-```
-
-Available codes: `Validation`, `Fetch`, `AssetLoad`, `Render`, `Config`.
-
-## 📤 Output format
-
-Every image-generating function returns a `Buffer`. Control format/quality with `output`:
-
-```ts
-await profileImage(userId, {
-  output: { format: "webp", quality: 90 },
-});
+const buffer = await profileImage(userId, { guildId, useRoleColor: true, theme: "discord" });
+await interaction.reply({ files: [toAttachment(buffer, "profile", "png")] });
 ```
 
-Supported formats: `png`, `jpeg`, `webp`.
+Every other card, the music adapters, theming, caching, error handling, and output options are documented with live examples at **[documentation](https://kira-arts.chocofactory.dev/)**.
 
 ## 📄 License
 
@@ -240,5 +65,6 @@ Apache-2.0 © [worddevs](https://github.com/worddevs)
 
 ## 🔗 Links
 
+- Documentation: https://kira-arts.chocofactory.dev/
 - Repository: https://github.com/worddevs/kira-arts
 - Issues: https://github.com/worddevs/kira-arts/issues

package/README.npm.md

@@ -0,0 +1,58 @@
+# kira-arts 💞
+
+A TypeScript library for generating Discord-style visual cards — profiles, welcome/leave events, level-ups, achievements, leaderboards, compatibility "ship" cards, and now-playing music cards — all powered by `@napi-rs/canvas`.
+
+**📚 Full documentation, live examples, and a Playground: [documentation](https://kira-arts.chocofactory.dev/)**
+
+[![npm version](https://img.shields.io/npm/v/kira-arts.svg)](https://www.npmjs.com/package/kira-arts)
+[![license](https://img.shields.io/npm/l/kira-arts.svg)](https://github.com/worddevs/kira-arts/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/kira-arts.svg)](https://www.npmjs.com/package/kira-arts)
+[![types](https://img.shields.io/npm/types/kira-arts.svg)](https://github.com/worddevs/kira-arts)
+
+## ✨ Features
+
+- 🖼️ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility), and Now Playing cards
+- 🎵 Now Playing card ships with adapters for moonlink.js, Lavalink-based clients, discord-player, and distube
+- 🎨 8 built-in themes, Nitro/role-color aware borders
+- 🧾 Output as `png`, `jpeg`, or `webp`, ready to use as a discord.js `AttachmentBuilder`
+
+## 📦 Installation
+
+```bash
+npm install kira-arts
+yarn add kira-arts
+pnpm add kira-arts
+bun add kira-arts
+```
+
+> Requires Node.js >= 20 and a project with `discord.js` ^14.27.0 already installed (peer dependency).
+
+## 🚀 Quick usage
+
+```ts
+import { Client, GatewayIntentBits } from "discord.js";
+import { setClient, profileImage, toAttachment } from "kira-arts";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+client.once("ready", () => {
+  setClient(client); // 👈 required before generating any card
+});
+
+client.login(process.env.TOKEN);
+
+const buffer = await profileImage(userId, { guildId, useRoleColor: true, theme: "discord" });
+await interaction.reply({ files: [toAttachment(buffer, "profile", "png")] });
+```
+
+Every other card, the music adapters, theming, caching, error handling, and output options are documented with live examples at **[kira-arts.chocofactory.dev](https://kira-arts.chocofactory.dev/)**.
+
+## 📄 License
+
+Apache-2.0 © [worddevs](https://github.com/worddevs)
+
+## 🔗 Links
+
+- Documentation: https://kira-arts.chocofactory.dev/
+- Repository: https://github.com/worddevs/kira-arts
+- Issues: https://github.com/worddevs/kira-arts/issues