@mohasinac/appkit 4.62.1 → 4.63.1

package/dist/_internal/server/features/pricing/actions.js

@@ -0,0 +1,144 @@
+/**
+ * The ONE write path for a platform rate.
+ *
+ * ## Why there is exactly one
+ *
+ * Rates live on `siteSettings`, which `PUT /api/admin/site` can already write
+ * — so this is not the only way the numbers CAN move. It is the only way they
+ * move with a recorded reason, an effective date and an `adminAuditLog` row,
+ * and that difference is the whole point of `/admin/pricing`.
+ *
+ * The general settings form stays able to write them. Locking it out would
+ * mean an admin fixing a typo in the COD ceiling gets a 400 from the page that
+ * has always owned it, and the fix would be to come here — which is a worse
+ * outcome than an occasional unlogged edit. What this buys is that the
+ * DELIBERATE act of repricing has one door with a record behind it.
+ *
+ * ## 🛑 Forward-only, enforced at the WRITE
+ *
+ * `rejectRateChange` is a pure function and lives in the registry so the form
+ * can run it too — but the form running it is a courtesy, and this is the
+ * enforcement. A backdated change here would restate figures already invoiced
+ * and already paid out; see the registry header.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { SITE_SETTINGS_COLLECTION, } from "../../../../features/admin/schemas/firestore.js";
+import { canEditRate, rateByPath, rejectRateChange, } from "../../../shared/features/pricing/rate-registry.js";
+import { recordAdminAction } from "../audit-log/actions.js";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+const SINGLETON_ID = "global";
+/**
+ * How many changes the log keeps, newest first.
+ *
+ * Sized so a year of ordinary repricing fits: 16 rates changed a few times
+ * each is well under this, and the page shows only the most recent per rate
+ * anyway. The cap exists because the array rides on a document every request
+ * reads, not because 200 entries is a lot of data.
+ */
+export const RATE_CHANGE_LOG_MAX = 200;
+/** Read a dotted path off the settings document. `null` when absent. */
+function readRate(settings, path) {
+    const value = path
+        .split(".")
+        .reduce((acc, key) => (acc && typeof acc === "object" ? acc[key] : undefined), settings);
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Change one rate.
+ *
+ * 🛑 **One rate per call, on purpose.** A bulk form would need one reason
+ * covering a heterogeneous set, which is the same argument that removed the
+ * bulk offer-cancel: one shared reason across unlike records is worse audit
+ * data than no bulk action. Repricing three things is three decisions.
+ */
+export async function applyRateChange(input, actor, now = new Date()) {
+    const descriptor = rateByPath(input.path);
+    if (!descriptor) {
+        throw new ValidationError("That is not a rate this platform charges.", {
+            path: `Unknown rate: ${input.path}`,
+        });
+    }
+    if (!canEditRate(descriptor.tier, actor.isAdmin)) {
+        /*
+         * A statutory rate reaches this branch for EVERYONE, admins included —
+         * which is why the message names the real destination rather than
+         * implying the caller lacks a permission they could be granted.
+         */
+        throw new ValidationError(descriptor.tier === "statutory"
+            ? "Statutory rates are not set here — they are sourced per HSN code in Tax codes."
+            : "Only an administrator can change a policy ceiling.", { path: descriptor.label });
+    }
+    const settings = await siteSettingsRepository.getSingleton();
+    const previousValue = readRate(settings, descriptor.path);
+    const effectiveFrom = input.effectiveFrom ?? now;
+    const problem = rejectRateChange({ effectiveFrom, previousValue, newValue: input.newValue, reason: input.reason }, descriptor.tier, now);
+    if (problem) {
+        throw new ValidationError(problem, { newValue: problem });
+    }
+    const entry = {
+        path: descriptor.path,
+        previousValue,
+        newValue: input.newValue,
+        effectiveFrom,
+        changedByUid: actor.uid,
+        changedByName: actor.name ?? "",
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        changedAt: now,
+    };
+    /*
+     * 🛑 A DOTTED path for the rate, and a whole-array write for the log.
+     *
+     * `update()` replaces a nested map wholesale (D13, recorded at length in
+     * `updateSingleton`), so writing `{ commissions: { platformFeePercent: 2 } }`
+     * would delete every other commission. The dotted form touches one leaf.
+     *
+     * The log cannot use `arrayUnion` because that cannot enforce the cap — the
+     * same reason `withHistory`'s batch paths fold in memory. Newest first, so
+     * the slice drops the OLDEST.
+     */
+    const nextLog = [entry, ...(settings.rateChanges ?? [])].slice(0, RATE_CHANGE_LOG_MAX);
+    await getAdminDb()
+        .collection(SITE_SETTINGS_COLLECTION)
+        .doc(SINGLETON_ID)
+        .update({
+        [descriptor.path]: input.newValue,
+        rateChanges: nextLog,
+        updatedAt: now,
+    });
+    /*
+     * Best-effort, never fails the change — the same contract every other
+     * `recordAdminAction` caller has. The rate has already moved; refusing to
+     * acknowledge it because the log write failed would leave the admin
+     * believing it had not.
+     */
+    try {
+        await recordAdminAction({
+            actorUid: actor.uid,
+            actorName: actor.name,
+            action: AdminAuditActionValues.PRICING_UPDATE,
+            targetType: "siteSettings",
+            targetId: descriptor.path,
+            targetLabel: descriptor.label,
+            ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+            metadata: {
+                tier: descriptor.tier,
+                unit: descriptor.unit,
+                previousValue,
+                newValue: input.newValue,
+                effectiveFrom: effectiveFrom.toISOString(),
+            },
+        });
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("applyRateChange: audit log write failed", {
+            path: descriptor.path,
+            message: normalized.message,
+        });
+    }
+    return { path: descriptor.path, previousValue, newValue: input.newValue, effectiveFrom };
+}

package/dist/_internal/server/features/shipping/book-split.d.ts

@@ -0,0 +1,86 @@
+/**
+ * S5a — one parcel per destination on a coordinated purchase.
+ *
+ * A coordinated purchase can send each member's share to their own address
+ * (`CoordinationMember.destinationAddressId`). That is N parcels from one
+ * order, which is N bookings and N serviceability checks.
+ *
+ * ## 🛑 Serviceability is checked for EVERY destination BEFORE any booking
+ *
+ * Booking as you go and failing on the fourth leaves three parcels already
+ * accepted by the carrier and a coordinator who cannot undo them — the
+ * cancel path exists but the money and the pickup slot are gone. A
+ * pre-flight over all destinations turns that into one refusal naming the
+ * pincode that cannot be served, before anything is committed.
+ *
+ * Two-phase on purpose, and it is NOT a transaction: a carrier booking has
+ * no rollback. What the pre-flight buys is that the common failure — an
+ * unservable pincode — is caught while rolling back is still free.
+ *
+ * ## 🛑 Bounded by `SHARED_PURCHASE_MAX_MEMBERS`
+ *
+ * Five destinations is five outbound calls for serviceability and five more
+ * to book, on a path somebody is waiting on. That ceiling is why the limit
+ * exists at all; see the registry's own header.
+ */
+import { type CoordinationMember } from "../../../shared/features/offers/coordination";
+export interface DestinationCheck {
+    addressId: string;
+    pincode: string;
+    serviceable: boolean;
+}
+/**
+ * Can every named destination actually be delivered to?
+ *
+ * 🛑 Returns the FULL list, not the first failure. A coordinator fixing one
+ * unservable address only to be told about the next one is three round trips
+ * for a problem that was knowable in one — and each round trip is another
+ * chance for someone to give up with the arrangement half-built.
+ *
+ * 🛑 An UNREADABLE check is treated as serviceable. A provider timeout is not
+ * evidence that a pincode cannot be served, and refusing on it would block a
+ * legitimate purchase on an outage we caused. The booking itself will fail
+ * loudly if the address really is unservable, which is the recoverable
+ * direction — and it is the same reasoning `bookShipment` applies to a wallet
+ * balance it could not read.
+ *
+ * A MISSING pincode is the opposite case and is reported unserviceable: that
+ * is a fact about the stored address, not about the provider, and it will not
+ * fix itself on a retry.
+ */
+export declare function checkDestinations(members: readonly CoordinationMember[], 
+/**
+ * 🛑 The parcel's weight in kg, NOT an origin pincode.
+ *
+ * `IShippingProvider.checkServiceability(pincode, weight)` reads its first
+ * argument as the DESTINATION. A reasonable guess of `(origin, destination)`
+ * would pass two strings into a `(string, number)` signature — caught by
+ * `tsc` here, but worth naming because the argument ORDER is the part a
+ * reader assumes.
+ */
+weightKg: number): Promise<DestinationCheck[]>;
+/**
+ * Refuse the whole arrangement if any destination cannot be served.
+ *
+ * Names every failing pincode, for the reason above.
+ */
+export declare function assertAllServiceable(checks: readonly DestinationCheck[]): void;
+/**
+ * The parcels one coordinated order produces.
+ *
+ * 🛑 **Keyed by ADDRESS, not by member.** Two members naming the same address
+ * are one parcel, not two — that is the whole reason `destinationIds` returns
+ * a distinct set. Fanning out per member would book the courier twice to the
+ * same door and bill for both.
+ *
+ * 🛑 **A member with no `destinationAddressId` is NOT in this list.** Absent
+ * means "the coordinator's address", which is the ordinary one-parcel case
+ * and is handled by `bookShipment`'s existing single-delivery path — the
+ * order's own snapshot. Inventing a parcel for them here would duplicate it.
+ */
+export interface ParcelPlan {
+    addressId: string;
+    /** Members whose share rides in this parcel. Never empty. */
+    memberUids: string[];
+}
+export declare function planParcels(members: readonly CoordinationMember[]): ParcelPlan[];

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

@@ -0,0 +1,130 @@
+/**
+ * S5a — one parcel per destination on a coordinated purchase.
+ *
+ * A coordinated purchase can send each member's share to their own address
+ * (`CoordinationMember.destinationAddressId`). That is N parcels from one
+ * order, which is N bookings and N serviceability checks.
+ *
+ * ## 🛑 Serviceability is checked for EVERY destination BEFORE any booking
+ *
+ * Booking as you go and failing on the fourth leaves three parcels already
+ * accepted by the carrier and a coordinator who cannot undo them — the
+ * cancel path exists but the money and the pickup slot are gone. A
+ * pre-flight over all destinations turns that into one refusal naming the
+ * pincode that cannot be served, before anything is committed.
+ *
+ * Two-phase on purpose, and it is NOT a transaction: a carrier booking has
+ * no rollback. What the pre-flight buys is that the common failure — an
+ * unservable pincode — is caught while rolling back is still free.
+ *
+ * ## 🛑 Bounded by `SHARED_PURCHASE_MAX_MEMBERS`
+ *
+ * Five destinations is five outbound calls for serviceability and five more
+ * to book, on a path somebody is waiting on. That ceiling is why the limit
+ * exists at all; see the registry's own header.
+ */
+import { getProviders } from "../../../../contracts/registry.js";
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { SHARED_PURCHASE_MAX_MEMBERS, destinationIds, } from "../../../shared/features/offers/coordination.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+/**
+ * Can every named destination actually be delivered to?
+ *
+ * 🛑 Returns the FULL list, not the first failure. A coordinator fixing one
+ * unservable address only to be told about the next one is three round trips
+ * for a problem that was knowable in one — and each round trip is another
+ * chance for someone to give up with the arrangement half-built.
+ *
+ * 🛑 An UNREADABLE check is treated as serviceable. A provider timeout is not
+ * evidence that a pincode cannot be served, and refusing on it would block a
+ * legitimate purchase on an outage we caused. The booking itself will fail
+ * loudly if the address really is unservable, which is the recoverable
+ * direction — and it is the same reasoning `bookShipment` applies to a wallet
+ * balance it could not read.
+ *
+ * A MISSING pincode is the opposite case and is reported unserviceable: that
+ * is a fact about the stored address, not about the provider, and it will not
+ * fix itself on a retry.
+ */
+export async function checkDestinations(members, 
+/**
+ * 🛑 The parcel's weight in kg, NOT an origin pincode.
+ *
+ * `IShippingProvider.checkServiceability(pincode, weight)` reads its first
+ * argument as the DESTINATION. A reasonable guess of `(origin, destination)`
+ * would pass two strings into a `(string, number)` signature — caught by
+ * `tsc` here, but worth naming because the argument ORDER is the part a
+ * reader assumes.
+ */
+weightKg) {
+    const ids = destinationIds(members);
+    if (ids.length === 0)
+        return [];
+    if (ids.length > SHARED_PURCHASE_MAX_MEMBERS) {
+        throw new ValidationError(`A coordinated purchase can ship to at most ${SHARED_PURCHASE_MAX_MEMBERS} addresses.`, { destinations: `${ids.length} distinct addresses named.` });
+    }
+    /*
+     * 🛑 Optional on the registry. This is the serviceability PRE-FLIGHT, so
+     * with no provider the honest answer is "unknown", not "unserviceable":
+     * reporting every destination as unserviceable would block an accept that
+     * manual dispatch handles perfectly well.
+     */
+    const provider = getProviders().shipping;
+    if (!provider) {
+        return ids.map((addressId) => ({ addressId, pincode: "", serviceable: true }));
+    }
+    const docs = await Promise.all(ids.map((id) => addressesRepository.findById(id)));
+    return Promise.all(ids.map(async (addressId, i) => {
+        /*
+         * 🛑 `.postalCode` needs no reveal — it is not PII and
+         * `AddressRepository` deliberately leaves it unencrypted so it stays
+         * queryable (see its own `computeAddressHash` comment). Calling
+         * `revealAddress` here would decrypt a name and a phone number we have
+         * no use for, on a path that only needs six digits.
+         */
+        const pincode = docs[i]?.postalCode ?? "";
+        if (!pincode)
+            return { addressId, pincode, serviceable: false };
+        try {
+            const res = await provider.checkServiceability(pincode, weightKg);
+            return { addressId, pincode, serviceable: res.isServiceable };
+        }
+        catch (err) {
+            void normalizeError(err);
+            serverLogger.warn("checkDestinations: serviceability unreadable", { addressId, pincode });
+            return { addressId, pincode, serviceable: true };
+        }
+    }));
+}
+/**
+ * Refuse the whole arrangement if any destination cannot be served.
+ *
+ * Names every failing pincode, for the reason above.
+ */
+export function assertAllServiceable(checks) {
+    const bad = checks.filter((c) => !c.serviceable);
+    if (bad.length === 0)
+        return;
+    throw new ValidationError(bad.length === 1
+        ? "One delivery address cannot be served by the courier."
+        : `${bad.length} delivery addresses cannot be served by the courier.`, {
+        destinations: bad
+            .map((b) => (b.pincode ? `${b.pincode}: not serviceable` : "missing pincode"))
+            .join("; "),
+    });
+}
+export function planParcels(members) {
+    const byAddress = new Map();
+    for (const m of members) {
+        if (!m.destinationAddressId)
+            continue;
+        const uids = byAddress.get(m.destinationAddressId);
+        if (uids)
+            uids.push(m.uid);
+        else
+            byAddress.set(m.destinationAddressId, [m.uid]);
+    }
+    return [...byAddress].map(([addressId, memberUids]) => ({ addressId, memberUids }));
+}

package/dist/_internal/server/features/shipping/book.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export interface BookShipmentInput {
+    orderId: string;
+    /** Centimetres and kilograms, from the dispatch form's box preset. */
+    dimensions: {
+        weight: number;
+        length: number;
+        width: number;
+        height: number;
+    };
+    /** The store address the courier collects from. */
+    pickupAddressId: string;
+}
+export interface BookShipmentResult {
+    trackingId: string;
+    courier?: string;
+    estimatedDelivery?: string;
+}
+/**
+ * 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 declare function bookShipment(input: BookShipmentInput): Promise<BookShipmentResult>;

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.js

@@ -1,3 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * Raising and clearing a courier block, and telling the ADMIN about it.
  *
@@ -21,6 +22,9 @@
  *    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.
@@ -227,7 +231,16 @@ async function emailStaff(input) {
     const { error } = await sendEmail({
         to: recipients,
         subject: input.title,
-        html: `<p>${body.replace(/\n\n/g, "</p><p>").replace(/\n/g, "<br/>")}</p>`,
+        /*
+         * 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) {
@@ -237,3 +250,15 @@ async function emailStaff(input) {
         });
     }
 }
+/**
+ * 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

@@ -39,7 +39,7 @@ import type { PublicSiteSettings } from "../../../shared/features/site-settings/
  */
 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