@mohasinac/appkit 4.1.3 → 4.3.0

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

@@ -0,0 +1,19 @@
+import type { JobContext } from "../runtime/types";
+export interface PrizeDrawOrderSnapshot {
+    paymentStatus?: string;
+    prizeDrawProductId?: string;
+    items?: Array<{
+        listingType?: string;
+    }>;
+}
+/**
+ * Instant-mode prize-draw winner assignment. Fires when an order's
+ * paymentStatus transitions into "paid" — not at order creation, since a
+ * prize-draw order isn't guaranteed to be paid yet at that point (manual
+ * bank/UPI payments are confirmed later by the seller/admin; Razorpay
+ * confirms near-instantly but still goes through this same status flip).
+ */
+export declare function handlePrizeDrawPaymentConfirmed(input: {
+    orderId: string;
+    order: PrizeDrawOrderSnapshot;
+}, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,30 @@
+import { normalizeError } from "../../../../errors/normalize";
+import { assignPrizeDrawWinner } from "./prizeDrawAssignWinner";
+const PRODUCT_COLLECTION = "products";
+/**
+ * Instant-mode prize-draw winner assignment. Fires when an order's
+ * paymentStatus transitions into "paid" — not at order creation, since a
+ * prize-draw order isn't guaranteed to be paid yet at that point (manual
+ * bank/UPI payments are confirmed later by the seller/admin; Razorpay
+ * confirms near-instantly but still goes through this same status flip).
+ */
+export async function handlePrizeDrawPaymentConfirmed(input, ctx) {
+    const { orderId, order } = input;
+    if (!order.prizeDrawProductId)
+        return;
+    if (!order.items?.some((it) => it.listingType === "prize-draw"))
+        return;
+    let product;
+    try {
+        const snap = await ctx.db.collection(PRODUCT_COLLECTION).doc(order.prizeDrawProductId).get();
+        product = snap.exists ? snap.data() : undefined;
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Failed to load prize-draw product for instant reveal", err, { orderId });
+        return;
+    }
+    if (!product || product.prizeRevealMode !== "instant")
+        return;
+    await assignPrizeDrawWinner(ctx, { orderId, productId: order.prizeDrawProductId });
+}

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

@@ -5,8 +5,8 @@ import type { JobContext } from "../runtime/types";
  * its `paymentDeadline`. Runs every 5 minutes (`EVERY_5_MIN`), so an order
  * can overshoot its 15-minute deadline by up to ~5 minutes before this
  * catches it — acceptable, matches the existing tight-interval precedent
- * (`prizeRevealOpen`/`prizeRevealClose`) rather than inventing a 1-minute
- * cron that would multiply invocation cost for marginal UX gain.
+ * (`prizeDrawExpiryReveal`) rather than inventing a 1-minute cron that would
+ * multiply invocation cost for marginal UX gain.
  *
  * Orders that already have a `paymentProofUrl` are excluded by the
  * repository query — those are the 2-hour auto-approve sweep's domain

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

@@ -11,8 +11,8 @@ import { ORDER_MESSAGES } from "../handlers/messages";
  * its `paymentDeadline`. Runs every 5 minutes (`EVERY_5_MIN`), so an order
  * can overshoot its 15-minute deadline by up to ~5 minutes before this
  * catches it — acceptable, matches the existing tight-interval precedent
- * (`prizeRevealOpen`/`prizeRevealClose`) rather than inventing a 1-minute
- * cron that would multiply invocation cost for marginal UX gain.
+ * (`prizeDrawExpiryReveal`) rather than inventing a 1-minute cron that would
+ * multiply invocation cost for marginal UX gain.
  *
  * Orders that already have a `paymentProofUrl` are excluded by the
  * repository query — those are the 2-hour auto-approve sweep's domain
@@ -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/prizeDrawAssignWinner.d.ts

@@ -0,0 +1,20 @@
+import type { JobContext } from "../runtime/types";
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+export interface AssignPrizeDrawWinnerResult {
+    kind: "revealed" | "already_revealed" | "pool_exhausted" | "not_eligible";
+    prizeWon?: OrderDocument["prizeWon"];
+}
+/**
+ * The single place a prize-draw winner is ever picked. Called by every
+ * trigger point (payment-confirmed for "instant" mode, sellout-detection,
+ * and the expiry sweep for "scheduled" mode) — never call the underlying
+ * transaction logic anywhere else.
+ *
+ * Preserves the exact `crypto.randomInt` rejection-sampled fairness RNG that
+ * buyers are shown a public GitHub source link for (product.prizeGithubFileUrl)
+ * — do not change the selection algorithm.
+ */
+export declare function assignPrizeDrawWinner(ctx: JobContext, args: {
+    orderId: string;
+    productId: string;
+}): Promise<AssignPrizeDrawWinnerResult>;

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

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import { normalizeError } from "../../../../errors/normalize";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions";
+const PRODUCT_COLLECTION = "products";
+const ORDER_COLLECTION = "orders";
+/**
+ * The single place a prize-draw winner is ever picked. Called by every
+ * trigger point (payment-confirmed for "instant" mode, sellout-detection,
+ * and the expiry sweep for "scheduled" mode) — never call the underlying
+ * transaction logic anywhere else.
+ *
+ * Preserves the exact `crypto.randomInt` rejection-sampled fairness RNG that
+ * buyers are shown a public GitHub source link for (product.prizeGithubFileUrl)
+ * — do not change the selection algorithm.
+ */
+export async function assignPrizeDrawWinner(ctx, args) {
+    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true") {
+        ctx.logger.info("FEATURE_PRIZE_DRAWS disabled — skipping winner assignment");
+        return { kind: "not_eligible" };
+    }
+    const { orderId, productId } = args;
+    const orderRef = ctx.db.collection(ORDER_COLLECTION).doc(orderId);
+    const productRef = ctx.db.collection(PRODUCT_COLLECTION).doc(productId);
+    const result = await ctx.db.runTransaction(async (tx) => {
+        const [productSnap, orderSnap] = await Promise.all([
+            tx.get(productRef),
+            tx.get(orderRef),
+        ]);
+        if (!productSnap.exists || !orderSnap.exists) {
+            return { kind: "not_eligible" };
+        }
+        const product = productSnap.data();
+        const order = orderSnap.data();
+        // Idempotent — a winner was already assigned to this order.
+        if (order.prizeWon) {
+            return { kind: "already_revealed", prizeWon: order.prizeWon };
+        }
+        if (order.paymentStatus !== "paid" ||
+            order.status === "cancelled" ||
+            order.status === "refunded") {
+            return { kind: "not_eligible" };
+        }
+        const items = Array.isArray(product.prizeDrawItems)
+            ? [...product.prizeDrawItems]
+            : [];
+        const unwonIndices = items
+            .map((it, idx) => (it.isWon ? -1 : idx))
+            .filter((idx) => idx >= 0);
+        if (unwonIndices.length === 0) {
+            // Defensive only — preflightChecks already blocks overselling past
+            // prizeMaxEntries, so this should be unreachable outside a genuine
+            // race between two concurrent checkouts. No auto-refund here (that
+            // was the old buyer-claim-deadline behavior, now retired) — just
+            // report it so the caller can log/notify.
+            return { kind: "pool_exhausted" };
+        }
+        // crypto.randomInt is rejection-sampled and uniform — safe for fairness.
+        const pickPosition = crypto.randomInt(0, unwonIndices.length);
+        const pickIndex = unwonIndices[pickPosition];
+        const winningItem = items[pickIndex];
+        items[pickIndex] = { ...winningItem, isWon: true, wonByOrderId: orderId };
+        tx.update(productRef, {
+            prizeDrawItems: items,
+            updatedAt: ctx.now,
+        });
+        const prizeWon = {
+            itemNumber: winningItem.itemNumber,
+            title: winningItem.title,
+            images: winningItem.images,
+            wonAt: ctx.now,
+        };
+        const orderItems = Array.isArray(order.items) ? [...order.items] : [];
+        const revealedItems = orderItems.map((it) => it.listingType === "prize-draw" ? { ...it, prizeRevealStatus: "revealed" } : it);
+        tx.update(orderRef, {
+            prizeWon,
+            ...(revealedItems.length > 0 ? { items: revealedItems } : {}),
+            updatedAt: ctx.now,
+        });
+        return { kind: "revealed", prizeWon, userId: order.userId, productTitle: product.title };
+    });
+    if (result.kind === "revealed") {
+        ctx.logger.info("Prize-draw winner assigned", {
+            orderId,
+            productId,
+            itemNumber: result.prizeWon.itemNumber,
+        });
+        if (result.userId) {
+            try {
+                await sendNotification({
+                    userId: result.userId,
+                    type: "prize_won",
+                    priority: "high",
+                    title: "Your prize is ready!",
+                    message: `You won "${result.prizeWon.title}" in "${result.productTitle ?? "the draw"}" — check your order for details.`,
+                    relatedId: orderId,
+                    relatedType: "order",
+                    actionUrl: `/user/orders/view/${orderId}`,
+                });
+            }
+            catch (err) {
+                void normalizeError(err);
+                ctx.logger.warn("Prize-won notification failed", {
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return { kind: "revealed", prizeWon: result.prizeWon };
+    }
+    if (result.kind === "pool_exhausted") {
+        ctx.logger.warn("Prize-draw pool exhausted at assignment time", { orderId, productId });
+    }
+    return result;
+}

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

@@ -0,0 +1,14 @@
+import type { JobContext } from "../runtime/types";
+/**
+ * "Scheduled" reveal mode, expiry half. Fires once a draw's
+ * prizeRevealWindowEnd passes: assigns a winner to every paid, unrevealed
+ * order for that draw, then closes it. Any prize items with no corresponding
+ * order simply stay unrevealed / with the seller — that's expected on a
+ * partial sellout, not an error.
+ *
+ * The sellout half of "scheduled" mode lives in prizeDrawSoldOutReveal.ts —
+ * whichever fires first (expiry here, or a full sellout there) closes the
+ * draw; this sweep naturally no-ops afterward since the product is already
+ * "closed".
+ */
+export declare function runPrizeDrawExpiryReveal(ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,74 @@
+import { normalizeError } from "../../../../errors/normalize";
+import { PRODUCT_FIELDS, ORDER_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names";
+import { assignPrizeDrawWinner } from "./prizeDrawAssignWinner";
+const PRODUCT_COLLECTION = "products";
+const ORDER_COLLECTION = "orders";
+const PRIZE_DRAW_LISTING_TYPE = "prize-draw";
+/**
+ * "Scheduled" reveal mode, expiry half. Fires once a draw's
+ * prizeRevealWindowEnd passes: assigns a winner to every paid, unrevealed
+ * order for that draw, then closes it. Any prize items with no corresponding
+ * order simply stay unrevealed / with the seller — that's expected on a
+ * partial sellout, not an error.
+ *
+ * The sellout half of "scheduled" mode lives in prizeDrawSoldOutReveal.ts —
+ * whichever fires first (expiry here, or a full sellout there) closes the
+ * draw; this sweep naturally no-ops afterward since the product is already
+ * "closed".
+ */
+export async function runPrizeDrawExpiryReveal(ctx) {
+    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true") {
+        ctx.logger.info("FEATURE_PRIZE_DRAWS disabled — skipping prize-draw expiry reveal");
+        return;
+    }
+    ctx.logger.info("Prize-draw expiry reveal sweep starting");
+    const snap = await ctx.db
+        .collection(PRODUCT_COLLECTION)
+        .where(PRODUCT_FIELDS.LISTING_TYPE, "==", PRIZE_DRAW_LISTING_TYPE)
+        .where(PRODUCT_FIELDS.PRIZE_REVEAL_STATUS, "==", PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.OPEN)
+        .where(PRODUCT_FIELDS.PRIZE_REVEAL_WINDOW_END, "<=", ctx.now)
+        .limit(100)
+        .get();
+    if (snap.empty) {
+        ctx.logger.info("No prize draws past expiry");
+        return;
+    }
+    for (const doc of snap.docs) {
+        const product = doc.data();
+        if (product.prizeDrawMode === "lottery")
+            continue; // out of scope — separate mechanic
+        const orders = await ctx.db
+            .collection(ORDER_COLLECTION)
+            .where("prizeDrawProductId", "==", doc.id)
+            .where(ORDER_FIELDS.PAYMENT_STATUS, "==", ORDER_FIELDS.PAYMENT_STATUS_VALUES.PAID)
+            .where(ORDER_FIELDS.STATUS, "in", [
+            ORDER_FIELDS.STATUS_VALUES.PENDING,
+            ORDER_FIELDS.STATUS_VALUES.CONFIRMED,
+            ORDER_FIELDS.STATUS_VALUES.PROCESSING,
+        ])
+            .get();
+        let revealed = 0;
+        for (const orderDoc of orders.docs) {
+            const order = orderDoc.data();
+            if (order.prizeWon)
+                continue;
+            try {
+                const result = await assignPrizeDrawWinner(ctx, {
+                    orderId: orderDoc.id,
+                    productId: doc.id,
+                });
+                if (result.kind === "revealed")
+                    revealed++;
+            }
+            catch (err) {
+                void normalizeError(err);
+                ctx.logger.error("Expiry reveal failed for order", err, { orderId: orderDoc.id, productId: doc.id });
+            }
+        }
+        await doc.ref.update({
+            [PRODUCT_FIELDS.PRIZE_REVEAL_STATUS]: PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.CLOSED,
+            [COMMON_FIELDS.UPDATED_AT]: ctx.now,
+        });
+        ctx.logger.info("Closed prize draw at expiry", { productId: doc.id, revealed });
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { JobContext } from "../runtime/types";
+export interface PrizeDrawStockSnapshot {
+    listingType?: string;
+    prizeDrawMode?: string;
+    prizeRevealMode?: string;
+    prizeRevealStatus?: string;
+    prizeMaxEntries?: number;
+    prizeCurrentEntries?: number;
+}
+export interface HandlePrizeDrawSoldOutInput {
+    productId: string;
+    before: PrizeDrawStockSnapshot | null;
+    after: PrizeDrawStockSnapshot | null;
+}
+/**
+ * "Scheduled" reveal mode, sellout half — the other trigger condition besides
+ * expiry (prizeDrawExpiryReveal.ts). Fires the instant a scheduled-mode draw's
+ * last entry sells, so buyers don't have to wait for the expiry sweep once
+ * every ticket is gone. Assigns a winner to every paid, unrevealed order for
+ * the draw, then closes it.
+ */
+export declare function handlePrizeDrawSoldOut(input: HandlePrizeDrawSoldOutInput, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,68 @@
+import { normalizeError } from "../../../../errors/normalize";
+import { PRODUCT_FIELDS, ORDER_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names";
+import { assignPrizeDrawWinner } from "./prizeDrawAssignWinner";
+const ORDER_COLLECTION = "orders";
+function isSoldOut(doc) {
+    if (!doc)
+        return false;
+    const max = doc.prizeMaxEntries ?? 0;
+    if (max <= 0)
+        return false;
+    return (doc.prizeCurrentEntries ?? 0) >= max;
+}
+/**
+ * "Scheduled" reveal mode, sellout half — the other trigger condition besides
+ * expiry (prizeDrawExpiryReveal.ts). Fires the instant a scheduled-mode draw's
+ * last entry sells, so buyers don't have to wait for the expiry sweep once
+ * every ticket is gone. Assigns a winner to every paid, unrevealed order for
+ * the draw, then closes it.
+ */
+export async function handlePrizeDrawSoldOut(input, ctx) {
+    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true")
+        return;
+    const { productId, before, after } = input;
+    if (!after)
+        return;
+    if (after.listingType !== "prize-draw")
+        return;
+    if (after.prizeDrawMode === "lottery")
+        return; // out of scope — separate mechanic
+    if (after.prizeRevealMode !== "scheduled")
+        return;
+    if (after.prizeRevealStatus !== PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.OPEN)
+        return;
+    // Only act on the crossing transition into sold-out — avoids re-firing on
+    // every later write to an already-closed draw.
+    if (isSoldOut(before) || !isSoldOut(after))
+        return;
+    const orders = await ctx.db
+        .collection(ORDER_COLLECTION)
+        .where("prizeDrawProductId", "==", productId)
+        .where(ORDER_FIELDS.PAYMENT_STATUS, "==", ORDER_FIELDS.PAYMENT_STATUS_VALUES.PAID)
+        .where(ORDER_FIELDS.STATUS, "in", [
+        ORDER_FIELDS.STATUS_VALUES.PENDING,
+        ORDER_FIELDS.STATUS_VALUES.CONFIRMED,
+        ORDER_FIELDS.STATUS_VALUES.PROCESSING,
+    ])
+        .get();
+    let revealed = 0;
+    for (const orderDoc of orders.docs) {
+        const order = orderDoc.data();
+        if (order.prizeWon)
+            continue;
+        try {
+            const result = await assignPrizeDrawWinner(ctx, { orderId: orderDoc.id, productId });
+            if (result.kind === "revealed")
+                revealed++;
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error("Sellout reveal failed for order", err, { orderId: orderDoc.id, productId });
+        }
+    }
+    await ctx.db.collection("products").doc(productId).update({
+        [PRODUCT_FIELDS.PRIZE_REVEAL_STATUS]: PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.CLOSED,
+        [COMMON_FIELDS.UPDATED_AT]: ctx.now,
+    });
+    ctx.logger.info("Closed prize draw on sellout", { productId, revealed });
+}

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";
@@ -37,11 +38,10 @@ export { onStoreWriteHandler } from "./onStoreWrite";
 export { adminAnalyticsHandler, type AdminAnalyticsResult } from "./adminAnalytics";
 export { storeAnalyticsHandler, type StoreAnalyticsInput, type StoreAnalyticsResult, } from "./storeAnalytics";
 export { listingProcessorHandler, supportedListingCollections, type ListingRequestBody, type ListingResponseBody, } from "./listingProcessor";
-export { prizeRevealOpenHandler } from "./prizeRevealOpen";
-export { prizeRevealCloseHandler } from "./prizeRevealClose";
-export { prizeRevealExpiryHandler } from "./prizeRevealExpiry";
-export { prizeRevealReminderHandler } from "./prizeRevealReminder";
 export { bundleStockSyncHandler } from "./bundleStockSync";
+export { onPrizeDrawPaymentConfirmedHandler } from "./onPrizeDrawPaymentConfirmed";
+export { prizeDrawSoldOutRevealHandler } from "./prizeDrawSoldOutReveal";
+export { prizeDrawExpiryRevealHandler } from "./prizeDrawExpiryReveal";
 export { onProductStockChangeHandler } from "./onProductStockChange";
 export { triggerEventRaffleHandler } from "./triggerEventRaffle";
 export { assignSpinPrizeHandler } from "./assignSpinPrize";

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";
@@ -37,13 +38,15 @@ export { onStoreWriteHandler } from "./onStoreWrite";
 export { adminAnalyticsHandler } from "./adminAnalytics";
 export { storeAnalyticsHandler, } from "./storeAnalytics";
 export { listingProcessorHandler, supportedListingCollections, } from "./listingProcessor";
-// SB1-L (S7-PrizeDraws) — 7 functions covering prize draws, bundle sync,
-// event raffles, and spin-the-wheel.
-export { prizeRevealOpenHandler } from "./prizeRevealOpen";
-export { prizeRevealCloseHandler } from "./prizeRevealClose";
-export { prizeRevealExpiryHandler } from "./prizeRevealExpiry";
-export { prizeRevealReminderHandler } from "./prizeRevealReminder";
+// SB1-L (S7-PrizeDraws) — bundle sync, event raffles, and spin-the-wheel.
+// Prize-draw reveal itself was redesigned to a fully-automatic model — see
+// prizeDrawAssignWinner.ts (shared core), onPrizeDrawPaymentConfirmed
+// (instant mode), prizeDrawSoldOutReveal (scheduled mode, sellout half), and
+// prizeDrawExpiryReveal (scheduled mode, expiry half) below.
 export { bundleStockSyncHandler } from "./bundleStockSync";
+export { onPrizeDrawPaymentConfirmedHandler } from "./onPrizeDrawPaymentConfirmed";
+export { prizeDrawSoldOutRevealHandler } from "./prizeDrawSoldOutReveal";
+export { prizeDrawExpiryRevealHandler } from "./prizeDrawExpiryReveal";
 // SB-UNI-V — Firestore onWrite trigger for product stock changes (recomputes
 // bundleStockStatus on categoryType:"bundle" rows + activeMemberCount on
 // groupedListings).

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

@@ -0,0 +1,3 @@
+import type { FirestoreTriggerHandler } from "../runtime/types";
+import { type PrizeDrawOrderSnapshot } from "../core/onPrizeDrawPaymentConfirmed";
+export declare const onPrizeDrawPaymentConfirmedHandler: FirestoreTriggerHandler<PrizeDrawOrderSnapshot, PrizeDrawOrderSnapshot>;

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

@@ -0,0 +1,11 @@
+import { handlePrizeDrawPaymentConfirmed, } from "../core/onPrizeDrawPaymentConfirmed";
+export const onPrizeDrawPaymentConfirmedHandler = async (event, ctx) => {
+    const before = event.before;
+    const after = event.after;
+    if (!after)
+        return;
+    // Only act on the paid transition — avoids re-firing on every other order write.
+    if (before?.paymentStatus === "paid" || after.paymentStatus !== "paid")
+        return;
+    await handlePrizeDrawPaymentConfirmed({ orderId: event.params.orderId, order: after }, ctx);
+};

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

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

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

@@ -0,0 +1,2 @@
+import { runPrizeDrawExpiryReveal } from "../core/prizeDrawExpiryReveal";
+export const prizeDrawExpiryRevealHandler = runPrizeDrawExpiryReveal;