@mohasinac/appkit 2.6.3 → 2.6.4

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

@@ -0,0 +1,139 @@
+import { notificationRepository } from "../../../../repositories";
+import { decryptPii } from "../../../../security/index";
+import { getAdminRealtimeDb } from "../../../../providers/db-firebase";
+import { ORDER_MESSAGES, EMAIL_SUBJECTS, JOB_ERROR_MESSAGES } from "../handlers/messages";
+const STATUS_CONFIG = {
+    confirmed: {
+        type: "order_confirmed",
+        title: ORDER_MESSAGES.CONFIRMED_TITLE,
+        message: (o) => ORDER_MESSAGES.CONFIRMED_MESSAGE(o.productTitle),
+        priority: "normal",
+        sendEmail: true,
+    },
+    shipped: {
+        type: "order_shipped",
+        title: ORDER_MESSAGES.SHIPPED_TITLE,
+        message: (o) => ORDER_MESSAGES.SHIPPED_MESSAGE(o.productTitle, o.trackingNumber),
+        priority: "high",
+        sendEmail: true,
+    },
+    delivered: {
+        type: "order_delivered",
+        title: ORDER_MESSAGES.DELIVERED_TITLE,
+        message: (o) => ORDER_MESSAGES.DELIVERED_MESSAGE(o.productTitle),
+        priority: "normal",
+        sendEmail: true,
+    },
+    cancelled: {
+        type: "order_cancelled",
+        title: ORDER_MESSAGES.CANCELLED_TITLE,
+        message: (o) => `Your order for "${o.productTitle}" has been cancelled.`,
+        priority: "normal",
+        sendEmail: false,
+    },
+};
+async function sendResendEmail(params) {
+    const subject = params.status === "confirmed"
+        ? EMAIL_SUBJECTS.ORDER_CONFIRMED(params.productTitle)
+        : params.status === "shipped"
+            ? EMAIL_SUBJECTS.ORDER_SHIPPED(params.productTitle)
+            : params.status === "delivered"
+                ? EMAIL_SUBJECTS.ORDER_DELIVERED(params.productTitle)
+                : EMAIL_SUBJECTS.ORDER_UPDATE_FALLBACK(params.productTitle);
+    const response = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${params.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            from: params.fromAddress,
+            to: [params.to],
+            subject,
+            html: `<p>Hi,</p><p>Your order for <strong>${params.productTitle}</strong> is now <strong>${params.status}</strong>.</p>${params.trackingNumber ? `<p>Tracking number: ${params.trackingNumber}</p>` : ""}<p>Thanks,<br/>${params.brandName} Team</p>`,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(JOB_ERROR_MESSAGES.RESEND_API_ERROR(response.status, body));
+    }
+}
+export async function handleOrderStatusChange(input, ctx) {
+    const { orderId, before, after } = input;
+    if (!before || !after)
+        return;
+    if (before.status === after.status)
+        return;
+    const newStatus = after.status;
+    const config = STATUS_CONFIG[newStatus];
+    if (!config) {
+        ctx.logger.info(`No handler for status transition → ${newStatus}`, { orderId });
+        return;
+    }
+    const userEmail = decryptPii(after.userEmail);
+    try {
+        const messageText = config.message({
+            productTitle: after.productTitle,
+            trackingNumber: after.trackingNumber,
+        });
+        await notificationRepository.create({
+            userId: after.userId,
+            type: config.type,
+            priority: config.priority,
+            title: config.title,
+            message: messageText,
+            relatedId: orderId,
+            relatedType: "order",
+        });
+        try {
+            await getAdminRealtimeDb().ref(`notifications/${after.userId}`).push({
+                type: config.type,
+                title: config.title,
+                message: messageText,
+                timestamp: Date.now(),
+                read: false,
+            });
+        }
+        catch (rtdbError) {
+            ctx.logger.error("Realtime DB push failed (non-fatal)", rtdbError);
+        }
+        if (config.sendEmail) {
+            const apiKey = ctx.env("RESEND_API_KEY") ?? "";
+            if (!apiKey) {
+                ctx.logger.error(JOB_ERROR_MESSAGES.RESEND_KEY_MISSING, null);
+            }
+            else {
+                try {
+                    const fromAddress = ctx.env("ORDER_EMAIL_FROM") ?? ctx.env("RESEND_FROM_ADDRESS") ?? "";
+                    const brandName = ctx.env("APPKIT_BRAND_NAME") ?? "";
+                    if (!fromAddress || !brandName) {
+                        ctx.logger.error("ORDER_EMAIL_FROM / APPKIT_BRAND_NAME not configured — skipping order status email", null, { orderId });
+                    }
+                    else {
+                        await sendResendEmail({
+                            to: userEmail,
+                            status: newStatus,
+                            orderId,
+                            productTitle: after.productTitle,
+                            trackingNumber: after.trackingNumber,
+                            apiKey,
+                            fromAddress,
+                            brandName,
+                        });
+                    }
+                }
+                catch (emailError) {
+                    ctx.logger.error("Email send failed (non-fatal)", emailError, { orderId });
+                }
+            }
+        }
+        ctx.logger.info(`Order ${orderId} status → ${newStatus}`, {
+            userId: after.userId,
+            emailSent: config.sendEmail,
+        });
+    }
+    catch (error) {
+        ctx.logger.error("Error handling order status change", error, { orderId });
+        throw error;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Core: SB-UNI-V product stock-change reaction.
+ *
+ * Looks up every bundle category (categoryType:"bundle") that lists the
+ * product in `bundleProductIds[]` and recomputes its `bundleStockStatus`.
+ * Also updates every grouped listing that lists the product in `productIds[]`
+ * — bumps `activeMemberCount` and `visibilityStatus`.
+ *
+ * Cheap: each affected bundle/group reads its `bundleProductIds.length`
+ * member products (≤16 typically). Caller should skip when the product's
+ * status didn't transition between "available" and "unavailable".
+ */
+import type { JobContext } from "../runtime/types";
+export declare function isAvailable(status?: string | null): boolean;
+export declare function syncBundlesForProduct(productId: string, ctx: JobContext): Promise<number>;
+export declare function syncGroupedListingsForProduct(productId: string, ctx: JobContext): Promise<number>;
+export interface HandleProductStockChangeInput {
+    productId: string;
+    beforeStatus: string | null;
+    afterStatus: string | null;
+    isDelete: boolean;
+}
+export declare function handleProductStockChange(input: HandleProductStockChangeInput, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,130 @@
+/**
+ * Core: SB-UNI-V product stock-change reaction.
+ *
+ * Looks up every bundle category (categoryType:"bundle") that lists the
+ * product in `bundleProductIds[]` and recomputes its `bundleStockStatus`.
+ * Also updates every grouped listing that lists the product in `productIds[]`
+ * — bumps `activeMemberCount` and `visibilityStatus`.
+ *
+ * Cheap: each affected bundle/group reads its `bundleProductIds.length`
+ * member products (≤16 typically). Caller should skip when the product's
+ * status didn't transition between "available" and "unavailable".
+ */
+const CATEGORIES_COLLECTION = "categories";
+const GROUPED_LISTINGS_COLLECTION = "groupedListings";
+const PRODUCT_COLLECTION = "products";
+const UNAVAILABLE_STATUSES = new Set(["sold", "out_of_stock", "discontinued"]);
+const MIN_ACTIVE_DEFAULT = 2;
+export function isAvailable(status) {
+    if (!status)
+        return false;
+    return !UNAVAILABLE_STATUSES.has(status);
+}
+async function recomputeBundleStatus(productIds, minActive, ctx) {
+    if (productIds.length === 0)
+        return "out_of_stock";
+    let unavailable = 0;
+    for (let i = 0; i < productIds.length; i += 30) {
+        const chunk = productIds.slice(i, i + 30);
+        const snap = await ctx.db
+            .collection(PRODUCT_COLLECTION)
+            .where("__name__", "in", chunk)
+            .get();
+        for (const doc of snap.docs) {
+            const status = doc.data().status;
+            if (!isAvailable(status))
+                unavailable++;
+        }
+        if (snap.size < chunk.length)
+            unavailable += chunk.length - snap.size;
+    }
+    const active = productIds.length - unavailable;
+    if (unavailable === 0)
+        return "in_stock";
+    if (active < minActive)
+        return "out_of_stock";
+    return "partial";
+}
+export async function syncBundlesForProduct(productId, ctx) {
+    const snap = await ctx.db
+        .collection(CATEGORIES_COLLECTION)
+        .where("categoryType", "==", "bundle")
+        .where("bundleProductIds", "array-contains", productId)
+        .get();
+    let updated = 0;
+    for (const bundleDoc of snap.docs) {
+        const data = bundleDoc.data();
+        const ids = data.bundleProductIds ?? [];
+        const minActive = data.minActiveMembers ?? 1;
+        const next = await recomputeBundleStatus(ids, minActive, ctx);
+        if (next !== data.bundleStockStatus) {
+            await bundleDoc.ref.update({
+                bundleStockStatus: next,
+                bundleQueryResolvedAt: ctx.now,
+                updatedAt: ctx.now,
+            });
+            updated++;
+        }
+    }
+    return updated;
+}
+export async function syncGroupedListingsForProduct(productId, ctx) {
+    const snap = await ctx.db
+        .collection(GROUPED_LISTINGS_COLLECTION)
+        .where("productIds", "array-contains", productId)
+        .get();
+    let updated = 0;
+    for (const groupDoc of snap.docs) {
+        const data = groupDoc.data();
+        const productIds = data.productIds ?? [];
+        if (productIds.length === 0)
+            continue;
+        const minActive = data.minActiveMembers ?? MIN_ACTIVE_DEFAULT;
+        let activeCount = 0;
+        for (let i = 0; i < productIds.length; i += 30) {
+            const chunk = productIds.slice(i, i + 30);
+            const productSnap = await ctx.db
+                .collection(PRODUCT_COLLECTION)
+                .where("__name__", "in", chunk)
+                .get();
+            for (const doc of productSnap.docs) {
+                const status = doc.data().status;
+                if (isAvailable(status))
+                    activeCount++;
+            }
+        }
+        const nextVisibility = activeCount >= minActive ? "visible" : "hidden";
+        if (activeCount !== data.activeMemberCount ||
+            nextVisibility !== data.visibilityStatus) {
+            await groupDoc.ref.update({
+                activeMemberCount: activeCount,
+                visibilityStatus: nextVisibility,
+                updatedAt: ctx.now,
+            });
+            updated++;
+        }
+    }
+    return updated;
+}
+export async function handleProductStockChange(input, ctx) {
+    const { productId, beforeStatus, afterStatus, isDelete } = input;
+    const beforeAvailable = isAvailable(beforeStatus);
+    const afterAvailable = isAvailable(afterStatus);
+    const stateFlipped = beforeAvailable !== afterAvailable;
+    if (!isDelete && !stateFlipped) {
+        return;
+    }
+    try {
+        const bundlesUpdated = await syncBundlesForProduct(productId, ctx);
+        const groupsUpdated = await syncGroupedListingsForProduct(productId, ctx);
+        ctx.logger.info("onProductStockChange synced", {
+            productId,
+            bundlesUpdated,
+            groupsUpdated,
+            isDelete,
+        });
+    }
+    catch (err) {
+        ctx.logger.error("onProductStockChange sync failed (non-fatal)", err, { productId });
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Core: keep category metrics + store stats in sync when a product document
+ * is written. Only published products count.
+ */
+import type { JobContext } from "../runtime/types";
+export type ProductDoc = Record<string, unknown>;
+export interface HandleProductWriteInput {
+    productId: string;
+    before: ProductDoc | null;
+    after: ProductDoc | null;
+}
+export declare function handleProductWrite(input: HandleProductWriteInput, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,94 @@
+/**
+ * Core: keep category metrics + store stats in sync when a product document
+ * is written. Only published products count.
+ */
+import { categoriesRepository, storeRepository, } from "../../../../repositories";
+import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
+const UNAVAILABLE_PRODUCT_STATUSES = new Set([
+    ProductStatusValues.SOLD,
+    ProductStatusValues.OUT_OF_STOCK,
+    ProductStatusValues.DISCONTINUED,
+]);
+void UNAVAILABLE_PRODUCT_STATUSES;
+async function getParentIds(categoryId) {
+    if (!categoryId)
+        return [];
+    return (await categoriesRepository.findById(categoryId))?.parentIds ?? [];
+}
+export async function handleProductWrite(input, ctx) {
+    const { productId, before, after } = input;
+    const beforeStatus = before?.status ?? null;
+    const afterStatus = after?.status ?? null;
+    const beforeCategory = before?.category ?? null;
+    const afterCategory = after?.category ?? null;
+    const beforeStoreId = (before?.storeId || before?.sellerId) ?? null;
+    const afterStoreId = (after?.storeId || after?.sellerId) ?? null;
+    const isAuction = after?.listingType === "auction";
+    const beforeIsAuction = before?.listingType === "auction";
+    const wasPublished = beforeStatus === ProductStatusValues.PUBLISHED;
+    const isPublished = afterStatus === ProductStatusValues.PUBLISHED;
+    const isDelete = !after;
+    try {
+        if (isDelete && wasPublished && beforeCategory) {
+            const parentIds = await getParentIds(beforeCategory);
+            const batch = ctx.db.batch();
+            categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
+            await batch.commit();
+            if (beforeStoreId)
+                await storeRepository.incrementTotalProducts(beforeStoreId, -1);
+            ctx.logger.info("Decremented counters on hard-delete", {
+                productId,
+                category: beforeCategory,
+                storeId: beforeStoreId,
+            });
+        }
+        else if (!wasPublished && isPublished && afterCategory) {
+            const parentIds = await getParentIds(afterCategory);
+            const batch = ctx.db.batch();
+            categoriesRepository.updateMetricsInBatch(batch, afterCategory, parentIds, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
+            await batch.commit();
+            if (afterStoreId)
+                await storeRepository.incrementTotalProducts(afterStoreId, 1);
+            ctx.logger.info("Incremented counters on publish", {
+                productId,
+                category: afterCategory,
+                storeId: afterStoreId,
+            });
+        }
+        else if (wasPublished && !isPublished && beforeCategory) {
+            const parentIds = await getParentIds(beforeCategory);
+            const batch = ctx.db.batch();
+            categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
+            await batch.commit();
+            if (beforeStoreId)
+                await storeRepository.incrementTotalProducts(beforeStoreId, -1);
+            ctx.logger.info("Decremented counters on unpublish", {
+                productId,
+                category: beforeCategory,
+                storeId: beforeStoreId,
+            });
+        }
+        else if (wasPublished &&
+            isPublished &&
+            beforeCategory &&
+            afterCategory &&
+            beforeCategory !== afterCategory) {
+            const [beforeParents, afterParents] = await Promise.all([
+                getParentIds(beforeCategory),
+                getParentIds(afterCategory),
+            ]);
+            const batch = ctx.db.batch();
+            categoriesRepository.updateMetricsInBatch(batch, beforeCategory, beforeParents, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
+            categoriesRepository.updateMetricsInBatch(batch, afterCategory, afterParents, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
+            await batch.commit();
+            ctx.logger.info("Moved product between categories", {
+                productId,
+                from: beforeCategory,
+                to: afterCategory,
+            });
+        }
+    }
+    catch (err) {
+        ctx.logger.error("Counter update failed (non-fatal)", err, { productId });
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { JobContext } from "../runtime/types";
+export interface HandleReviewWriteInput {
+    reviewId: string;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+}
+export declare function handleReviewWrite(input: HandleReviewWriteInput, ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,49 @@
+import { reviewRepository, storeRepository } from "../../../../repositories";
+import { ReviewStatusValues } from "../../../../features/reviews/schemas/firestore";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
+export async function handleReviewWrite(input, ctx) {
+    const { reviewId, before: beforeData, after: afterData } = input;
+    const beforeStatus = beforeData?.status ?? null;
+    const afterStatus = afterData?.status ?? null;
+    const wasApproved = beforeStatus === ReviewStatusValues.APPROVED;
+    const isApproved = afterStatus === ReviewStatusValues.APPROVED;
+    if (!wasApproved && !isApproved)
+        return;
+    const data = afterData ?? beforeData;
+    if (!data)
+        return;
+    const productId = data.productId ?? null;
+    const storeId = data.storeId ?? null;
+    if (!productId) {
+        ctx.logger.error("Review has no productId — skipping", null, { reviewId });
+        return;
+    }
+    try {
+        const { count, avgRating } = await reviewRepository.getApprovedRatingAggregate(productId);
+        await ctx.db.collection(PRODUCT_COLLECTION).doc(productId).update({
+            avgRating,
+            reviewCount: count,
+            updatedAt: new Date(),
+        });
+        ctx.logger.info("Updated product rating stats", {
+            reviewId,
+            productId,
+            count,
+            avgRating,
+        });
+        if (storeId) {
+            const storeStats = await reviewRepository.getApprovedRatingAggregateByStore(storeId);
+            await storeRepository.updateReviewStats(storeId, storeStats.count, storeStats.avgRating);
+            ctx.logger.info("Updated store review stats", {
+                reviewId,
+                storeId,
+                count: storeStats.count,
+                avgRating: storeStats.avgRating,
+            });
+        }
+    }
+    catch (err) {
+        ctx.logger.error("Failed to update rating stats", err, { reviewId, productId, storeId });
+        throw err;
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Core: stores/{id} onWrite — currently a no-op. Previous implementation
+ * synced an external search index that has since been removed.
+ */
+import type { JobContext } from "../runtime/types";
+export type StoreDoc = Record<string, unknown>;
+export interface HandleStoreWriteInput {
+    storeId: string;
+    before: StoreDoc | null;
+    after: StoreDoc | null;
+}
+export declare function handleStoreWrite(_input: HandleStoreWriteInput, _ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,7 @@
+/**
+ * Core: stores/{id} onWrite — currently a no-op. Previous implementation
+ * synced an external search index that has since been removed.
+ */
+export async function handleStoreWrite(_input, _ctx) {
+    // Intentionally empty — search provider removed; Firestore queries handle search now.
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Core: dispatch pending payouts via Razorpay Payouts API.
+ *
+ * Reads RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET / RAZORPAY_ACCOUNT_NUMBER from
+ * env (via `ctx.env`). On 3rd consecutive failure the record is marked failed.
+ */
+import type { JobContext } from "../runtime/types";
+export declare function runPayoutBatch(ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,102 @@
+/**
+ * Core: dispatch pending payouts via Razorpay Payouts API.
+ *
+ * Reads RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET / RAZORPAY_ACCOUNT_NUMBER from
+ * env (via `ctx.env`). On 3rd consecutive failure the record is marked failed.
+ */
+import { payoutRepository } from "../../../../repositories";
+const MAX_FAILURES = 3;
+async function dispatch(ctx, entry) {
+    const { ref, data: payout } = entry;
+    await payoutRepository.markProcessing(ref);
+    try {
+        const keyId = ctx.env("RAZORPAY_KEY_ID") ?? "";
+        const keySecret = ctx.env("RAZORPAY_KEY_SECRET") ?? "";
+        const accountNumber = ctx.env("RAZORPAY_ACCOUNT_NUMBER") ?? "";
+        const apiBaseUrl = ctx.env("RAZORPAY_API_BASE_URL") ?? "https://api.razorpay.com/v1";
+        const brandName = ctx.env("APP_BRAND_NAME") ?? "";
+        if (!keyId || !keySecret || !accountNumber) {
+            throw new Error("Razorpay credentials not configured");
+        }
+        const basicAuth = Buffer.from(`${keyId}:${keySecret}`).toString("base64");
+        let fundAccount;
+        if (payout.paymentMethod === "upi" && payout.upiId) {
+            fundAccount = { account_type: "vpa", vpa: { address: payout.upiId } };
+        }
+        else if (payout.bankAccount) {
+            fundAccount = {
+                account_type: "bank_account",
+                bank_account: {
+                    name: payout.bankAccount.accountHolderName,
+                    ifsc: payout.bankAccount.ifscCode,
+                    account_number: payout.bankAccount.accountNumberMasked,
+                },
+            };
+        }
+        else {
+            throw new Error("Payout has no fund account configured");
+        }
+        const payload = {
+            account_number: accountNumber,
+            fund_account: {
+                ...fundAccount,
+                contact: { name: payout.sellerEmail, type: "vendor", email: payout.sellerEmail },
+            },
+            // Use netAmount when refund deductions have been applied, otherwise gross amount.
+            amount: Math.round((payout.netAmount ?? payout.amount) * 100),
+            currency: payout.currency.toUpperCase(),
+            mode: payout.paymentMethod === "upi" ? "UPI" : "NEFT",
+            purpose: "payout",
+            reference_id: payout.id,
+            narration: brandName
+                ? `${brandName} payout for seller ${payout.storeId}`
+                : `Payout for seller ${payout.storeId}`,
+        };
+        const response = await fetch(`${apiBaseUrl}/payouts`, {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${basicAuth}`,
+                "Content-Type": "application/json",
+                "X-Payout-Idempotency": payout.id,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const errBody = await response.text();
+            throw new Error(`Razorpay ${response.status}: ${errBody}`);
+        }
+        const result = (await response.json());
+        await payoutRepository.recordSuccess(ref, result.id, result.status);
+        ctx.logger.info(`Payout ${payout.id} dispatched`, { razorpayId: result.id, razorpayStatus: result.status });
+    }
+    catch (error) {
+        const failureCount = (payout.failureCount ?? 0) + 1;
+        const isFinal = failureCount >= MAX_FAILURES;
+        const reason = error instanceof Error ? error.message : String(error);
+        await payoutRepository.recordFailure(ref, failureCount, reason, isFinal);
+        if (isFinal) {
+            ctx.logger.error(`Payout ${payout.id} permanently failed after ${MAX_FAILURES} attempts`, error, {
+                sellerId: payout.storeId,
+            });
+        }
+        else {
+            ctx.logger.warn(`Payout ${payout.id} failed (attempt ${failureCount})`, { error: reason });
+        }
+    }
+}
+export async function runPayoutBatch(ctx) {
+    ctx.logger.info("Starting payout batch sweep");
+    const pending = await payoutRepository.getPending();
+    if (pending.length === 0) {
+        ctx.logger.info("No pending payouts to process");
+        return;
+    }
+    ctx.logger.info(`Dispatching ${pending.length} payout(s)`);
+    const results = await Promise.allSettled(pending.map((entry) => dispatch(ctx, entry)));
+    const failed = results.filter((r) => r.status === "rejected").length;
+    ctx.logger.info("Payout batch complete", {
+        total: pending.length,
+        succeeded: pending.length - failed,
+        failed,
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { JobContext } from "../runtime/types";
+export declare function runPendingOrderTimeout(ctx: JobContext): Promise<void>;

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

@@ -0,0 +1,27 @@
+import { notificationRepository, orderRepository } from "../../../../repositories";
+import { ORDER_MESSAGES } from "../handlers/messages";
+const DEFAULT_TIMEOUT_HOURS = 24;
+export async function runPendingOrderTimeout(ctx) {
+    const timeoutHours = Number(ctx.env("ORDER_TIMEOUT_HOURS") ?? DEFAULT_TIMEOUT_HOURS);
+    ctx.logger.info(`Scanning orders unpaid > ${timeoutHours}h`);
+    const timedOut = await orderRepository.getTimedOutPending(timeoutHours);
+    if (timedOut.length === 0) {
+        ctx.logger.info("No timed-out pending orders found");
+        return;
+    }
+    const batch = ctx.db.batch();
+    for (const entry of timedOut) {
+        orderRepository.cancelInBatch(batch, entry.ref);
+        notificationRepository.createInBatch(batch, {
+            userId: entry.data.userId,
+            type: "order_cancelled",
+            priority: "normal",
+            title: ORDER_MESSAGES.CANCELLED_TITLE,
+            message: ORDER_MESSAGES.CANCELLED_TIMEOUT_MESSAGE(entry.data.productTitle, timeoutHours),
+            relatedId: entry.data.id,
+            relatedType: "order",
+        });
+    }
+    await batch.commit();
+    ctx.logger.info("Pending order timeout complete", { cancelled: timedOut.length });
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Core: rebuild `position` + `subtreeSize` for every category via
+ * DFS pre-order from the roots. Heals drift left by the trigger's
+ * `positionDirty` flag and any failed real-time updates.
+ */
+import type { JobContext } from "../runtime/types";
+export declare function runPositionsReconcile(ctx: JobContext): Promise<void>;