@prototypevip/baileys 0.1.4 → 0.1.6

package/lib/Utils/prototype-helpers.js

@@ -0,0 +1,732 @@
+/**
+ * Prototype VIP Baileys Helpers (0.1.6)
+ *
+ * طبقة helpers سهلة فوق المسارات الأصلية الموجودة في المكتبة
+ * (sock.sendMessage → nativeFlow / album / code / event / product ...).
+ * مفيش هنا أي بروتوكول جديد: كل دالة بتفوّض لمسار مجرَّب جوه المكتبة.
+ */
+
+import { proto } from "../../WAProto/index.js";
+import { generateWAMessageFromContent } from "./messages.js";
+import { wrapViewOnce } from "./view-once.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`);
+  }
+};
+
+/** View-Once من content.viewOnce أو options.viewOnce (true | "v2" | "force" | {version,force}) */
+const pickViewOnce = (content, options) => content?.viewOnce ?? options?.viewOnce;
+
+const MIME_BY_EXT = {
+  pdf: "application/pdf",
+  zip: "application/zip",
+  rar: "application/vnd.rar",
+  "7z": "application/x-7z-compressed",
+  txt: "text/plain",
+  json: "application/json",
+  csv: "text/csv",
+  html: "text/html",
+  js: "text/javascript",
+  apk: "application/vnd.android.package-archive",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  mp3: "audio/mpeg",
+  mp4: "video/mp4",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+};
+
+const mimeFromName = (name = "") => MIME_BY_EXT[String(name).split("?")[0].split(".").pop()?.toLowerCase()] || "application/octet-stream";
+
+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,
+      wrapViewOnce({
+        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),
+            })),
+          })),
+        },
+      }, pickViewOnce(content, options)),
+      { 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,
+  });
+  const { viewOnce, ...sendOptions } = options;
+  return sock.sendMessage(jid, { album, ...(viewOnce ? { viewOnce } : {}) }, sendOptions);
+}
+
+/* ───────────────────────────── 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);
+  const viewOnce = pickViewOnce(content, options);
+  if (viewOnce) carousel.setViewOnce(viewOnce);
+
+  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());
+  }
+
+  const { viewOnce: _vo, ...sendOptions } = options;
+  return carousel.send(jid, { userJid: sock.user?.id, ...sendOptions });
+}
+
+/* ───────────────────────────── 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 ───────────────────────────── */
+
+/**
+ * View-Once لأي نوع رسالة (0.1.6) — مش صورة/فيديو/صوت بس:
+ *   نص، ملف، أزرار، قائمة، كاروسيل، ألبوم، منتج، لوكيشن، جهة اتصال، Rich ...
+ *
+ *   await sendViewOnce(sock, jid, { image: { url }, caption: "x" })
+ *   await sendViewOnce(sock, jid, { text: "x", buttons: [...] })          // → sendButtons
+ *   await sendViewOnce(sock, jid, { text: "x", sections: [...] })         // → sendList
+ *   await sendViewOnce(sock, jid, { text: "x", cards: [...] })            // → sendCarousel
+ *   await sendViewOnce(sock, jid, [{ image }, { video }])                 // → sendAlbum
+ *   options.viewOnce = true | "v2" | "force"  (الافتراضي true)
+ */
+export async function sendViewOnce(sock, jid, content, options = {}) {
+  assertSock(sock);
+  const flag = (typeof content === "object" && !Array.isArray(content) && content?.viewOnce) || options.viewOnce || true;
+  const opts = { ...options, viewOnce: flag };
+
+  if (Array.isArray(content)) return sendAlbum(sock, jid, content, opts);
+
+  const payload = typeof content === "string" ? { text: content } : { ...content };
+  delete payload.viewOnce;
+
+  if (Array.isArray(payload.cards)) return sendCarousel(sock, jid, payload, opts);
+  if (Array.isArray(payload.sections)) return sendList(sock, jid, payload, opts);
+  if (Array.isArray(payload.buttons) && payload.buttons.length) return sendButtons(sock, jid, payload, opts);
+  return sock.sendMessage(jid, { ...payload, viewOnce: flag }, options);
+}
+
+/* ───────────────────────────── extras (0.1.6) ───────────────────────────── */
+
+/**
+ * ملف/مستند. source: { url } | Buffer | رابط نصي | { document, fileName, mimetype, caption }
+ *   await sendDocument(sock, jid, { url: "https://x/a.pdf", fileName: "a.pdf", caption: "تفضل" }, { viewOnce: true })
+ */
+export async function sendDocument(sock, jid, content = {}, options = {}) {
+  assertSock(sock);
+  const src = typeof content === "string" ? { url: content } : Buffer.isBuffer(content) ? { document: content } : { ...content };
+  const doc = src.document ?? src.file ?? src.buffer ?? (src.url ? { url: src.url } : undefined);
+  if (!doc) throw new Error("sendDocument requires document | file | buffer | url");
+  const document = typeof doc === "string" ? { url: doc } : doc;
+  const urlLike = document?.url || (typeof src.url === "string" ? src.url : "");
+  const fileName = src.fileName || src.filename || src.name || (urlLike ? String(urlLike).split("?")[0].split("/").pop() : "file");
+  const mimetype = src.mimetype || src.mime || mimeFromName(fileName);
+  const { caption, text } = src;
+  return sock.sendMessage(
+    jid,
+    { document, fileName, mimetype, ...(caption || text ? { caption: caption ?? text } : {}) },
+    options
+  );
+}
+
+/** تعديل رسالة بعتّها قبل كده (نص/كابشن) */
+export async function sendEdit(sock, jid, key, content, options = {}) {
+  assertSock(sock);
+  if (!key) throw new Error("sendEdit requires the original message key");
+  const payload = typeof content === "string" ? { text: content } : { ...content };
+  return sock.sendMessage(jid, { ...payload, edit: key }, options);
+}
+
+/** حذف رسالة للكل */
+export async function sendDelete(sock, jid, key) {
+  assertSock(sock);
+  if (!key) throw new Error("sendDelete requires the message key");
+  return sock.sendMessage(jid, { delete: key });
+}
+
+/**
+ * يبعت بعد ما يعمل "بيكتب..." (أو "بيسجل..." لو recording) لمدة typingMs
+ *   await sendWithTyping(sock, jid, { text: "أهلا" }, { typingMs: 1200 })
+ */
+export async function sendWithTyping(sock, jid, content, options = {}) {
+  assertSock(sock);
+  const { typingMs = 1000, presence = "composing", ...sendOptions } = options;
+  const canPresence = typeof sock.sendPresenceUpdate === "function";
+  try {
+    if (canPresence) {
+      await sock.sendPresenceUpdate(presence, jid);
+      await new Promise((r) => setTimeout(r, Math.max(0, Number(typingMs) || 0)));
+    }
+    const payload = typeof content === "string" ? { text: content } : content;
+    return await sock.sendMessage(jid, payload, sendOptions);
+  } finally {
+    if (canPresence) await sock.sendPresenceUpdate("paused", jid).catch(() => {});
+  }
+}
+
+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.sendDocument = (jid, content, opts) => sendDocument(sock, jid, content, opts);
+  sock.sendEdit = (jid, key, content, opts) => sendEdit(sock, jid, key, content, opts);
+  sock.sendDelete = (jid, key) => sendDelete(sock, jid, key);
+  sock.sendWithTyping = (jid, content, opts) => sendWithTyping(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,
+  sendDocument,
+  sendEdit,
+  sendDelete,
+  sendWithTyping,
+  sendReaction,
+  sendPoll,
+  sendMentionAll,
+  sendLocation,
+  sendContact,
+  sendProduct,
+  sendSticker,
+  sendScheduledCall,
+  sendCallInvite,
+  toLid,
+  toPn,
+  isLid,
+  isPn,
+  normalizeJid,
+  attachPrototypeHelpers,
+};