@mohasinac/appkit 4.1.3 → 4.2.0

package/dist/_internal/server/jobs/core/newsletterExport.js

@@ -0,0 +1,43 @@
+/**
+ * Core: async newsletter-subscriber CSV export (`newsletterExport` job).
+ *
+ * `GET /api/admin/newsletter/export` used to build the full CSV in-process,
+ * synchronously, for up to 10,000 subscribers — a real 10s-timeout risk on
+ * Vercel Hobby as the list grows (CLAUDE.md Rule #6). This runner does the
+ * same work inside a Firebase Function instead and writes the CSV text onto
+ * the job's `result.data.csv` field — small enough for a Firestore doc at
+ * realistic subscriber counts, and avoids routing through Storage (which
+ * would need a `/media/...` proxy URL per the Media Architecture rules
+ * rather than a raw signed URL).
+ */
+import { newsletterRepository } from "../../../../repositories";
+import { sortBy } from "../../../../constants/sort";
+import { COMMON_FIELDS } from "../../../../constants/field-names";
+function escape(value) {
+    const s = String(value ?? "");
+    return s.includes(",") || s.includes('"') || s.includes("\n")
+        ? `"${s.replace(/"/g, '""')}"`
+        : s;
+}
+function csvRow(cols) {
+    return cols.map(escape).join(",");
+}
+export async function runNewsletterExport(ctx) {
+    const result = await newsletterRepository.list({
+        sorts: sortBy(COMMON_FIELDS.CREATED_AT),
+        page: "1",
+        pageSize: "10000",
+    });
+    const rows = result.data;
+    const header = csvRow(["id", "email", "status", "source", "subscribedAt", "createdAt"]);
+    const dataRows = rows.map((s) => csvRow([s["id"], s["email"] ?? "", s["status"] ?? "", s["source"] ?? "", s["subscribedAt"] ?? "", s["createdAt"] ?? ""]));
+    const csv = [header, ...dataRows].join("\r\n");
+    ctx.logger.info("newsletterExport: complete", { subscriberCount: rows.length });
+    return {
+        summary: { total: rows.length, succeeded: rows.length, skipped: 0, failed: 0 },
+        succeeded: [],
+        skipped: [],
+        failed: [],
+        data: { csv, subscriberCount: rows.length },
+    };
+}

package/dist/_internal/server/jobs/core/onOrderStatusChange.d.ts

@@ -6,6 +6,8 @@ export type OrderAfter = {
     userEmail: string;
     productTitle: string;
     trackingNumber?: string;
+    /** Buyer opted into the ₹10 WhatsApp order-updates addon at checkout. */
+    whatsappNotifyAddon?: boolean;
 };
 export type OrderBefore = {
     status: OrderStatus;

package/dist/_internal/server/jobs/core/onOrderStatusChange.js

@@ -56,6 +56,7 @@ export async function handleOrderStatusChange(input, ctx) {
             relatedId: orderId,
             relatedType: "order",
             userEmail,
+            orderWhatsappAddonPaid: after.whatsappNotifyAddon === true,
         });
         try {
             await getAdminRealtimeDb().ref(`notifications/${after.userId}`).push({

package/dist/_internal/server/jobs/core/paymentWindowTimeout.js

@@ -51,6 +51,7 @@ export async function runPaymentWindowTimeout(ctx) {
         message: ORDER_MESSAGES.CANCELLED_PAYMENT_WINDOW_MESSAGE(entry.data.productTitle),
         relatedId: entry.id,
         relatedType: "order",
+        orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
     })));
     ctx.logger.info("Payment window timeout sweep complete", {
         scanned: expired.length,

package/dist/_internal/server/jobs/core/pendingOrderTimeout.js

@@ -49,6 +49,7 @@ export async function runPendingOrderTimeout(ctx) {
         message: ORDER_MESSAGES.CANCELLED_TIMEOUT_MESSAGE(entry.data.productTitle, timeoutHours),
         relatedId: entry.id,
         relatedType: "order",
+        orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
     })));
     ctx.logger.info("Pending order timeout complete", { cancelled: timedOut.length, restored });
 }

package/dist/_internal/server/jobs/core/revenueRollup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Core: daily revenue rollup.
+ *
+ * `GET /api/admin/dashboard` used to sum `totalPrice` over the FULL
+ * `delivered`-status orders list on every request (`orderRepository.findByStatus`
+ * has no bound) — a real, growing Firestore-read cost and a 10s-timeout risk
+ * on Vercel Hobby (CLAUDE.md Rule #6) as order volume increases. This job
+ * pre-computes the same aggregate once a day and writes it to the
+ * `analytics/dashboardRollup` singleton doc; the API route now reads that
+ * single doc instead of scanning the collection.
+ */
+import type { JobContext } from "../runtime/types";
+export declare function runRevenueRollup(ctx: JobContext): Promise<void>;

package/dist/_internal/server/jobs/core/revenueRollup.js

@@ -0,0 +1,22 @@
+/**
+ * Core: daily revenue rollup.
+ *
+ * `GET /api/admin/dashboard` used to sum `totalPrice` over the FULL
+ * `delivered`-status orders list on every request (`orderRepository.findByStatus`
+ * has no bound) — a real, growing Firestore-read cost and a 10s-timeout risk
+ * on Vercel Hobby (CLAUDE.md Rule #6) as order volume increases. This job
+ * pre-computes the same aggregate once a day and writes it to the
+ * `analytics/dashboardRollup` singleton doc; the API route now reads that
+ * single doc instead of scanning the collection.
+ */
+import { orderRepository } from "../../../../repositories";
+import { analyticsRollupRepository } from "../../../../repositories";
+export async function runRevenueRollup(ctx) {
+    const deliveredOrders = await orderRepository.findByStatus("delivered").catch(() => []);
+    const totalRevenue = deliveredOrders.reduce((sum, order) => sum + (Number(order.totalPrice ?? 0) || 0), 0);
+    await analyticsRollupRepository.setDashboardRollup({
+        totalRevenue,
+        deliveredOrderCount: deliveredOrders.length,
+    });
+    ctx.logger.info("revenueRollup: complete", { totalRevenue, deliveredOrderCount: deliveredOrders.length });
+}

package/dist/_internal/server/jobs/core/whatsappNotify.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Core: async WhatsApp notification dispatch (`whatsappNotify` job).
+ *
+ * `sendNotification()` (appkit/src/features/admin/actions/notification-actions.ts)
+ * no longer calls the Meta Cloud API synchronously in-request — it enqueues
+ * this job instead (CLAUDE.md Rule #6 async job primitive) and returns
+ * immediately. This runner does the actual send, with a bounded retry, and
+ * writes the outcome back onto `notifications/{notificationId}` so admins
+ * have visibility beyond the `jobs/{jobId}` doc itself.
+ *
+ * Retry note: `sendWhatsAppTemplateMessage`/`sendWhatsAppBusinessMessage`
+ * return a plain boolean (not a status code), so this runner cannot cleanly
+ * distinguish a transient 5xx from a terminal 4xx (bad token, unknown
+ * template) the way a status-code-aware client could. It retries any
+ * failure up to MAX_ATTEMPTS with a short backoff — an acceptable
+ * simplification since this runs off the critical path, well inside the
+ * Firebase Function's 300s budget, and a terminal error just burns two
+ * extra fast failures before giving up.
+ */
+import type { JobContext } from "../runtime/types";
+import type { JobRunResult } from "./jobRunners";
+export interface WhatsAppNotifyPayload {
+    toPhone: string;
+    title: string;
+    message: string;
+    type: string;
+    /** Approved Meta template name for this notification type, if configured. */
+    templateName?: string;
+    /** BCP-47 language code the template was approved in. Defaults to "en". */
+    templateLanguage?: string;
+    notificationId: string;
+    phoneNumberId: string;
+    accessToken: string;
+}
+export declare function runWhatsAppNotify(payload: WhatsAppNotifyPayload, ctx: JobContext): Promise<JobRunResult>;

package/dist/_internal/server/jobs/core/whatsappNotify.js

@@ -0,0 +1,82 @@
+/**
+ * Core: async WhatsApp notification dispatch (`whatsappNotify` job).
+ *
+ * `sendNotification()` (appkit/src/features/admin/actions/notification-actions.ts)
+ * no longer calls the Meta Cloud API synchronously in-request — it enqueues
+ * this job instead (CLAUDE.md Rule #6 async job primitive) and returns
+ * immediately. This runner does the actual send, with a bounded retry, and
+ * writes the outcome back onto `notifications/{notificationId}` so admins
+ * have visibility beyond the `jobs/{jobId}` doc itself.
+ *
+ * Retry note: `sendWhatsAppTemplateMessage`/`sendWhatsAppBusinessMessage`
+ * return a plain boolean (not a status code), so this runner cannot cleanly
+ * distinguish a transient 5xx from a terminal 4xx (bad token, unknown
+ * template) the way a status-code-aware client could. It retries any
+ * failure up to MAX_ATTEMPTS with a short backoff — an acceptable
+ * simplification since this runs off the critical path, well inside the
+ * Firebase Function's 300s budget, and a terminal error just burns two
+ * extra fast failures before giving up.
+ */
+import { normalizeError } from "../../../../errors/normalize";
+import { notificationRepository } from "../../../../features/admin/repository/notification.repository";
+import { sendWhatsAppTemplateMessage, sendWhatsAppBusinessMessage, } from "../../../../features/whatsapp-bot/helpers/whatsapp";
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 1500;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function runWhatsAppNotify(payload, ctx) {
+    const { toPhone, title, message, templateName, templateLanguage, notificationId, phoneNumberId, accessToken } = payload;
+    let sent = false;
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS && !sent; attempt++) {
+        try {
+            sent = templateName
+                ? await sendWhatsAppTemplateMessage({
+                    toPhone,
+                    phoneNumberId,
+                    accessToken,
+                    templateName,
+                    languageCode: templateLanguage ?? "en",
+                    bodyParams: [title, message],
+                })
+                : await sendWhatsAppBusinessMessage({
+                    toPhone,
+                    phoneNumberId,
+                    accessToken,
+                    message: `*${title}*\n${message}`,
+                });
+            if (!sent)
+                lastError = "Meta WhatsApp API returned a non-OK response";
+        }
+        catch (err) {
+            void normalizeError(err);
+            lastError = err instanceof Error ? err.message : String(err);
+        }
+        if (!sent && attempt < MAX_ATTEMPTS) {
+            ctx.logger.warn("whatsappNotify: send attempt failed, retrying", { notificationId, attempt, error: lastError ?? "" });
+            await delay(RETRY_DELAY_MS * attempt);
+        }
+    }
+    if (!templateName) {
+        ctx.logger.warn("whatsappNotify: no approved template configured for this notification type — sent as free-form text, which Meta rejects outside the 24h customer-service window", { notificationId });
+    }
+    await notificationRepository
+        .update(notificationId, { whatsappStatus: sent ? "sent" : "failed" })
+        .catch((err) => {
+        void normalizeError(err);
+        ctx.logger.warn("whatsappNotify: failed to write back whatsappStatus onto notification doc", {
+            notificationId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    });
+    if (!sent) {
+        throw new Error(lastError ?? "WhatsApp send failed after retries");
+    }
+    return {
+        summary: { total: 1, succeeded: 1, skipped: 0, failed: 0 },
+        succeeded: [notificationId],
+        skipped: [],
+        failed: [],
+    };
+}

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -28,6 +28,7 @@ export { paymentWindowTimeoutHandler } from "./paymentWindowTimeout";
 export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
+export { revenueRollupHandler } from "./revenueRollup";
 export { positionsReconcileHandler } from "./positionsReconcile";
 export { payoutBatchHandler } from "./payoutBatch";
 export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility";

package/dist/_internal/server/jobs/handlers/index.js

@@ -28,6 +28,7 @@ export { paymentWindowTimeoutHandler } from "./paymentWindowTimeout";
 export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
+export { revenueRollupHandler } from "./revenueRollup";
 export { positionsReconcileHandler } from "./positionsReconcile";
 export { payoutBatchHandler } from "./payoutBatch";
 export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility";

package/dist/_internal/server/jobs/handlers/revenueRollup.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const revenueRollupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/revenueRollup.js

@@ -0,0 +1,2 @@
+import { runRevenueRollup } from "../core/revenueRollup";
+export const revenueRollupHandler = runRevenueRollup;

package/dist/_internal/shared/features/checkout/config.d.ts

@@ -2,6 +2,13 @@ export declare const CHECKOUT_DEFAULT_COMMISSIONS: {
     readonly codDepositPercent: 10;
     readonly codHandlingFeeMin: 200;
     readonly codHandlingFeePercent: 10;
+    readonly whatsappNotifyFeeEnabled: false;
+    readonly whatsappNotifyFee: 10;
+    readonly giftWrapFeeEnabled: false;
+    readonly giftWrapFee: 49;
+    readonly shipmentProtectionFeeEnabled: false;
+    readonly shipmentProtectionFeePercent: 2;
+    readonly shipmentProtectionFeeMin: 30;
     readonly sellerShippingFixed: 50;
     readonly platformShippingPercent: 10;
     readonly platformShippingFixedMin: 50;

package/dist/_internal/shared/features/checkout/config.js

@@ -2,6 +2,13 @@ export const CHECKOUT_DEFAULT_COMMISSIONS = {
     codDepositPercent: 10,
     codHandlingFeeMin: 200,
     codHandlingFeePercent: 10,
+    whatsappNotifyFeeEnabled: false,
+    whatsappNotifyFee: 10,
+    giftWrapFeeEnabled: false,
+    giftWrapFee: 49,
+    shipmentProtectionFeeEnabled: false,
+    shipmentProtectionFeePercent: 2,
+    shipmentProtectionFeeMin: 30,
     sellerShippingFixed: 50,
     platformShippingPercent: 10,
     platformShippingFixedMin: 50,

package/dist/_internal/shared/fees/calculator.d.ts

@@ -50,6 +50,32 @@ export interface CodHandlingFeeRates {
 }
 /** COD handling fee charged to the buyer: max(fixed floor, subtotal × percent). */
 export declare function computeCodHandlingFee(subtotal: number, rates: CodHandlingFeeRates): number;
+export interface WhatsAppNotifyFeeRates {
+    /** Admin master toggle — the addon isn't charged (even if the buyer selected it) unless this is true. */
+    whatsappNotifyFeeEnabled?: boolean;
+    /** Flat rupee fee charged when the buyer opts in. Falls back to ₹10. */
+    whatsappNotifyFee?: number;
+}
+/** Flat WhatsApp order-updates addon fee — charged only when the buyer opted in AND the admin has the addon enabled. */
+export declare function computeWhatsAppNotifyFee(addonSelected: boolean, rates: WhatsAppNotifyFeeRates): number;
+export interface GiftWrapFeeRates {
+    /** Admin master toggle — the addon isn't charged (even if the buyer selected it) unless this is true. */
+    giftWrapFeeEnabled?: boolean;
+    /** Flat rupee fee charged when the buyer opts in. Falls back to ₹49. */
+    giftWrapFee?: number;
+}
+/** Flat gift-wrap addon fee — charged only when the buyer opted in AND the admin has the addon enabled. */
+export declare function computeGiftWrapFee(addonSelected: boolean, rates: GiftWrapFeeRates): number;
+export interface ShipmentProtectionFeeRates {
+    /** Admin master toggle — the addon isn't charged (even if the buyer selected it) unless this is true. */
+    shipmentProtectionFeeEnabled?: boolean;
+    /** Percent of subtotal. Falls back to 2%. */
+    shipmentProtectionFeePercent?: number;
+    /** Rupee floor. Falls back to ₹30. */
+    shipmentProtectionFeeMin?: number;
+}
+/** Shipment-protection addon fee: max(fixed floor, subtotal × percent) — charged only when the buyer opted in AND the admin has the addon enabled. */
+export declare function computeShipmentProtectionFee(subtotal: number, addonSelected: boolean, rates: ShipmentProtectionFeeRates): number;
 /**
  * P-8 GST — buyer-facing product tax, distinct from the platform-commission
  * GST above. Intra-state orders split the rate evenly between CGST + SGST;

package/dist/_internal/shared/fees/calculator.js

@@ -38,6 +38,31 @@ export function computeCodHandlingFee(subtotal, rates) {
     const percentFee = roundRupees(subtotal * (percent / 100));
     return Math.max(min, percentFee);
 }
+const DEFAULT_WHATSAPP_NOTIFY_FEE = 10;
+/** Flat WhatsApp order-updates addon fee — charged only when the buyer opted in AND the admin has the addon enabled. */
+export function computeWhatsAppNotifyFee(addonSelected, rates) {
+    if (!addonSelected || !rates.whatsappNotifyFeeEnabled)
+        return 0;
+    return rates.whatsappNotifyFee ?? DEFAULT_WHATSAPP_NOTIFY_FEE;
+}
+const DEFAULT_GIFT_WRAP_FEE = 49;
+/** Flat gift-wrap addon fee — charged only when the buyer opted in AND the admin has the addon enabled. */
+export function computeGiftWrapFee(addonSelected, rates) {
+    if (!addonSelected || !rates.giftWrapFeeEnabled)
+        return 0;
+    return rates.giftWrapFee ?? DEFAULT_GIFT_WRAP_FEE;
+}
+const DEFAULT_SHIPMENT_PROTECTION_FEE_PERCENT = 2;
+const DEFAULT_SHIPMENT_PROTECTION_FEE_MIN = 30;
+/** Shipment-protection addon fee: max(fixed floor, subtotal × percent) — charged only when the buyer opted in AND the admin has the addon enabled. */
+export function computeShipmentProtectionFee(subtotal, addonSelected, rates) {
+    if (!addonSelected || !rates.shipmentProtectionFeeEnabled)
+        return 0;
+    const percent = rates.shipmentProtectionFeePercent ?? DEFAULT_SHIPMENT_PROTECTION_FEE_PERCENT;
+    const min = rates.shipmentProtectionFeeMin ?? DEFAULT_SHIPMENT_PROTECTION_FEE_MIN;
+    const percentFee = roundRupees(subtotal * (percent / 100));
+    return Math.max(min, percentFee);
+}
 export function calculateGst(rate, intraState, taxableAmount) {
     const gstAmount = roundRupees(taxableAmount * (rate / 100));
     if (intraState) {

package/dist/features/about/components/FeesView.js

@@ -65,6 +65,24 @@ export async function FeesView({} = {}) {
             who: t("paidByBuyer"),
             note: t("codHandlingFeeNote"),
         },
+        {
+            category: t("whatsappNotifyFeeTitle"),
+            rate: t("whatsappNotifyFeeRate"),
+            who: t("paidByBuyer"),
+            note: t("whatsappNotifyFeeNote"),
+        },
+        {
+            category: t("giftWrapFeeTitle"),
+            rate: t("giftWrapFeeRate"),
+            who: t("paidByBuyer"),
+            note: t("giftWrapFeeNote"),
+        },
+        {
+            category: t("shipmentProtectionFeeTitle"),
+            rate: t("shipmentProtectionFeeRate"),
+            who: t("paidByBuyer"),
+            note: t("shipmentProtectionFeeNote"),
+        },
     ];
     const OFFER_PAYOUT_ROWS = [
         { label: t("grossSale"), example: "₹1,000" },

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

@@ -14,11 +14,14 @@ export interface SendNotificationInput extends NotificationCreateInput {
     userPhone?: string;
     /** Pre-rendered email HTML — falls back to a plain-text <p> when absent. */
     emailHtml?: string;
+    /** Buyer paid the ₹10 WhatsApp order-updates addon — enables WhatsApp channel for this notification even when the user has no standing WhatsApp subscription. */
+    orderWhatsappAddonPaid?: boolean;
 }
 export interface SendNotificationResult {
     notification: NotificationDocument;
     email: "sent" | "skipped" | "failed";
-    whatsapp: "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.

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

@@ -3,10 +3,39 @@ import { notificationRepository } from "../repository/notification.repository";
 import { siteSettingsRepository } from "../repository/site-settings.repository";
 import { userRepository } from "../../auth/repository/user.repository";
 import { createResendProvider } from "../../../providers/email-resend/provider";
-import { sendWhatsAppBusinessMessage } from "../../whatsapp-bot/helpers/whatsapp";
+import { enqueueJob } from "../../jobs/actions/enqueue-job";
 import { serverLogger } from "../../../monitoring";
 import { decryptPii } from "../../../security/index";
 import { DEFAULT_NOTIFICATION_CHANNELS, meetsMinPriority, } from "../schemas/firestore";
+/**
+ * Notification types whose WhatsApp send is gated behind the buyer's
+ * per-order ₹10 WhatsApp-updates addon (`OrderDocument.whatsappNotifyAddon`)
+ * — see `orderWhatsappAddonPaid` on `SendNotificationInput`. Every other
+ * type (bid_won, offers, scam reports, support tickets, admin alerts, …)
+ * keeps the original two-gate behavior (admin channel enabled + user hasn't
+ * opted out) unchanged.
+ */
+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. */
+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);
 }
@@ -121,28 +150,45 @@ export async function sendNotification(input) {
             }
         }
     }
-    // WhatsApp channel — admin enabled AND user hasn't opted out
+    // 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))) {
+        (!channels.whatsapp.types?.length || channels.whatsapp.types.includes(type)) &&
+        (!ORDER_GATED_TYPES.has(type) || input.orderWhatsappAddonPaid === true)) {
         const phoneNumberId = creds.whatsappPhoneNumberId?.trim() ?? "";
         const accessToken = creds.whatsappCloudApiToken?.trim() ?? "";
         if (phoneNumberId && accessToken) {
             try {
-                const ok = await sendWhatsAppBusinessMessage({
-                    toPhone: resolvedPhone,
-                    message: `*${title}*\n${message}`,
-                    phoneNumberId,
-                    accessToken,
+                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 });
                 });
-                whatsappStatus = ok ? "sent" : "failed";
             }
             catch (err) {
                 void normalizeError(err);
-                serverLogger.error("sendNotification: WhatsApp dispatch failed", { userId: input.userId, err });
+                serverLogger.error("sendNotification: WhatsApp job enqueue failed", { userId: input.userId, err });
                 whatsappStatus = "failed";
             }
         }

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

@@ -156,7 +156,7 @@ export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, crea
         settingsMutation.mutate(payload);
     };
     return (_jsx(StackedViewShell, { portal: "admin", ...rest, title: labels.title ?? "Ad Inventory", sections: [
-            _jsxs(Row, { align: "center", justify: "between", gap: "3", children: [_jsx(Text, { variant: "secondary", children: "Manage ad inventory, placement mapping, and publishing state." }), _jsx(TextLink, { variant: "bare", href: createHref, rounded: "md", paddingX: "sm", size: "sm", weight: "medium", layout: "inline-flex", align: "center", className: "h-9 bg-neutral-900 text-white bg-[var(--appkit-color-surface)] dark:text-[var(--appkit-color-text)]", children: "New ad" })] }),
+            _jsxs(Row, { align: "center", justify: "between", gap: "3", children: [_jsx(Text, { variant: "secondary", children: "Manage ad inventory, placement mapping, and publishing state." }), _jsx(TextLink, { variant: "bare", href: createHref, rounded: "md", paddingX: "sm", size: "sm", weight: "medium", layout: "inline-flex", align: "center", className: "h-9 bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text)]", children: "New ad" })] }),
             adsQuery.error ? (_jsx(Alert, { variant: "error", title: "Could not load ads", children: adsQuery.error instanceof Error ? adsQuery.error.message : "Unknown error" })) : null,
             _jsx(AdsSettingsPanel, { adsenseClientId: adsenseClientId, setAdsenseClientId: setAdsenseClientId, thirdPartyScriptUrl: thirdPartyScriptUrl, setThirdPartyScriptUrl: setThirdPartyScriptUrl, consentRequired: consentRequired, setConsentRequired: setConsentRequired, serverCredentialIssues: serverCredentialIssues, localCredentialIssues: localCredentialIssues, credentialStatus: credentialStatus, providerCredentialsMasked: adsQuery.data?.providerCredentialsMasked, settingsMutation: settingsMutation, hasPendingCredentialInput: hasPendingCredentialInput, currentConsentRequired: Boolean(adsQuery.data?.consentRequired), settingsMessage: settingsMessage, onSave: saveSettings }),
             _jsx(AdsFilterRow, { q: q, setQ: setQ, status: status, setStatus: setStatus, provider: provider, setProvider: setProvider, placement: placement, setPlacement: setPlacement, placements: placements, onPageReset: () => setPage(1) }),

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

@@ -1,10 +1,10 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
-import { useApiMutation } from "@mohasinac/appkit/client";
+import { useApiMutation, useBulkEvent, RTDB_PATHS } from "@mohasinac/appkit/client";
 import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
 import { sortBy } from "@mohasinac/appkit";
-import React, { useCallback, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { Button, ConfirmDeleteModal, FilterChipGroup, ListingLayout, RowActionMenu, useToast } from "../../../ui";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
@@ -33,24 +33,55 @@ export function AdminNewsletterView({ children, onBulkUnsubscribe, ...props }) {
             showToast(err?.message ?? "Failed to unsubscribe.", "error");
         },
     });
+    // Export runs as an async `newsletterExport` job (Async Job Primitive) —
+    // the route only enqueues; this subscribes to the same RTDB bulk-event
+    // channel every other async job in the admin panel uses.
+    const [exporting, setExporting] = useState(false);
+    const exportEvent = useBulkEvent({ rtdbPath: RTDB_PATHS.BULK_EVENTS });
     const handleExportCsv = useCallback(async () => {
+        setExporting(true);
         try {
             const response = await fetch(ADMIN_ENDPOINTS.NEWSLETTER_EXPORT);
             if (!response.ok)
                 throw new Error("Export failed");
-            const blob = await response.blob();
-            const url = URL.createObjectURL(blob);
-            const a = document.createElement("a");
-            a.href = url;
-            a.download = "newsletter-subscribers.csv";
-            a.click();
-            URL.revokeObjectURL(url);
+            const body = (await response.json());
+            const { jobId, customToken } = body.data ?? {};
+            if (jobId && customToken) {
+                exportEvent.subscribe(jobId, customToken);
+            }
+            else {
+                throw new Error("Export failed to start");
+            }
         }
         catch (_err) {
             void normalizeError(_err);
+            setExporting(false);
             showToast("Failed to export CSV.", "error");
         }
-    }, [showToast]);
+    }, [showToast, exportEvent]);
+    useEffect(() => {
+        if (exportEvent.status === "success") {
+            setExporting(false);
+            const csv = exportEvent.result?.data?.csv;
+            if (csv) {
+                const blob = new Blob([csv], { type: "text/csv;charset=utf-8" });
+                const url = URL.createObjectURL(blob);
+                const a = document.createElement("a");
+                a.href = url;
+                a.download = `newsletter-subscribers-${new Date().toISOString().slice(0, 10)}.csv`;
+                a.click();
+                URL.revokeObjectURL(url);
+            }
+            else {
+                showToast("Export finished with no data.", "error");
+            }
+        }
+        else if (exportEvent.status === "failed" || exportEvent.status === "timeout") {
+            setExporting(false);
+            showToast(exportEvent.error ?? "Failed to export CSV.", "error");
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [exportEvent.status]);
     if (React.Children.count(children) > 0) {
         return (_jsx(ListingLayout, { portal: "admin", ...props, children: children }));
     }
@@ -85,7 +116,7 @@ export function AdminNewsletterView({ children, onBulkUnsubscribe, ...props }) {
             return mappedRows.length;
         },
         buildFilters: (state) => state.status && state.status !== "All" ? sieveFilter("status", SIEVE_OP.EQ, state.status) : undefined,
-        toolbarExtra: (_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: handleExportCsv, children: ACTIONS.ADMIN["export-csv"].label })),
+        toolbarExtra: (_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: handleExportCsv, isLoading: exporting, disabled: exporting, children: ACTIONS.ADMIN["export-csv"].label })),
         buildBulkActions: onBulkUnsubscribe
             ? (selection) => [
                 buildBulkAction(ACTIONS.ADMIN["unsubscribe-newsletter"], async () => {