@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/_internal/server/features/shipping/courier-block.js

@@ -0,0 +1,239 @@
+/**
+ * Raising and clearing a courier block, and telling the ADMIN about it.
+ *
+ * ## The problem this exists for
+ *
+ * Shiprocket is PREPAID and has no recharge API, so topping up the courier
+ * wallet is irreducibly a human action. If the platform books couriers, an
+ * empty wallet silently stops dispatch on orders buyers have already paid for.
+ *
+ * ## The two rules
+ *
+ * 1. 🛑 **The order is never auto-cancelled over it.** `seller-dispatch`'s
+ *    `precondition` carries `!hasOpenCourierBlock(o)`, so its 2-business-day
+ *    `onDue: "act"` clock PAUSES while blocked instead of cancelling the order
+ *    and refunding the buyer with the seller blamed for our funding state.
+ *
+ * 2. 🛑 **The admin alert is deduped on the WALLET, never on the order.** Fifty
+ *    blocked orders are ONE problem with one fix. The daily email ceiling
+ *    applies to staff mail too (`send-guard.ts:92` — the kill switch spares
+ *    staff, the ceiling does not), so fifty per-order emails would spend the
+ *    whole 80/day budget saying the same thing fifty times and leave the
+ *    operator blind to everything else.
+ */
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+// `adminNotificationsRepository` lives behind the repositories barrel — the
+// same import the two existing staff-signal call sites use.
+import { adminNotificationsRepository } from "../../../../repositories/index.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { sendEmail } from "../../../../features/contact/email.js";
+/**
+ * The dedupe key: the PROVIDER, not the order.
+ *
+ * One string, so a hundred stuck orders collapse into one case whose
+ * `observedCount` is the number of orders waiting — which is also the only
+ * number an operator actually needs in order to decide how urgently to top up.
+ */
+function walletCaseKey(provider) {
+    return `courier-wallet:${provider}`;
+}
+/**
+ * How many shipments' worth of balance counts as "low".
+ *
+ * 🛑 Expressed in SHIPMENTS, not rupees. A ₹500 floor is meaningless without
+ * knowing what a booking costs, and the question an operator is really asking
+ * is "how many more parcels can I send before this stops". Four is roughly a
+ * day's slack at this volume, which is the point: the alert should arrive while
+ * topping up is still routine.
+ *
+ * `TYPICAL_BOOKING_COST` is an ESTIMATE and is labelled one — the real figure
+ * per parcel comes from `checkServiceability` and varies by weight and
+ * destination. It only has to be the right order of magnitude to make the
+ * warning land before the wallet is actually empty.
+ */
+const LOW_BALANCE_SHIPMENTS = 4;
+const TYPICAL_BOOKING_COST = 80;
+/**
+ * Read the courier wallet and, if it is running low, alert the admin ONCE.
+ *
+ * Called from `dailyStatusDigest` — 🛑 deliberately NOT a new scheduled
+ * function. Cloud Scheduler bills per registered job and this is one read a
+ * day; the same reasoning that put the ledger reconciler inside
+ * `dailyDataCleanup`.
+ *
+ * Never throws: a wallet read is diagnostics, and a digest that fails because
+ * one provider was unreachable stops reporting the fifteen things that were
+ * fine.
+ */
+export async function checkCourierWalletAndAlert(
+/*
+ * 🛑 Accepts `undefined` rather than being handed a cast.
+ * `ProviderRegistry.shipping` is declared optional, and although
+ * `providers.config.ts` always populates it, that is a runtime guarantee the
+ * TYPE does not make — and `as IShippingProvider` would silence the one
+ * signal that the registry was never initialised.
+ */
+provider) {
+    if (!provider) {
+        return { balance: null, low: false, alerted: false, reason: "no shipping provider" };
+    }
+    let balance;
+    try {
+        balance = await provider.getWalletBalance();
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        return { balance: null, low: false, alerted: false, reason: e.message };
+    }
+    if (!balance.known) {
+        /*
+         * 🛑 No alert, and no "balance 0" either. An unreadable balance is not a
+         * low balance — alerting on it would page an operator every time the
+         * network hiccupped, and they would learn to ignore the one that mattered.
+         * The reason is returned so the digest can SAY it was unreadable.
+         */
+        return {
+            balance: null,
+            low: false,
+            alerted: false,
+            reason: balance.supported ? (balance.reason ?? "unreadable") : "no wallet",
+        };
+    }
+    const low = balance.amount < LOW_BALANCE_SHIPMENTS * TYPICAL_BOOKING_COST;
+    if (!low)
+        return { balance: balance.amount, low: false, alerted: false };
+    const alerted = await alertAdminOnce({
+        provider: provider.name,
+        reason: "insufficient_funds",
+        detail: `balance ${balance.amount}`,
+    }).catch((err) => {
+        const e = normalizeError(err);
+        serverLogger.error("courier-wallet: admin alert failed", {
+            provider: provider.name,
+            error: e.message,
+        });
+        return false;
+    });
+    return { balance: balance.amount, low: true, alerted };
+}
+/**
+ * One case, one in-app alert, one email — per WALLET, per unresolved episode.
+ *
+ * `openOrObserve` is what makes this idempotent: a second blocked order raises
+ * `observedCount` on the existing case rather than opening a new one, and the
+ * email is only sent when a case was actually OPENED.
+ */
+async function alertAdminOnce(input) {
+    const { provider, reason, detail } = input;
+    const key = walletCaseKey(provider);
+    const title = reason === "insufficient_funds"
+        ? `Courier wallet needs a top-up (${provider})`
+        : `Courier booking failing (${provider})`;
+    const result = await paymentCasesRepository().openOrObserve({
+        kind: "courier_unavailable",
+        /*
+         * 🛑 `subjectId` identifies THE PROBLEM, not the observation — the
+         * repository's own words, and here the problem is the wallet. Passing the
+         * order id would open one case per stuck order, which is the exact noise
+         * `openOrObserve` exists to prevent ("an operator learns to ignore it, and
+         * the first real chargeback is lost in 8,000 rows").
+         */
+        subjectId: key,
+        severity: "error",
+        title,
+        detail: reason === "insufficient_funds"
+            ? `Bookings are failing for lack of funds. Paid orders are waiting and are NOT being auto-cancelled. Top up the ${provider} wallet, then retry from the order.`
+            : `Bookings are failing (${reason}). Paid orders are waiting and are NOT being auto-cancelled.${detail ? ` Upstream: ${detail.slice(0, 200)}` : ""}`,
+        /*
+         * The entity is the STORE-agnostic provider, so `entityType: "store"` would
+         * be a lie and `"order"` would re-key it to one order. `"job"` is the
+         * closest honest member of that union: this is a piece of our own
+         * machinery failing, not one record being wrong.
+         */
+        entityType: "job",
+        entityId: key,
+    });
+    /*
+     * 🛑 Only on a NEWLY CREATED case. This is the whole dedupe: an already-open
+     * episode has already been emailed, and re-sending it daily — or once per
+     * blocked order, once booking is wired — is the budget bug this function
+     * exists to avoid. The daily ceiling applies to staff mail too.
+     */
+    if (!result.created)
+        return false;
+    // One durable staff row the admin inbox reads and the digest counts —
+    // `audienceUserIds: []` is the "staff signal is a record, not a blast"
+    // pattern, rather than N personal notifications.
+    await adminNotificationsRepository
+        .create({
+        /*
+         * No cast. The fields are the real `AdminNotificationDocument` ones —
+         * `category`, not `type` — because a cast here would silence every other
+         * field's check too, which is how the `as never` on the older catalogue
+         * handler hid a wrong `createdAt` (CLAUDE.md § Notifications).
+         */
+        category: "system",
+        severity: "error",
+        title,
+        body: `${title}. Paid orders are waiting; none will be auto-cancelled while this is open.`,
+        isRead: false,
+        entityType: "job",
+        entityId: key,
+        audienceUserIds: [],
+    })
+        .catch((err) => {
+        void normalizeError(err);
+    });
+    await emailStaff({ title, provider, reason });
+    return true;
+}
+/**
+ * The staff email.
+ *
+ * 🛑 `feature` is a NAMED FLOW, not a `NotificationType`, and that is a
+ * deliberate correction to the plan this came from.
+ *
+ * `SendGuardContext.feature` is documented as "a notification type, or a named
+ * non-notification flow (`daily_digest`, `checkout_otp`, `payout_summary`)",
+ * and this is the second kind. A `NotificationType` is addressed to a USER and
+ * carries preferences, templates and an audience — none of which make sense
+ * here: nobody can opt out of "the courier wallet is empty", and there is no
+ * user it belongs to. Adding one would have meant four compile-checked map
+ * entries describing a notification nobody receives.
+ *
+ * `audience: "staff"` is load-bearing: the admin kill switch suppresses
+ * user-facing mail only, so switching customer email off must not stop the
+ * operator finding out that paid orders have stopped moving.
+ */
+async function emailStaff(input) {
+    const settings = await siteSettingsRepository.getSingleton().catch((err) => {
+        void normalizeError(err);
+        return null;
+    });
+    // Same recipient list the daily digest uses — one place to configure "who
+    // hears about operational problems".
+    const recipients = (settings?.emailSettings?.dailyDigest?.recipients ?? []).filter((r) => r.trim().length > 0);
+    if (recipients.length === 0) {
+        serverLogger.warn("courier-block: no staff recipients configured — case raised, no email", {
+            provider: input.provider,
+        });
+        return;
+    }
+    const body = input.reason === "insufficient_funds"
+        ? `Courier bookings are failing for lack of funds on the ${input.provider} wallet.\n\nPaid orders are waiting. They are NOT being auto-cancelled — the dispatch clock is paused while this is open.\n\nTop up the wallet, then retry from the order or the money-cases queue.`
+        : `Courier bookings are failing on ${input.provider} (${input.reason}).\n\nPaid orders are waiting. They are NOT being auto-cancelled — the dispatch clock is paused while this is open.`;
+    const { error } = await sendEmail({
+        to: recipients,
+        subject: input.title,
+        html: `<p>${body.replace(/\n\n/g, "</p><p>").replace(/\n/g, "<br/>")}</p>`,
+        text: body,
+    }, { channel: "email", feature: "courier_wallet_low", audience: "staff" });
+    if (error) {
+        serverLogger.error("courier-block: staff email failed", {
+            provider: input.provider,
+            error: String(error),
+        });
+    }
+}

package/dist/_internal/server/features/site-settings/adapters.d.ts

@@ -37,7 +37,7 @@ import type { PublicSiteSettings } from "../../../shared/features/site-settings/
  * was traced to a call site; anything without one belongs in the private list,
  * because an unused public field is pure attack surface.
  */
-export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes", "chat", "search"];
+export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "support", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes", "chat", "search"];
 /** Everything else, with the reason it stays server-side. */
 export declare const PRIVATE_SITE_SETTINGS_FIELDS: readonly ["id", "createdAt", "updatedAt", "credentials", "emailSettings", "legalPages", "commissions", "emi", "gst", "laborRate", "adSettings", "integrations", "platformLimits", "auctionConfig", "siteName", "tagline", "motto", "logo", "favicon", "seo", "socialLinks", "features", "shipping", "returns", "faq", "aboutContent", "navbarConfig", "footerConfig", "theme", "featuredResults", "messaging"];
 export interface ToPublicSiteSettingsOptions {

package/dist/_internal/server/features/site-settings/adapters.js

@@ -9,6 +9,18 @@ export const PUBLIC_SITE_SETTINGS_FIELDS = [
     "listings", // useListingTypeFlags — narrowed to listings.listingTypes; categoryTypes has no client reader
     "notificationChannels", // NotificationPreferencesPanel reads the per-channel toggles
     "announcementBar", // the homepage banner (AdminSiteSettingsView edits it)
+    /*
+     * `support.enabled` — a REAL client reader, which is the bar this list sets:
+     * `getUserNavGroups` filters the buyer's support nav entry on it, and
+     * `UserLayoutClient` is a client component.
+     *
+     * 🛑 Publishing it is also harmless by inspection, and that is worth stating
+     * rather than assuming: the group holds exactly one boolean, and "is support
+     * reachable" is a fact a buyer discovers by looking at the page anyway. If a
+     * second field is ever added here, triage it separately — the group being
+     * public does not make its future members public.
+     */
+    "support",
     "navConfig", // NavbarWithSettings, DashboardLayoutClient
     "actionConfig", // useAuthGate
     "background", // DashboardLayoutClient (background.light / .dark)
@@ -114,6 +126,9 @@ export function toPublicSiteSettings(doc, opts) {
         },
         notificationChannels: doc.notificationChannels,
         announcementBar: doc.announcementBar,
+        // Narrowed to the one boolean a client reads, not the group by reference —
+        // so a field added to `support` later is not published by accident.
+        support: doc.support ? { enabled: doc.support.enabled !== false } : undefined,
         navConfig: doc.navConfig,
         actionConfig: doc.actionConfig,
         background: doc.background,

package/dist/_internal/server/features/stores/adapters.d.ts

@@ -25,9 +25,9 @@ import type { StoreDetail, StoreListItem } from "../../../../features/stores/typ
  * Document fields that may reach an unauthenticated client. Keep in sync with
  * the object literals below — the audit asserts both directions.
  */
-export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "supportsShippingProtection", "supportsSaleProtection", "createdAt"];
+export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "supportsShippingProtection", "supportsSaleProtection", "allowSharedPurchase", "sharedPurchaseHandlingFee", "sharedPurchaseExtraShippingPerDestination", "createdAt"];
 /** Everything else, with the reason it stays server-side. */
-export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt", "gstin", "legalName", "registeredAddress"];
+export declare const PRIVATE_STORE_FIELDS: readonly ["acceptsPoints", "searchTxt", "updatedAt", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt", "gstin", "legalName", "registeredAddress"];
 /**
  * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
  * Firestore row. The legacy top-level counters below predate `stats` and are

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

@@ -33,10 +33,48 @@ 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 = [
+    /*
+     * 🛑 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 +185,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.js

@@ -18,9 +18,46 @@ 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.
+ */
 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 },

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,7 +120,14 @@ 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 = {
             storeId,
             // `displayName` is plaintext by D1; the email fallback must be revealed.

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/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;
+}>;