ikemoji 1.0.5 → 2.0.0

package/index.js

@@ -3,12 +3,17 @@
  * ✔ Keeps original emoji in text (REQUIRED by Telegram)
  * ✔ UTF-16 correct offsets
  * ✔ Handles multiple emojis
+ * ✔ Button helpers (Bot API 9.4+)
  */
 
 const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
 
+// ─────────────────────────────────────────────
+// CORE UTILS
+// ─────────────────────────────────────────────
+
 /**
- * Get UTF-16 code unit length
+ * Get UTF-16 code unit length of a string
  */
 function getUtf16Length(str) {
   let length = 0;
@@ -19,11 +24,40 @@ function getUtf16Length(str) {
 }
 
 /**
- * Replace emojis with custom emoji entities
- * IMPORTANT: stripOriginal MUST be false for Telegram Bot API
+ * Check if string is an emoji
+ */
+function isEmo(str) {
+  return /\p{Extended_Pictographic}/u.test(str);
+}
+
+/**
+ * Merge and sort multiple entity arrays by offset
+ */
+function mergeEntities(baseEntities, newEntities) {
+  const all = [...baseEntities, ...newEntities];
+  all.sort((a, b) => a.offset - b.offset);
+  return all;
+}
+
+// ─────────────────────────────────────────────
+// TEXT / ENTITY HELPERS
+// ─────────────────────────────────────────────
+
+/**
+ * Replace emojis in text with custom emoji entities.
+ * IMPORTANT: Original emoji chars are kept in output — Telegram requires them.
+ *
+ * @param {string} text
+ * @param {Object} emojiMap  - { '⭐': 'custom_emoji_id', ... }
+ * @param {Object} [options]
+ * @param {boolean} [options.skipUnmapped=true] - Drop unmapped emojis from output
+ * @returns {{ text: string, entities: Array }}
+ *
+ * @example
+ * const { text, entities } = emo('Hello ⭐!', { '⭐': '5368324170671202286' });
+ * bot.sendMessage(chatId, text, { entities });
  */
 function emo(text, emojiMap, options = {}) {
-  // Force stripOriginal to false - Telegram REQUIRES the original emoji
   const { skipUnmapped = true } = options;
   const entities = [];
   let out = '';
@@ -31,22 +65,18 @@ function emo(text, emojiMap, options = {}) {
 
   for (const { segment } of segmenter.segment(text)) {
     const id = emojiMap[segment];
-    
     if (id) {
-      // Keep the original emoji (REQUIRED by Telegram)
       out += segment;
       const segmentLength = getUtf16Length(segment);
       entities.push({
         type: 'custom_emoji',
         offset: outOffset,
         length: segmentLength,
-        custom_emoji_id: id
+        custom_emoji_id: id,
       });
       outOffset += segmentLength;
     } else {
-      // Regular text or unmapped emoji
       const isEmoji = isEmo(segment);
-      
       if (!skipUnmapped || !isEmoji) {
         out += segment;
         outOffset += getUtf16Length(segment);
@@ -58,7 +88,12 @@ function emo(text, emojiMap, options = {}) {
 }
 
 /**
- * Generate entities for existing text with emojis
+ * Generate custom_emoji entities for an already-built string.
+ * Use this when you have the final text and just need the entity list.
+ *
+ * @param {string} text
+ * @param {Object} emojiMap
+ * @returns {Array} entities
  */
 function emoEnt(text, emojiMap) {
   const entities = [];
@@ -71,7 +106,7 @@ function emoEnt(text, emojiMap) {
         type: 'custom_emoji',
         offset,
         length: segmentLength,
-        custom_emoji_id: emojiMap[segment]
+        custom_emoji_id: emojiMap[segment],
       });
     }
     offset += getUtf16Length(segment);
@@ -81,7 +116,10 @@ function emoEnt(text, emojiMap) {
 }
 
 /**
- * Find all unique emojis in text
+ * Find all unique emojis present in a string
+ *
+ * @param {string} text
+ * @returns {string[]}
  */
 function findEmo(text) {
   const set = new Set();
@@ -92,59 +130,144 @@ function findEmo(text) {
 }
 
 /**
- * Validate entities array
+ * Validate a custom_emoji entities array
+ *
+ * @param {Array} entities
+ * @param {string} [text] - If provided, checks offsets don't exceed text length
+ * @returns {{ valid: boolean, errors: string[] }}
  */
 function checkEnt(entities, text) {
   const errors = [];
   const textLength = text ? getUtf16Length(text) : Infinity;
-  
+
   if (entities.length > 100) {
     errors.push(`Too many entities (${entities.length})`);
   }
-  
+
   entities.forEach((e, i) => {
-    if (e.type !== 'custom_emoji') {
+    if (e.type !== 'custom_emoji')
       errors.push(`Entity ${i}: invalid type "${e.type}"`);
-    }
-    if (!e.custom_emoji_id) {
+    if (!e.custom_emoji_id)
       errors.push(`Entity ${i}: missing custom_emoji_id`);
-    }
-    if (typeof e.length !== 'number' || e.length < 1) {
+    if (typeof e.length !== 'number' || e.length < 1)
       errors.push(`Entity ${i}: invalid length ${e.length}`);
-    }
-    if (typeof e.offset !== 'number' || e.offset < 0) {
+    if (typeof e.offset !== 'number' || e.offset < 0)
       errors.push(`Entity ${i}: invalid offset ${e.offset}`);
-    }
-    if (text && (e.offset + e.length > textLength)) {
+    if (text && e.offset + e.length > textLength)
       errors.push(`Entity ${i}: offset ${e.offset} + length ${e.length} exceeds text length ${textLength}`);
-    }
   });
-  
+
   return { valid: errors.length === 0, errors };
 }
 
+// ─────────────────────────────────────────────
+// BUTTON HELPERS (Bot API 9.4+)
+// ─────────────────────────────────────────────
+
 /**
- * Check if string is emoji
+ * Add a custom emoji icon to any button object.
+ * Works for both InlineKeyboardButton and KeyboardButton.
+ * Requires bot owner to have Telegram Premium.
+ *
+ * @param {Object} button - Existing button object
+ * @param {string} emojiId - Custom emoji ID
+ * @returns {Object}
+ *
+ * @example
+ * btnEmo({ text: '⭐ Star', callback_data: 'star' }, '5368324170671202286')
  */
-function isEmo(str) {
-  return /\p{Extended_Pictographic}/u.test(str);
+function btnEmo(button, emojiId) {
+  return { ...button, icon_custom_emoji_id: emojiId };
 }
 
 /**
- * Merge and sort entity arrays
+ * Add a custom emoji icon + color style to a button.
+ *
+ * @param {Object} button
+ * @param {string} emojiId
+ * @param {'default'|'secondary'|'destructive'} [style]
+ * @returns {Object}
+ *
+ * @example
+ * btnEmoStyled({ text: '🗑 Delete', callback_data: 'del' }, '5447644880824181073', 'destructive')
  */
-function mergeEntities(baseEntities, newEntities) {
-  const all = [...baseEntities, ...newEntities];
-  all.sort((a, b) => a.offset - b.offset);
-  return all;
+function btnEmoStyled(button, emojiId, style) {
+  const result = { ...button, icon_custom_emoji_id: emojiId };
+  if (style) result.style = style;
+  return result;
+}
+
+/**
+ * Build one keyboard row from an array of button definitions.
+ * Each def may include shorthand `emojiId` and `style` fields
+ * that get wired to icon_custom_emoji_id / style automatically.
+ *
+ * @param {Array<Object>} defs
+ * @returns {Array<Object>} InlineKeyboardButton[]
+ *
+ * @example
+ * buildRow([
+ *   { text: '⭐', callback_data: 'a', emojiId: '111' },
+ *   { text: '💬', callback_data: 'b', emojiId: '222' },
+ * ])
+ */
+function buildRow(defs) {
+  return defs.map(({ emojiId, style, ...button }) => {
+    if (emojiId) button.icon_custom_emoji_id = emojiId;
+    if (style)   button.style = style;
+    return button;
+  });
 }
 
+/**
+ * Build a complete inline keyboard reply_markup from a 2D array of button defs.
+ *
+ * @param {Array<Array<Object>>} rows
+ * @returns {{ inline_keyboard: Array<Array<Object>> }}
+ *
+ * @example
+ * const markup = buildKeyboard([
+ *   [{ text: '⭐ Star', callback_data: 'star', emojiId: '111' }],
+ *   [{ text: '🗑 Delete', callback_data: 'del', emojiId: '222', style: 'destructive' }],
+ * ]);
+ * bot.sendMessage(chatId, text, { entities, ...markup });
+ */
+function buildKeyboard(rows) {
+  return { inline_keyboard: rows.map(buildRow) };
+}
+
+/**
+ * Build a reply keyboard markup from a 2D array of button defs.
+ *
+ * @param {Array<Array<Object>>} rows
+ * @param {Object} [opts] - Extra options e.g. { one_time_keyboard: true }
+ * @returns {{ keyboard, resize_keyboard, ...opts }}
+ */
+function buildReplyKeyboard(rows, opts = {}) {
+  return {
+    keyboard: rows.map(buildRow),
+    resize_keyboard: true,
+    ...opts,
+  };
+}
+
+// ─────────────────────────────────────────────
+// EXPORTS
+// ─────────────────────────────────────────────
+
 module.exports = {
+  // Text / entities
   emo,
   emoEnt,
   findEmo,
   checkEnt,
-  isEmo,
   mergeEntities,
-  getUtf16Length
+  getUtf16Length,
+  isEmo,
+  // Buttons
+  btnEmo,
+  btnEmoStyled,
+  buildRow,
+  buildKeyboard,
+  buildReplyKeyboard,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikemoji",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "Telegram Bot API 9.4 custom emoji helper - UTF-16 correct, ZWJ/skin tone safe, Telegraf compatible",
   "main": "index.js",
   "scripts": {