@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/stores/adapters.js

@@ -33,10 +33,62 @@ export const PUBLIC_STORE_FIELDS = [
     // which is the one outcome the tri-state rule forbids.
     "supportsShippingProtection",
     "supportsSaleProtection",
+    /*
+     * ── D46/D47 + S5a — three more public store flags, same argument ──────────
+     *
+     * PUBLIC for the tri-state reason the two protection flags above are: the
+     * buyer has to know whether this seller will split an order across
+     * addresses BEFORE they commit, and withholding it makes "has not opted in"
+     * indistinguishable from "we did not tell you".
+     *
+     * The two shared-purchase FEES are public for a stronger reason still: a
+     * coordinator commits to a quoted total, and a handling fee plus N−1
+     * shipping legs discovered after they committed is exactly the surprise the
+     * arrangement makes expensive.
+     */
+    "allowSharedPurchase",
+    "sharedPurchaseHandlingFee",
+    "sharedPurchaseExtraShippingPerDestination",
     "createdAt",
 ];
 /** Everything else, with the reason it stays server-side. */
 export const PRIVATE_STORE_FIELDS = [
+    /*
+     * 🛑 `trustedSeller` — OUR RISK POSTURE, not a badge.
+     *
+     * It means we pay this store before the parcel is delivered, so the platform
+     * carries a lost parcel and a non-delivery dispute. That is a statement
+     * about what we are willing to lose, and a buyer has no use for it: it says
+     * nothing about the goods, the seller's rating or their dispatch record.
+     *
+     * Published, it would read as an endorsement — "LetItRip trusts this store"
+     * — which is both a claim we never made and an incentive for sellers to
+     * compete for the flag. It is admin-granted on risk grounds and revocable;
+     * neither survives being visible.
+     */
+    "trustedSeller",
+    /*
+     * 🛑 PRIVATE, and it was briefly classified PUBLIC on a mistaken argument
+     * worth recording so nobody re-makes it.
+     *
+     * The argument was "the cart has to show a buyer whether their points can be
+     * used HERE before they commit" — which is true, and is NOT a reason for
+     * this projection to carry the field. Measured: the cart reads
+     * `pricingPreview.stores[].acceptsPoints`, produced by the checkout pricing
+     * preview (checkout/actions.ts:2980), and the only client readers are
+     * `CartPriceBreakdown.tsx:317` and `CartRouteClient.tsx:1282`, both off that
+     * preview. Neither touches `toStoreListItem` / `toStoreDetail`.
+     *
+     * So the store projection has no reader, and the rule for this file is
+     * explicit: a field moves to PUBLIC only once you can NAME the client that
+     * reads it from this payload. "A different payload needs it" is not that.
+     *
+     * A store page could legitimately advertise "accepts points" one day. When a
+     * reader exists, move it and add it to both builders — the omission is what
+     * `audit-public-projection-parity` caught here (declared PUBLIC, emitted by
+     * nothing), which is the half-migrated state that reads as done.
+     */
+    "acceptsPoints",
     // Internal search index, not content. It is a normalized re-encoding of
     // storeName/description/category — publishing it would leak nothing new, but
     // it has no client reader and would bloat every store payload with a few
@@ -147,6 +199,19 @@ export function toStoreListItem(doc, _opts) {
          */
         supportsShippingProtection: doc.supportsShippingProtection ?? false,
         supportsSaleProtection: doc.supportsSaleProtection ?? false,
+        /*
+         * Same `?? false` rule for the same reason — a definite "not offered"
+         * rather than an `undefined` a truthiness test reads as neither.
+         *
+         * 🛑 The two FEES are passed through as `undefined` when unset, and that
+         * asymmetry is deliberate: a flag's absence means "no", but a fee's
+         * absence means "not configured", which is NOT the same as ₹0. Defaulting
+         * them to zero would quote a coordinator a free arrangement from a store
+         * that simply has not set a price.
+         */
+        allowSharedPurchase: doc.allowSharedPurchase ?? false,
+        sharedPurchaseHandlingFee: doc.sharedPurchaseHandlingFee,
+        sharedPurchaseExtraShippingPerDestination: doc.sharedPurchaseExtraShippingPerDestination,
         createdAt: toIsoString(doc.createdAt),
     };
 }

package/dist/_internal/server/functions/scheduled.d.ts

@@ -5,6 +5,7 @@ export declare const hardBanReinstatement: import("./types").ScheduledFunctionDe
 export declare const paymentReviewAutoApprove: import("./types").ScheduledFunctionDefinition;
 export declare const couponExpiry: import("./types").ScheduledFunctionDefinition;
 export declare const offerExpiry: import("./types").ScheduledFunctionDefinition;
+export declare const reservationExpiry: import("./types").ScheduledFunctionDefinition;
 export declare const productStatsSync: import("./types").ScheduledFunctionDefinition;
 export declare const revenueRollup: import("./types").ScheduledFunctionDefinition;
 export declare const searchIndexBuild: import("./types").ScheduledFunctionDefinition;
@@ -99,4 +100,4 @@ export declare const prizeDrawExpiryReveal: import("./types").ScheduledFunctionD
 export declare const bundleStockSync: import("./types").ScheduledFunctionDefinition;
 export declare const emiInstallmentReminder: import("./types").ScheduledFunctionDefinition;
 export declare const catalogueImageStalenessReminder: import("./types").ScheduledFunctionDefinition;
-export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];
+export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];

package/dist/_internal/server/functions/scheduled.js

@@ -1,6 +1,6 @@
 // Scheduled function definitions (Cloud Scheduler triggers).
 // Cron syntax accepts both Firebase shorthand and standard cron expressions.
-import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, boxRollupReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, obligationSweepHandler, paymentReconcileHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, marketPriceRollupHandler, searchIndexBuildHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
+import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, boxRollupReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, reservationExpiryHandler, obligationSweepHandler, paymentReconcileHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, marketPriceRollupHandler, searchIndexBuildHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
 import { defineFunction } from "./define.js";
 const REGION = "asia-south1";
 const EVERY_5_MIN = "every 5 minutes";
@@ -18,9 +18,80 @@ export const pendingOrderTimeout = defineFunction({
     handler: pendingOrderTimeoutHandler,
     options: { region: REGION, timeoutSeconds: 120, memory: "256MiB", maxInstances: 1 },
 });
+/*
+ * ── 🛑 THE "RETIRE THREE SWEEPS" PLAN STEP IS SELF-CONTRADICTORY ────────────
+ *
+ * Phase 8's plan text reads: *"a retry is a new document … picked up by a
+ * sweep folded into `paymentWindowTimeout` … **Then** retire the three
+ * superseded sweeps"* — and names those three as `pendingOrderTimeout`,
+ * **`paymentWindowTimeout`** and `paymentReviewAutoApprove`.
+ *
+ * It cannot be both. `paymentWindowTimeout` is now the HOST of the job-retry
+ * sweep (see `runDueJobRetries`, called first in its handler, before the early
+ * return), so retiring it would delete the only mechanism that runs a
+ * scheduled retry — and the create trigger deliberately defers to that sweep,
+ * because creating the retry document fires the trigger instantly and would
+ * collapse the backoff to zero. Deleting the host leaves every retry
+ * permanently `pending`: a stall that reads as a queue, which is the exact
+ * failure Phase 8 exists to remove.
+ *
+ * So the retry/DLQ half is built and the retirement is NOT done. That is a
+ * deliberate stop, not an omission:
+ *
+ *  - These three cancel unpaid orders and restock real inventory. Deleting
+ *    them on the strength of a plan line, in a session that cannot run a
+ *    single check, is the autonomous destructive decision Rule #1 forbids.
+ *  - The claim that obligations supersede them needs reading all three
+ *    against the obligation policies AND confirming `obligationSweep`'s `act`
+ *    tier covers each — and the sweep's own comment records that its acting
+ *    branch was narrowed precisely because monetary outcomes were not safe to
+ *    automate. That narrowing was widened for six kinds; whether it covers
+ *    these three is a measurement, not an inference.
+ *  - The Scheduler arithmetic in the plan (34 → 31) is therefore unchanged by
+ *    this commit. Nothing was added either, so the count stands wherever it
+ *    actually is — and CLAUDE.md says to recount rather than quote it, this
+ *    number having drifted six times.
+ *
+ * Whoever takes the retirement: pick a different host for the retry sweep
+ * first, or keep `paymentWindowTimeout` and retire only the other two.
+ *
+ * ── 🛑 MEASURED 2026-10-23: RETIRE NEITHER OF THE OTHER TWO EITHER ─────────
+ *
+ * The paragraph above asks for a measurement rather than an inference —
+ * *"whether [`obligationSweep`'s act tier] covers these three is a
+ * measurement"* — so here it is. **It does not cover either of them, and the
+ * answer is a single predicate.**
+ *
+ * `OBLIGATION_POLICIES["seller-accept"]` is the only candidate for
+ * `pendingOrderTimeout`, and its precondition opens with:
+ *
+ *     precondition: (o) => isPaid(o) && notTerminal(o) && !o.acceptedAt && …
+ *     duration: { value: 3, unit: "days" }
+ *
+ * with `const isPaid = (o) => o.paymentStatus === "paid"`. A pending COD order
+ * is **not paid** — that is the entire point of COD — so the policy EXCLUDES
+ * exactly the orders this sweep exists for, and waits three days where the
+ * sweep acts at 24 hours. Pairwise disjoint, which is the same failure shape
+ * the obligations collection was built to end (Root Cause #27: three sweeps,
+ * pairwise disjoint, an order holding stock forever).
+ *
+ * `paymentReviewAutoApprove` has no candidate at all. The ONLY policy
+ * mentioning `paymentReviewOutcome` is `proof-reupload`, keyed on
+ * `=== "reupload_requested"` — the BUYER re-uploading, not staff failing to
+ * review. Nothing in the twelve kinds means "a proof nobody looked at".
+ *
+ * **Retiring them would therefore**: leave unpaid COD orders holding real
+ * stock forever, and leave an uploaded proof nobody reviewed in limbo forever.
+ * Both silent — an order that is never cancelled raises nothing.
+ *
+ * So the correct state is THREE sweeps kept, not one. The plan's "retire the
+ * other two" was an inference from a coverage claim that measurement does not
+ * support, and this note exists so the next reader does not re-derive it from
+ * the same plan line.
+ */
 export const paymentWindowTimeout = defineFunction({
     name: "paymentWindowTimeout",
-    description: "Cancel + restock orders whose 15-minute manual-payment window expired without proof.",
+    description: "Cancel + restock orders whose 15-minute manual-payment window expired without proof. Also hosts R1 (stuck gateway events) and the Phase 8 job-retry sweep, both before its early return.",
     trigger: { kind: "schedule", cron: EVERY_5_MIN },
     handler: paymentWindowTimeoutHandler,
     options: { region: REGION, timeoutSeconds: 120, memory: "256MiB", maxInstances: 1 },
@@ -53,6 +124,27 @@ export const offerExpiry = defineFunction({
     handler: offerExpiryHandler,
     options: { region: REGION, timeoutSeconds: 120, memory: "256MiB", maxInstances: 1 },
 });
+/*
+ * 🛑 The ONLY bound on a leaked stock hold.
+ *
+ * Every other way a reservation ends is an action somebody takes; this is
+ * what happens when nobody does. Without it a hold is permanent, and a
+ * permanent hold is indistinguishable from stock the seller no longer has —
+ * with no error anywhere, because a lower `availableQuantity` is just a
+ * number.
+ *
+ * Every 15 minutes rather than daily: the default hold is 72 hours, so the
+ * cadence is not about precision, it is about the WORST case. A daily sweep
+ * means "expired at 09:01, buyable again tomorrow", and a buyer told an item
+ * is sold out for a day after the hold lapsed is the failure this prevents.
+ */
+export const reservationExpiry = defineFunction({
+    name: "reservationExpiry",
+    description: "Expire stock reservations past their TTL and restore availableQuantity (every 15 minutes).",
+    trigger: { kind: "schedule", cron: "every 15 minutes" },
+    handler: reservationExpiryHandler,
+    options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
+});
 export const productStatsSync = defineFunction({
     name: "productStatsSync",
     description: "Recompute aggregated product statistics (daily 01:00 UTC).",
@@ -407,6 +499,7 @@ export const SCHEDULED_FUNCTIONS = [
     paymentReviewAutoApprove,
     couponExpiry,
     offerExpiry,
+    reservationExpiry,
     productStatsSync,
     revenueRollup,
     priceIndexRollup,

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

@@ -3,7 +3,7 @@ import { getDefaultCurrency } from "../../../../core/index.js";
 import { computePayoutDeduction } from "../../../shared/fees/calculator.js";
 import { payoutCutoff } from "../../../shared/fees/payout-hold.js";
 import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../shared/features/shipping/protections.js";
-import { ordersTaxableValue, ordersShippingReimbursement, } from "../../../shared/checkout/order-math.js";
+import { ordersTaxableValue, ordersShippingReimbursement, ordersPointsBorneByStore, } from "../../../shared/checkout/order-math.js";
 import { BATCH_LIMIT } from "../handlers/messages.js";
 /*
  * 🛑 `AUTO_PAYOUT_WINDOW_DAYS = 7` and `getBusinessDayCutoff` were REMOVED on
@@ -120,8 +120,17 @@ export async function runAutoPayoutEligibility(ctx) {
          * `{ id, data }` wrappers, and passing the wrapper would read every field
          * as undefined and silently reimburse zero.
          */
-        ordersShippingReimbursement(orders.map((o) => o.data)));
+        ordersShippingReimbursement(orders.map((o) => o.data)), 
+        /*
+         * D46/D47 — the store-funded points, both ends (decisions 3 and 17).
+         * Same `.data` unwrap for the same reason, and the same position outside
+         * the fee bases: a commission on a discount the seller funded is not a
+         * commission on a sale.
+         */
+        ordersPointsBorneByStore(orders.map((o) => o.data)));
         const payoutInput = {
+            /* Every row this job writes settles a SELLER liability. */
+            payeeType: "store",
             storeId,
             // `displayName` is plaintext by D1; the email fallback must be revealed.
             sellerName: (seller.displayName ?? sellerPlain.email ?? sellerId),

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

@@ -58,6 +58,10 @@ export interface DailyStatusDigestSummary {
     nearestCaseDueAt: Date | null;
     /** Gateway events that never reached a terminal status — the inbox backlog. */
     unprocessedGatewayEventCount: number;
+    courierWalletBalance: number | null;
+    courierWalletLow: boolean;
+    /** Why the balance is null, when it is. Printed instead of a figure. */
+    courierWalletNote?: string;
 }
 /** Gathers the last-24h numbers. Exported so the admin manual-trigger route can reuse it. */
 export declare function collectDailyStatusSummary(): Promise<DailyStatusDigestSummary>;

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

@@ -16,6 +16,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Fragment } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { getProviders } from "../../../../contracts/registry.js";
+import { checkCourierWalletAndAlert } from "../../features/shipping/courier-block.js";
 import { sendEmail } from "../../../../features/contact/email.js";
 import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
 import { ORDER_COLLECTION, OrderStatusValues } from "../../../../features/orders/schemas/firestore.js";
@@ -163,6 +165,14 @@ export async function collectDailyStatusSummary() {
      * nearest-deadline query below swallows and returns null rather than
      * throwing.
      */
+    /*
+     * The courier wallet. Same spirit as `safeCount` above — it can never fail
+     * the digest, and it ALERTS at most once per unresolved episode rather than
+     * once per day (the case's `openOrObserve` is the dedupe). `getProviders()`
+     * always populates `shipping`, and the base class's `getWalletBalance`
+     * default answers "no wallet" for manual, so this needs no capability check.
+     */
+    const courierWallet = await checkCourierWalletAndAlert(getProviders().shipping);
     const [paymentCasesError, paymentCasesWarning, paymentCasesInfo, unprocessedGatewayEventCount] = await Promise.all([
         safeCount(db
             .collection(PAYMENT_CASES_COLLECTION)
@@ -245,6 +255,9 @@ export async function collectDailyStatusSummary() {
         paymentCasesInfo,
         nearestCaseDueAt,
         unprocessedGatewayEventCount,
+        courierWalletBalance: courierWallet.balance,
+        courierWalletLow: courierWallet.low,
+        ...(courierWallet.reason ? { courierWalletNote: courierWallet.reason } : {}),
     };
 }
 function renderDigestHtml(summary, siteName, version) {
@@ -254,7 +267,9 @@ function renderDigestHtml(summary, siteName, version) {
                             ? `Deployment ${version} is live. Activity for the last 24 hours.`
                             : "Activity for the last 24 hours.", _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Orders placed", value: summary.orderCount }), _jsx(StatLine, { label: "Revenue (excl. cancelled/refunded)", value: currency(summary.revenue) }), _jsx(StatLine, { label: "Active listings", value: summary.activeListingCount }), _jsx(StatLine, { label: "Pending > 24h (needs attention)", value: summary.stuckPendingCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Orders by status" }), _jsx("br", {}), _jsx("br", {}), statusRows.length === 0 ? ("No orders in this window.") : (statusRows.map(([status, count]) => (_jsx(StatLine, { label: status, value: count }, status))))] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Inbox" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "New contact messages", value: summary.contactTotal }), _jsx(StatLine, { label: "New support tickets", value: summary.newTicketCount }), _jsx(StatLine, { label: "Tickets open / in progress / waiting on user", value: `${summary.ticketsOpen} / ${summary.ticketsInProgress} / ${summary.ticketsWaitingOnUser}` }), _jsx(StatLine, { label: "Unread admin notifications", value: summary.unreadAdminNotificationCount })] }), summary.contactMessages.length > 0 ? (_jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Contact messages" }), _jsx("br", {}), _jsx("br", {}), summary.contactMessages.map((m) => (_jsxs(Fragment, { children: [_jsx(EmailBold, { children: m.subject }), _jsx("br", {}), m.name, " \u2014", " ", _jsxs(EmailLink, { href: `mailto:${m.email}?subject=${encodeURIComponent(`Re: ${m.subject}`)}`, children: ["Reply to ", m.email] }), _jsx("br", {}), m.excerpt, _jsx("br", {}), _jsx("br", {})] }, m.id))), summary.contactTotal > summary.contactMessages.length
                             ? `…and ${summary.contactTotal - summary.contactMessages.length} more in /admin/contact.`
-                            : null] })) : null, _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Needs attention" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Manual payments pending", value: summary.manualPaymentPendingCount }), _jsx(StatLine, { label: "New scam reports", value: summary.newScamReportCount }), _jsx(StatLine, { label: "New newsletter subscribers", value: summary.newSubscriberCount }), _jsx(StatLine, { label: "Admin actions logged", value: summary.adminActionCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Money at risk" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Open cases \u2014 urgent", value: summary.paymentCasesError }), _jsx(StatLine, { label: "Open cases \u2014 warning", value: summary.paymentCasesWarning }), _jsx(StatLine, { label: "Open cases \u2014 info", value: summary.paymentCasesInfo }), _jsx(StatLine, { label: "Nearest external deadline", value: summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none" }), _jsx(StatLine, { label: "Unfinished gateway events", value: summary.unprocessedGatewayEventCount })] }), _jsx(EmailFooter, { copyright: `© ${new Date().getFullYear()}${siteName ? ` ${siteName}` : ""}. All rights reserved.` })] }) }))}`;
+                            : null] })) : null, _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Needs attention" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Manual payments pending", value: summary.manualPaymentPendingCount }), _jsx(StatLine, { label: "New scam reports", value: summary.newScamReportCount }), _jsx(StatLine, { label: "New newsletter subscribers", value: summary.newSubscriberCount }), _jsx(StatLine, { label: "Admin actions logged", value: summary.adminActionCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Money at risk" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Open cases \u2014 urgent", value: summary.paymentCasesError }), _jsx(StatLine, { label: "Open cases \u2014 warning", value: summary.paymentCasesWarning }), _jsx(StatLine, { label: "Open cases \u2014 info", value: summary.paymentCasesInfo }), _jsx(StatLine, { label: "Nearest external deadline", value: summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none" }), _jsx(StatLine, { label: "Unfinished gateway events", value: summary.unprocessedGatewayEventCount }), _jsx(StatLine, { label: "Courier wallet", value: summary.courierWalletBalance === null
+                                ? `unknown (${summary.courierWalletNote ?? "not read"})`
+                                : `${currency(summary.courierWalletBalance)}${summary.courierWalletLow ? " — LOW, top up" : ""}` })] }), _jsx(EmailFooter, { copyright: `© ${new Date().getFullYear()}${siteName ? ` ${siteName}` : ""}. All rights reserved.` })] }) }))}`;
 }
 /**
  * The plain-text twin of `renderDigestHtml`.
@@ -288,7 +303,9 @@ function renderDigestText(summary, version) {
      * the same unconditional rendering, because a mail client showing the text
      * part must not get a digest missing the one block with a deadline in it.
      */
-    lines.push("", "MONEY AT RISK", `Open cases — urgent: ${summary.paymentCasesError}`, `Open cases — warning: ${summary.paymentCasesWarning}`, `Open cases — info: ${summary.paymentCasesInfo}`, `Nearest external deadline: ${summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none"}`, `Unfinished gateway events: ${summary.unprocessedGatewayEventCount}`);
+    lines.push("", "MONEY AT RISK", `Open cases — urgent: ${summary.paymentCasesError}`, `Open cases — warning: ${summary.paymentCasesWarning}`, `Open cases — info: ${summary.paymentCasesInfo}`, `Nearest external deadline: ${summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none"}`, `Unfinished gateway events: ${summary.unprocessedGatewayEventCount}`, `Courier wallet: ${summary.courierWalletBalance === null
+        ? `unknown (${summary.courierWalletNote ?? "not read"})`
+        : `${currency(summary.courierWalletBalance)}${summary.courierWalletLow ? " — LOW, top up" : ""}`}`);
     return lines.join("\n");
 }
 const DEPLOY_MARKER_COLLECTION = "system";

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

@@ -46,4 +46,5 @@ export { handleProductStockChange, type HandleProductStockChangeInput, syncBundl
 export { handleReviewWrite, type HandleReviewWriteInput } from "./onReviewWrite";
 export { handleCategoryWrite, type HandleCategoryWriteInput, type CategoryDoc, } from "./onCategoryWrite";
 export { handleStoreWrite, type HandleStoreWriteInput, type StoreDoc, } from "./onStoreWrite";
-export { handleJobCreated, type HandleJobCreatedInput } from "./onJobCreated";
+export { handleJobCreated, runDueJobRetries, type HandleJobCreatedInput, } from "./onJobCreated";
+export { runJobOnce, type RunJobOnceInput } from "./runJobOnce";

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

@@ -49,4 +49,5 @@ export { handleProductStockChange, syncBundlesForProduct, syncGroupedListingsFor
 export { handleReviewWrite } from "./onReviewWrite.js";
 export { handleCategoryWrite, } from "./onCategoryWrite.js";
 export { handleStoreWrite, } from "./onStoreWrite.js";
-export { handleJobCreated } from "./onJobCreated.js";
+export { handleJobCreated, runDueJobRetries, } from "./onJobCreated.js";
+export { runJobOnce } from "./runJobOnce.js";

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

@@ -14,6 +14,7 @@ import { runResetOtpVerification } from "./resetOtpVerification.js";
 import { runNewsletterExport } from "./newsletterExport.js";
 import { runStoreNameBackfill } from "./storeNameBackfill.js";
 import { runCategoryTaxonomyBackfill } from "./categoryTaxonomyBackfill.js";
+import { bookShipment } from "../../features/shipping/book.js";
 async function runPayoutsWeeklyJob(_payload, ctx) {
     const { payoutsCreated, ordersProcessed, payoutIds } = await runWeeklyPayoutEligibility(ctx);
     return {
@@ -56,7 +57,51 @@ async function runCategoryTaxonomyBackfillJob(payload, ctx) {
     const kind = payload.kind === "rename" ? "rename" : "reparent";
     return runCategoryTaxonomyBackfill({ categoryId: String(payload.categoryId ?? ""), kind }, ctx);
 }
+/**
+ * Book a parcel through the platform's carrier account.
+ *
+ * 🛑 A JOB rather than a synchronous route, and the reason is Rule #6. A
+ * booking is an outbound carrier call on a path the seller is waiting on,
+ * against a 10s sync-function ceiling — and a timeout there is the worst
+ * outcome available: the carrier may have accepted, so retrying double-books
+ * and not retrying leaves a parcel nobody collects.
+ *
+ * The runner's own failure is recoverable: `bookShipment` refuses an order
+ * that already has a tracking number, so a retried job is a no-op rather
+ * than a second parcel.
+ */
+async function runBookShipmentJob(payload, _ctx) {
+    const dims = (payload.dimensions ?? {});
+    const result = await bookShipment({
+        orderId: String(payload.orderId ?? ""),
+        pickupAddressId: String(payload.pickupAddressId ?? ""),
+        dimensions: {
+            weight: Number(dims.weight ?? 0),
+            length: Number(dims.length ?? 0),
+            width: Number(dims.width ?? 0),
+            height: Number(dims.height ?? 0),
+        },
+    });
+    const orderId = String(payload.orderId ?? "");
+    return {
+        summary: { total: 1, succeeded: 1, skipped: 0, failed: 0 },
+        succeeded: [orderId],
+        skipped: [],
+        failed: [],
+        /*
+         * The tracking id goes in `data`, which `useBulkEvent` surfaces — the
+         * seller's next question after "did it book" is "what is the number",
+         * and making them reload the order to find it is a wasted round trip.
+         */
+        data: {
+            trackingId: result.trackingId,
+            ...(result.courier ? { courier: result.courier } : {}),
+            ...(result.estimatedDelivery ? { estimatedDelivery: result.estimatedDelivery } : {}),
+        },
+    };
+}
 export const JOB_RUNNERS = {
+    bookShipment: runBookShipmentJob,
     payoutsWeekly: runPayoutsWeeklyJob,
     hardBanCascade: runHardBanCascadeJob,
     resetOtpVerification: runResetOtpVerificationJob,

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

@@ -5,13 +5,11 @@
  * (CLAUDE.md Rule #6 — Vercel routes never do heavy work; they write a
  * `jobs` doc and return, this Function does the actual processing).
  *
- * Flow:
- *   1. Mark the job "processing".
- *   2. Look up a runner in `JOB_RUNNERS` by `job.jobType`.
- *   3. Run it, mark the job "done"/"failed", and best-effort ping the
- *      `bulk_events/{jobId}` RTDB channel the client is subscribed to via
- *      `useBulkEvent` — every RTDB write is its own try/catch so a ping
- *      failure never masks the real Firestore result.
+ * ## 🛑 It no longer runs the job itself — `runJobOnce` does (Phase 8)
+ *
+ * The attempt, the failure classification and the retry scheduling all live in
+ * `runJobOnce`, which the retry sweep also calls. One dispatch path for both
+ * entry points, or the two drift the first time either learns something.
  */
 import type { JobDocument } from "../../../../features/jobs/schemas/firestore";
 import type { JobContext } from "../runtime/types";
@@ -20,3 +18,28 @@ export interface HandleJobCreatedInput {
     job: JobDocument;
 }
 export declare function handleJobCreated(input: HandleJobCreatedInput, ctx: JobContext): Promise<void>;
+/**
+ * The retry sweep — runs every scheduled attempt whose time has come.
+ *
+ * ## 🛑 Folded into an EXISTING scheduled function, not a new one
+ *
+ * It is called from `paymentWindowTimeout` (every 5 minutes). Cloud Scheduler
+ * bills per registered job and this project already carries ~34 of them
+ * against 3 free; adding a 35th to run a usually-empty query is the cost this
+ * plan explicitly refuses. The same reasoning put the ledger reconciler inside
+ * `dailyDataCleanup` and R1 inside this same function.
+ *
+ * 🛑 And it is placed FIRST at its call site, before that function's early
+ * return — `paymentWindowTimeout` returns as soon as there are no expired
+ * payment windows, which is most ticks, so appending would run the sweep only
+ * on the minority of ticks with unrelated work (Root Cause #27).
+ *
+ * Sequential, not `Promise.all`. A job runner is heavy by definition — that is
+ * why it is a job — and twenty of them concurrently inside one 540s function
+ * is how a sweep exhausts its own budget. Twenty sequential attempts that run
+ * out of time simply leave the rest `pending` for the next tick, which is the
+ * safe failure.
+ */
+export declare function runDueJobRetries(ctx: JobContext): Promise<{
+    ran: number;
+}>;

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

@@ -5,55 +5,88 @@
  * (CLAUDE.md Rule #6 — Vercel routes never do heavy work; they write a
  * `jobs` doc and return, this Function does the actual processing).
  *
- * Flow:
- *   1. Mark the job "processing".
- *   2. Look up a runner in `JOB_RUNNERS` by `job.jobType`.
- *   3. Run it, mark the job "done"/"failed", and best-effort ping the
- *      `bulk_events/{jobId}` RTDB channel the client is subscribed to via
- *      `useBulkEvent` — every RTDB write is its own try/catch so a ping
- *      failure never masks the real Firestore result.
+ * ## 🛑 It no longer runs the job itself — `runJobOnce` does (Phase 8)
+ *
+ * The attempt, the failure classification and the retry scheduling all live in
+ * `runJobOnce`, which the retry sweep also calls. One dispatch path for both
+ * entry points, or the two drift the first time either learns something.
  */
-import { normalizeError } from "../../../../errors/normalize.js";
 import { jobsRepository } from "../../../../repositories/index.js";
-import { getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
-import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
-import { JOB_RUNNERS } from "./jobRunners.js";
-async function pingBulkEvent(jobId, payload, ctx) {
-    try {
-        await getAdminRealtimeDb()
-            .ref(`${RTDB_PATHS.BULK_EVENTS}/${jobId}`)
-            .set({ ...payload, updatedAt: Date.now() });
-    }
-    catch (err) {
-        void normalizeError(err);
-        ctx.logger.warn("onJobCreated: RTDB ping failed (non-fatal)", {
-            jobId,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
+import { runJobOnce } from "./runJobOnce.js";
 export async function handleJobCreated(input, ctx) {
     const { jobId, job } = input;
-    await jobsRepository.markProcessing(jobId);
-    const runner = JOB_RUNNERS[job.jobType];
-    if (!runner) {
-        const error = `No runner registered for jobType: ${job.jobType}`;
-        await jobsRepository.markFailed(jobId, error);
-        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error }, ctx);
-        ctx.logger.error("onJobCreated: unregistered jobType", null, { jobId, jobType: job.jobType });
-        return;
-    }
-    try {
-        const result = await runner(job.payload, ctx);
-        await jobsRepository.markDone(jobId, result);
-        await pingBulkEvent(jobId, { status: "success", action: job.jobType, ...result }, ctx);
-        ctx.logger.info("onJobCreated: job complete", { jobId, jobType: job.jobType, summary: result.summary });
+    /*
+     * ── 🛑 A SCHEDULED RETRY MUST NOT RUN HERE ────────────────────────────────
+     *
+     * This guard is the whole reason Phase 8's backoff works, and its absence
+     * was a defect in this feature's own first draft.
+     *
+     * A retry is a NEW `jobs` document (it has to be — this trigger fires on
+     * CREATE, so flipping a job back to `pending` would never wake anything).
+     * But creating that document fires THIS trigger immediately — so without
+     * this check, every retry would run the instant it was scheduled, the
+     * 5-minute and 30-minute backoffs would be zero, and three attempts would
+     * burn in under a second against a fault that had not had time to clear.
+     * The backoff fields would still be written, so the database would read as
+     * though it had waited.
+     *
+     * `nextAttemptAt` in the future means "the sweep owns this one". Returning
+     * leaves the document `pending`, which is exactly what `getDueRetries`
+     * queries for.
+     */
+    if (job.nextAttemptAt) {
+        const due = new Date(job.nextAttemptAt).getTime();
+        if (Number.isFinite(due) && due > Date.now()) {
+            ctx.logger.info("onJobCreated: retry scheduled, deferring to the sweep", {
+                jobId,
+                jobType: job.jobType,
+                attempt: job.attempt ?? 1,
+                nextAttemptAt: new Date(due).toISOString(),
+            });
+            return;
+        }
     }
-    catch (err) {
-        void normalizeError(err);
-        const message = err instanceof Error ? err.message : String(err);
-        await jobsRepository.markFailed(jobId, message);
-        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error: message }, ctx);
-        ctx.logger.error("onJobCreated: job failed", err, { jobId, jobType: job.jobType });
+    await runJobOnce({ jobId, job }, ctx);
+}
+/**
+ * The retry sweep — runs every scheduled attempt whose time has come.
+ *
+ * ## 🛑 Folded into an EXISTING scheduled function, not a new one
+ *
+ * It is called from `paymentWindowTimeout` (every 5 minutes). Cloud Scheduler
+ * bills per registered job and this project already carries ~34 of them
+ * against 3 free; adding a 35th to run a usually-empty query is the cost this
+ * plan explicitly refuses. The same reasoning put the ledger reconciler inside
+ * `dailyDataCleanup` and R1 inside this same function.
+ *
+ * 🛑 And it is placed FIRST at its call site, before that function's early
+ * return — `paymentWindowTimeout` returns as soon as there are no expired
+ * payment windows, which is most ticks, so appending would run the sweep only
+ * on the minority of ticks with unrelated work (Root Cause #27).
+ *
+ * Sequential, not `Promise.all`. A job runner is heavy by definition — that is
+ * why it is a job — and twenty of them concurrently inside one 540s function
+ * is how a sweep exhausts its own budget. Twenty sequential attempts that run
+ * out of time simply leave the rest `pending` for the next tick, which is the
+ * safe failure.
+ */
+export async function runDueJobRetries(ctx) {
+    const due = await jobsRepository.getDueRetries();
+    if (due.length === 0)
+        return { ran: 0 };
+    ctx.logger.info("job retries: running due attempts", { count: due.length });
+    let ran = 0;
+    for (const { id, data } of due) {
+        /*
+         * `runJobOnce` never throws — it records every outcome on the job itself.
+         * The `.catch` is belt-and-braces so one pathological job cannot abort the
+         * rest of the sweep, which would leave the remainder un-retried with no
+         * record of why.
+         */
+        await runJobOnce({ jobId: id, job: data }, ctx).catch((err) => {
+            ctx.logger.error("job retries: attempt threw", err, { jobId: id });
+        });
+        ran += 1;
     }
+    return { ran };
 }

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

@@ -6,9 +6,16 @@ export type OrderAfter = {
     userEmail: string;
     productTitle: string;
     trackingNumber?: string;
+    /**
+     * Phase 7 — the invoice is numbered on the PAYMENT transition, which is a
+     * different axis from `status` and is why these two fields are here.
+     */
+    paymentStatus?: string;
+    invoiceNumber?: string;
 };
 export type OrderBefore = {
     status: OrderStatus;
+    paymentStatus?: string;
 };
 export interface HandleOrderStatusChangeInput {
     orderId: string;