@mohasinac/appkit 4.63.4 → 4.63.5

package/dist/features/account/components/BuyerShoppingGuideView.js

@@ -25,7 +25,7 @@ const SECTIONS = [
     },
     {
         Icon: CheckCircle, title: "Order Confirmation",
-        content: (_jsxs(_Fragment, { children: [_jsx(Text, { className: GC.textMuted, children: "After a successful payment you'll see an on-screen confirmation with your order ID. You'll also receive:" }), _jsxs(Ul, { className: `${GC.listDiscMuted} mt-3`, children: [_jsx(Li, { children: "An email confirmation to your registered address" }), _jsx(Li, { children: "An in-app notification you can read any time from the bell in the header" })] }), _jsxs(Text, { className: `${GC.textMuted} mt-3`, children: ["View all your orders at any time under ", _jsx(Span, { weight: "bold", children: "My Account \u2192 My Orders" }), "."] })] })),
+        content: (_jsxs(_Fragment, { children: [_jsx(Text, { className: GC.textMuted, children: "After a successful payment you'll see an on-screen confirmation with your order ID. You'll also receive:" }), _jsxs(Ul, { className: `${GC.listDiscMuted} mt-3`, children: [_jsx(Li, { children: "An email confirmation to your registered address" }), _jsx(Li, { children: "A WhatsApp message if you've added and verified your phone number" })] }), _jsxs(Text, { className: `${GC.textMuted} mt-3`, children: ["View all your orders at any time under ", _jsx(Span, { weight: "bold", children: "My Account \u2192 My Orders" }), "."] })] })),
     },
     {
         Icon: UserX, title: "Guest Limitations",

package/dist/features/account/components/NotificationPreferencesPanel.js

@@ -30,7 +30,7 @@ export function NotificationPreferencesPanel({ fetchUrl = ACCOUNT_ENDPOINTS.NOTI
     const { showToast } = useToast();
     const { data: settings } = useSiteSettings();
     const adminChannels = settings?.notificationChannels;
-    const [channels, setChannels] = useState({ email: true, sms: true });
+    const [channels, setChannels] = useState({ email: true, whatsapp: true, sms: true });
     const [types, setTypes] = useState({
         orderUpdates: true, bids: true, promotions: true,
         system: true, reviews: true, messages: true, offers: true,
@@ -92,7 +92,8 @@ export function NotificationPreferencesPanel({ fetchUrl = ACCOUNT_ENDPOINTS.NOTI
     }
     // Which channels are admin-enabled (only show those toggles to the user)
     const emailAdminEnabled = adminChannels?.email?.enabled ?? false;
+    const whatsappAdminEnabled = adminChannels?.whatsapp?.enabled ?? false;
     const smsAdminEnabled = adminChannels?.sms?.enabled ?? false;
-    const anyChannelEnabled = emailAdminEnabled || smsAdminEnabled;
-    return (_jsxs(Stack, { gap: "lg", children: [_jsx(SectionCard, { title: "In-app notifications", children: _jsxs(Row, { align: "center", justify: "between", gap: "md", padding: "y-sm", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", size: "sm", weight: "medium", children: "In-app notifications" }), _jsx(Text, { variant: "secondary", className: "mt-0.5", size: "xs", children: "Always on \u2014 displayed in the notification bell and inbox" })] }), _jsx(Row, { className: "h-5 w-9 bg-[var(--appkit-color-primary)] px-[0.125rem]", align: "center", justify: "end", rounded: "full", "aria-label": "Always on", children: _jsx(Span, { className: "h-4 w-4", rounded: "full", surface: "default", shadow: "default" }) })] }) }), anyChannelEnabled && (_jsxs(SectionCard, { title: "Notification channels", children: [emailAdminEnabled && (_jsx(ToggleRow, { label: "Email", description: "Receive notifications by email", checked: channels.email !== false, onChange: (v) => setChannel("email", v) })), smsAdminEnabled && (_jsx(ToggleRow, { label: "SMS", description: "Receive SMS text notifications", checked: channels.sms !== false, onChange: (v) => setChannel("sms", v) }))] })), _jsx(SectionCard, { title: "Notification types", children: TYPE_ROWS.map((row) => (_jsx(ToggleRow, { label: row.label, description: row.description, checked: types[row.key] !== false, onChange: (v) => setType(row.key, v) }, row.key))) }), _jsxs(Row, { justify: "end", gap: "sm", children: [saved && (_jsx(Text, { className: "text-[var(--appkit-color-success)] self-center", size: "sm", children: "Preferences saved \u2713" })), _jsx(Button, { onClick: handleSave, isLoading: saving, size: "sm", children: "Save preferences" })] })] }));
+    const anyChannelEnabled = emailAdminEnabled || whatsappAdminEnabled || smsAdminEnabled;
+    return (_jsxs(Stack, { gap: "lg", children: [_jsx(SectionCard, { title: "In-app notifications", children: _jsxs(Row, { align: "center", justify: "between", gap: "md", padding: "y-sm", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", size: "sm", weight: "medium", children: "In-app notifications" }), _jsx(Text, { variant: "secondary", className: "mt-0.5", size: "xs", children: "Always on \u2014 displayed in the notification bell and inbox" })] }), _jsx(Row, { className: "h-5 w-9 bg-[var(--appkit-color-primary)] px-[0.125rem]", align: "center", justify: "end", rounded: "full", "aria-label": "Always on", children: _jsx(Span, { className: "h-4 w-4", rounded: "full", surface: "default", shadow: "default" }) })] }) }), anyChannelEnabled && (_jsxs(SectionCard, { title: "Notification channels", children: [emailAdminEnabled && (_jsx(ToggleRow, { label: "Email", description: "Receive notifications by email", checked: channels.email !== false, onChange: (v) => setChannel("email", v) })), whatsappAdminEnabled && (_jsx(ToggleRow, { label: "WhatsApp", description: "Receive notifications on WhatsApp", checked: channels.whatsapp !== false, onChange: (v) => setChannel("whatsapp", v) })), smsAdminEnabled && (_jsx(ToggleRow, { label: "SMS", description: "Receive SMS text notifications", checked: channels.sms !== false, onChange: (v) => setChannel("sms", v) }))] })), _jsx(SectionCard, { title: "Notification types", children: TYPE_ROWS.map((row) => (_jsx(ToggleRow, { label: row.label, description: row.description, checked: types[row.key] !== false, onChange: (v) => setType(row.key, v) }, row.key))) }), _jsxs(Row, { justify: "end", gap: "sm", children: [saved && (_jsx(Text, { className: "text-[var(--appkit-color-success)] self-center", size: "sm", children: "Preferences saved \u2713" })), _jsx(Button, { onClick: handleSave, isLoading: saving, size: "sm", children: "Save preferences" })] })] }));
 }

package/dist/features/account/types/index.d.ts

@@ -75,6 +75,8 @@ export interface UserAddress {
 export interface NotificationChannelPrefs {
     /** Disable all email notifications for this user (default: true = enabled). */
     email?: boolean;
+    /** Disable all WhatsApp notifications for this user. */
+    whatsapp?: boolean;
     /** Disable all SMS notifications for this user. */
     sms?: boolean;
 }

package/dist/features/admin/actions/notification-actions.d.ts

@@ -11,8 +11,21 @@ export declare function getUnreadNotificationCount(userId: string): Promise<numb
 export interface SendNotificationInput extends NotificationCreateInput {
     /** User's email — used by the email channel when enabled. */
     userEmail?: string;
+    /** User's phone with country code, digits only — used by WhatsApp channel. */
+    userPhone?: string;
     /** Pre-rendered email HTML — falls back to a plain-text <p> when absent. */
     emailHtml?: string;
+    /**
+     * The store this notification is about, for the order-lifecycle types in
+     * `ORDER_GATED_TYPES`. Its WhatsApp subscription decides whether the
+     * WhatsApp arm runs; absent, those types fall back to in-app + email.
+     *
+     * Resolved HERE rather than by each caller: six call sites would otherwise
+     * each do their own store read and each be a place the rule could drift
+     * (Root Cause #75). The read only happens when the type is gated AND
+     * WhatsApp is otherwise eligible, so the common path costs nothing.
+     */
+    storeId?: string;
     /**
      * Which portal the recipient reads this in — decides where `actionUrl`
      * points when the caller does not supply one.
@@ -48,15 +61,17 @@ export interface SendNotificationInput extends NotificationCreateInput {
 export interface SendNotificationResult {
     notification: NotificationDocument;
     email: "sent" | "skipped" | "failed";
+    /** WhatsApp dispatch is now async (enqueued as a `whatsappNotify` job) — "queued" replaces "sent" as the immediate outcome; the real delivery result lands on `notification.whatsappStatus`. */
+    whatsapp: "queued" | "skipped" | "failed";
 }
 /**
  * Create an in-app notification and fan out to enabled external channels.
  *
- * In-app is always written. Email is sent only when:
+ * In-app is always written.  Email / WhatsApp are sent only when:
  *   1. The channel is enabled in siteSettings.notificationChannels
  *   2. Notification priority meets the channel's minPriority threshold
  *   3. The optional `types` filter includes this notification type (or is absent)
- *   4. The contact field (userEmail) is supplied by the caller
+ *   4. The contact field (userEmail / userPhone) is supplied by the caller
  *   5. The required credentials are set in siteSettings.credentials
  */
 export declare function sendNotification(input: SendNotificationInput): Promise<SendNotificationResult>;

package/dist/features/admin/actions/notification-actions.js

@@ -2,13 +2,15 @@ import { normalizeError } from "../../../errors/normalize.js";
 import { notificationRepository } from "../repository/notification.repository.js";
 import { siteSettingsRepository } from "../repository/site-settings.repository.js";
 import { userRepository } from "../../auth/repository/user.repository.js";
+import { storeRepository } from "../../stores/repository/store.repository.js";
+import { safeRead } from "../../../errors/safe-read.js";
 import { createResendProvider } from "../../../providers/email-resend/provider.js";
 import { isChannelHealthy, withChannelRetry } from "../../../_internal/server/notifications/channel-health.js";
+import { enqueueJob } from "../../jobs/actions/enqueue-job.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { resolveNotificationActionUrl, TYPE_AUDIENCE, } from "../../../_internal/shared/features/notifications/action-url.js";
 import { isEmailEligible } from "../../../_internal/shared/features/notifications/email-eligibility.js";
 import { renderNotificationEmail } from "../../email/notification-templates.js";
-import { DEFAULT_NOTIFICATION_CHANNELS, meetsMinPriority, } from "../schemas/firestore.js";
 /**
  * A notification's `actionUrl` is a site-relative path — correct for the
  * in-app bell, useless in an email, where a bare `/user/orders/x` is not a
@@ -31,6 +33,85 @@ function absoluteActionUrl(path) {
     const base = process.env.NEXT_PUBLIC_APP_URL?.replace(/\/+$/, "");
     return base ? `${base}${path}` : path;
 }
+import { DEFAULT_NOTIFICATION_CHANNELS, meetsMinPriority, } from "../schemas/firestore.js";
+/**
+ * Notification types whose WhatsApp send is gated behind the SELLER's
+ * standing WhatsApp-notifications subscription — see `storeId` on
+ * `SendNotificationInput`.
+ *
+ * 🛑 This replaced a per-ORDER ₹10 addon the buyer paid at checkout
+ * (`OrderDocument.whatsappNotifyAddon`). The axis moved deliberately: the
+ * platform owns one WhatsApp number, so the cost is a standing monthly one
+ * borne by the seller who benefits from it, not a line item a buyer opts into
+ * per order. A buyer should not have to purchase their own delivery updates.
+ *
+ * Every other type (bid_won, offers, scam reports, support tickets, admin
+ * alerts, …) keeps the original two gates — admin channel enabled, user has
+ * not opted out — unchanged.
+ */
+/**
+ * Does this store subscribe to WhatsApp order notifications?
+ *
+ * The subscription is a monthly add-on priced by the admin
+ * (`commissions.whatsappNotifyMonthlyFee`); this reads only whether it is
+ * currently active. Billing lives with the other recurring charges, not here.
+ *
+ * 🛑 Fails CLOSED. A store we cannot read, or one that has not subscribed,
+ * gets no WhatsApp send — the buyer still receives the in-app notification and
+ * the email, which are ungated. Failing open would message customers on behalf
+ * of a seller who is not paying for it, and bill the platform for the template.
+ */
+async function storeWhatsAppSubscribed(storeId) {
+    if (!storeId)
+        return false;
+    const store = await safeRead(() => storeRepository.findBySlug(storeId), {
+        route: "sendNotification",
+        key: `whatsapp-subscription:${storeId}`,
+        fallback: null,
+    });
+    return store?.whatsappNotifySubscribed === true;
+}
+const ORDER_GATED_TYPES = new Set([
+    "order_placed",
+    "order_confirmed",
+    "order_shipped",
+    "order_delivered",
+    "order_cancelled",
+    "refund_initiated",
+]);
+/**
+ * Notification type → the flat `SiteSettingsCredentials` field holding its
+ * approved Meta template name.
+ *
+ * 🛑 **`Partial` here is CORRECT and is not the `typeToPrefsKey` mistake.**
+ *
+ * The distinction is what a missing key MEANS. A missing `typeToPrefsKey`
+ * entry silently ignored a user's opt-out — a real setting that read as
+ * honoured and was not. A missing entry here means "no Meta-approved template
+ * exists for this type", which is a fact about the Meta account, not a bug:
+ * six of the 28 types have one, and the rest legitimately fall back to
+ * free-form (which Meta accepts inside the 24-hour customer-service window
+ * and rejects outside it — the runner already logs that rejection).
+ *
+ * Getting six approved templates is a Meta Business review process, not a
+ * code change, so listing all 28 here with empty values would be a
+ * `Record<…>` that lies about coverage.
+ *
+ * The six that ARE approved are the order lifecycle, which is also the set
+ * gated behind the buyer's ₹10 addon above — the two lists agree on purpose.
+ */
+const WHATSAPP_TEMPLATE_FIELD = {
+    order_placed: "whatsappTemplateOrderPlaced",
+    order_confirmed: "whatsappTemplateOrderConfirmed",
+    order_shipped: "whatsappTemplateOrderShipped",
+    order_delivered: "whatsappTemplateOrderDelivered",
+    order_cancelled: "whatsappTemplateOrderCancelled",
+    refund_initiated: "whatsappTemplateRefundInitiated",
+};
+function resolveWhatsAppTemplateName(type, creds) {
+    const field = WHATSAPP_TEMPLATE_FIELD[type];
+    return (field ? creds[field] : undefined)?.trim() ?? "";
+}
 export async function markNotificationRead(id) {
     await notificationRepository.markAsRead(id);
 }
@@ -53,15 +134,15 @@ export async function getUnreadNotificationCount(userId) {
 /**
  * Create an in-app notification and fan out to enabled external channels.
  *
- * In-app is always written. Email is sent only when:
+ * In-app is always written.  Email / WhatsApp are sent only when:
  *   1. The channel is enabled in siteSettings.notificationChannels
  *   2. Notification priority meets the channel's minPriority threshold
  *   3. The optional `types` filter includes this notification type (or is absent)
- *   4. The contact field (userEmail) is supplied by the caller
+ *   4. The contact field (userEmail / userPhone) is supplied by the caller
  *   5. The required credentials are set in siteSettings.credentials
  */
 export async function sendNotification(input) {
-    const { userEmail, emailHtml, audience, eligibilityOverride, ...notifInput } = input;
+    const { userEmail, userPhone, emailHtml, audience, eligibilityOverride, ...notifInput } = input;
     /*
      * Fill `actionUrl` when the caller did not.
      *
@@ -103,12 +184,12 @@ export async function sendNotification(input) {
      * suppresses the emailed/messaged COPY, not the notification.
      *
      * One map gates both channels deliberately. If a type is ever genuinely
-     * worth a channel of its own, split the map then rather than
+     * WhatsApp-worthy but not email-worthy, split the map then rather than
      * loosening this early return.
      */
     if (!isEmailEligible(notifInput.type) &&
         eligibilityOverride !== "staff_requested") {
-        return { notification, email: "skipped" };
+        return { notification, email: "skipped", whatsapp: "skipped" };
     }
     // Load channel config + credentials (one Firestore read).
     let settings;
@@ -118,7 +199,7 @@ export async function sendNotification(input) {
     catch (err) {
         void normalizeError(err);
         serverLogger.warn("sendNotification: could not load siteSettings — skipping external channels", { err });
-        return { notification, email: "skipped" };
+        return { notification, email: "skipped", whatsapp: "skipped" };
     }
     const channels = settings.notificationChannels ?? DEFAULT_NOTIFICATION_CHANNELS;
     const creds = settings.credentials ?? {};
@@ -150,6 +231,7 @@ export async function sendNotification(input) {
         ? userRepository.revealUser(fetchedUserDoc)
         : null;
     const resolvedEmail = userEmail ?? fetchedUserPlain?.email ?? undefined;
+    const resolvedPhone = userPhone ?? fetchedUserPlain?.phoneNumber ?? undefined;
     // Map NotificationType to a NotificationTypePrefs key.
     /*
      * 🛑 COMPLETE and compile-checked: `Record<NotificationType, …>`, not
@@ -212,7 +294,7 @@ export async function sendNotification(input) {
     const typeKey = typeToPrefsKey[type];
     // If the user has explicitly disabled this notification type, skip all external channels.
     if (typeKey && userTypePrefs[typeKey] === false) {
-        return { notification, email: "skipped" };
+        return { notification, email: "skipped", whatsapp: "skipped" };
     }
     // Email channel — admin enabled AND user hasn't opted out
     let emailStatus = "skipped";
@@ -259,10 +341,73 @@ export async function sendNotification(input) {
             }
         }
     }
+    // WhatsApp channel — admin enabled AND user hasn't opted out AND (for
+    // order-lifecycle types) the buyer paid the per-order WhatsApp addon.
+    let whatsappStatus = "skipped";
+    if (channels.whatsapp.enabled &&
+        userChannelPrefs.whatsapp !== false &&
+        resolvedPhone &&
+        meetsMinPriority(priority, channels.whatsapp.minPriority) &&
+        (!channels.whatsapp.types?.length || channels.whatsapp.types.includes(type)) &&
+        (!ORDER_GATED_TYPES.has(type) || (await storeWhatsAppSubscribed(input.storeId)))) {
+        /*
+         * ENV FIRST, site settings second.
+         *
+         * The platform owns one WhatsApp number, so its credentials are
+         * deployment configuration rather than admin-editable content — they
+         * belong beside the other secrets in the env, not in a Firestore document
+         * an admin screen can rewrite. Rotating a leaked Meta token should be a
+         * redeploy, not a form submission.
+         *
+         * 🛑 `WHATSAPP_PHONE_NUMBER_ID` is the Cloud API's numeric id, NOT the
+         * dialable number: sends go to `/{phone-number-id}/messages`, and a `+1…`
+         * string there is a 404 that looks like a routing bug.
+         *
+         * The site-settings fallback is kept so an install that configured these
+         * through the admin screen keeps working — this changes precedence, not
+         * behaviour, and nothing has to be migrated.
+         */
+        const phoneNumberId = process.env.WHATSAPP_PHONE_NUMBER_ID?.trim() ||
+            (creds.whatsappPhoneNumberId?.trim() ?? "");
+        const accessToken = process.env.WHATSAPP_MESSAGES_TOKEN?.trim() ||
+            (creds.whatsappCloudApiToken?.trim() ?? "");
+        if (phoneNumberId && accessToken) {
+            try {
+                const { jobId } = await enqueueJob({
+                    jobType: "whatsappNotify",
+                    payload: {
+                        toPhone: resolvedPhone,
+                        title,
+                        message,
+                        type,
+                        templateName: resolveWhatsAppTemplateName(type, creds),
+                        templateLanguage: creds.whatsappTemplateLanguage ?? "en",
+                        notificationId: notification.id,
+                        phoneNumberId,
+                        accessToken,
+                    },
+                    requestedBy: input.userId,
+                });
+                whatsappStatus = "queued";
+                await notificationRepository
+                    .update(notification.id, { whatsappStatus: "queued", whatsappJobId: jobId })
+                    .catch((err) => {
+                    void normalizeError(err);
+                    serverLogger.warn("sendNotification: failed to write whatsappJobId onto notification doc", { notificationId: notification.id });
+                });
+            }
+            catch (err) {
+                void normalizeError(err);
+                serverLogger.error("sendNotification: WhatsApp job enqueue failed", { userId: input.userId, err });
+                whatsappStatus = "failed";
+            }
+        }
+    }
     serverLogger.info("sendNotification: dispatched", {
         userId: input.userId,
         type,
         email: emailStatus,
+        whatsapp: whatsappStatus,
     });
-    return { notification, email: emailStatus };
+    return { notification, email: emailStatus, whatsapp: whatsappStatus };
 }

package/dist/features/admin/components/AdminOrderEditorView.d.ts

@@ -37,7 +37,7 @@ export interface AdminOrderEditorViewProps {
     paymentReviewOutcome?: string;
     /**
      * Paid add-ons + applied coupon for this order. Operational, not decorative:
-     * `giftWrapAddon` tells the packer to wrap the parcel, and the
+     * `whatsappNotifyAddon` is who a status change should message, and the
      * coupon is what an admin needs when reconciling a discounted order.
      */
     addons?: OrderAddonBadgesOrder;

package/dist/features/admin/components/AdminOrdersView.js

@@ -255,6 +255,8 @@ export function AdminOrdersView({ children, ...props }) {
                 // Straight off the order document — the admin list route returns
                 // raw docs, so these need no serializer entry (cf. Root Cause #38).
                 addons: {
+                    whatsappNotifyAddon: Boolean(item.whatsappNotifyAddon),
+                    whatsappNotifyFee: Number(item.whatsappNotifyFee ?? 0) || undefined,
                     giftWrapAddon: Boolean(item.giftWrapAddon),
                     giftWrapFee: Number(item.giftWrapFee ?? 0) || undefined,
                     giftWrapMessage: toStringValue(item.giftWrapMessage) || undefined,