@mohasinac/appkit 4.63.4 → 4.64.0

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

@@ -0,0 +1,63 @@
+/**
+ * Core: MONTHLY seller-standing rollup — grants and revokes the Trusted
+ * Seller tier, and with it early payout.
+ *
+ * ## What it writes
+ *
+ * `stores/{id}.standing` — the cached metrics (this IS the cache; the seller's
+ * progress panel, the public badge and the admin view all read it off the
+ * store document they already load, and none of them recomputes anything).
+ * On a transition it also writes `sellerTier` and `trustedSeller` TOGETHER.
+ *
+ * 🛑 `trustedSeller` moves MONEY. It is read by both payout sweeps
+ * (`weeklyPayoutEligibility`, `autoPayoutEligibility`) via
+ * `storeRepository.findTrustedStoreIds()`, and it means the store is paid at
+ * SHIPPING instead of at delivery — so the platform carries a lost parcel with
+ * the money already gone. That is why this job is the only automatic writer,
+ * why every transition gets an audit row, and why an admin can pin a store
+ * with `standing.tierLockedByAdmin`.
+ *
+ * 🛑 The flag's author wrote, at `store.repository.ts`: *"trust is granted by
+ * hand, one store at a time, on risk grounds. If this ever saturates, the
+ * grant has stopped being deliberate."* Automatic granting is exactly that
+ * case, accepted deliberately by the owner. The mitigations are real and must
+ * not be quietly dropped: both a distinct-BUYER and a distinct-ADDRESS floor,
+ * self-bought orders excluded, test data excluded, and the 500-store bound on
+ * `findTrustedStoreIds` left in place so saturation is visible.
+ */
+import type { JobContext } from "../runtime/types";
+export interface SellerStandingRollupResult {
+    /** Stores examined. */
+    examined: number;
+    /** Stores whose `standing` cache was written. */
+    written: number;
+    granted: string[];
+    revoked: string[];
+    /** Stores skipped because an admin pinned their tier. */
+    locked: number;
+    /** True when the month-end guard declined to run. */
+    skippedNotMonthEnd: boolean;
+}
+/**
+ * 🛑 THIS IS WHY THE CRON IS `0 2 28-31 * *` AND NOT `0 0 31 * *`.
+ *
+ * Cloud Scheduler uses unix-cron, which has no `L` (last-day) token. A cron on
+ * day 31 **never fires in February, April, June, September or November** — it
+ * would silently skip 5 of 12 months, and the symptom is not an error but a
+ * tier that updates "sometimes". So the schedule fires on each of the last four
+ * candidate days and this guard keeps exactly the real one.
+ *
+ * Uses UTC parts throughout, matching the scheduler's declared `timeZone: UTC`.
+ * A local-time implementation would disagree with the trigger near midnight.
+ */
+export declare function isLastDayOfMonth(d: Date): boolean;
+/** The next month-end at or after `d`, for the seller-facing `nextComputeAt`. */
+export declare function nextLastDayOfMonth(d: Date): Date;
+export interface SellerStandingRollupOptions {
+    /**
+     * Run regardless of the date. For the admin "recompute now" path and for
+     * verification — NOT for the schedule.
+     */
+    force?: boolean;
+}
+export declare function runSellerStandingRollup(ctx: JobContext, opts?: SellerStandingRollupOptions): Promise<SellerStandingRollupResult>;

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

@@ -0,0 +1,412 @@
+/**
+ * Core: MONTHLY seller-standing rollup — grants and revokes the Trusted
+ * Seller tier, and with it early payout.
+ *
+ * ## What it writes
+ *
+ * `stores/{id}.standing` — the cached metrics (this IS the cache; the seller's
+ * progress panel, the public badge and the admin view all read it off the
+ * store document they already load, and none of them recomputes anything).
+ * On a transition it also writes `sellerTier` and `trustedSeller` TOGETHER.
+ *
+ * 🛑 `trustedSeller` moves MONEY. It is read by both payout sweeps
+ * (`weeklyPayoutEligibility`, `autoPayoutEligibility`) via
+ * `storeRepository.findTrustedStoreIds()`, and it means the store is paid at
+ * SHIPPING instead of at delivery — so the platform carries a lost parcel with
+ * the money already gone. That is why this job is the only automatic writer,
+ * why every transition gets an audit row, and why an admin can pin a store
+ * with `standing.tierLockedByAdmin`.
+ *
+ * 🛑 The flag's author wrote, at `store.repository.ts`: *"trust is granted by
+ * hand, one store at a time, on risk grounds. If this ever saturates, the
+ * grant has stopped being deliberate."* Automatic granting is exactly that
+ * case, accepted deliberately by the owner. The mitigations are real and must
+ * not be quietly dropped: both a distinct-BUYER and a distinct-ADDRESS floor,
+ * self-bought orders excluded, test data excluded, and the 500-store bound on
+ * `findTrustedStoreIds` left in place so saturation is visible.
+ */
+import { storeRepository } from "../../../../repositories/index.js";
+import { ORDER_FIELDS, REVIEW_FIELDS } from "../../../../constants/field-names.js";
+import { recordAdminAction } from "../../features/audit-log/actions.js";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { evaluateSellerStanding, SELLER_STANDING_DEFAULTS, SELLER_TIER, } from "../../../shared/features/seller-standing/config.js";
+const EMPTY_RESULT = {
+    examined: 0,
+    written: 0,
+    granted: [],
+    revoked: [],
+    locked: 0,
+    skippedNotMonthEnd: true,
+};
+/** Firestore page size for the two windowed scans. */
+const SCAN_PAGE = 500;
+// ---------------------------------------------------------------------------
+// The month-end guard
+// ---------------------------------------------------------------------------
+/**
+ * 🛑 THIS IS WHY THE CRON IS `0 2 28-31 * *` AND NOT `0 0 31 * *`.
+ *
+ * Cloud Scheduler uses unix-cron, which has no `L` (last-day) token. A cron on
+ * day 31 **never fires in February, April, June, September or November** — it
+ * would silently skip 5 of 12 months, and the symptom is not an error but a
+ * tier that updates "sometimes". So the schedule fires on each of the last four
+ * candidate days and this guard keeps exactly the real one.
+ *
+ * Uses UTC parts throughout, matching the scheduler's declared `timeZone: UTC`.
+ * A local-time implementation would disagree with the trigger near midnight.
+ */
+export function isLastDayOfMonth(d) {
+    const next = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1));
+    return next.getUTCMonth() !== d.getUTCMonth();
+}
+/** The next month-end at or after `d`, for the seller-facing `nextComputeAt`. */
+export function nextLastDayOfMonth(d) {
+    // Day 0 of the following month is the last day of this one.
+    const endOfThis = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0));
+    if (endOfThis.getTime() > d.getTime())
+        return endOfThis;
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 2, 0));
+}
+const emptyTally = () => ({
+    deliveredOrders: 0,
+    buyers: new Set(),
+    addresses: new Set(),
+    ratingSum: 0,
+    ratingCount: 0,
+});
+function toMetrics(t) {
+    return {
+        deliveredOrders: t.deliveredOrders,
+        distinctBuyers: t.buyers.size,
+        distinctAddresses: t.addresses.size,
+        ratedOrders: t.ratingCount,
+        /*
+         * 0 when there are no ratings, never NaN. `ratingSum / 0` is NaN, and NaN
+         * fails every `>=` comparison — which happens to give the right verdict
+         * here but writes NaN into Firestore, where it is rejected outright on
+         * some paths and renders as "NaN" in the seller's panel on others.
+         */
+        averageRating: t.ratingCount === 0 ? 0 : t.ratingSum / t.ratingCount,
+    };
+}
+function isTestRow(data) {
+    /*
+     * Both spellings. `isTestData` is the legacy boolean and `seedPurpose` is
+     * the newer field it is derived from; a row may carry either, so testing one
+     * would let the other through and let a tester fixture count toward a real
+     * money-moving grant.
+     */
+    if (data.isTestData === true)
+        return true;
+    return data.seedPurpose === "test" || data.seedPurpose === "tester";
+}
+export async function runSellerStandingRollup(ctx, opts = {}) {
+    if (!opts.force && !isLastDayOfMonth(ctx.now)) {
+        ctx.logger.info("sellerStandingRollup: not month-end, skipping", {
+            now: ctx.now.toISOString(),
+        });
+        return { ...EMPTY_RESULT };
+    }
+    /*
+     * 🛑 The CONSTANT, not a settings read.
+     *
+     * This briefly folded an admin override from `siteSettings.sellerStanding`
+     * onto the defaults. That made the job disagree with `/seller-guide` and
+     * `/help/seller-badges`, which render their criteria from the code defaults
+     * — so retuning the numbers would have changed what the tier is granted on
+     * while both public pages went on promising the old figures. One constant,
+     * every surface, agreeing by construction.
+     */
+    const thresholds = SELLER_STANDING_DEFAULTS;
+    const cutoff = new Date(ctx.now.getTime() - thresholds.windowDays * 24 * 60 * 60 * 1000);
+    const nextComputeAt = nextLastDayOfMonth(ctx.now);
+    ctx.logger.info("sellerStandingRollup: starting", {
+        windowDays: thresholds.windowDays,
+        cutoff: cutoff.toISOString(),
+        forced: Boolean(opts.force),
+    });
+    // ── Stores ───────────────────────────────────────────────────────────────
+    /*
+     * Enumerate STORES, not the orders' distinct storeIds. A store that sold
+     * nothing this window must still be evaluated, because that is precisely the
+     * store whose tier should be REVOKED — a reconciler built from the events
+     * that exist can only ever add (Root Cause #102).
+     */
+    const stores = new Map();
+    const storeSnap = await ctx.db
+        .collection("stores")
+        .select("ownerId", "status", "sellerTier", "trustedSeller", "tierLockedByAdmin")
+        .get();
+    for (const doc of storeSnap.docs) {
+        const d = doc.data();
+        stores.set(doc.id, {
+            id: doc.id,
+            ownerId: d.ownerId,
+            status: d.status,
+            sellerTier: d.sellerTier,
+            trustedSeller: d.trustedSeller,
+            tierLockedByAdmin: d.tierLockedByAdmin === true,
+        });
+    }
+    const tallies = new Map();
+    const tally = (storeId) => {
+        let t = tallies.get(storeId);
+        if (!t) {
+            t = emptyTally();
+            tallies.set(storeId, t);
+        }
+        return t;
+    };
+    // ── Orders in the window ─────────────────────────────────────────────────
+    /*
+     * 🛑 Windowed on `orderDate`, which is REQUIRED, not on `deliveryDate`,
+     * which is optional and written by exactly one job (`obligationSweep`). A
+     * Firestore inequality EXCLUDES every document lacking the field, so a range
+     * on `deliveryDate` would silently drop every order a seller marked
+     * delivered by hand — returning a confident undercount with no error
+     * anywhere (Root Cause #100).
+     *
+     * One collection-wide windowed scan rather than a query per store: a
+     * per-store `storeId == X AND orderDate >= cutoff` needs a composite index,
+     * and a missing one fails as FAILED_PRECONDITION that every caller here
+     * would have to not-swallow (Root Cause #2). A single-field inequality is
+     * served by the automatic index. `status` is filtered in memory for the same
+     * reason.
+     */
+    let orderCursor = null;
+    let ordersScanned = 0;
+    for (;;) {
+        let q = ctx.db
+            .collection("orders")
+            .where(ORDER_FIELDS.ORDER_DATE, ">=", cutoff)
+            .orderBy(ORDER_FIELDS.ORDER_DATE, "asc")
+            .limit(SCAN_PAGE);
+        if (orderCursor)
+            q = q.startAfter(orderCursor);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        for (const doc of snap.docs) {
+            const d = doc.data();
+            ordersScanned += 1;
+            if (d.status !== "delivered")
+                continue;
+            if (isTestRow(d))
+                continue;
+            const storeId = d.storeId;
+            if (!storeId)
+                continue;
+            const store = stores.get(storeId);
+            if (!store)
+                continue;
+            const userId = d.userId;
+            /*
+             * 🛑 Self-bought orders do not count. Without this a seller reaches the
+             * tier — and early payout — by buying from themselves 25 times, which is
+             * the cheapest possible attack on a criterion that releases money early.
+             */
+            if (userId && store.ownerId && userId === store.ownerId)
+                continue;
+            const t = tally(storeId);
+            t.deliveredOrders += 1;
+            if (userId)
+                t.buyers.add(userId);
+            /*
+             * 🛑 `deliveryAddressId` — the `addresses` row this order was taken
+             * from. It is a provenance pointer, NOT PII and NOT encrypted, so
+             * counting distinct values needs no decryption and no fingerprint of
+             * our own.
+             *
+             * Orders predating the delivery snapshot carry none and contribute
+             * nothing to this criterion. That is forward-only by design: inventing
+             * a key from `deliveryPincode` instead would count two different
+             * households in one pincode as one address, and the encrypted
+             * `deliveryAddressLine1` cannot be read here at all.
+             *
+             * Honest about its limit: a determined seller can save the same physical
+             * place as several address rows. The distinct-BUYER floor is the real
+             * defence; this one raises the cost.
+             */
+            if (d.deliveryAddressId)
+                t.addresses.add(d.deliveryAddressId);
+        }
+        orderCursor = snap.docs[snap.docs.length - 1];
+        if (snap.size < SCAN_PAGE)
+            break;
+    }
+    // ── Reviews in the window ────────────────────────────────────────────────
+    /*
+     * Windowed on `createdAt`, which every document carries via `BaseDocument`.
+     * `ReviewDocument` has no `publishedAt` field at all — CLAUDE.md's seed
+     * table says it does, and that is stale.
+     */
+    let reviewCursor = null;
+    for (;;) {
+        let q = ctx.db
+            .collection("reviews")
+            .where(REVIEW_FIELDS.CREATED_AT, ">=", cutoff)
+            .orderBy(REVIEW_FIELDS.CREATED_AT, "asc")
+            .limit(SCAN_PAGE);
+        if (reviewCursor)
+            q = q.startAfter(reviewCursor);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        for (const doc of snap.docs) {
+            const d = doc.data();
+            if (d.status !== "approved")
+                continue;
+            if (isTestRow(d))
+                continue;
+            const storeId = d.storeId;
+            if (!storeId || !stores.has(storeId))
+                continue;
+            const rating = Number(d.rating);
+            if (!Number.isFinite(rating))
+                continue;
+            const t = tally(storeId);
+            t.ratingSum += rating;
+            t.ratingCount += 1;
+        }
+        reviewCursor = snap.docs[snap.docs.length - 1];
+        if (snap.size < SCAN_PAGE)
+            break;
+    }
+    // ── Evaluate + write ─────────────────────────────────────────────────────
+    /*
+     * 🛑 Through the REPOSITORY, not `ctx.db.update()`.
+     *
+     * `adminUpdate` runs `withStoreHistory`, and `sellerTier` / `trustedSeller`
+     * are both in `STORE_TRACKED_FIELDS` — so a transition earns a
+     * `statusHistory` entry stamped `actorRole: "system"`. A raw document write
+     * would move money with no timeline entry, which is the one thing the
+     * timeline exists for on this field.
+     *
+     * `prior` is the projected shell rather than a full document, which is safe
+     * and deliberate: `withHistory` diffs only `tracked` fields that appear in
+     * the PATCH, and the patch only ever carries `standing` (untracked),
+     * `sellerTier` and `trustedSeller` — both of which the shell selects. The
+     * cast says exactly that and nothing more.
+     */
+    const writeStore = (store, patch) => storeRepository.adminUpdate(store.id, patch, { actor: { role: "system" }, trigger: "sellerStandingRollup" }, store);
+    const granted = [];
+    const revoked = [];
+    let written = 0;
+    let locked = 0;
+    for (const store of stores.values()) {
+        const metrics = toMetrics(tallies.get(store.id) ?? emptyTally());
+        const verdict = evaluateSellerStanding(metrics, thresholds);
+        /*
+         * `standing` is a pure MEASUREMENT — no admin state in it. The pin lives
+         * at the top level precisely so this object can be rebuilt wholesale every
+         * month without carrying a decision forward or needing to be merged.
+         */
+        const standing = {
+            computedAt: ctx.now,
+            nextComputeAt,
+            windowDays: thresholds.windowDays,
+            ...metrics,
+            met: verdict.met,
+        };
+        /*
+         * An admin-pinned store still gets a REFRESHED `standing` — the seller
+         * should see their real figures — but its tier is left exactly where the
+         * admin put it. Writing the metrics while not acting on them is the whole
+         * point of the lock.
+         */
+        if (store.tierLockedByAdmin) {
+            locked += 1;
+            await writeStore(store, { standing });
+            written += 1;
+            continue;
+        }
+        /*
+         * 🛑 A store that is not ACTIVE can never hold the tier. Suspension
+         * already clears it immediately (see `storeRepository.setStatus`), and
+         * this is the belt: a suspended store must not be re-granted early payout
+         * by a month-end run just because its 90-day history still looks good.
+         */
+        const eligible = store.status === "active" && verdict.tier === SELLER_TIER.TRUSTED;
+        const currentTier = store.sellerTier ?? SELLER_TIER.SELLER;
+        const nextTier = eligible ? SELLER_TIER.TRUSTED : SELLER_TIER.SELLER;
+        const update = { standing };
+        const isTransition = nextTier !== currentTier || Boolean(store.trustedSeller) !== eligible;
+        if (isTransition) {
+            update.sellerTier = nextTier;
+            update.trustedSeller = eligible;
+            if (eligible)
+                granted.push(store.id);
+            else
+                revoked.push(store.id);
+        }
+        await writeStore(store, update);
+        written += 1;
+        if (!isTransition)
+            continue;
+        /*
+         * 🛑 Audit and notify on a REAL transition only. Re-saving the monthly
+         * `standing` on an unchanged store would otherwise write an audit row
+         * describing a decision nobody made and email a seller about nothing —
+         * and a log of non-events is how a log stops being read. Same rule the
+         * admin PATCH route applies to this exact field.
+         */
+        void recordAdminAction({
+            actorUid: "system",
+            action: AdminAuditActionValues.STORE_TRUST_CHANGE,
+            targetType: "store",
+            targetId: store.id,
+            targetLabel: store.id,
+            reason: eligible
+                ? "Met every Trusted Seller criterion at the monthly recompute"
+                : "Fell below a Trusted Seller criterion at the monthly recompute",
+            metadata: {
+                trustedSeller: eligible,
+                previous: Boolean(store.trustedSeller),
+                sellerTier: nextTier,
+                trigger: "sellerStandingRollup",
+                ...metrics,
+            },
+        });
+        if (!store.ownerId)
+            continue;
+        /*
+         * The seller is told, because the consequence is concrete in both
+         * directions: gaining the tier changes when they get paid, and losing it
+         * changes it back. Fire-and-forget — a notification failure must not
+         * abort a sweep that has already written the tier.
+         */
+        void sendNotification({
+            userId: store.ownerId,
+            type: "system",
+            priority: "normal",
+            title: eligible ? "You're now a Trusted Seller" : "Trusted Seller status paused",
+            message: eligible
+                ? "Your store met every Trusted Seller criterion this month. Your badge is live and your payouts now start when you ship, rather than on delivery."
+                : `Your store no longer meets every Trusted Seller criterion, so the badge is paused and payouts return to starting on delivery. ${verdict.unmetCount === 1 ? "One criterion" : `${verdict.unmetCount} criteria`} to regain it — see your seller guide for the current figures.`,
+        }).catch((err) => {
+            const e = normalizeError(err);
+            ctx.logger.warn("sellerStandingRollup: notification failed", {
+                storeId: store.id,
+                error: e.message,
+            });
+        });
+    }
+    ctx.logger.info("sellerStandingRollup: complete", {
+        examined: stores.size,
+        ordersScanned,
+        written,
+        granted: granted.length,
+        revoked: revoked.length,
+        locked,
+    });
+    return {
+        examined: stores.size,
+        written,
+        granted,
+        revoked,
+        locked,
+        skippedNotMonthEnd: false,
+    };
+}

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,140 @@
+/**
+ * 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.js";
+import { notificationRepository } from "../../../../features/admin/repository/notification.repository.js";
+import { sendWhatsAppTemplateMessage, sendWhatsAppBusinessMessage, } from "../../../../features/whatsapp-bot/helpers/whatsapp.js";
+import { isChannelHealthy, recordChannelOutcome } from "../../notifications/channel-health.js";
+import { guardSend, logSuppressedSend } from "../../notifications/send-guard.js";
+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, type, templateName, templateLanguage, notificationId, phoneNumberId, accessToken } = payload;
+    /*
+     * The messaging guard, applied HERE rather than inside
+     * `sendWhatsAppBusinessMessage` itself.
+     *
+     * 🛑 That placement is deliberate and must not be "improved" by pushing a
+     * required guard parameter down into the sender. `features/whatsapp-bot/helpers/whatsapp.ts`
+     * is re-exported from `appkit/src/index.ts` (via `isAdminNumber`), and
+     * `guardSend` reaches `firebase-admin` through the settings and budget
+     * repositories. A static import of it from that file would put
+     * `firebase-admin` in the main entry's import graph, which is precisely the
+     * Turbopack client-bundle trap in Root Cause #6/#24 — it builds fine locally
+     * on webpack and fails every page in production.
+     *
+     * So the senders stay pure and each of the three real call sites guards
+     * itself; `scripts/audit-unguarded-send.mjs` enforces that a file calling a
+     * WhatsApp sender also calls `guardSend`.
+     *
+     * Note this job is only ever reached for an email/WhatsApp-ELIGIBLE type —
+     * `sendNotification` returns before enqueuing otherwise — so this is the
+     * ceiling and kill-switch check, not the type check.
+     */
+    const guard = {
+        channel: "whatsapp",
+        feature: type,
+        audience: "user",
+    };
+    const decision = await guardSend(guard);
+    if (!decision.allow) {
+        logSuppressedSend(guard, decision);
+        await notificationRepository
+            .update(notificationId, { whatsappStatus: "skipped" })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+            succeeded: [],
+            skipped: [notificationId],
+            failed: [],
+        };
+    }
+    if (!(await isChannelHealthy("whatsapp"))) {
+        ctx.logger.warn("whatsappNotify: WhatsApp channel circuit is open — skipping send", { notificationId });
+        await notificationRepository
+            .update(notificationId, { whatsappStatus: "skipped" })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+            succeeded: [],
+            skipped: [notificationId],
+            failed: [],
+        };
+    }
+    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 recordChannelOutcome("whatsapp", sent);
+    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

@@ -32,6 +32,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { sellerStandingRollupHandler } from "./sellerStandingRollup";
 export { priceIndexRollupHandler } from "./priceIndexRollup";
 export { marketPriceRollupHandler } from "./marketPriceRollup";
 export { searchIndexBuildHandler } from "./searchIndexBuild";

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

@@ -32,6 +32,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement.js";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove.js";
 export { productStatsSyncHandler } from "./productStatsSync.js";
 export { revenueRollupHandler } from "./revenueRollup.js";
+export { sellerStandingRollupHandler } from "./sellerStandingRollup.js";
 export { priceIndexRollupHandler } from "./priceIndexRollup.js";
 export { marketPriceRollupHandler } from "./marketPriceRollup.js";
 export { searchIndexBuildHandler } from "./searchIndexBuild.js";