hrvclan 1.0.9 → 1.0.10

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "hrvclan",
-  "version": "1.0.9",
-  "description": "Generate leaderboard card images",
-  "main": "src/index.js",
+  "version": "1.0.10",
+  "description": "Hrv Clans Public NPM Package",
+  "main": "src/main.js",
   "keywords": [
     "leaderboard",
+    "ship",
     "card",
     "image-generator",
     "hrv-web",
@@ -13,8 +14,6 @@
   "author": "Nguyễn Thành Tài",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.13.5",
-    "node-fetch": "^3.3.2",
     "puppeteer": "^24.37.2"
   },
   "files": [

package/readme.md

@@ -1,98 +1,240 @@
-# 📊 Hrv Clans Public NPM Package (CommonJS)
+# 📊 Hrv Clan – Public NPM Package (CommonJS)
+
+Node.js package render:
+
+- 📈 Leaderboard → PNG
+- ❤️ Ship Love Image → PNG
+
+> Works only with CommonJS (`require`)  
+> Do NOT use ESModules
 
-- Action With **CommonJS (`require`)**, not use ESModule.
-- **The Hrv Clan only published the image of leaderboard creation version (Some Features Are Comming Soon)**
 ---
 
-# 🚀 1. Mandatory Requirements
+# 🚀 1. Requirements
 
 - Node.js >= 18
-- CommonJS and not use ESModules
-- Windows / Linux / VPS have run it
+- CommonJS only
+- Windows / Linux / VPS supported
 
-Check Node Version:
+Check version:
 
 ```bash
 node -v
 ```
-## 2. How to use
-### Step 1: Install Module
-```
+
+---
+
+# 📦 2. Installation
+
+```bash
 npm install hrvclan
 ```
-### Step 2: Import Package
-```
+
+---
+
+# 📥 3. Import Package
+
+```js
 const {
   getLeaderboardCardUrl,
   fetchLeaderboardCardImage,
-  saveLeaderboardImage
-} = require('hrvclan');
-```
-### Step 3: Test It Out
+  saveLeaderboardImage,
+  ship
+} = require("hrvclan");
 ```
-const fs = require("fs");
 
-// Import
+---
+
+# 📈 4. Leaderboard Usage
+
+## Example
+
+```js
+const fs = require("fs");
 const {
   getLeaderboardCardUrl,
   fetchLeaderboardCardImage,
   saveLeaderboardImage
 } = require("hrvclan");
 
-// Example Data
 const entries = [
-  {
-    name: "example_jack",
-    score: 9999,
-    avatar: "https://i.pravatar.cc/150?img=1"
-  },
-  {
-    name: "example_nam",
-    score: 7200,
-    avatar: "https://i.pravatar.cc/150?img=2"
-  },
-  {
-    name: "example_linh",
-    score: 5500,
-    avatar: "https://i.pravatar.cc/150?img=3"
-  },
-  {
-    name: "example_hoa",
-    score: 3000,
-    avatar: "https://i.pravatar.cc/150?img=4"
-  }
+  { name: "jack", score: 9999, avatar: "https://i.pravatar.cc/150?img=1" },
+  { name: "nam", score: 7200, avatar: "https://i.pravatar.cc/150?img=2" },
+  { name: "linh", score: 5500, avatar: "https://i.pravatar.cc/150?img=3" },
+  { name: "hoa", score: 3000, avatar: "https://i.pravatar.cc/150?img=4" }
 ];
 
 async function run() {
-  try {
-    // Method 1: Get Link
-    console.log("🔗 URL");
-    const url = getLeaderboardCardUrl(entries);
-    console.log(url);
 
-    console.log("📸 Rendering the image...");
+  // 1️⃣ Get preview URL
+  const url = getLeaderboardCardUrl(entries);
+  console.log("Preview:", url);
 
-    // Method 2: Save Directly
-    await saveLeaderboardImage(entries, "./leaderboard.png");
+  // 2️⃣ Save directly
+  await saveLeaderboardImage(entries, "./leaderboard.png");
 
-    console.log("✅ Saved Files leaderboard.png");
+  // 3️⃣ Get Buffer
+  const buffer = await fetchLeaderboardCardImage(entries, {
+    width: 1080,
+    height: 1920,
+    fullPage: false
+  });
 
-    // Method 3: Get Buffer Image (like method 2)
-    const buffer = await fetchLeaderboardCardImage(entries, {
-      width: 1080,
-      height: 1920,
-      fullPage: false
-    });
+  fs.writeFileSync("leaderboard-buffer.png", buffer);
+}
 
-    fs.writeFileSync("leaderboard-buffer.png", buffer);
+run();
+```
+
+---
 
-    console.log("✅ Saved files leaderboard-buffer.png");
+# ❤️ 5. Ship Usage
 
-  } catch (err) {
-    console.error("❌ Error:", err);
-  }
+Generate love compatibility image.
+
+## Example
+
+```js
+const fs = require("fs");
+const { ship } = require("hrvclan");
+
+async function run() {
+
+  const buffer = await ship({
+    avt1: "https://i.pravatar.cc/150?img=5",
+    avt2: "https://i.pravatar.cc/150?img=6",
+    percent: 88 // optional (random if not provided)
+  });
+
+  fs.writeFileSync("ship.png", buffer);
+
+  console.log("Ship image saved!");
 }
 
 run();
+```
+
+---
+
+# 📚 API Reference
+
+---
+
+## 📈 Leaderboard
+
+### getLeaderboardCardUrl(entries)
+
+Returns HTML preview URL.
+
+```
+string
+```
+
+---
+
+### fetchLeaderboardCardImage(entries, options)
+
+Returns PNG Buffer.
+
+```
+Promise<Buffer>
+```
+
+Options:
+
+| Name | Type |
+|------|------|
+| width | number |
+| height | number |
+| fullPage | boolean |
+
+---
+
+### saveLeaderboardImage(entries, filePath)
+
+Save PNG file directly.
+
+```
+Promise<void>
+```
+
+---
+
+## ❤️ Ship
+
+### ship(options)
+
+Returns PNG Buffer.
+
+```
+Promise<Buffer>
+```
+
+Options:
+
+| Name | Type | Required          |
+|------|------|-------------------|
+| avt1 | string (image URL) | ✅ |
+| avt2 | string (image URL) | ✅ |
+| percent | number (0-100) | ❌ |
+
+If percent is not provided → random 0–100.
+
+---
+
+# 📦 Data Format
+
+Leaderboard entry:
+
+```js
+{
+  name: string,
+  score: number,
+  avatar: string
+}
+```
+
+---
+
+# 🛠 Troubleshooting
+
+### Cannot use import statement outside module
+
+Use:
+
+```js
+require("hrvclan");
+```
+
+NOT:
+
+```js
+import ...
+```
+
+---
+
+### Puppeteer error on VPS
+
+Install:
+
+```bash
+npm install puppeteer --unsafe-perm=true
+```
+
+---
+
+# 🔄 Versioning
+
+Increase version before publishing:
+
+```bash
+npm version patch
+npm publish
+```
+
+---
+
+# 👑 Author
 
-```
+Hrv Clan

package/src/main.js

@@ -0,0 +1,7 @@
+const ship = require("./ship");
+const leaderboard = require("./leaderboard");
+
+module.exports = {
+    ship,
+    leaderboard
+};

package/src/ship.js

@@ -0,0 +1,103 @@
+const { createCanvas, loadImage } = require('canvas');
+const axios = require('axios');
+const path = require('path');
+
+async function safeLoadImage(url, fallbackPath = null) {
+    if (!url || !url.startsWith('http'))
+        return fallbackPath ? loadLocal(fallbackPath) : null;
+
+    try {
+        const response = await axios.get(url, {
+            responseType: 'arraybuffer',
+            timeout: 10000,
+            headers: { 'User-Agent': 'Mozilla/5.0' }
+        });
+        return await loadImage(Buffer.from(response.data));
+    } catch {
+        return fallbackPath ? loadLocal(fallbackPath) : null;
+    }
+}
+
+function loadLocal(p) {
+    try {
+        return loadImage(path.join(__dirname, p));
+    } catch {
+        return null;
+    }
+}
+
+function getEmojiUrl(emoji) {
+    const hex = [...emoji]
+        .map(char => char.codePointAt(0).toString(16))
+        .join('-');
+    return `https://cdnjs.cloudflare.com/ajax/libs/twemoji/14.0.2/72x72/${hex}.png`;
+}
+
+async function generateShipImage(query) {
+    const { bg, avt1, avt2, percent: pQuery } = query;
+    const percent = parseInt(pQuery) || Math.floor(Math.random() * 101);
+
+    const canvas = createCanvas(340, 150);
+    const ctx = canvas.getContext('2d');
+
+    let heartEmoji = '❤️';
+    let glowColor = '#ff0000';
+    if (percent < 20) { heartEmoji = '💔'; glowColor = '#808080'; }
+    else if (percent < 50) { heartEmoji = '🧡'; glowColor = '#ffa500'; }
+    else if (percent < 80) { heartEmoji = '💖'; glowColor = '#ff69b4'; }
+    else { heartEmoji = '❤️‍🔥'; glowColor = '#ffffff'; }
+
+    const [imgBg, imgAvt1, imgAvt2, imgHeart] = await Promise.all([
+        safeLoadImage(bg),
+        safeLoadImage(avt1, 'assets/avatar.png'),
+        safeLoadImage(avt2, 'assets/avatar.png'),
+        safeLoadImage(getEmojiUrl(heartEmoji))
+    ]);
+
+    if (imgBg) ctx.drawImage(imgBg, 0, 0, 340, 150);
+    else {
+        ctx.fillStyle = '#1a1a1a';
+        ctx.fillRect(0, 0, 340, 150);
+    }
+
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.45)';
+    ctx.fillRect(10, 10, 320, 130);
+
+    const drawAvatar = (img, x) => {
+        if (!img) return;
+        ctx.save();
+        ctx.beginPath();
+        ctx.arc(x, 75, 45, 0, Math.PI * 2);
+        ctx.clip();
+        ctx.drawImage(img, x - 45, 30, 90, 90);
+        ctx.restore();
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = 3;
+        ctx.stroke();
+    };
+
+    drawAvatar(imgAvt1, 70);
+    drawAvatar(imgAvt2, 270);
+
+    if (imgHeart) {
+        const size = 95;
+        ctx.save();
+        ctx.shadowBlur = 30;
+        ctx.shadowColor = glowColor;
+        ctx.drawImage(imgHeart, 170 - size / 2, 75 - size / 2, size, size);
+        ctx.restore();
+    }
+
+    ctx.font = 'bold 24px sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.strokeStyle = 'black';
+    ctx.lineWidth = 5;
+    ctx.strokeText(`${percent}%`, 170, 80);
+    ctx.fillStyle = 'white';
+    ctx.fillText(`${percent}%`, 170, 75);
+
+    return canvas.toBuffer('image/png');
+}
+
+module.exports = { generateShipImage };