@mohasinac/appkit 4.63.4 → 4.64.0

package/dist/features/whatsapp-bot/api/webhook/route.js

@@ -0,0 +1,43 @@
+/**
+ * feat-whatsapp-bot — POST /api/whatsapp/webhook
+ *
+ * WhatsApp webhook receiver for incoming messages.
+ *
+ * Consumer stub:
+ * ```ts
+ * export { whatsappWebhookPOST as POST } from "@mohasinac/feat-whatsapp-bot";
+ * ```
+ */
+import { NextResponse } from "next/server.js";
+import { getProviders } from "../../../../contracts/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+export async function POST(request) {
+    try {
+        const body = await request.json();
+        const { db, eventBus } = getProviders();
+        if (!db)
+            return NextResponse.json({ success: false, error: "DB not configured" }, { status: 503 });
+        // Store webhook payload for processing
+        const repo = db.getRepository("whatsapp_messages");
+        const created = await repo.create({
+            ...body,
+            receivedAt: new Date(),
+            processed: false,
+        });
+        // Emit event for async processing if eventBus available
+        if (eventBus) {
+            await eventBus.emit("whatsapp.message.received", created);
+        }
+        return NextResponse.json({
+            success: true,
+            data: created,
+        }, { status: 201 });
+    }
+    catch (error) {
+        void normalizeError(error);
+        return NextResponse.json({
+            success: false,
+            error: error instanceof Error ? error.message : "Internal server error",
+        }, { status: 500 });
+    }
+}

package/dist/features/whatsapp-bot/components/SellerWhatsAppSettingsView.d.ts

@@ -0,0 +1,57 @@
+/**
+ * WHY: a seller's WhatsApp settings are now ONE decision — do they pay the
+ *      monthly fee to have order updates sent to their buyers on the
+ *      platform's WhatsApp number.
+ *
+ * 🛑 This replaced a 574-line credential form that asked every seller for a
+ * WhatsApp Business Account ID, a Catalogue ID and a **System User Access
+ * Token**, then stored that token encrypted on their store document.
+ *
+ * Three things were wrong with it, and they are why none of it is coming back:
+ *
+ *   1. Almost no small seller will create a Meta app and mint a system user
+ *      token. A setting nobody can complete is a feature nobody has.
+ *   2. It made LetItRip the custodian of a live Meta credential per seller.
+ *      `StoreRepository.mapDoc` decrypted that token on EVERY read, so any
+ *      code path that forgot to project was handling plaintext — a gap
+ *      CLAUDE.md flags as deserving its own session.
+ *   3. The catalogue half it existed for is gone: `/whatsapp/{slug}/feed.csv`
+ *      is a public feed the seller points their own Commerce Manager at, so
+ *      no credential crosses the boundary at all.
+ *
+ * WHAT: subscription status, the price, and the toggle.
+ *
+ * ## Presentational on purpose
+ *
+ * Takes the price and the current state as PROPS rather than reading site
+ * settings itself. Site settings are server-read and passed down — the
+ * monthly fee lives beside the platform's Meta credentials in a document that
+ * must never reach a browser, and a client hook here would be a second reader
+ * of it (Root Cause #70).
+ *
+ * EXPORTS: SellerWhatsAppSettingsView, SellerWhatsAppSettingsViewProps
+ *
+ * @tag domain:whatsapp
+ * @tag layer:component
+ * @tag access:client
+ */
+import React from "react";
+export interface SellerWhatsAppSettingsViewProps {
+    /** Is this store currently subscribed? Server-resolved from the store document. */
+    subscribed: boolean;
+    /** Admin-set monthly price, in rupees. Server-resolved from site settings. */
+    monthlyFee: number;
+    /** Currency for the price label. */
+    currency?: string;
+    /**
+     * Is the channel switched on platform-wide? When false the toggle is
+     * disabled and says so — a seller who subscribes into a disabled channel
+     * pays for silence.
+     */
+    channelEnabled: boolean;
+    /** Persists the change. Resolves to the new state. */
+    onToggleSubscription: (next: boolean) => Promise<void>;
+    /** Gate from the store's capabilities; false renders a read-only explanation. */
+    hasCapability?: boolean;
+}
+export declare function SellerWhatsAppSettingsView({ subscribed, monthlyFee, currency, channelEnabled, onToggleSubscription, hasCapability, }: SellerWhatsAppSettingsViewProps): React.JSX.Element;

package/dist/features/whatsapp-bot/components/SellerWhatsAppSettingsView.js

@@ -0,0 +1,76 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * WHY: a seller's WhatsApp settings are now ONE decision — do they pay the
+ *      monthly fee to have order updates sent to their buyers on the
+ *      platform's WhatsApp number.
+ *
+ * 🛑 This replaced a 574-line credential form that asked every seller for a
+ * WhatsApp Business Account ID, a Catalogue ID and a **System User Access
+ * Token**, then stored that token encrypted on their store document.
+ *
+ * Three things were wrong with it, and they are why none of it is coming back:
+ *
+ *   1. Almost no small seller will create a Meta app and mint a system user
+ *      token. A setting nobody can complete is a feature nobody has.
+ *   2. It made LetItRip the custodian of a live Meta credential per seller.
+ *      `StoreRepository.mapDoc` decrypted that token on EVERY read, so any
+ *      code path that forgot to project was handling plaintext — a gap
+ *      CLAUDE.md flags as deserving its own session.
+ *   3. The catalogue half it existed for is gone: `/whatsapp/{slug}/feed.csv`
+ *      is a public feed the seller points their own Commerce Manager at, so
+ *      no credential crosses the boundary at all.
+ *
+ * WHAT: subscription status, the price, and the toggle.
+ *
+ * ## Presentational on purpose
+ *
+ * Takes the price and the current state as PROPS rather than reading site
+ * settings itself. Site settings are server-read and passed down — the
+ * monthly fee lives beside the platform's Meta credentials in a document that
+ * must never reach a browser, and a client hook here would be a second reader
+ * of it (Root Cause #70).
+ *
+ * EXPORTS: SellerWhatsAppSettingsView, SellerWhatsAppSettingsViewProps
+ *
+ * @tag domain:whatsapp
+ * @tag layer:component
+ * @tag access:client
+ */
+import { useState } from "react";
+import { Alert, Badge, Div, Heading, Row, Section, Span, Stack, Text, Toggle, useToast, } from "../../../ui/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+export function SellerWhatsAppSettingsView({ subscribed, monthlyFee, currency = "INR", channelEnabled, onToggleSubscription, hasCapability = true, }) {
+    const [isOn, setIsOn] = useState(subscribed);
+    const [saving, setSaving] = useState(false);
+    const { showToast } = useToast();
+    const handleToggle = async (next) => {
+        if (saving)
+            return;
+        const previous = isOn;
+        setIsOn(next);
+        setSaving(true);
+        try {
+            await onToggleSubscription(next);
+            showToast(next
+                ? "WhatsApp order updates are on. Your buyers will get them from the next order."
+                : "WhatsApp order updates are off. Buyers still get email and in-app updates.", "success");
+        }
+        catch (err) {
+            /*
+             * Not swallowed, and the optimistic flip is REVERTED. A toggle that
+             * stays on after a failed write tells the seller they are subscribed
+             * when they are not — and the first they would hear of it is a buyer
+             * asking why no updates arrived.
+             */
+            void normalizeError(err);
+            setIsOn(previous);
+            showToast("Could not change your subscription. Please try again.", "error");
+        }
+        finally {
+            setSaving(false);
+        }
+    };
+    return (_jsx(Section, { children: _jsxs(Div, { className: "mx-auto max-w-2xl", children: [_jsx(Heading, { level: 1, className: "mb-1", color: "primary", size: "2xl", weight: "bold", children: "WhatsApp order updates" }), _jsx(Text, { variant: "secondary", className: "mb-6", size: "sm", children: "Send your buyers order updates on WhatsApp \u2014 confirmed, shipped, delivered \u2014 from LetItRip's verified business number. You don't need a WhatsApp Business account of your own, and nothing is installed on your phone." }), !channelEnabled && (_jsx(Alert, { variant: "warning", className: "mb-4", children: "WhatsApp updates are currently switched off platform-wide, so nothing will be sent even if you subscribe. We'll start sending as soon as it's back on." })), _jsxs(Stack, { gap: "md", surface: "card", padding: "md", children: [_jsxs(Row, { justify: "between", align: "center", gap: "md", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Subscription" }), _jsx(Badge, { variant: isOn ? "success" : "inactive", children: isOn ? "Active" : "Not subscribed" })] }), _jsxs(Text, { color: "muted", size: "sm", children: [formatCurrency(monthlyFee, currency), " per month. Covers every order update to every buyer \u2014 not charged per message."] })] }), _jsx(Toggle, { checked: isOn, onChange: handleToggle, disabled: saving || !hasCapability, size: "md" })] }), !hasCapability && (_jsx(Div, { textSize: "sm", className: "border border-warning/20", color: "warning", surface: "warning-surface", padding: "inlineSm", rounded: "lg", children: "Your store doesn't have this add-on enabled. Contact support to turn it on." }))] }), _jsx(Heading, { level: 2, className: "mt-8 mb-3", size: "lg", weight: "semibold", children: "What your buyers get" }), _jsxs(Stack, { gap: "sm", surface: "card", padding: "md", children: [_jsxs(Text, { color: "muted", size: "sm", children: ["A WhatsApp message when an order is ", _jsx(Span, { weight: "semibold", children: "confirmed" }), ",", " ", _jsx(Span, { weight: "semibold", children: "shipped" }), ", ", _jsx(Span, { weight: "semibold", children: "delivered" }), ",", " ", _jsx(Span, { weight: "semibold", children: "cancelled" }), " or ", _jsx(Span, { weight: "semibold", children: "refunded" }), ". Nothing promotional \u2014 buyers who opted out of WhatsApp never receive these."] }), _jsx(Text, { color: "muted", size: "sm", children: "Messages come from LetItRip's number, not yours, so your personal number stays private and replies land with our support team rather than on your phone." }), _jsx(Text, { color: "muted", size: "sm", children: "Turning this off changes nothing else: buyers keep getting the same updates by email and in their account." })] })] }) }));
+}

package/dist/features/whatsapp-bot/components/WhatsAppChatButton.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+interface WhatsAppChatButtonProps {
+    waNumber: string;
+    message?: string;
+    label?: string;
+    className?: string;
+}
+export declare function WhatsAppChatButton({ waNumber, message, label, className, }: WhatsAppChatButtonProps): React.JSX.Element;
+export {};

package/dist/features/whatsapp-bot/components/WhatsAppChatButton.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Link from "next/link.js";
+const CLS_WA_BTN = "inline-flex items-center gap-[var(--appkit-space-2)] rounded-lg bg-success-solid px-[var(--appkit-space-4)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] font-semibold text-success-on-solid transition-colors hover:brightness-110";
+export function WhatsAppChatButton({ waNumber, message = "Hi! I have a question.", label = "Chat on WhatsApp", className, }) {
+    const href = `https://wa.me/${waNumber}?text=${encodeURIComponent(message)}`;
+    return (_jsxs(Link, { href: href, target: "_blank", rel: "noopener noreferrer", className: `${CLS_WA_BTN} ${className ?? ""}`, children: [_jsx("svg", { className: "h-4 w-4", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413z" }) }), label] }));
+}

package/dist/features/whatsapp-bot/components/index.d.ts

@@ -0,0 +1,3 @@
+export { WhatsAppChatButton } from "./WhatsAppChatButton";
+export { SellerWhatsAppSettingsView } from "./SellerWhatsAppSettingsView";
+export type { SellerWhatsAppSettingsViewProps } from "./SellerWhatsAppSettingsView";

package/dist/features/whatsapp-bot/components/index.js

@@ -0,0 +1,2 @@
+export { WhatsAppChatButton } from "./WhatsAppChatButton.js";
+export { SellerWhatsAppSettingsView } from "./SellerWhatsAppSettingsView.js";

package/dist/features/whatsapp-bot/helpers/whatsapp.d.ts

@@ -0,0 +1,52 @@
+import type { CheckoutMessageInput, StatusNotificationInput, WebhookVerifyInput, IncomingWebhookPayload, SendWhatsAppInput, StatusMessageInput, WaBusinessSendInput, WaBusinessTemplateSendInput, CatalogSyncInput, CatalogSyncResult, PurchaseAnnouncementInput } from "../types";
+export declare function buildCheckoutMessageURL(input: CheckoutMessageInput): string;
+export declare function buildStatusNotificationURL(input: StatusNotificationInput): string;
+export declare function verifyWebhookSignature(input: WebhookVerifyInput): boolean;
+export declare function isAdminNumber(incomingNumber: string, adminBotNumber: string): boolean;
+/**
+ * Parse an incoming WhatsApp webhook payload (Twilio form-encoded or Wati.io JSON).
+ * Returns null if the payload cannot be parsed or is missing required fields.
+ */
+export declare function parseIncomingWebhookPayload(rawBody: string, contentType: string): IncomingWebhookPayload | null;
+/**
+ * Build a human-readable status notification message for an order.
+ * Pass a custom `statusMessages` map to override the defaults.
+ */
+export declare function buildStatusMessage(input: StatusMessageInput, statusMessages?: Record<string, string>): string;
+/**
+ * Send a WhatsApp message via Meta WhatsApp Business Cloud API.
+ * Distinct from the Twilio-based sendWhatsAppMessage — used for server-initiated
+ * platform announcements. Returns true on success, false on any failure.
+ */
+export declare function sendWhatsAppBusinessMessage(input: WaBusinessSendInput): Promise<boolean>;
+/**
+ * Send a pre-approved Meta message TEMPLATE via WhatsApp Business Cloud API.
+ * Required for business-initiated sends outside the 24h customer-service
+ * window (proactive order/status notifications) — Meta rejects free-form
+ * `sendWhatsAppBusinessMessage` `type: "text"` sends in that case. Returns
+ * true on success, false on any failure (including a missing/unapproved
+ * template — Meta returns a 4xx with an error body, not a network failure).
+ */
+export declare function sendWhatsAppTemplateMessage(input: WaBusinessTemplateSendInput): Promise<boolean>;
+/**
+ * Sync a store's products to a Meta Commerce Catalog via items_batch API.
+ * Batches at 50 items per call (Meta limit). Returns aggregate results.
+ */
+export declare function syncProductsToCatalog(input: CatalogSyncInput): Promise<CatalogSyncResult>;
+/**
+ * Build a plain-text purchase announcement message for WhatsApp.
+ * Sent to admin numbers and store owner when a new order is placed.
+ */
+export declare function buildPurchaseAnnouncementMessage(input: PurchaseAnnouncementInput): string;
+/**
+ * Build a wa.me share link with a pre-filled message.
+ * Opens WhatsApp contact picker — user selects group manually.
+ * This is the only API-compliant way to target a WhatsApp group.
+ */
+export declare function buildGroupShareLink(message: string): string;
+export { buildPaymentProofReviewMessage } from "../../orders/utils/payment-proof-message";
+/**
+ * Send an outbound WhatsApp message via Twilio REST API.
+ * Returns true on success, false on failure.
+ */
+export declare function sendWhatsAppMessage(input: SendWhatsAppInput): Promise<boolean>;

package/dist/features/whatsapp-bot/helpers/whatsapp.js

@@ -0,0 +1,288 @@
+import { normalizeError } from "../../../errors/normalize.js";
+import { createHmac, timingSafeEqual } from "crypto";
+import { getDefaultCurrencySymbol, getDefaultLocale, } from "../../../core/baseline-resolver.js";
+const META_GRAPH_BASE = "https://graph.facebook.com/v20.0";
+export function buildCheckoutMessageURL(input) {
+    const { waNumber, cart, total, address, isPreorder = false } = input;
+    const prefix = isPreorder ? "\uD83D\uDD16 *PRE-ORDER*\n\n" : "";
+    const lines = cart.map((i) => `• ${i.name} ×${i.qty} — ${getDefaultCurrencySymbol()}${(i.salePrice * i.qty).toLocaleString(getDefaultLocale())}`);
+    const body = [
+        `${prefix}Hi Hobson! I'd like to place an order:`,
+        "",
+        ...lines,
+        "",
+        `*Total: ${getDefaultCurrencySymbol()}${total.toLocaleString(getDefaultLocale())}*`,
+        "",
+        `Deliver to: ${address.name}, ${address.line1}${address.line2 ? ", " + address.line2 : ""}, ${address.city} - ${address.pincode}`,
+        `Phone: ${address.phone}`,
+        "",
+        "Please share payment details.",
+    ].join("\n");
+    return `https://wa.me/${waNumber}?text=${encodeURIComponent(body)}`;
+}
+export function buildStatusNotificationURL(input) {
+    const { userPhone, template, vars } = input;
+    const body = template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
+    return `https://wa.me/${userPhone}?text=${encodeURIComponent(body)}`;
+}
+export function verifyWebhookSignature(input) {
+    const { payload, signature, secret } = input;
+    const expected = createHmac("sha256", secret).update(payload).digest("hex");
+    const expectedBuf = Buffer.from(expected, "hex");
+    const sigBuf = Buffer.from(signature, "hex");
+    if (expectedBuf.length !== sigBuf.length)
+        return false;
+    return timingSafeEqual(expectedBuf, sigBuf);
+}
+export function isAdminNumber(incomingNumber, adminBotNumber) {
+    const clean = (n) => n.replace(/\D/g, "");
+    return clean(incomingNumber).endsWith(clean(adminBotNumber));
+}
+/**
+ * Parse an incoming WhatsApp webhook payload (Twilio form-encoded or Wati.io JSON).
+ * Returns null if the payload cannot be parsed or is missing required fields.
+ */
+export function parseIncomingWebhookPayload(rawBody, contentType) {
+    try {
+        if (contentType.includes("application/x-www-form-urlencoded")) {
+            const params = new URLSearchParams(rawBody);
+            const from = params.get("From") ?? "";
+            const body = params.get("Body") ?? "";
+            if (!from || !body)
+                return null;
+            return {
+                from: from.replace(/^whatsapp:/i, "").replace(/\D/g, ""),
+                body: body.trim(),
+            };
+        }
+        // JSON format (Wati.io or generic)
+        const json = JSON.parse(rawBody);
+        const from = typeof json.senderWaId === "string"
+            ? json.senderWaId
+            : typeof json.from === "string"
+                ? json.from
+                : "";
+        const body = typeof json.text?.body ===
+            "string"
+            ? json.text.body
+            : typeof json.body === "string"
+                ? json.body
+                : "";
+        if (!from || !body)
+            return null;
+        return { from: from.replace(/\D/g, ""), body: body.trim() };
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        return null;
+    }
+}
+const DEFAULT_STATUS_MESSAGES = {
+    pending_payment: "🛒 Your order #{id} has been received and is awaiting payment confirmation.",
+    payment_confirmed: "✅ Payment confirmed for order #{id}! We're getting it ready.",
+    processing: "📦 Your order #{id} is being packed and prepared for dispatch.",
+    shipped: "🚚 Your order #{id} is on its way!{tracking}",
+    out_for_delivery: "🏃 Your order #{id} is out for delivery today!",
+    delivered: "🎉 Order #{id} delivered! Thank you for your order!",
+    cancelled: "❌ Your order #{id} has been cancelled. Contact us if you have any questions.",
+    refund_initiated: "💸 Refund initiated for order #{id}. It should reflect within 5–7 business days.",
+};
+/**
+ * Build a human-readable status notification message for an order.
+ * Pass a custom `statusMessages` map to override the defaults.
+ */
+export function buildStatusMessage(input, statusMessages = DEFAULT_STATUS_MESSAGES) {
+    const { orderId, status, trackingNumber, courierName } = input;
+    const template = statusMessages[status] ??
+        `Your order #${orderId} status updated to: ${status}.`;
+    const trackingLine = trackingNumber
+        ? `\nTracking: ${courierName ? courierName + " — " : ""}${trackingNumber}`
+        : "";
+    return template.replace("{id}", orderId).replace("{tracking}", trackingLine);
+}
+/**
+ * Send a WhatsApp message via Meta WhatsApp Business Cloud API.
+ * Distinct from the Twilio-based sendWhatsAppMessage — used for server-initiated
+ * platform announcements. Returns true on success, false on any failure.
+ */
+export async function sendWhatsAppBusinessMessage(input) {
+    const { toPhone, message, phoneNumberId, accessToken } = input;
+    const cleanPhone = toPhone.replace(/\D/g, "");
+    if (!cleanPhone || !phoneNumberId || !accessToken)
+        return false;
+    try {
+        const res = await fetch(`${META_GRAPH_BASE}/${phoneNumberId}/messages`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({
+                messaging_product: "whatsapp",
+                to: cleanPhone,
+                type: "text",
+                text: { body: message },
+            }),
+        });
+        return res.ok;
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        return false;
+    }
+}
+/**
+ * Send a pre-approved Meta message TEMPLATE via WhatsApp Business Cloud API.
+ * Required for business-initiated sends outside the 24h customer-service
+ * window (proactive order/status notifications) — Meta rejects free-form
+ * `sendWhatsAppBusinessMessage` `type: "text"` sends in that case. Returns
+ * true on success, false on any failure (including a missing/unapproved
+ * template — Meta returns a 4xx with an error body, not a network failure).
+ */
+export async function sendWhatsAppTemplateMessage(input) {
+    const { toPhone, phoneNumberId, accessToken, templateName, languageCode, bodyParams } = input;
+    const cleanPhone = toPhone.replace(/\D/g, "");
+    if (!cleanPhone || !phoneNumberId || !accessToken || !templateName)
+        return false;
+    try {
+        const res = await fetch(`${META_GRAPH_BASE}/${phoneNumberId}/messages`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({
+                messaging_product: "whatsapp",
+                to: cleanPhone,
+                type: "template",
+                template: {
+                    name: templateName,
+                    language: { code: languageCode },
+                    ...(bodyParams?.length
+                        ? {
+                            components: [
+                                {
+                                    type: "body",
+                                    parameters: bodyParams.map((text) => ({ type: "text", text })),
+                                },
+                            ],
+                        }
+                        : {}),
+                },
+            }),
+        });
+        return res.ok;
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        return false;
+    }
+}
+/**
+ * Sync a store's products to a Meta Commerce Catalog via items_batch API.
+ * Batches at 50 items per call (Meta limit). Returns aggregate results.
+ */
+export async function syncProductsToCatalog(input) {
+    const { catalogId, accessToken, products } = input;
+    const result = {
+        handles: [],
+        successCount: 0,
+        failureCount: 0,
+        errors: [],
+    };
+    const BATCH_SIZE = 50;
+    for (let i = 0; i < products.length; i += BATCH_SIZE) {
+        const batch = products.slice(i, i + BATCH_SIZE);
+        const requests = batch.map((p) => ({
+            method: "UPDATE",
+            retailer_id: p.id,
+            data: {
+                name: p.title,
+                description: p.description,
+                // Meta expects "<amount> <ISO_CURRENCY>" e.g. "450.00 INR"
+                price: `${p.price.toFixed(2)} ${p.currency}`,
+                image_url: p.imageUrl,
+                availability: p.availability,
+                condition: p.condition,
+                ...(p.link ? { url: p.link } : {}),
+            },
+        }));
+        try {
+            const res = await fetch(`${META_GRAPH_BASE}/${catalogId}/items_batch`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${accessToken}`,
+                },
+                body: JSON.stringify({ requests }),
+            });
+            const json = (await res.json());
+            if (res.ok && json.handles) {
+                result.handles.push(...json.handles);
+                result.successCount += batch.length;
+            }
+            else {
+                result.failureCount += batch.length;
+                result.errors.push(json.error?.message ?? `Batch ${i / BATCH_SIZE + 1} failed`);
+            }
+        }
+        catch (err) {
+            void normalizeError(err);
+            result.failureCount += batch.length;
+            result.errors.push(String(err));
+        }
+    }
+    return result;
+}
+/**
+ * Build a plain-text purchase announcement message for WhatsApp.
+ * Sent to admin numbers and store owner when a new order is placed.
+ */
+export function buildPurchaseAnnouncementMessage(input) {
+    const { buyerName, firstItemName, additionalItemCount, totalAmount, orderId } = input;
+    const extra = additionalItemCount > 0 ? ` + ${additionalItemCount} more item${additionalItemCount > 1 ? "s" : ""}` : "";
+    const amount = totalAmount.toLocaleString("en-IN");
+    return `🛍️ New order! ${buyerName} purchased ${firstItemName}${extra} for ₹${amount}. Order #${orderId}`;
+}
+/**
+ * Build a wa.me share link with a pre-filled message.
+ * Opens WhatsApp contact picker — user selects group manually.
+ * This is the only API-compliant way to target a WhatsApp group.
+ */
+export function buildGroupShareLink(message) {
+    return `https://wa.me/?text=${encodeURIComponent(message)}`;
+}
+/*
+ * `buildPaymentProofReviewMessage` lives in `features/orders/utils/`, not
+ * beside these senders. It is a pure wa.me link-body builder with no crypto
+ * and no network, and it belongs to the orders domain — the move happened
+ * during the 2026-10-20 removal and is kept, because re-homing it here would
+ * drag this file's top-level `crypto` import into the client barrel's graph
+ * (Root Cause #24).
+ */
+export { buildPaymentProofReviewMessage } from "../../orders/utils/payment-proof-message.js";
+/**
+ * Send an outbound WhatsApp message via Twilio REST API.
+ * Returns true on success, false on failure.
+ */
+export async function sendWhatsAppMessage(input) {
+    const { toPhone, message, accountSid, authToken, fromNumber } = input;
+    const cleanPhone = toPhone.replace(/\D/g, "");
+    if (!cleanPhone)
+        return false;
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;
+    const body = new URLSearchParams({
+        From: fromNumber,
+        To: `whatsapp:+${cleanPhone}`,
+        Body: message,
+    });
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`,
+        },
+        body: body.toString(),
+    });
+    return res.ok;
+}

package/dist/features/whatsapp-bot/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./components";
+export { manifest } from "./manifest";

package/dist/features/whatsapp-bot/index.js

@@ -0,0 +1,3 @@
+export * from "./types/index.js";
+export * from "./components/index.js";
+export { manifest } from "./manifest.js";

package/dist/features/whatsapp-bot/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureManifest } from "../../contracts";
+export declare const manifest: FeatureManifest;

package/dist/features/whatsapp-bot/manifest.js

@@ -0,0 +1,13 @@
+export const manifest = {
+    name: "whatsappBot",
+    i18nNamespace: "whatsappBot",
+    envKeys: [
+        "WHATSAPP_BOT_NUMBER",
+        "WHATSAPP_WEBHOOK_SECRET",
+    ],
+    routes: [],
+    apiRoutes: [
+        { segment: "api/whatsapp/webhook", methods: ["POST"] },
+        { segment: "api/whatsapp/send-status", methods: ["POST"] },
+    ],
+};

package/dist/features/whatsapp-bot/messages/en.json

@@ -0,0 +1,7 @@
+{
+    "whatsappBot": {
+        "chatNow": "Chat on WhatsApp",
+        "orderViaWhatsapp": "Order via WhatsApp",
+        "supportViaWhatsapp": "Contact support"
+    }
+}

package/dist/features/whatsapp-bot/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @mohasinac/appkit/features/whatsapp-bot/server
+ *
+ * Server-only entry point for WhatsApp bot helpers (crypto operations).
+ */
+export * from "./helpers/whatsapp";
+export * from "./types";

package/dist/features/whatsapp-bot/server.js

@@ -0,0 +1,7 @@
+/**
+ * @mohasinac/appkit/features/whatsapp-bot/server
+ *
+ * Server-only entry point for WhatsApp bot helpers (crypto operations).
+ */
+export * from "./helpers/whatsapp.js";
+export * from "./types/index.js";