@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/_internal/shared/features/orders/refund-copy.js

@@ -38,7 +38,24 @@ export const REFUND_COPY = {
         acknowledgments: [
             "I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.",
             "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).",
-            "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable.",
+            /*
+             * 🛑 Phase 9 — TOKENS, resolved by `resolvePublishedCopy` at render.
+             *
+             * This literal was one of the three contradicting owners of the refund
+             * timeline: "5–7 business days" here, "5–7 business days via Razorpay"
+             * on the policy page (naming a gateway that was not even the one in
+             * use), and "3–5 business days" in the FAQ. Three statements of one
+             * fact, no reconciliation, and the FAQ one admin-editable so it could
+             * drift further after deployment.
+             *
+             * The caller renders this through `resolvePublishedCopy`, so the number
+             * now has exactly one definition. Note this string is an
+             * ACKNOWLEDGEMENT the buyer ticks — a token left unresolved here would
+             * appear in something they are agreeing to, which is the strongest
+             * possible argument for the unknown-token rule leaving `{{…}}` visible
+             * rather than blanking it.
+             */
+            "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable.",
         ],
     },
     siblingPayments: {

package/dist/_internal/shared/features/points/accepts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Does this store accept buyer points as part-payment?
+ *
+ * ## Why this is a function and not a bare field read
+ *
+ * Decision 3 has two halves: *"the main store always accepts, others opt in"*.
+ * The opt-in half is `StoreDocument.acceptsPoints`; the always half is the
+ * platform's own storefront, which cannot decline to fund its own programme.
+ *
+ * 🛑 The platform store is resolved in CODE rather than seeded `true`, because a
+ * seeded flag can be switched off by an edit, a reseed, or an admin clicking the
+ * wrong toggle — and the one store that must never stop accepting is the one the
+ * whole programme is advertised on. `UserPointsView` tells buyers points are
+ * spendable; if the only store could opt out, that promise would be a lie that
+ * nothing detected.
+ *
+ * ## 🛑 Absent means NOT accepted
+ *
+ * Matching `supportsSaleProtection`'s rule on the same document, and for the
+ * same reason: the accepting store ABSORBS the redemption against its payout,
+ * so defaulting absent to `true` would enrol every existing seller in funding
+ * discounts they never agreed to. A tri-state would be worse still — a buyer
+ * cannot tell a seller who declined from one who has not been asked.
+ */
+/**
+ * The platform's own storefront.
+ *
+ * Hard-coded deliberately: this is an identity, not a setting. It is the same
+ * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
+ * platform's own.
+ */
+export declare const PLATFORM_STORE_ID = "store-letitrip-official";
+export declare function storeAcceptsPoints(store: {
+    id?: string;
+    acceptsPoints?: boolean;
+} | null | undefined, storeId?: string): boolean;

package/dist/_internal/shared/features/points/accepts.js

@@ -0,0 +1,43 @@
+/**
+ * Does this store accept buyer points as part-payment?
+ *
+ * ## Why this is a function and not a bare field read
+ *
+ * Decision 3 has two halves: *"the main store always accepts, others opt in"*.
+ * The opt-in half is `StoreDocument.acceptsPoints`; the always half is the
+ * platform's own storefront, which cannot decline to fund its own programme.
+ *
+ * 🛑 The platform store is resolved in CODE rather than seeded `true`, because a
+ * seeded flag can be switched off by an edit, a reseed, or an admin clicking the
+ * wrong toggle — and the one store that must never stop accepting is the one the
+ * whole programme is advertised on. `UserPointsView` tells buyers points are
+ * spendable; if the only store could opt out, that promise would be a lie that
+ * nothing detected.
+ *
+ * ## 🛑 Absent means NOT accepted
+ *
+ * Matching `supportsSaleProtection`'s rule on the same document, and for the
+ * same reason: the accepting store ABSORBS the redemption against its payout,
+ * so defaulting absent to `true` would enrol every existing seller in funding
+ * discounts they never agreed to. A tri-state would be worse still — a buyer
+ * cannot tell a seller who declined from one who has not been asked.
+ */
+/**
+ * The platform's own storefront.
+ *
+ * Hard-coded deliberately: this is an identity, not a setting. It is the same
+ * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
+ * platform's own.
+ */
+export const PLATFORM_STORE_ID = "store-letitrip-official";
+export function storeAcceptsPoints(store, storeId) {
+    /*
+     * The id is taken from either source so a caller holding only an id (the
+     * order-group loop) and one holding the document (an admin surface) get the
+     * same answer. Mismatched sources would be two rules again.
+     */
+    const id = store?.id ?? storeId;
+    if (id === PLATFORM_STORE_ID)
+        return true;
+    return store?.acceptsPoints === true;
+}

package/dist/_internal/shared/features/shipping/shared-purchase.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared purchase, S5a — one payer, N destinations.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * The coordinator buys everything and assigns a destination per item, so one
+ * paid order becomes N parcels. That is **~20% of the shared-purchase work for
+ * most of its value** (the plan's own assessment), because it needs none of
+ * the hard parts: no multi-party payment, no coordinator deposit, no approval
+ * cascade, no per-buyer invoicing, no per-buyer GST, and no stock-reservation
+ * primitive.
+ *
+ * 🛑 It is NOT S5b. There is exactly ONE payer and ONE place of supply, which
+ * is what keeps the tax, the invoice and the refund path unchanged. The moment
+ * a second person pays, every one of those becomes per-buyer and the design is
+ * a different design.
+ *
+ * ## 🛑 Why the fees are SNAPSHOTTED, and the precedent that proves it
+ *
+ * A coordinator commits to a quoted total. If the handling fee or the
+ * per-destination shipping is re-read at settle, a seller can raise it after
+ * the quote and the coordinator absorbs the difference.
+ *
+ * The codebase already has this exact hole and this exact fix: the refund path
+ * reads `finalSale` from the ORDER snapshot rather than the live product,
+ * because — in its own words — "re-reading the live product would let a seller
+ * flip the switch afterwards". D61 generalises it: *any agreement with a gap
+ * between "terms agreed" and "money taken" must snapshot its terms at
+ * agreement.*
+ *
+ * So `quoteSharedPurchase` takes the rates as ARGUMENTS and the caller
+ * snapshots the result onto the order. There is no settings read in here.
+ */
+/** The two rates, read from the store document at quote time. */
+export interface SharedPurchaseRates {
+    allowSharedPurchase?: boolean;
+    sharedPurchaseHandlingFee?: number;
+    sharedPurchaseExtraShippingPerDestination?: number;
+}
+export interface SharedPurchaseQuoteInput {
+    /**
+     * Distinct destinations in this order group, INCLUDING the first.
+     *
+     * 🛑 A count of DISTINCT addresses, not of items. Three items to one address
+     * is one parcel and no extra leg; two items to two addresses is two. Passing
+     * an item count would charge a coordinator for splitting an order they did
+     * not split.
+     */
+    destinationCount: number;
+    /** The store's snapshotted rates. */
+    rates: SharedPurchaseRates;
+}
+export interface SharedPurchaseQuote {
+    /** True when this is actually a multi-destination order. */
+    isShared: boolean;
+    /** Flat handling fee, or 0. */
+    handlingFee: number;
+    /** Extra shipping for destinations beyond the first, or 0. */
+    extraShippingFee: number;
+    /** `handlingFee + extraShippingFee`, the figure added to the order total. */
+    total: number;
+    /**
+     * Set when the arrangement cannot be priced — the seller allows it but has
+     * not configured a rate.
+     *
+     * 🛑 The caller MUST act on this rather than treating the fee as ₹0. That is
+     * D44 exactly: `shippingUnavailable` existed with its own docstring saying
+     * "the caller MUST act on this rather than trusting `shippingFee: 0`", had
+     * ZERO consumers, and an `estimate`-mode store shipped free on every path as
+     * a result. An unpriced arrangement must be refused, not given away.
+     */
+    unpriced?: "handling" | "extra-shipping";
+}
+/**
+ * Price a shared-purchase arrangement for ONE order group.
+ *
+ * Pure: no settings read, no Firestore, no clock. The rates come in, the
+ * figure comes out, and the caller snapshots it.
+ */
+export declare function quoteSharedPurchase(input: SharedPurchaseQuoteInput): SharedPurchaseQuote;
+/**
+ * Distinct destinations across a set of lines.
+ *
+ * 🛑 Lines with NO `destinationAddressId` collapse into one bucket — the
+ * order's own address — rather than counting as a destination each. Otherwise
+ * an ordinary three-item order would look like three destinations and be
+ * charged two extra legs.
+ */
+export declare function countDestinations(lines: readonly {
+    destinationAddressId?: string;
+}[]): number;

package/dist/_internal/shared/features/shipping/shared-purchase.js

@@ -0,0 +1,108 @@
+/**
+ * Shared purchase, S5a — one payer, N destinations.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * The coordinator buys everything and assigns a destination per item, so one
+ * paid order becomes N parcels. That is **~20% of the shared-purchase work for
+ * most of its value** (the plan's own assessment), because it needs none of
+ * the hard parts: no multi-party payment, no coordinator deposit, no approval
+ * cascade, no per-buyer invoicing, no per-buyer GST, and no stock-reservation
+ * primitive.
+ *
+ * 🛑 It is NOT S5b. There is exactly ONE payer and ONE place of supply, which
+ * is what keeps the tax, the invoice and the refund path unchanged. The moment
+ * a second person pays, every one of those becomes per-buyer and the design is
+ * a different design.
+ *
+ * ## 🛑 Why the fees are SNAPSHOTTED, and the precedent that proves it
+ *
+ * A coordinator commits to a quoted total. If the handling fee or the
+ * per-destination shipping is re-read at settle, a seller can raise it after
+ * the quote and the coordinator absorbs the difference.
+ *
+ * The codebase already has this exact hole and this exact fix: the refund path
+ * reads `finalSale` from the ORDER snapshot rather than the live product,
+ * because — in its own words — "re-reading the live product would let a seller
+ * flip the switch afterwards". D61 generalises it: *any agreement with a gap
+ * between "terms agreed" and "money taken" must snapshot its terms at
+ * agreement.*
+ *
+ * So `quoteSharedPurchase` takes the rates as ARGUMENTS and the caller
+ * snapshots the result onto the order. There is no settings read in here.
+ */
+import { roundRupees } from "../../../../utils/number.formatter.js";
+/**
+ * Price a shared-purchase arrangement for ONE order group.
+ *
+ * Pure: no settings read, no Firestore, no clock. The rates come in, the
+ * figure comes out, and the caller snapshots it.
+ */
+export function quoteSharedPurchase(input) {
+    const none = {
+        isShared: false,
+        handlingFee: 0,
+        extraShippingFee: 0,
+        total: 0,
+    };
+    /*
+     * One destination is an ordinary order. Checked BEFORE the allow flag, so a
+     * seller who has not opted in is unaffected by this code path entirely —
+     * rather than being refused an order they were always able to take.
+     */
+    const destinations = Math.max(1, Math.floor(input.destinationCount));
+    if (destinations <= 1)
+        return none;
+    if (input.rates.allowSharedPurchase !== true) {
+        /*
+         * 🛑 Returns `isShared: false` rather than throwing, and the CALLER
+         * refuses. This function prices; it does not authorise. A thrown error
+         * here would be caught by a preview path and rendered as a broken page,
+         * where the correct behaviour is to tell the buyer this seller does not
+         * split orders.
+         */
+        return none;
+    }
+    const handling = input.rates.sharedPurchaseHandlingFee;
+    const perExtra = input.rates.sharedPurchaseExtraShippingPerDestination;
+    /*
+     * 🛑 `undefined` is UNPRICED, not zero — see the `unpriced` field. A seller
+     * who opted in without setting a rate has not agreed to do it for free, and
+     * charging ₹0 would hand them the extra labour at their own cost silently.
+     */
+    if (typeof handling !== "number" || !Number.isFinite(handling)) {
+        return { ...none, isShared: true, unpriced: "handling" };
+    }
+    if (typeof perExtra !== "number" || !Number.isFinite(perExtra)) {
+        return { ...none, isShared: true, unpriced: "extra-shipping" };
+    }
+    const handlingFee = roundRupees(Math.max(0, handling));
+    // BEYOND THE FIRST: the first destination's shipping is what the order would
+    // have paid anyway, so only the marginal legs are charged here.
+    const extraShippingFee = roundRupees(Math.max(0, perExtra) * (destinations - 1));
+    return {
+        isShared: true,
+        handlingFee,
+        extraShippingFee,
+        total: roundRupees(handlingFee + extraShippingFee),
+    };
+}
+/**
+ * Distinct destinations across a set of lines.
+ *
+ * 🛑 Lines with NO `destinationAddressId` collapse into one bucket — the
+ * order's own address — rather than counting as a destination each. Otherwise
+ * an ordinary three-item order would look like three destinations and be
+ * charged two extra legs.
+ */
+export function countDestinations(lines) {
+    const ids = new Set();
+    let usesOrderAddress = false;
+    for (const line of lines) {
+        if (line.destinationAddressId)
+            ids.add(line.destinationAddressId);
+        else
+            usesOrderAddress = true;
+    }
+    return ids.size + (usesOrderAddress ? 1 : 0);
+}

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -42,6 +42,17 @@ export interface PublicSiteSettings {
     chat?: {
         enabled: boolean;
     };
+    /**
+     * Is the support desk reachable — read by `UserLayoutClient`, a client
+     * component. Narrowed to the one boolean rather than passed by reference,
+     * so a field added to the document's `support` group later is not published
+     * by accident; `PUBLIC_SITE_SETTINGS_FIELDS` carries the same caveat beside
+     * its entry. Optional here because the group is absent on a settings
+     * document written before it existed.
+     */
+    support?: {
+        enabled: boolean;
+    };
     /**
      * The browser-side search index kill switch. **ON by default** — the
      * projection emits `indexEnabled: doc.search?.indexEnabled !== false`, so

package/dist/_internal/shared/fees/calculator.d.ts

@@ -79,6 +79,17 @@ export interface PayoutDeduction {
      * plus ₹80 postage" is a sentence; one net figure is not.
      */
     shippingReimbursement: number;
+    /**
+     * Rupee value of buyer points this order was settled with, deducted from
+     * `netAmount` (D46/D47, decisions 3 and 17 — the accepting store funds the
+     * redemption).
+     *
+     * Returned as its own figure rather than folded into `totalDeduction` for the
+     * same reason `shippingReimbursement` is: *"'₹900 less ₹30 commission plus
+     * ₹80 postage' is a sentence; one net figure is not."* A seller looking at a
+     * short payout needs to see which of the four terms shortened it.
+     */
+    pointsFunded: number;
 }
 /**
  * What a seller is actually paid.
@@ -101,8 +112,29 @@ export interface PayoutDeduction {
  *
  * Defaulted to 0, so the three call sites that do not yet pass it keep their
  * current behaviour exactly rather than silently gaining a term.
+ *
+ * ## 🛑 `pointsFunded` is the mirror of that, and it is a DEDUCTION
+ *
+ * Decisions 3 and 17: the programme is seller-funded at both ends — the
+ * accepting store absorbs the redemption, the originating store bears the
+ * earn — and the platform funds neither. So points spent on an order reduce
+ * that order's payout by the rupee value spent.
+ *
+ * It sits in the SAME position as postage and for the inverse reason: outside
+ * the commission and gateway bases. The seller agreed to fund a discount, not
+ * to pay us a commission on the discount they funded, and a gateway percentage
+ * on money no gateway touched is not a card fee at all.
+ *
+ * 🛑 So `grossAmount` is untouched and the fee figures are IDENTICAL whether
+ * points were used or not. That is what keeps the commission the seller is
+ * charged a function of the sale rather than of how the buyer chose to settle
+ * it — and it is why this cannot be implemented by passing a smaller
+ * `grossAmount`, which is the obvious shortcut and silently reduces our own
+ * commission by 2% of every redemption.
+ *
+ * Also defaulted to 0, for the same reason.
  */
-export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number): PayoutDeduction;
+export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number, pointsFunded?: number): PayoutDeduction;
 export interface CodHandlingFeeRates {
     /**
      * Rupee CEILING on the COD handling fee. Optional so a `siteSettings`

package/dist/_internal/shared/fees/calculator.js

@@ -114,8 +114,29 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
  *
  * Defaulted to 0, so the three call sites that do not yet pass it keep their
  * current behaviour exactly rather than silently gaining a term.
+ *
+ * ## 🛑 `pointsFunded` is the mirror of that, and it is a DEDUCTION
+ *
+ * Decisions 3 and 17: the programme is seller-funded at both ends — the
+ * accepting store absorbs the redemption, the originating store bears the
+ * earn — and the platform funds neither. So points spent on an order reduce
+ * that order's payout by the rupee value spent.
+ *
+ * It sits in the SAME position as postage and for the inverse reason: outside
+ * the commission and gateway bases. The seller agreed to fund a discount, not
+ * to pay us a commission on the discount they funded, and a gateway percentage
+ * on money no gateway touched is not a card fee at all.
+ *
+ * 🛑 So `grossAmount` is untouched and the fee figures are IDENTICAL whether
+ * points were used or not. That is what keeps the commission the seller is
+ * charged a function of the sale rather than of how the buyer chose to settle
+ * it — and it is why this cannot be implemented by passing a smaller
+ * `grossAmount`, which is the obvious shortcut and silently reduces our own
+ * commission by 2% of every redemption.
+ *
+ * Also defaulted to 0, for the same reason.
  */
-export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0) {
+export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0, pointsFunded = 0) {
     const platformFee = roundRupees(grossAmount * (commissions.platformFeePercent / 100));
     const gatewayFee = roundRupees(grossAmount * ((commissions.gatewayFeePercent ?? 0) / 100));
     const gstOnFee = roundRupees(platformFee * (commissions.gstPercent / 100));
@@ -123,7 +144,15 @@ export function computePayoutDeduction(grossAmount, commissions, shippingReimbur
     const postage = Number.isFinite(shippingReimbursement)
         ? Math.max(0, shippingReimbursement)
         : 0;
-    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage));
+    const points = Number.isFinite(pointsFunded) ? Math.max(0, pointsFunded) : 0;
+    /*
+     * Clamped at zero, as it already was. A redemption cannot exceed 50% of the
+     * order total, so it cannot plausibly exceed the net — but a floor here means
+     * no caller can ever hand a seller a negative payout, which would be written
+     * to a `PayoutDocument.amount` that every downstream sum then treats as a
+     * credit against the platform.
+     */
+    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage - points));
     return {
         platformFee,
         gatewayFee,
@@ -131,6 +160,7 @@ export function computePayoutDeduction(grossAmount, commissions, shippingReimbur
         totalDeduction,
         netAmount,
         shippingReimbursement: roundRupees(postage),
+        pointsFunded: roundRupees(points),
     };
 }
 /** Buyer-facing COD handling ceiling, in decimal rupees. */

package/dist/_internal/shared/media/limits.d.ts

@@ -27,6 +27,16 @@ export type MediaKind = "image" | "video" | "pdf";
 export declare const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export declare const PRODUCT_MAX_VIDEOS = 1;
+/**
+ * Photos a buyer may attach to one review.
+ *
+ * 🛑 Deliberately NOT `PRODUCT_MAX_IMAGES`, which is 24 and is a SELLER's
+ * ceiling for a whole listing. `audit-media-limit-literals` suggests that
+ * constant for any `images: z.array(…).max(n)`, and taking the suggestion
+ * here would have quadrupled what a review accepts — the right shape, the
+ * wrong number. A review is a few photos of one thing.
+ */
+export declare const REVIEW_MAX_IMAGES = 6;
 /**
  * Highest legal `index` in a product media filename.
  *

package/dist/_internal/shared/media/limits.js

@@ -41,6 +41,16 @@ export const MAX_VIDEO_BYTES = 50 * MEGABYTE;
 export const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export const PRODUCT_MAX_VIDEOS = 1;
+/**
+ * Photos a buyer may attach to one review.
+ *
+ * 🛑 Deliberately NOT `PRODUCT_MAX_IMAGES`, which is 24 and is a SELLER's
+ * ceiling for a whole listing. `audit-media-limit-literals` suggests that
+ * constant for any `images: z.array(…).max(n)`, and taking the suggestion
+ * here would have quadrupled what a review accepts — the right shape, the
+ * wrong number. A review is a few photos of one thing.
+ */
+export const REVIEW_MAX_IMAGES = 6;
 /**
  * Highest legal `index` in a product media filename.
  *

package/dist/_internal/shared/types/action-result.js

@@ -1,5 +1,6 @@
 import { normalizeError } from "../../../errors/normalize.js";
 import { mapToHttpError } from "../../../errors/error-mapping.js";
+import { toApiIssues } from "../../../errors/error-envelope.js";
 import { describeCauseChain } from "../../../errors/describe-cause.js";
 import { reportActionError } from "./action-error-reporter.js";
 /**
@@ -57,7 +58,20 @@ export async function wrapAction(fn) {
             ok: false,
             code: mapped.code,
             error: mapped.message,
-            ...(mapped.issues ? { issues: mapped.issues } : {}),
+            /*
+             * 🛑 `toApiIssues`, not the raw issues — this was the ONE producer in
+             * the codebase that skipped the scrubber, and it is the one with 221
+             * call sites.
+             *
+             * A raw `ZodIssue` carries `received`: the value the user actually
+             * submitted. On a failed signup, address save or payout-details save
+             * that is an email, a phone number or a bank account, echoed straight
+             * back into the client payload. `toApiIssues` narrows each issue to
+             * `{ message, path?, code? }`, which is exactly why it exists — every
+             * other producer (`routeHandler`, `createApiHandler`, the offer
+             * actions) already routes through it.
+             */
+            ...(mapped.issues ? { issues: toApiIssues(mapped.issues) } : {}),
         };
     }
 }

package/dist/client/api/surface-error.js

@@ -1,6 +1,6 @@
 import { isApiError } from "./ApiError.js";
 import { ApiClientError } from "../../http/ApiClient.js";
-import { applyZodIssues, hasAttachableIssue } from "../../ui/forms/apply-zod-issues.js";
+import { applyZodIssues, hasAttachableIssue, rootLevelMessages } from "../../ui/forms/apply-zod-issues.js";
 import { normalizeError } from "../../errors/normalize.js";
 import { getErrorDisplay, toUserMessage } from "../../errors/error-display-map.js";
 import { HTTP_ERROR_CODES } from "../../errors/error-mapping.js";
@@ -36,7 +36,21 @@ export function surfaceError(err, opts) {
     const issues = issuesOf(err);
     if (setFieldError && hasAttachableIssue(issues)) {
         applyZodIssues(issues, (name, message) => setFieldError(name, message ?? ""));
-        return; // inline errors only — no toast
+        /*
+         * 🛑 Root-level issues are NOT covered by the line above and must still be
+         * surfaced, or a cross-field rule fails silently.
+         *
+         * `applyZodIssues` skips any issue with an empty `path` — there is no
+         * field to put it on. For a mixed response (one field error plus one
+         * cross-field `.refine()`, the shape of "passwords must match" or "end
+         * date must be after start date") `hasAttachableIssue` is true, so we used
+         * to take this branch and `return` with the refine message discarded: the
+         * save was refused and nothing on screen said why.
+         */
+        for (const message of rootLevelMessages(issues)) {
+            showToast(message, "error");
+        }
+        return; // field errors inline; only the unattachable ones toast
     }
     if (hasStableErrorCode(err)) {
         const display = getErrorDisplay(err.code);

package/dist/client/api/useApiMutation.js

@@ -3,6 +3,7 @@ import * as React from "react";
 import { useMutation, } from "@tanstack/react-query";
 import { useToast } from "../../ui/components/Toast.js";
 import { surfaceError } from "./surface-error.js";
+import { toUserMessage } from "../../errors/error-display-map.js";
 export function useApiMutation(options) {
     const { showToast, updateToast } = useToast();
     const loadingIdRef = React.useRef(null);
@@ -40,7 +41,22 @@ export function useApiMutation(options) {
         onSettled: (data, err, variables, context, ctx) => {
             if (loadingIdRef.current) {
                 if (err) {
-                    updateToast(loadingIdRef.current, "error", err instanceof Error ? err.message : "Action failed");
+                    /*
+                     * 🛑 This was `err instanceof Error ? err.message : "Action failed"`
+                     * — verbatim the inverted ternary `audit-raw-error-text`'s own
+                     * header calls "the dominant shape", sitting two lines below the
+                     * correct `surfaceError` call in the same hook. The authored
+                     * sentence showed only when the value was NOT an Error, i.e. almost
+                     * never, so the normal case published the raw message.
+                     *
+                     * It was dormant only because `loadingMessage` currently has no
+                     * call sites; the first consumer to set one would have got two
+                     * toasts, one of them raw. `updateToast` is also absent from that
+                     * audit's SINKS list, so nothing would have caught it.
+                     */
+                    updateToast(loadingIdRef.current, "error", toUserMessage(err?.code, undefined, {
+                        fallback: "Action failed",
+                    }));
                 }
                 else if (!successMessage) {
                     updateToast(loadingIdRef.current, "success", "Done");

package/dist/client.d.ts

@@ -283,6 +283,8 @@ export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister,
 export type { LoginCredentials, RegisterData, ForgotPasswordData, ResetPasswordData, VerifyEmailData, ChangeEmailData } from "./features/auth/index";
 export { CartView, CartItemRow, CartGroupLineRow, CartSummary, CartPriceBreakdown, CartDrawer, CheckoutView, CheckoutSuccessView, CheckoutAddressStep, useGuestCart, useCartCount, useAddToCart, useCart, useGuestCartMerge, useCartQuery } from "./features/cart/index";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./features/cart/index";
+export { PointsTenderPicker } from "./features/cart/index";
+export type { PointsTenderPickerProps } from "./features/cart/index";
 export { clientLineTotal } from "./features/cart/utils/line-total";
 export type { PricedCartLine } from "./features/cart/utils/line-total";
 export type { CartPriceBreakdownData, CartPriceBreakdownStore, StoreAddonsValue, StoreAddonsRates } from "./features/cart/index";
@@ -389,6 +391,11 @@ export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewP
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
+export { OrderProvenanceCard } from "./features/orders/components/OrderProvenanceCard";
+export type { OrderProvenanceCardProps } from "./features/orders/components/OrderProvenanceCard";
+export { RaiseDisputeForm } from "./features/orders/components/RaiseDisputeForm";
+export type { RaiseDisputeFormProps } from "./features/orders/components/RaiseDisputeForm";
+export type { OrderSourceContext } from "./features/orders/schemas/firestore";
 export { PROTECTION_CLAIM_REASON_LABEL } from "./features/protection-claims/schemas/firestore";
 export type { ProtectionClaimReason } from "./features/protection-claims/schemas/firestore";
 export { OrderCompletionPanel } from "./features/orders/components/OrderCompletionPanel";
@@ -455,7 +462,7 @@ export type { OwnerQuickActionsProps, OwnerQuickActionsResource } from "./featur
 export type { StoreListingEntitlements } from "./features/seller/hooks/useStoreListingEntitlements";
 export type { ListingTypePlugin } from "./_internal/shared/listing-types/_registry";
 export type { ListingType } from "./features/products/types/index";
-export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits";
+export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, REVIEW_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits";
 export type { MediaKind, AllowedImageMime, AllowedVideoMime, AllowedDocMime, AllowedMime, } from "./_internal/shared/media/limits";
 export { ScamAwarenessModal } from "./features/scams/components/ScamAwarenessModal";
 export type { ScamAwarenessModalProps } from "./features/scams/components/ScamAwarenessModal";
@@ -586,6 +593,10 @@ export type { SellerSupportViewProps } from "./features/seller/components/Seller
 export { REFUND_COPY } from "./_internal/shared/features/orders/refund-copy";
 export { RETURN_REASON, FINAL_SALE_EXEMPT_REASONS, RETURN_REASON_LABEL, RETURN_REASON_GROUP_LABEL, isFinalSaleExempt, isReturnReason, selectableReturnReasons, } from "./_internal/shared/features/orders/return-reasons";
 export type { ReturnReason } from "./_internal/shared/features/orders/return-reasons";
+export { DISPUTE_KIND, DISPUTE_KIND_LABEL, DISPUTE_GATE, DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, isDisputeKind, checkDisputeGate, resolveDisputeEtd, disputeNotReachedFilableFrom, } from "./_internal/shared/features/orders/dispute-reasons";
+export type { DisputeKind, DisputeGateOrder, DisputeGateResult, } from "./_internal/shared/features/orders/dispute-reasons";
+export { INTEGRATIONS, INTEGRATION_ORDER, readIntegrationStates, integrationPatch, allIntegrationsPatch, } from "./_internal/shared/features/admin/integrations";
+export type { IntegrationId, IntegrationDescriptor, IntegrationState, } from "./_internal/shared/features/admin/integrations";
 export { RefundRequestView } from "./features/orders/components/RefundRequestView";
 export type { RefundRequestViewProps, RefundRequestSubmission, } from "./features/orders/components/RefundRequestView";
 export { ORDER_RETURN_WINDOW_DAYS, ORDER_RETURN_WINDOW_MS, ORDER_CANCELLABLE_STATUSES, } from "./_internal/shared/features/orders/config";