@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/shipping/book.js

@@ -0,0 +1,176 @@
+/**
+ * Booking a parcel through the platform's own carrier account — Part 1′.
+ *
+ * ## 🛑 Why this could not be built until Part 14
+ *
+ * `CreateShipmentInput` needs a structured `{name, phone, addressLine1, city,
+ * state, pincode, country}` for BOTH ends. Until the delivery snapshot landed
+ * the order carried `shippingAddress?: string` — flat free text with no
+ * pincode and no phone — and the only way to produce a party from it was to
+ * parse prose. The `placeOfSupply` comment already refuses that for tax, and
+ * the same argument holds here: a mis-parsed pincode is a parcel that goes to
+ * the wrong city, except nothing errors and the label prints fine.
+ *
+ * `deliveryPartyFor(order)` now returns exactly that shape, or `null` when a
+ * required field is missing — which is the only honest answer for an order
+ * placed before the snapshot existed.
+ *
+ * ## 🛑 `platformBookedShipment` is the flag this writes
+ *
+ * `order-math.ts` gates shipping reimbursement on it
+ * (`if (order.platformBookedShipment === true) return 0`) and
+ * `quote.ts:241` records that it has had **ZERO writers** — so the
+ * reimbursement rule has been reading a flag nothing sets. This is its
+ * writer, which is why the booking and the dispatch form are one unit of
+ * work and why the form must not ship first: a "Book through us" button with
+ * no booking behind it is a control the server refuses.
+ */
+import { getProviders } from "../../../../contracts/registry.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { deliveryPartyFor } from "../../../shared/features/orders/delivery-snapshot.js";
+import { revealPii } from "../../../../security/pii-accessors.js";
+import { ORDER_PII_FIELDS } from "../../../../security/pii-schemas.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+/**
+ * Book one parcel.
+ *
+ * ## 🛑 The wallet is checked BEFORE the booking, and a failure is a 409
+ *
+ * A carrier account with no balance rejects the booking — but some providers
+ * accept it and then silently fail to hand over, which produces a tracking id
+ * that never moves. Checking first turns "the parcel vanished" into "top up
+ * the account", and the 409 is deliberate: the request is well-formed and the
+ * seller is not confused, the world is simply not ready.
+ *
+ * 🛑 `getWalletBalance` is NOT abstract on `IShippingProvider` — manual
+ * shipping has no wallet, so a provider that does not implement it returns
+ * undefined and the check is SKIPPED rather than failing. A missing balance
+ * must never block a manual dispatch.
+ */
+export async function bookShipment(input) {
+    const order = (await orderRepository.findById(input.orderId));
+    if (!order)
+        throw new NotFoundError("Order not found.");
+    if (order.trackingNumber) {
+        /*
+         * 409, not 400. Double-booking is the expensive mistake here — two
+         * parcels, two charges, one of them never collected — and it is easy to
+         * cause by refreshing a form.
+         */
+        throw new ValidationError("This order already has a shipment.", {
+            orderId: `Already booked as ${order.trackingNumber}.`,
+        });
+    }
+    /*
+     * 🛑 DECRYPTED first. `OrderDocument`'s delivery name, phone and address
+     * lines are `Encrypted<string>` (ciphertext-by-default), and `Encrypted<T>`
+     * is deliberately assignable to nothing that wants a plain `string` — which
+     * is what made this a compile error rather than a courier label printed
+     * with `enc:v1:…` on it.
+     *
+     * A courier booking is the one place the plaintext is genuinely required:
+     * the carrier has to deliver to a real person at a real door. Masked would
+     * be the wrong default HERE and the right one almost everywhere else, which
+     * is why the two accessors are separately named.
+     */
+    const delivery = deliveryPartyFor(revealPii(order, ORDER_PII_FIELDS));
+    if (!delivery) {
+        /*
+         * An order placed before the delivery snapshot existed. Refused, loudly,
+         * rather than guessed at — see the module header on parsing prose.
+         */
+        throw new ValidationError("This order has no structured delivery address, so it cannot be booked automatically.", { orderId: "Placed before structured addresses; dispatch it manually." });
+    }
+    const pickupDoc = await addressesRepository.findById(input.pickupAddressId);
+    const store = order.storeId ? await storeRepository.findBySlug(order.storeId) : null;
+    /*
+     * 🛑 The pickup address must belong to the ORDER'S STORE. Checking only
+     * that it exists would let one seller's parcel be collected from another
+     * seller's premises — the same class of hole `assertOwnedAddresses` closes
+     * for coordinated purchases, and it is reachable here by id alone.
+     */
+    if (!pickupDoc ||
+        pickupDoc.ownerType !== "store" ||
+        !store ||
+        pickupDoc.ownerId !== store.id) {
+        throw new ValidationError("That pickup address is not available for this store.", {
+            pickupAddressId: "Pick one of this store's own addresses.",
+        });
+    }
+    const pickupPlain = addressesRepository.revealAddress(pickupDoc);
+    const pickup = {
+        name: String(pickupPlain.fullName ?? store.storeName ?? ""),
+        phone: String(pickupPlain.phone ?? ""),
+        addressLine1: String(pickupPlain.addressLine1 ?? ""),
+        ...(pickupPlain.addressLine2 ? { addressLine2: String(pickupPlain.addressLine2) } : {}),
+        city: pickupPlain.city ?? "",
+        state: pickupPlain.state ?? "",
+        pincode: pickupPlain.postalCode ?? "",
+        country: pickupPlain.country ?? "",
+    };
+    /*
+     * 🛑 `getProviders().shipping` is OPTIONAL on the registry, and refusing
+     * here is the honest handling. `providers.config.ts` always registers one
+     * today, so this is unreachable in this app — but a non-null assertion
+     * would turn the day somebody ships a build without it into a
+     * `Cannot read properties of undefined` at the moment money is involved,
+     * instead of a sentence a seller can act on.
+     */
+    const provider = getProviders().shipping;
+    if (!provider) {
+        throw new ValidationError("No shipping provider is configured.", {
+            orderId: "Automatic booking is unavailable — dispatch this order manually.",
+        });
+    }
+    /*
+     * 🛑 `WalletBalance` is a THREE-state union and collapsing it is the whole
+     * hazard the contract's own header describes. Only `{known: true, amount: 0}`
+     * is a decision to skip. `{known: false}` means either "no wallet exists"
+     * (manual shipping) or "could not read it right now" — and refusing on an
+     * unreadable balance would fail every dispatch on a transient blip.
+     *
+     * An earlier draft of this function tested `typeof balance === "number"`,
+     * which is never true against this contract: the guard was dead, so a
+     * genuinely empty wallet would have been booked into anyway.
+     */
+    const balance = await provider.getWalletBalance().catch((err) => {
+        void normalizeError(err);
+        serverLogger.warn("bookShipment: wallet balance unavailable", { orderId: input.orderId });
+        return { known: false, supported: true };
+    });
+    if (balance.known && balance.amount <= 0) {
+        throw new ValidationError("The courier account has no balance, so the booking was not attempted.", { orderId: "Top up the carrier wallet and try again." });
+    }
+    const payload = {
+        orderId: input.orderId,
+        dimensions: input.dimensions,
+        pickup,
+        delivery,
+        ...(order.paymentMethod === "cod"
+            ? { isCod: true, codAmount: order.codRemainingAmount ?? order.totalPrice }
+            : {}),
+    };
+    const shipment = await provider.createShipment(payload);
+    /*
+     * 🛑 `platformBookedShipment: true` is the WHOLE POINT of this function.
+     *
+     * `order-math.ts` already gates shipping reimbursement on it and nothing
+     * has ever set it. Writing the tracking id without it would book the parcel
+     * AND reimburse the seller for postage the platform just paid.
+     */
+    await orderRepository.update(input.orderId, {
+        trackingNumber: shipment.trackingId,
+        ...(shipment.courier ? { carrier: shipment.courier } : {}),
+        platformBookedShipment: true,
+    });
+    return {
+        trackingId: shipment.trackingId,
+        ...(shipment.courier ? { courier: shipment.courier } : {}),
+        ...(shipment.estimatedDelivery ? { estimatedDelivery: shipment.estimatedDelivery } : {}),
+    };
+}

package/dist/_internal/server/features/shipping/courier-block.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+import type { WalletBalance } from "../../../../contracts";
+/**
+ * ## 🛑 What is HERE and what deliberately is not
+ *
+ * Shipped: the wallet THRESHOLD check and the whole admin-alert path, driven by
+ * the daily digest. That is a real producer today and needs nothing new — and
+ * it is the better signal anyway: reacting only to failures means the first
+ * warning is always a buyer's order already stuck.
+ *
+ * NOT shipped: raising a block on a specific order. That belongs with the
+ * booking path, and nothing platform-books yet (`createShipment` has zero
+ * callers). A `raiseCourierBlock` with no producer is the speculative-infra
+ * pattern, so it lands when the caller does.
+ *
+ * `OrderDocument.courierBlock` and `seller-dispatch`'s
+ * `!hasOpenCourierBlock(o)` guard ARE already in place, and that ordering is
+ * deliberate: a safety property must exist BEFORE the thing it guards against,
+ * or the very first block auto-cancels a paid order. Inert today, correct the
+ * moment anything writes the field.
+ */
+/** Why we could not book. Mirrors `OrderDocument.courierBlock.reason`. */
+export type CourierBlockReason = NonNullable<OrderDocument["courierBlock"]>["reason"];
+export interface CourierWalletCheck {
+    /** `null` when the provider has no wallet, or we could not read it. */
+    balance: number | null;
+    low: boolean;
+    alerted: boolean;
+    reason?: string;
+}
+/**
+ * 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 declare function checkCourierWalletAndAlert(provider: {
+    name: string;
+    getWalletBalance: () => Promise<WalletBalance>;
+} | undefined): Promise<CourierWalletCheck>;

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

@@ -0,0 +1,264 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { Fragment } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { EmailContainer, EmailDoc, EmailRow, } from "../../../../features/email/primitives.js";
+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,
+        /*
+         * Composed from the Email primitives rather than hand-built HTML.
+         *
+         * The old line string-replaced `\n\n` into `</p><p>`, which produces
+         * markup no email client was ever tested against and which
+         * `audit-email-raw-html` blocks for that reason. `EmailDoc` renders the
+         * table-based, inline-styled structure clients actually honour, and the
+         * paragraph split now happens on the DATA before it reaches the markup.
+         */
+        html: renderStaffAlertEmail(input.title, body),
+        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),
+        });
+    }
+}
+/**
+ * The staff courier-block alert, as an email document.
+ *
+ * Kept local to this file rather than exported: it is one alert with one
+ * shape, and a shared "generic staff alert" helper would invite the next
+ * caller to pass admin-editable text through it — which is how an email
+ * template becomes an injection surface. The body here is built entirely from
+ * our own constants and the provider/reason enums.
+ */
+function renderStaffAlertEmail(title, body) {
+    return `<!DOCTYPE html>${renderToStaticMarkup(_jsx(EmailDoc, { title: title, children: _jsx(EmailContainer, { children: _jsx(EmailRow, { children: body.split("\n\n").map((para, i) => (_jsxs(Fragment, { children: [i > 0 ? _jsx("br", {}) : null, i > 0 ? _jsx("br", {}) : null, para.split("\n").map((line, j) => (_jsxs(Fragment, { children: [j > 0 ? _jsx("br", {}) : null, line] }, j)))] }, i))) }) }) }))}`;
+}

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

@@ -37,9 +37,9 @@ 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 declare const PRIVATE_SITE_SETTINGS_FIELDS: readonly ["rateChanges", "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 {
     /**
      * The resolved marker → wordmark → text watermark chain. Injected because

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)
@@ -54,6 +66,20 @@ export const PUBLIC_SITE_SETTINGS_FIELDS = [
 ];
 /** Everything else, with the reason it stays server-side. */
 export const PRIVATE_SITE_SETTINGS_FIELDS = [
+    /*
+     * 🛑 `rateChanges` — the rate-change log behind /admin/pricing.
+     *
+     * Every entry names an internal rate, who moved it and why. The WHY is the
+     * worst of it: a reason reads "undercutting X" or "margin too thin on
+     * bundles", which is commercial strategy typed by an admin who was told it
+     * was an internal note.
+     *
+     * Half the rates are already private (`gatewayFeePercent`,
+     * `payoutHoldDays`, `minPayoutAmount`), so publishing their history would
+     * also publish the values themselves — the current figure is the newest
+     * entry's `newValue`.
+     */
+    "rateChanges",
     "id", // singleton bookkeeping
     "createdAt", // bookkeeping
     "updatedAt", // bookkeeping
@@ -114,6 +140,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 ["trustedSeller", "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