@prototypevip/baileys 0.1.4 → 0.1.5

package/HELPERS.md

@@ -0,0 +1,107 @@
+# @prototypevip/baileys — Helpers (v0.1.5)
+
+طبقة helpers فوق المسارات الأصلية في المكتبة (`sock.sendMessage` → `nativeFlow` / `album` / `code` / `event` / `product`).
+مفيش بروتوكول جديد هنا؛ كل دالة بتفوّض لمسار موجود ومجرَّب.
+
+## Setup
+
+```js
+import makeWASocket, { attachPrototypeHelpers } from '@prototypevip/baileys'
+
+const sock = makeWASocket({ ... })
+attachPrototypeHelpers(sock)
+```
+
+الدوال متاحة كمان كـ named exports: `sendButtons(sock, jid, content, options)` … إلخ.
+
+## أزرار / قوائم
+
+```js
+await sock.sendButtons(jid, {
+  text: 'اختار', footer: 'Prototype VIP',
+  buttons: [
+    { text: 'Menu', id: '#menu' },
+    { text: 'موقع', url: 'https://example.com' },
+    { text: 'نسخ', copy: 'CODE' },
+    { text: 'اتصل', call: '201234567890' }
+  ]
+}, { quoted: m })
+
+// مع ميديا (بتتحوّل لـ header): image | video | document
+await sock.sendButtons(jid, { text: 'كابشن', image: { url: '...' }, buttons: [...] })
+
+// أيقونة AI (شات خاص فقط — في الجروب بتتجاهل)
+await sock.sendAIMessage(jid, { text: 'أهلا', buttons: [...] })
+
+// قائمة اختيار (single_select داخل Native Flow). legacy: true = listMessage الكلاسيكي
+await sock.sendList(jid, {
+  text: 'القائمة', title: 'T', buttonText: 'افتح',
+  sections: [{ title: 'قسم', rows: [{ title: 'A', description: 'd', id: '#a' }] }]
+})
+
+await sock.sendQuickButtons(jid, 'اختار', ['نعم', 'لا'])
+```
+
+## ألبوم / Carousel
+
+```js
+await sock.sendAlbum(jid, [{ image: { url } , caption: '1' }, { video: { url } }], { delayMs: 1500 })
+
+// Carousel حقيقي (كل كارت لازم image أو video)
+await sock.sendCarousel(jid, {
+  text: 'منتجات', footer: 'Prototype VIP',
+  cards: [{ title: 'منتج 1', body: 'وصف', image: 'https://...', buttons: [{ text: 'اشتري', id: '#buy1' }] }]
+})
+```
+
+## Rich (شكل Meta AI)
+
+```js
+await sock.sendRichCode(jid, { title: 'مثال', code: 'console.log(1)', language: 'javascript' })
+
+// ⚠️ HTML: مفيش render حقيقي لـ HTML جوه الفقاعة في المكتبة.
+// sendRichHtml بيبعت الـ HTML كـ code block ملوّن داخل Rich Response.
+await sock.sendRichHtml(jid, { title: 'Card', html: '<div>...</div>' })
+```
+
+## مكالمات
+
+```js
+// Scheduled Call Event (مفيش WebRTC outbound حقيقي في Baileys)
+await sock.sendScheduledCall(jid, { name: 'اجتماع', startDate: new Date(Date.now() + 3600_000), callType: 'audio' })
+await sock.sendCallInvite(jid, { name: 'مكالمة سريعة', callType: 'video', minutesFromNow: 2 })
+```
+
+## متفرقات
+
+```js
+await sock.sendViewOnce(jid, { image: { url }, caption: 'مرة واحدة' })
+await sock.sendPoll(jid, 'رأيك؟', ['حلو', 'عادي'], { selectableCount: 1 })
+await sock.sendReaction(jid, m.key, '🔥')
+await sock.sendMentionAll(groupJid, 'يا جماعة')
+await sock.sendLocation(jid, 30.04, 31.23, { name: 'القاهرة', address: '...' })
+await sock.sendContact(jid, { fullName: 'أحمد', phone: '201234567890' })
+await sock.sendProduct(jid, { title: 'منتج', price: 100, currencyCode: 'EGP', image: 'https://...' }) // الصورة مطلوبة
+await sock.sendSticker(jid, { url: 'https://.../x.webp' })
+```
+
+## JID / LID
+
+الـ LID **مش** مشتق من رقم التليفون، فالتحويل بيعتمد على mapping حقيقي (`sock.signalRepository.lidMapping`)
+وبيرجّع `null` لو الـ mapping مش معروف.
+
+```js
+await sock.toLid('2010xxxxxxx@s.whatsapp.net') // → '...@lid' | null   (async)
+await sock.toPn('...@lid')                     // → '...@s.whatsapp.net' | null (async)
+sock.normalizeJid('201...:12@s.whatsapp.net')  // يشيل رقم الجهاز بس
+sock.isLid(jid); sock.isPn(jid)
+```
+
+## Builders
+
+```js
+const btn = sock.button()      // Button
+const car = sock.carouselBuilder()
+const rich = sock.aiRich()
+// chain methods ثم .send(jid)
+```

package/lib/Utils/index.js

@@ -34,3 +34,4 @@ export * from "./integrity-guard.js";
 export * from "./newsletter-status.js";
 export * from "./status-helpers.js";
 export * from "./modern-messages.js";
+export * from "./prototype-helpers.js";

package/lib/Utils/messages-media.js

@@ -17,6 +17,7 @@ import {
   DEFAULT_ORIGIN,
   MEDIA_HKDF_KEY_MAPPING,
   MEDIA_PATH_MAP,
+  NEWSLETTER_MEDIA_PATH_MAP,
 } from "../Defaults/index.js";
 import {
   getBinaryNodeChild,
@@ -725,7 +726,7 @@ export const getWAUploadToServer = (
   { customUploadHosts, fetchAgent, logger, options },
   refreshMediaConn,
 ) => {
-  return async (filePath, { mediaType, fileEncSha256B64, timeoutMs }) => {
+  return async (filePath, { mediaType, fileEncSha256B64, timeoutMs, newsletter }) => {
     // send a query JSON to obtain the url & auth token to upload our media
     let uploadInfo = await refreshMediaConn(false);
     let urls;
@@ -745,7 +746,8 @@ export const getWAUploadToServer = (
     for (const { hostname } of hosts) {
       logger.debug(`uploading to "${hostname}"`);
       const auth = encodeURIComponent(uploadInfo.auth);
-      const url = `https://${hostname}${MEDIA_PATH_MAP[mediaType]}/${fileEncSha256B64}?auth=${auth}&token=${fileEncSha256B64}`;
+      const mediaPath = (newsletter && NEWSLETTER_MEDIA_PATH_MAP[mediaType]) || MEDIA_PATH_MAP[mediaType];
+      const url = `https://${hostname}${mediaPath}/${fileEncSha256B64}?auth=${auth}&token=${fileEncSha256B64}`;
       let result;
       try {
         result = await uploadMedia(
@@ -758,8 +760,9 @@ export const getWAUploadToServer = (
           },
           logger,
         );
-        if (result?.url || result?.direct_path) {
+        if (result?.url || result?.direct_path || (newsletter && result?.handle)) {
           urls = {
+            handle: result.handle,
             mediaUrl: result.url,
             directPath: result.direct_path,
             meta_hmac: result.meta_hmac,

package/lib/Utils/messages.js

@@ -402,6 +402,7 @@ export const prepareWAMessageMedia = async (message, options) => {
       fileEncSha256B64: fileSha256B64,
       mediaType: mediaType,
       timeoutMs: options.mediaUploadTimeoutMs,
+      newsletter: true,
     });
     await fs.unlink(filePath);
     const obj = WAProto.Message.fromObject({

package/lib/Utils/newsletter-status.js

@@ -381,6 +381,7 @@ export const makeNewsletterStatusSender = (sock, config) => async (jid, content,
         resolveServerId,
         serverIdTimeoutMs,
         transport,
+        wrapAdminProfile,
         ...messageOptions
     } = options
 
@@ -424,7 +425,7 @@ export const makeNewsletterStatusSender = (sock, config) => async (jid, content,
 
     const node = buildNewsletterStatusNode({
         jid,
-        message: fullMsg.message,
+        message: wrapAdminProfile ? buildNewsletterAdminProfileStatusMessage(fullMsg.message) : fullMsg.message,
         messageId: fullMsg.key.id,
         mediaType,
         mediaHandle: requestedMediaHandle ?? mediaId ?? uploadedMediaHandle,

package/lib/Utils/prototype-helpers.js

@@ -0,0 +1,610 @@
+/**
+ * Prototype VIP Baileys Helpers (0.1.5)
+ *
+ * طبقة helpers سهلة فوق المسارات الأصلية الموجودة في المكتبة
+ * (sock.sendMessage → nativeFlow / album / code / event / product ...).
+ * مفيش هنا أي بروتوكول جديد: كل دالة بتفوّض لمسار مجرَّب جوه المكتبة.
+ */
+
+import { proto } from "../../WAProto/index.js";
+import { generateWAMessageFromContent } from "./messages.js";
+// الكلاسات دي مصدَّرة أصلاً من message-builder.js عن طريق Utils/index.js
+import { Button, ButtonV2, Carousel, AIRich, Toolkit } from "./message-builder.js";
+
+/* ───────────────────────────── internals ───────────────────────────── */
+
+const MEDIA_KEYS = ["image", "video", "document"];
+
+const hasMedia = (obj) => MEDIA_KEYS.some((k) => obj?.[k]);
+
+const isPrivateJid = (jid) =>
+  typeof jid === "string" && (jid.endsWith("@s.whatsapp.net") || jid.endsWith("@lid"));
+
+const assertSock = (sock, method = "sendMessage") => {
+  if (!sock || typeof sock[method] !== "function") {
+    throw new Error(`Invalid socket: sock.${method} is not a function`);
+  }
+};
+
+const defaultRowId = (label) => `#${String(label || "row").trim().replace(/\s+/g, "_")}`;
+
+/**
+ * يحوّل أي شكل مدعوم لزر إلى الصيغة اللي بتفهمها المكتبة في { nativeFlow: [...] }:
+ *   { text, id } | { text, url } | { text, copy } | { text, call } | { text, sections }
+ * ويقبل كمان الصيغ البديلة: rowId / display_text / cta_url / copy_code / phone_number
+ * والصيغة الخام { name, buttonParamsJson } بتعدّي زي ما هي.
+ */
+function normalizeButton(btn) {
+  if (!btn || typeof btn !== "object") {
+    throw new TypeError("Each button must be an object");
+  }
+  if (btn.name && btn.buttonParamsJson) return btn; // native format
+
+  const text = btn.text ?? btn.display_text ?? btn.buttonText ?? btn.title;
+  const out = { text };
+  if (btn.icon) out.icon = btn.icon;
+
+  const id = btn.id ?? btn.rowId;
+  const url = btn.url ?? btn.cta_url;
+  const copy = btn.copy ?? btn.copy_code;
+  const call = btn.call ?? btn.phone_number;
+
+  if (id) out.id = id;
+  else if (copy) out.copy = String(copy);
+  else if (url) {
+    out.url = url;
+    if (btn.useWebview) out.useWebview = btn.useWebview;
+  } else if (call) out.call = String(call);
+  else if (Array.isArray(btn.sections)) out.sections = btn.sections;
+  else out.id = defaultRowId(text || "btn"); // default: quick_reply
+  return out;
+}
+
+/* ───────────────────────────── buttons ───────────────────────────── */
+
+/**
+ * يبني أزرار Native Flow بالصيغة الخام ({ name, buttonParamsJson })
+ * لو عاوز تبعتها مباشرة في interactiveMessage.nativeFlowMessage.buttons.
+ */
+export function buildNativeFlowButtons(buttons = []) {
+  return buttons.map((raw) => {
+    const btn = normalizeButton(raw);
+    if (btn.name && btn.buttonParamsJson) return btn;
+    const label = btn.text;
+    if (btn.id) {
+      return { name: "quick_reply", buttonParamsJson: JSON.stringify({ display_text: label || "Button", id: btn.id }) };
+    }
+    if (btn.copy) {
+      return { name: "cta_copy", buttonParamsJson: JSON.stringify({ display_text: label || "Copy", copy_code: btn.copy }) };
+    }
+    if (btn.url) {
+      return {
+        name: "cta_url",
+        buttonParamsJson: JSON.stringify({ display_text: label || "Open", url: btn.url, merchant_url: btn.url }),
+      };
+    }
+    if (btn.call) {
+      return { name: "cta_call", buttonParamsJson: JSON.stringify({ display_text: label || "Call", phone_number: btn.call }) };
+    }
+    return { name: "single_select", buttonParamsJson: JSON.stringify({ title: label || "Select", sections: btn.sections }) };
+  });
+}
+
+/**
+ * أزرار Native Flow (تفوّض لـ sock.sendMessage → { nativeFlow })
+ *
+ * await sendButtons(sock, jid, {
+ *   text: "اختار", footer: "Prototype VIP",
+ *   buttons: [{ text:"Menu", id:"#menu" }, { text:"Site", url:"https://..." },
+ *             { text:"Copy", copy:"CODE" }, { text:"Call", call:"2012..." }],
+ *   // اختياري: image | video | document (بيتحوّل لـ header)، title، subtitle، ai: true
+ * }, { quoted: m })
+ */
+export async function sendButtons(sock, jid, content = {}, options = {}) {
+  assertSock(sock);
+  const { text, caption, buttons, ai, ...rest } = content;
+
+  if (!Array.isArray(buttons) || buttons.length === 0) {
+    throw new Error("sendButtons requires a non-empty buttons array");
+  }
+
+  const payload = { ...rest, nativeFlow: buttons.map(normalizeButton) };
+
+  // مسار nativeFlow في المكتبة بيستخدم text للنص العادي و caption مع الميديا
+  if (hasMedia(rest)) {
+    payload.caption = caption ?? text ?? "";
+  } else {
+    payload.text = text ?? caption ?? "";
+  }
+
+  // أيقونة الـ AI: sendMessage بيقبلها كـ content.ai وفي الشات الخاص بس
+  const wantAi = ai ?? options.ai ?? options.AI;
+  if (wantAi && isPrivateJid(jid)) payload.ai = true;
+
+  const { ai: _a, AI: _b, ...sendOptions } = options;
+  return sock.sendMessage(jid, payload, sendOptions);
+}
+
+/**
+ * قائمة اختيار. الافتراضي: single_select داخل Native Flow (بيشتغل على الأجهزة الحديثة).
+ * مرّر legacy: true لو عاوز listMessage الكلاسيكي.
+ */
+export async function sendList(sock, jid, content = {}, options = {}) {
+  assertSock(sock);
+  const { text = "", footer, title = "", buttonText = "Select", sections, legacy = false, ...rest } = content;
+
+  if (!Array.isArray(sections) || sections.length === 0) {
+    throw new Error("sendList requires a non-empty sections array");
+  }
+
+  if (legacy) {
+    const msg = generateWAMessageFromContent(
+      jid,
+      {
+        listMessage: {
+          title,
+          description: text,
+          buttonText,
+          listType: proto.Message.ListMessage.ListType.SINGLE_SELECT,
+          footerText: footer || undefined,
+          sections: sections.map((sec) => ({
+            title: sec.title || "",
+            rows: (sec.rows || []).map((row) => ({
+              title: row.title || row.text || "",
+              description: row.description || "",
+              rowId: row.rowId || row.id || defaultRowId(row.title || row.text),
+            })),
+          })),
+        },
+      },
+      { userJid: sock.user?.id, quoted: options.quoted, messageId: options.messageId }
+    );
+    const additionalNodes = isPrivateJid(jid)
+      ? [{ tag: "biz", attrs: {}, content: [{ tag: "list", attrs: { v: "2", type: "product_list" } }] }]
+      : [];
+    await sock.relayMessage(jid, msg.message, {
+      messageId: msg.key.id,
+      additionalNodes: [...(options.additionalNodes || []), ...additionalNodes],
+      useCachedGroupMetadata: options.useCachedGroupMetadata,
+      statusJidList: options.statusJidList,
+    });
+    return msg;
+  }
+
+  const nfSections = sections.map((sec) => ({
+    title: sec.title || "",
+    ...(sec.highlight_label ? { highlight_label: sec.highlight_label } : {}),
+    rows: (sec.rows || []).map((row) => ({
+      header: row.header || "",
+      title: row.title || row.text || "",
+      description: row.description || "",
+      id: row.id || row.rowId || defaultRowId(row.title || row.text),
+    })),
+  }));
+
+  return sendButtons(
+    sock,
+    jid,
+    { ...rest, text, footer, title, buttons: [{ text: buttonText, sections: nfSections }] },
+    options
+  );
+}
+
+/** اختصار: أزرار رد سريع من نصوص بس */
+export async function sendQuickButtons(sock, jid, text, buttonLabels = [], options = {}) {
+  const buttons = buttonLabels.map((label, i) => ({
+    text: label,
+    id: `#btn_${i + 1}`,
+  }));
+  return sendButtons(sock, jid, { text, buttons }, options);
+}
+
+/** رسالة بأيقونة AI (شات خاص فقط — في الجروبات بتتبعت عادي من غير الأيقونة) */
+export async function sendAIMessage(sock, jid, content, options = {}) {
+  const base = typeof content === "string" ? { text: content } : { ...content };
+  if (Array.isArray(base.buttons) && base.buttons.length) {
+    return sendButtons(sock, jid, { ...base, ai: true }, options);
+  }
+  assertSock(sock);
+  const { ai: _a, AI: _b, ...sendOptions } = options;
+  return sock.sendMessage(jid, isPrivateJid(jid) ? { ...base, ai: true } : base, sendOptions);
+}
+
+/* ───────────────────────────── album ───────────────────────────── */
+
+/**
+ * ألبوم صور/فيديوهات. المكتبة بتتوقع album كمصفوفة، وبتقرأ expectedImageCount/
+ * expectedVideoCount من نفس المصفوفة، فبنضيفهم عليها.
+ *
+ * await sendAlbum(sock, jid, [{ image:{url}, caption:"1" }, { video:{url} }], { quoted: m, delayMs: 1500 })
+ */
+export async function sendAlbum(sock, jid, mediaItems = [], options = {}) {
+  assertSock(sock);
+  if (!Array.isArray(mediaItems) || mediaItems.length === 0) {
+    throw new Error("sendAlbum requires a non-empty array of media items");
+  }
+  for (const [i, item] of mediaItems.entries()) {
+    if (!item || (!item.image && !item.video)) {
+      throw new Error(`sendAlbum: item [${i}] must contain image or video`);
+    }
+  }
+  const album = Object.assign([...mediaItems], {
+    expectedImageCount: mediaItems.filter((i) => i.image).length,
+    expectedVideoCount: mediaItems.filter((i) => i.video).length,
+  });
+  return sock.sendMessage(jid, { album }, options);
+}
+
+/* ───────────────────────────── carousel ───────────────────────────── */
+
+/**
+ * Carousel حقيقي عن طريق كلاسات المكتبة (Button.toCard + Carousel).
+ * كل كارت لازم يكون له image أو video.
+ *
+ * await sendCarousel(sock, jid, {
+ *   text: "اختار منتج", footer: "Prototype VIP",
+ *   cards: [{ title:"منتج 1", body:"وصف", image:"https://..." (أو Buffer), buttons:[{ text:"اشتري", id:"#buy1" }] }]
+ * })
+ */
+export async function sendCarousel(sock, jid, content = {}, options = {}) {
+  assertSock(sock, "relayMessage");
+  const { text = "", footer = "", cards } = content;
+  if (!Array.isArray(cards) || cards.length === 0) {
+    throw new Error("sendCarousel requires a non-empty cards array");
+  }
+
+  const carousel = new Carousel(sock).setBody(text);
+  if (footer) carousel.setFooter(footer);
+
+  for (const [i, card] of cards.entries()) {
+    const media = card.image ?? card.video;
+    if (!media) throw new Error(`sendCarousel: card [${i}] must include image or video`);
+
+    const b = new Button(sock);
+    if (card.title) b.setTitle(card.title);
+    if (card.subtitle) b.setSubtitle(card.subtitle);
+    b.setBody(card.body || card.caption || card.title || " ");
+    if (card.footer) b.setFooter(card.footer);
+
+    const toData = (m, kind) => (Buffer.isBuffer(m) ? { [kind]: m } : typeof m === "string" ? { [kind]: { url: m } } : { [kind]: m });
+    b.setMedia(card.image ? toData(card.image, "image") : toData(card.video, "video"));
+
+    for (const nb of buildNativeFlowButtons(card.buttons || [])) {
+      b.addButton(nb.name, nb.buttonParamsJson);
+    }
+    carousel.addCard(await b.toCard());
+  }
+
+  await carousel.send(jid, { userJid: sock.user?.id, ...options });
+}
+
+/* ───────────────────────────── rich (AI) ───────────────────────────── */
+
+/**
+ * ⚠️ مهم: واتساب/المكتبة مفيهاش render حقيقي لـ HTML داخل الفقاعة.
+ * اللي بيحصل فعلياً: بتتبعت رسالة Rich Response (شكل Meta AI) والـ HTML
+ * بيظهر كـ code block ملوّن (syntax highlight) — ده المسار الوحيد المدعوم
+ * والمجرَّب في المكتبة (prepareRichResponseMessage).
+ */
+export async function sendRichHtml(sock, jid, content, options = {}) {
+  assertSock(sock);
+  const { title, html = "", summary, footer } = typeof content === "string" ? { html: content } : content || {};
+  if (!html) throw new Error("sendRichHtml requires html");
+
+  return sock.sendMessage(
+    jid,
+    {
+      ...(title ? { headerText: title } : {}),
+      ...(summary ? { contentText: summary } : {}),
+      code: html,
+      language: "html",
+      ...(footer ? { footerText: footer } : {}),
+    },
+    options
+  );
+}
+
+/** alias قديم — نفس sendRichHtml (اتشال منه المسار الوهمي AIRich.html) */
+export async function sendRichHtmlAdvanced(sock, jid, content, options = {}) {
+  return sendRichHtml(sock, jid, content, options);
+}
+
+/** رسالة Rich بكود ملوّن بأي لغة */
+export async function sendRichCode(sock, jid, { code, language = "javascript", title, summary, footer } = {}, options = {}) {
+  assertSock(sock);
+  if (!code) throw new Error("sendRichCode requires code");
+  return sock.sendMessage(
+    jid,
+    {
+      ...(title ? { headerText: title } : {}),
+      ...(summary ? { contentText: summary } : {}),
+      code,
+      language,
+      ...(footer ? { footerText: footer } : {}),
+    },
+    options
+  );
+}
+
+/* ───────────────────────────── misc senders ───────────────────────────── */
+
+export async function sendViewOnce(sock, jid, content, options = {}) {
+  assertSock(sock);
+  const payload = typeof content === "string" ? { text: content } : { ...content };
+  return sock.sendMessage(jid, { ...payload, viewOnce: true }, options);
+}
+
+export async function sendReaction(sock, jid, key, emoji = "👍") {
+  assertSock(sock);
+  return sock.sendMessage(jid, { react: { text: emoji, key } });
+}
+
+export async function sendPoll(sock, jid, name, values = [], options = {}) {
+  assertSock(sock);
+  const { selectableCount = 1, ...sendOptions } = options;
+  return sock.sendMessage(jid, { poll: { name, values, selectableCount } }, sendOptions);
+}
+
+/** منشن لكل أعضاء الجروب (بيرمي خطأ لو معرفش يجيب الأعضاء بدل ما يبعت من غير منشن) */
+export async function sendMentionAll(sock, jid, text, options = {}) {
+  assertSock(sock);
+  if (!jid.endsWith("@g.us")) throw new Error("sendMentionAll only works in groups");
+  const meta = await sock.groupMetadata(jid);
+  const mentions = (meta.participants || []).map((p) => p.id).filter(Boolean);
+  return sock.sendMessage(jid, { text, mentions }, options);
+}
+
+/** options: { name, address, ...sendOptions } */
+export async function sendLocation(sock, jid, degreesLatitude, degreesLongitude, options = {}) {
+  assertSock(sock);
+  const { name = "", address = "", ...sendOptions } = options;
+  return sock.sendMessage(
+    jid,
+    { location: { degreesLatitude, degreesLongitude, name, address } },
+    sendOptions
+  );
+}
+
+/** contacts: { fullName|name, phone|number, organization|org } أو مصفوفة منهم */
+export async function sendContact(sock, jid, contacts, options = {}) {
+  assertSock(sock);
+  const clean = (s) => String(s ?? "").replace(/[\r\n;,\\]/g, " ").trim();
+  const list = (Array.isArray(contacts) ? contacts : [contacts]).map((c) => {
+    const phone = String(c.phone || c.number || "").replace(/\D/g, "");
+    if (!phone) throw new Error("sendContact: phone is required");
+    const name = clean(c.fullName || c.name || phone);
+    const org = clean(c.organization || c.org);
+    const vcard =
+      `BEGIN:VCARD\nVERSION:3.0\nFN:${name}\n` +
+      (org ? `ORG:${org}\n` : "") +
+      `TEL;type=CELL;type=VOICE;waid=${phone}:+${phone}\nEND:VCARD`;
+    return { displayName: name, vcard };
+  });
+
+  return sock.sendMessage(
+    jid,
+    {
+      contacts: {
+        displayName: list.length === 1 ? list[0].displayName : `${list.length} contacts`,
+        contacts: list,
+      },
+    },
+    options
+  );
+}
+
+/** product: { title, description, price, currencyCode, productId, retailerId, url, image|thumbnail } (الصورة مطلوبة) */
+export async function sendProduct(sock, jid, product = {}, options = {}) {
+  assertSock(sock);
+  const productImage = product.image || product.thumbnail || product.productImage;
+  if (!productImage) throw new Error("sendProduct requires an image (image | thumbnail | productImage)");
+  const image = typeof productImage === "string" ? { url: productImage } : productImage;
+
+  return sock.sendMessage(
+    jid,
+    {
+      product: {
+        productId: String(product.productId || "1"),
+        title: product.title || "Product",
+        description: product.description || "",
+        currencyCode: product.currencyCode || "USD",
+        priceAmount1000: product.price ? Math.round(Number(product.price) * 1000) : 0,
+        retailerId: product.retailerId || "prototypevip",
+        url: product.url || "",
+        productImageCount: 1,
+        productImage: image,
+      },
+      businessOwnerJid: product.businessOwnerJid || sock.user?.id,
+      body: product.body || product.description || "",
+      footer: product.footer || "",
+    },
+    options
+  );
+}
+
+/** sticker: Buffer | { url } | رابط/مسار نصي */
+export async function sendSticker(sock, jid, sticker, options = {}) {
+  assertSock(sock);
+  const media = typeof sticker === "string" ? { url: sticker } : sticker;
+  return sock.sendMessage(jid, { sticker: media }, options);
+}
+
+/* ───────────────────────────── calls ───────────────────────────── */
+
+/**
+ * مكالمة مجدولة (Event بنوع call). مفيش outbound WebRTC call حقيقي في Baileys.
+ * callType: "audio" | "video"
+ */
+export async function sendScheduledCall(sock, jid, content = {}, options = {}) {
+  assertSock(sock);
+  const {
+    name = "Call",
+    description = "",
+    startDate = new Date(Date.now() + 5 * 60 * 1000),
+    endDate,
+    callType = "audio",
+    extraGuestsAllowed = true,
+    location,
+  } = content;
+
+  const toDate = (d) => (d instanceof Date ? d : new Date(d));
+  const start = toDate(startDate);
+  if (Number.isNaN(start.getTime())) throw new Error("sendScheduledCall: invalid startDate");
+  const end = endDate ? toDate(endDate) : new Date(start.getTime() + 60 * 60 * 1000);
+  if (Number.isNaN(end.getTime())) throw new Error("sendScheduledCall: invalid endDate");
+
+  return sock.sendMessage(
+    jid,
+    {
+      event: {
+        name,
+        description,
+        startDate: start,
+        endDate: end,
+        call: callType === "video" ? "video" : "audio",
+        isScheduleCall: true,
+        extraGuestsAllowed,
+        location,
+      },
+    },
+    options
+  );
+}
+
+export async function sendCallInvite(sock, jid, content = {}, options = {}) {
+  const {
+    name = "مكالمة واردة",
+    description = "اضغط للانضمام للمكالمة",
+    callType = "audio",
+    minutesFromNow = 2,
+  } = typeof content === "string" ? { name: content } : content;
+
+  return sendScheduledCall(
+    sock,
+    jid,
+    {
+      name,
+      description,
+      startDate: new Date(Date.now() + minutesFromNow * 60 * 1000),
+      callType,
+      extraGuestsAllowed: true,
+    },
+    options
+  );
+}
+
+/* ───────────────────────────── JID / LID ───────────────────────────── */
+
+export function isLid(jid) {
+  return typeof jid === "string" && jid.endsWith("@lid");
+}
+
+export function isPn(jid) {
+  return typeof jid === "string" && jid.endsWith("@s.whatsapp.net");
+}
+
+const stripDevice = (jid) => {
+  if (typeof jid !== "string") return jid;
+  const [user, server] = jid.split("@");
+  return `${user.split(":")[0]}@${server}`;
+};
+
+/**
+ * LID مش مشتق من رقم التليفون — لازم mapping حقيقي من WhatsApp.
+ * بتستعمل sock.signalRepository.lidMapping. بترجّع null لو الـ mapping مش معروف.
+ */
+export async function toLid(sock, jid) {
+  if (!jid) return jid;
+  if (isLid(jid)) return stripDevice(jid);
+  const lid = await sock?.signalRepository?.lidMapping?.getLIDForPN?.(stripDevice(jid));
+  return lid ? stripDevice(lid) : null;
+}
+
+export async function toPn(sock, jid) {
+  if (!jid) return jid;
+  if (isPn(jid)) return stripDevice(jid);
+  const pn = await sock?.signalRepository?.lidMapping?.getPNForLID?.(stripDevice(jid));
+  return pn ? stripDevice(pn) : null;
+}
+
+/** يشيل رقم الجهاز (:12) من أي JID من غير ما يغيّر نوعه */
+export function normalizeJid(jid) {
+  return stripDevice(jid);
+}
+
+/* ───────────────────────────── attach ───────────────────────────── */
+
+/**
+ * يربط كل الـ helpers على sock:
+ *   attachPrototypeHelpers(sock); await sock.sendButtons(jid, {...})
+ */
+export function attachPrototypeHelpers(sock) {
+  if (!sock || typeof sock.relayMessage !== "function" || typeof sock.sendMessage !== "function") {
+    throw new Error("Invalid socket instance");
+  }
+
+  sock.sendButtons = (jid, content, opts) => sendButtons(sock, jid, content, opts);
+  sock.sendList = (jid, content, opts) => sendList(sock, jid, content, opts);
+  sock.sendAlbum = (jid, media, opts) => sendAlbum(sock, jid, media, opts);
+  sock.sendRichHtml = (jid, content, opts) => sendRichHtml(sock, jid, content, opts);
+  sock.sendRichHtmlAdvanced = (jid, content, opts) => sendRichHtmlAdvanced(sock, jid, content, opts);
+  sock.sendRichCode = (jid, content, opts) => sendRichCode(sock, jid, content, opts);
+  sock.sendAIMessage = (jid, content, opts) => sendAIMessage(sock, jid, content, opts);
+  sock.sendQuickButtons = (jid, text, labels, opts) => sendQuickButtons(sock, jid, text, labels, opts);
+  sock.sendCarousel = (jid, content, opts) => sendCarousel(sock, jid, content, opts);
+  sock.sendViewOnce = (jid, content, opts) => sendViewOnce(sock, jid, content, opts);
+  sock.sendReaction = (jid, key, emoji) => sendReaction(sock, jid, key, emoji);
+  sock.sendPoll = (jid, name, values, opts) => sendPoll(sock, jid, name, values, opts);
+  sock.sendMentionAll = (jid, text, opts) => sendMentionAll(sock, jid, text, opts);
+  sock.sendLocation = (jid, lat, lng, opts) => sendLocation(sock, jid, lat, lng, opts);
+  sock.sendContact = (jid, contacts, opts) => sendContact(sock, jid, contacts, opts);
+  sock.sendProduct = (jid, product, opts) => sendProduct(sock, jid, product, opts);
+  sock.sendSticker = (jid, sticker, opts) => sendSticker(sock, jid, sticker, opts);
+  sock.sendScheduledCall = (jid, content, opts) => sendScheduledCall(sock, jid, content, opts);
+  sock.sendCallInvite = (jid, content, opts) => sendCallInvite(sock, jid, content, opts);
+
+  // JID / LID
+  sock.toLid = (jid) => toLid(sock, jid); // async
+  sock.toPn = (jid) => toPn(sock, jid); // async
+  sock.isLid = isLid;
+  sock.isPn = isPn;
+  sock.normalizeJid = normalizeJid;
+
+  // Builders (من message-builder.js)
+  sock.button = () => new Button(sock);
+  sock.buttonV2 = () => new ButtonV2(sock);
+  sock.carouselBuilder = () => new Carousel(sock);
+  sock.aiRich = () => new AIRich(sock);
+  sock.Toolkit = Toolkit;
+
+  return sock;
+}
+
+export default {
+  buildNativeFlowButtons,
+  sendButtons,
+  sendList,
+  sendAlbum,
+  sendRichHtml,
+  sendRichHtmlAdvanced,
+  sendRichCode,
+  sendAIMessage,
+  sendQuickButtons,
+  sendCarousel,
+  sendViewOnce,
+  sendReaction,
+  sendPoll,
+  sendMentionAll,
+  sendLocation,
+  sendContact,
+  sendProduct,
+  sendSticker,
+  sendScheduledCall,
+  sendCallInvite,
+  toLid,
+  toPn,
+  isLid,
+  isPn,
+  normalizeJid,
+  attachPrototypeHelpers,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@prototypevip/baileys",
-  "version": "0.1.4",
-  "description": "Baileys fork (@prototypevip/baileys) — clean + Channel/Group/Personal Status APIs (0.1.4)",
+  "version": "0.1.5",
+  "description": "Baileys fork (@prototypevip/baileys) — clean + Channel/Group/Personal Status + Interactive Buttons/Lists/Album/Carousel + Rich code responses + Call Invites helpers (0.1.5)",
   "main": "lib/index.js",
   "type": "module",
   "scripts": {
@@ -20,7 +20,8 @@
   "files": [
     "lib/**/*",
     "WAProto/**/*",
-    "engine-requirements.js"
+    "engine-requirements.js",
+    "HELPERS.md"
   ],
   "keywords": [
     "automation",
@@ -34,7 +35,13 @@
     "whatsapp-bot",
     "whatsapp-chat",
     "whatsapp-group",
-    "whatsapp-web"
+    "whatsapp-web",
+    "interactive-messages",
+    "buttons",
+    "album",
+    "native-flow",
+    "call-invite",
+    "rich-response"
   ],
   "homepage": "https://github.com/GSK-F/baileys",
   "author": "The Prototype",