@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/features/cart/components/CartPriceBreakdown.d.ts

@@ -32,6 +32,11 @@ export interface CartPriceBreakdownStore {
     supportsShippingProtection: boolean;
     supportsSaleProtection: boolean;
     hasFinalSaleItem: boolean;
+    /** D46/D47 + decision 22 — whether this seller accepts points, and how many. */
+    acceptsPoints: boolean;
+    pointsApplied: number;
+    /** S5a — handling + extra shipping legs for this store's order. */
+    sharedPurchaseFee: number;
 }
 /** Mirrors `CheckoutPricingPreview` without importing server code. */
 export interface CartPriceBreakdownData {
@@ -46,7 +51,15 @@ export interface CartPriceBreakdownData {
     couponDiscount: number;
     platformFee: number;
     gstOnFee: number;
+    /** S5a — handling + extra shipping legs across the cart. */
+    sharedPurchaseFee: number;
     total: number;
+    /** D46/D47 — points applied across every accepting store. */
+    pointsApplied: number;
+    /** What the buyer actually pays: `total − pointsApplied`. */
+    amountDue: number;
+    /** Their remaining balance, for the toggle's own label. */
+    pointsBalance: number;
     stores: CartPriceBreakdownStore[];
 }
 export interface CartPriceBreakdownProps {

package/dist/features/cart/components/CartPriceBreakdown.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Div, Row, Stack, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 function Line({ label, amount, tone = "muted", strong = false, }) {
@@ -21,5 +21,9 @@ export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unava
     const subtotalLabel = itemCount !== undefined
         ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""}${storeCount > 1 ? `, ${storeCount} stores` : ""})`
         : "Subtotal";
-    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: true }) }), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
+    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
+                    ? "Your points could not be applied to this order."
+                    : storeCount > 1
+                        ? "None of these sellers accepts points."
+                        : "This seller does not accept points." })), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
 }

package/dist/features/cart/components/PointsTenderPicker.d.ts

@@ -0,0 +1,61 @@
+import React from "react";
+/**
+ * "Pay with my points" — one checkbox for the whole cart (D46/D47).
+ *
+ * ## Why ONE control for the cart, where add-ons get one per store
+ *
+ * An add-on is a thing the buyer buys from a particular seller, so choosing it
+ * per seller is the only coherent shape. Points are the buyer's own balance:
+ * they do not belong to a seller, and asking "how many of your points would you
+ * like to spend at each of these three shops" is a question nobody wants to
+ * answer. So the buyer opts in once and the server spends what it can, in group
+ * order, at the sellers who accept them (decision 22).
+ *
+ * ## 🛑 A checkbox and NOT a number input, deliberately
+ *
+ * Decision 24: tick it and as many points as the 50% cap allows are applied;
+ * whatever cannot be applied stays in the balance for a later order. Nothing is
+ * forfeited, so there is no amount worth agonising over — and more importantly,
+ * an amount the client can send is an amount the client can lie about. The
+ * figure is always derived server-side from the live balance.
+ *
+ * ## It renders nothing when there is nothing to offer
+ *
+ * A zero balance gets no control at all rather than a disabled one. A disabled
+ * checkbox beside "0 points" is an advertisement, and the place to advertise
+ * the programme is the points page, not the cart of somebody who cannot use it.
+ */
+export interface PointsTenderPickerProps {
+    /** Current cart flag. */
+    value: boolean;
+    onChange: (next: boolean) => void;
+    /**
+     * The buyer's live balance, in points (1 point = ₹1).
+     *
+     * 🛑 Zero when the cart has not opted in, because the server only reads a
+     * balance it is going to use — so this cannot be relied on to decide whether
+     * to RENDER. `hasBalance` below exists for that.
+     */
+    balance: number;
+    /**
+     * Points actually applied to this cart, from the server preview. Undefined
+     * while the preview is in flight.
+     */
+    applied?: number;
+    /**
+     * Whether the buyer has ANY points, independent of the opt-in state.
+     *
+     * Separate from `balance` for the reason above: with the toggle off the
+     * preview returns `pointsBalance: 0`, so a control gated on `balance > 0`
+     * could never be switched back on once switched off — a one-way door, the
+     * `BackToTop` failure in Root Cause #41.
+     */
+    hasBalance: boolean;
+    /** No store in the cart accepts points — the control says so instead of hiding. */
+    noAcceptingStore?: boolean;
+    currency?: string;
+    disabled?: boolean;
+    disabledReason?: string;
+    className?: string;
+}
+export declare function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore, currency, disabled, disabledReason, className, }: PointsTenderPickerProps): React.JSX.Element | null;

package/dist/features/cart/components/PointsTenderPicker.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { IconBox } from "../../../ui/components/IconBox.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+export function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore = false, currency = "INR", disabled = false, disabledReason, className = "", }) {
+    if (!hasBalance)
+        return null;
+    const shownBalance = value ? balance : 0;
+    return (_jsx(Div, { surface: "muted", rounded: "lg", padding: "sm", className: className, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { align: "center", gap: "sm", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "brand", rounded: "lg", children: _jsx(Icon, { name: "points", size: "sm" }) }), _jsx(Div, { className: "min-w-0 flex-1", children: _jsx(FieldCheckbox, { name: "useAllPoints", label: "Pay with my points", checked: value, onChange: onChange, disabled: disabled || noAcceptingStore }) })] }), noAcceptingStore ? (_jsx(Text, { size: "xs", color: "muted", children: "Points cannot be used with the seller(s) in this cart." })) : disabled && disabledReason ? (_jsx(Text, { size: "xs", color: "muted", children: disabledReason })) : value && applied !== undefined ? (applied > 0 ? (_jsxs(Text, { size: "xs", color: "muted", children: [applied.toLocaleString("en-IN"), " points applied (", formatCurrency(applied, currency), ")", shownBalance > applied
+                            ? ` · ${(shownBalance - applied).toLocaleString("en-IN")} left over`
+                            : ""] })) : (_jsx(Text, { size: "xs", color: "muted", children: "No points could be applied to this order." }))) : (_jsx(Text, { size: "xs", color: "muted", children: "Up to half of an order can be paid with points." }))] }) }));
+}

package/dist/features/cart/components/StoreAddonsPicker.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Gift, ShieldAlert, ShieldCheck, ShieldOff } from "lucide-react";
 import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { Disclaimer } from "../../../ui/components/Disclaimer.js";
 import { IconBox } from "../../../ui/components/IconBox.js";
 import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
@@ -54,5 +55,5 @@ export function StoreAddonsPicker({ storeId, storeSubtotal, value, onChange, rat
                             ? "This seller does not offer shipment or sale protection."
                             : shippingDeclined
                                 ? "This seller does not offer shipment protection."
-                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] }))] }));
+                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] })), (shippingOffered || saleOffered) && _jsx(Disclaimer, { id: "protection-cover", inline: true })] }));
 }

package/dist/features/cart/components/index.d.ts

@@ -7,6 +7,8 @@ export { CartSummary } from "./CartSummary";
 export type { CartSummaryProps } from "./CartSummary";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker";
 export type { StoreAddonsPickerProps, StoreAddonsValue, StoreAddonsRates, } from "./StoreAddonsPicker";
+export { PointsTenderPicker } from "./PointsTenderPicker";
+export type { PointsTenderPickerProps } from "./PointsTenderPicker";
 export { CartPriceBreakdown } from "./CartPriceBreakdown";
 export type { CartPriceBreakdownProps, CartPriceBreakdownData, CartPriceBreakdownStore, } from "./CartPriceBreakdown";
 export { CheckoutView } from "./CheckoutView";

package/dist/features/cart/components/index.js

@@ -3,6 +3,7 @@ export { CartGroupLineRow } from "./CartGroupLineRow.js";
 export { CartView } from "./CartView.js";
 export { CartSummary } from "./CartSummary.js";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker.js";
+export { PointsTenderPicker } from "./PointsTenderPicker.js";
 export { CartPriceBreakdown } from "./CartPriceBreakdown.js";
 export { CheckoutView } from "./CheckoutView.js";
 export { CheckoutAddressStep } from "./CheckoutAddressStep.js";

package/dist/features/cart/repository/cart.repository.d.ts

@@ -129,6 +129,25 @@ export declare class CartRepository extends BaseRepository<CartDocument> {
      * and keeping both shapes around invites readers that handle only one.
      */
     setStoreAddons(userId: string, storeId: string, addons: CartStoreAddons | null): Promise<void>;
+    /**
+     * Opt the cart in or out of paying with points (D46/D47, decision 24).
+     *
+     * 🛑 A BOOLEAN, and the schema deliberately has no numeric sibling. Opt in
+     * and the server applies as many points as the 50% cap allows; whatever
+     * cannot be applied stays in the balance for a later order. A client-supplied
+     * amount is a client-supplied discount, which is the whole reason
+     * `storeAddons` is the source of truth for add-on fees rather than a request
+     * body.
+     *
+     * Written with the same `set(..., { merge: true })` as its neighbours so a
+     * concurrent add-on or selection write is not clobbered.
+     *
+     * 🛑 Opting OUT deletes the field rather than writing `false` — absent and
+     * `false` mean the same thing to every reader (`cart.useAllPoints === true`),
+     * and keeping both shapes invites a reader that handles only one. Same
+     * reasoning as `setStoreAddons` directly above.
+     */
+    setUseAllPoints(userId: string, useAllPoints: boolean): Promise<void>;
     /**
      * Cloud Functions: return refs of stale carts not updated within TTL.
      */

package/dist/features/cart/repository/cart.repository.js

@@ -590,6 +590,33 @@ export class CartRepository extends BaseRepository {
             updatedAt: new Date(),
         }, { merge: true });
     }
+    /**
+     * Opt the cart in or out of paying with points (D46/D47, decision 24).
+     *
+     * 🛑 A BOOLEAN, and the schema deliberately has no numeric sibling. Opt in
+     * and the server applies as many points as the 50% cap allows; whatever
+     * cannot be applied stays in the balance for a later order. A client-supplied
+     * amount is a client-supplied discount, which is the whole reason
+     * `storeAddons` is the source of truth for add-on fees rather than a request
+     * body.
+     *
+     * Written with the same `set(..., { merge: true })` as its neighbours so a
+     * concurrent add-on or selection write is not clobbered.
+     *
+     * 🛑 Opting OUT deletes the field rather than writing `false` — absent and
+     * `false` mean the same thing to every reader (`cart.useAllPoints === true`),
+     * and keeping both shapes invites a reader that handles only one. Same
+     * reasoning as `setStoreAddons` directly above.
+     */
+    async setUseAllPoints(userId, useAllPoints) {
+        await this.db
+            .collection(this.collection)
+            .doc(userId)
+            .set({
+            useAllPoints: useAllPoints ? true : FieldValue.delete(),
+            updatedAt: new Date(),
+        }, { merge: true });
+    }
     /*
      * `pruneStoreAddons(userId, keepStoreIds)` used to live here. It had zero
      * callers from the day it was written, and `pruneForItems` now does the same

package/dist/features/cart/schemas/firestore.d.ts

@@ -6,6 +6,7 @@
  */
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types/index";
+import type { CouponType } from "../../promotions/types/index";
 /**
  * What KIND of thing one cart line represents.
  *
@@ -57,6 +58,33 @@ export interface CartLineMember {
     gstRate?: 0 | 5 | 12 | 18 | 28;
     hsnCode?: string;
     listingType?: ListingType;
+    /**
+     * How the coordinator expressed this member's share of the line.
+     *
+     * Absent means `"amount"` — every line written before splits existed, so no
+     * migration and no behaviour change until a coordinator picks percentages.
+     *
+     * 🛑 The PERCENTAGE is the stored fact, not the resolved rupees. Percentages
+     * apply to the LANDED cost (goods + shipping + fees), so a member's figure
+     * MOVES when shipping is re-quoted — storing the computed amount instead
+     * would freeze a number that no longer matches the agreed share. The
+     * computed figures are snapshotted at COMMIT, which is where the
+     * coordinator's agreement actually becomes binding (D61).
+     *
+     * `resolveSplit` (`_internal/shared/checkout/split.ts`) is the only thing
+     * that turns these into money.
+     */
+    splitMode?: "amount" | "percent";
+    /** 0–100, read only when `splitMode === "percent"`. */
+    percent?: number;
+    /**
+     * The member's agreed contribution in decimal rupees, when typed directly.
+     *
+     * 🛑 NOT the same as `unitPrice`. `unitPrice` is what the ITEM costs;
+     * this is what this PERSON agreed to put in, and the two differ by design
+     * the moment a split is uneven or the total exceeds the landed cost.
+     */
+    contribution?: number;
 }
 export interface CartItemDocument {
     itemId: string;
@@ -183,6 +211,26 @@ export interface CartItemDocument {
     chosenShippingProviderId?: string;
     /** Fee in decimal rupees for the chosen provider, snapshotted at cart time. */
     chosenShippingFee?: number;
+    /**
+     * ── S5a: which address THIS line ships to ────────────────────────────────
+     *
+     * One payer, N destinations. Absent means "the order's own shipping
+     * address", which is every cart that predates this and every ordinary
+     * single-destination order — so nothing changes for them.
+     *
+     * 🛑 An `addresses/{id}` REFERENCE, never a copied address. Copying would
+     * put a name, a phone number and a street address onto the cart document,
+     * which is a PII store with no encryption, no `*_PII_FIELDS` entry and no
+     * retention story — and carts are swept by a TTL job that is not written to
+     * handle personal data. The id resolves server-side at checkout, where the
+     * address is already being read and decrypted.
+     *
+     * 🛑 It must belong to the BUYER. An arbitrary `addresses` id would let a
+     * caller address a parcel to any stored address on the platform, which is
+     * both a delivery hijack and a way to read whether an id exists. Checked
+     * server-side at the write, not trusted from the client.
+     */
+    destinationAddressId?: string;
     addedAt: Date;
     updatedAt: Date;
 }
@@ -196,6 +244,28 @@ export interface CartAppliedCoupon {
     storeId?: string;
     /** Item IDs (CartItemDocument.itemId) this coupon was calculated against */
     applicableItemIds?: string[];
+    /**
+     * The coupon's type, snapshotted at apply time (D51).
+     *
+     * 🛑 Needed because `detectCouponConflict` buckets on TYPE, not scope: a
+     * `points_earn` coupon is admin-scoped like every platform coupon but
+     * competes for its own slot, so without this field on the stored entry the
+     * detector could not tell a points coupon already in the cart from an
+     * ordinary platform one, and `RIPLI05` would block every other admin coupon
+     * — the exact defect the third bucket exists to prevent.
+     *
+     * Absent means "a discount coupon", which is what every cart written before
+     * this field holds, and is the reading that preserves the previous
+     * behaviour exactly.
+     *
+     * 🛑 Snapshotted deliberately, unlike the restrictions: a coupon's TYPE
+     * decides which slot it occupies, so re-reading it live would mean an admin
+     * editing a coupon's type could retroactively make a live cart's
+     * combination illegal. The money is still re-validated against the live
+     * coupon at placement (`revalidateAppliedCoupons`), which is where a changed
+     * discount has to be caught.
+     */
+    type?: CouponType;
 }
 /**
  * Paid add-ons the buyer opted into, for ONE store.
@@ -239,6 +309,28 @@ export interface CartDocument extends BaseDocument {
      * rather than a flag someone has to remember to check.
      */
     storeAddons?: Record<string, CartStoreAddons>;
+    /**
+     * The buyer has opted to spend points on this checkout.
+     *
+     * ## 🛑 A BOOLEAN, and the amount is never stored or sent
+     *
+     * Owner's rule: *"if use point it is all and then the balance is returned if
+     * excess"* — one opt-in, all-or-nothing. Ticked, the checkout applies as many
+     * points as the 50% cap allows; whatever cannot be applied stays in the
+     * balance. The buyer never types a number.
+     *
+     * So this is the ONLY thing the client may say about points. The amount is
+     * derived server-side from the live balance and
+     * `POINTS_MAX_REDEMPTION_PERCENT` at the moment the order is priced — the
+     * same rule that makes `storeAddons` above the source of truth rather than a
+     * request body, and for the same reason: a client-supplied money figure is a
+     * client-supplied discount.
+     *
+     * 🛑 This replaces a deleted `pointsToRedeem?: number` on the checkout input,
+     * whose handler debited the buyer AFTER the gateway had captured full price
+     * (D46). A number was the wrong shape as well as the wrong place.
+     */
+    useAllPoints?: boolean;
 }
 export declare const CART_COLLECTION: "carts";
 export declare const CART_INDEXED_FIELDS: string[];

package/dist/features/catalogue/components/CatalogueItemEditorView.js

@@ -95,11 +95,11 @@ export function CatalogueItemEditorView({ item, onSaved }) {
                     // than pointing at a photo the user has since removed.
                     onChange({ images: urls, mainImage: urls[0] ?? "" });
                 }, onUpload: handleUpload, accept: IMAGE_ACCEPT_ATTR, maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." })),
-            categorySlugs: ({ values, onChange }) => (
+            categorySlugs: ({ values, onChange, errors }) => (
             // Explicit `<string>`: with `multiple`, `value` is `V[]`, so an
             // inferred V reads the array itself as the option type.
-            _jsx(PaginatedSelect, { multiple: true, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
-            brandSlug: ({ values, onChange }) => (_jsx(PaginatedSelect, { value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
+            _jsx(PaginatedSelect, { multiple: true, name: "categorySlugs", error: errors.categorySlugs, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
+            brandSlug: ({ values, onChange, errors }) => (_jsx(PaginatedSelect, { name: "brandSlug", error: errors.brandSlug, value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
         },
     }), [handleUpload]);
     const nav = useSectionFormNav(sections, form, { scope: "user:catalogue-item" });

package/dist/features/contact/email.d.ts

@@ -1,14 +1,9 @@
 import "server-only";
 import type { SendGuardContext } from "../../_internal/shared/features/messaging/config";
 import type { JsonValue } from "@mohasinac/appkit";
-type SendEmailOptions = Record<string, JsonValue> & {
-    to: string | string[];
-    subject: string;
+import type { EmailOptions } from "../../contracts/email";
+type SendEmailOptions = Omit<EmailOptions, "html"> & {
     html?: string;
-    text?: string;
-    from?: string;
-    cc?: string | string[];
-    replyTo?: string;
 };
 /**
  * Everything `sendEmail` needs beyond the message itself.
@@ -22,9 +17,9 @@ type SendEmailOptions = Record<string, JsonValue> & {
  * (CLAUDE.md Rule #22: make the wrong thing unrepresentable).
  *
  * Kept as a separate second parameter rather than a field on
- * `SendEmailOptions` because that type has a `Record<string, JsonValue>` index
- * signature — a structured object would not satisfy it, and widening the index
- * signature to accommodate one field would weaken every other field's typing.
+ * `SendEmailOptions`, which is now the provider's own `EmailOptions`. The
+ * guard is about who may send and why; it is not part of the message, and
+ * folding it in would put it on the wire to the provider.
  */
 export type SendEmailGuard = SendGuardContext;
 /**
@@ -59,6 +54,28 @@ export interface OrderConfirmationEmailParams {
         unitPrice: number;
         totalPrice: number;
     }>;
+    /**
+     * Phase 7 — the invoice PDF to attach, as STORED bytes.
+     *
+     * 🛑 Bytes, never a path and never a renderer. Two renders can disagree — a
+     * changed template, a different library version — and the buyer's copy must
+     * be byte-identical to ours. Letting this function render would be a second
+     * render by definition.
+     *
+     * 🛑 Optional, and absence must stay silent. The invoice is numbered on the
+     * PAID transition and its bytes are produced on first request, so a COD
+     * order confirmed before payment legitimately has none — and this email has
+     * always sent without an attachment. Failing or warning here would turn the
+     * normal case into a noisy one.
+     *
+     * Resend supports attachments already (`email-resend/provider.ts`), so this
+     * needs no new send, no new credential and no change to the 80/day ceiling.
+     * Only the payload is bigger.
+     */
+    invoicePdf?: {
+        filename: string;
+        content: Buffer;
+    };
 }
 export declare function sendOrderConfirmationEmail(params: OrderConfirmationEmailParams): Promise<{
     success: boolean;

package/dist/features/contact/email.js

@@ -124,9 +124,10 @@ export async function sendEmail(opts, guard) {
                 ? opts.cc
                 : undefined,
             replyTo: typeof opts.replyTo === "string" ? opts.replyTo : undefined,
-            headers: typeof opts.headers === "object" && opts.headers
-                ? opts.headers
-                : undefined,
+            headers: opts.headers,
+            // Forwarded, not dropped — the provider has mapped these to Resend's
+            // `attachments` all along; nothing here ever handed them over.
+            attachments: opts.attachments,
         });
         void recordSendAttempt({
             to: opts.to,
@@ -184,6 +185,22 @@ export async function sendOrderConfirmationEmail(params) {
             to,
             subject: `Order Confirmed — ${orderId}`,
             html,
+            /*
+             * Phase 7 — the invoice, when there is one. The STORED bytes, handed
+             * in by the caller: see `invoicePdf` on the params type for why this
+             * function must not render its own.
+             */
+            ...(params.invoicePdf
+                ? {
+                    attachments: [
+                        {
+                            filename: params.invoicePdf.filename,
+                            content: params.invoicePdf.content,
+                            contentType: "application/pdf",
+                        },
+                    ],
+                }
+                : {}),
             text: `Hi ${userName},\n\nYour order ${orderId} has been confirmed!\n\n${itemsText}\nTotal: ${formattedTotal}\nPayment: ${paymentLabel}\nShip to: ${shippingAddress ?? "-"}\n\nView your order: ${orderUrl}\n\n© ${currentYear()} ${siteName}`,
         }, {
             channel: "email",

package/dist/features/dispute-reasons/repository/dispute-reasons.repository.d.ts

@@ -0,0 +1,38 @@
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import type { DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+import { type DisputeReasonDocument } from "../schemas/firestore";
+export declare class DisputeReasonsRepository extends BaseRepository<DisputeReasonDocument> {
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    /**
+     * The picker's list, scoped to one kind.
+     *
+     * 🛑 Scoped by KIND, not merged. A buyer reporting a damaged item must not be
+     * offered "it never arrived" — that reason belongs to the other gate, and
+     * picking it would produce a dispute the gate then refuses, which reads to
+     * the buyer as the form being broken rather than as the wrong choice.
+     */
+    listActiveByKind(kind: DisputeKind, model: SieveModel): Promise<FirebaseSieveResult<DisputeReasonDocument>>;
+    /**
+     * Add a reason. Staff only — enforced at the route, not here.
+     *
+     * 🛑 Keyed `dreason-<slug>`, so two agents cannot add the same wording twice.
+     * A colliding create returns the EXISTING row rather than overwriting it:
+     * that row has an author and may already be named on live disputes, and the
+     * second agent's intent ("there should be a reason for this") is satisfied by
+     * what exists. Same rule as the shipping-box presets.
+     */
+    createReason(input: {
+        label: string;
+        kind: DisputeKind;
+        createdByUid: string;
+        createdByName: string;
+    }): Promise<{
+        reason: DisputeReasonDocument;
+        created: boolean;
+    }>;
+    /** Soft-retire. See the schema for why this is never a delete. */
+    retire(id: string): Promise<void>;
+}
+export declare const disputeReasonsRepository: DisputeReasonsRepository;

package/dist/features/dispute-reasons/repository/dispute-reasons.repository.js

@@ -0,0 +1,80 @@
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+import { slugify } from "../../../utils/string.formatter.js";
+import { DISPUTE_REASON_COLLECTION, DISPUTE_REASON_FIELDS, DISPUTE_REASON_LABEL_MAX, } from "../schemas/firestore.js";
+export class DisputeReasonsRepository extends BaseRepository {
+    constructor() {
+        super(DISPUTE_REASON_COLLECTION);
+    }
+    /**
+     * The picker's list, scoped to one kind.
+     *
+     * 🛑 Scoped by KIND, not merged. A buyer reporting a damaged item must not be
+     * offered "it never arrived" — that reason belongs to the other gate, and
+     * picking it would produce a dispute the gate then refuses, which reads to
+     * the buyer as the form being broken rather than as the wrong choice.
+     */
+    async listActiveByKind(kind, model) {
+        const baseQuery = this.getCollection()
+            .where(DISPUTE_REASON_FIELDS.IS_ACTIVE, "==", true)
+            .where(DISPUTE_REASON_FIELDS.KIND, "==", kind);
+        return this.sieveQuery(model, DisputeReasonsRepository.SIEVE_FIELDS, { baseQuery, defaultPageSize: 20, maxPageSize: 50 });
+    }
+    /**
+     * Add a reason. Staff only — enforced at the route, not here.
+     *
+     * 🛑 Keyed `dreason-<slug>`, so two agents cannot add the same wording twice.
+     * A colliding create returns the EXISTING row rather than overwriting it:
+     * that row has an author and may already be named on live disputes, and the
+     * second agent's intent ("there should be a reason for this") is satisfied by
+     * what exists. Same rule as the shipping-box presets.
+     */
+    async createReason(input) {
+        const label = input.label.trim().slice(0, DISPUTE_REASON_LABEL_MAX);
+        const id = `dreason-${slugify(label)}`;
+        const existing = await this.findById(id);
+        /*
+         * A retired row that someone re-adds is REACTIVATED rather than duplicated
+         * — otherwise the slug collides forever and the agent can never get their
+         * reason back. Reactivating keeps the original author, which is correct:
+         * they wrote the wording.
+         */
+        if (existing) {
+            if (!existing.isActive) {
+                await this.update(id, { isActive: true, updatedAt: new Date() });
+                return { reason: { ...existing, isActive: true }, created: false };
+            }
+            return { reason: existing, created: false };
+        }
+        const now = new Date();
+        const reason = {
+            id,
+            label,
+            kind: input.kind,
+            isActive: true,
+            createdByUid: input.createdByUid,
+            createdByName: input.createdByName,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.createWithId(id, reason);
+        return { reason, created: true };
+    }
+    /** Soft-retire. See the schema for why this is never a delete. */
+    async retire(id) {
+        await this.update(id, { isActive: false, updatedAt: new Date() });
+    }
+}
+DisputeReasonsRepository.SIEVE_FIELDS = {
+    /*
+     * 🛑 `label` must be here because `PaginatedSelect` SEARCHES it. An
+     * unallowlisted searched field does not raise — `sieve.ts` sets
+     * `throwExceptions: false`, so `findField` returns undefined, the clause is
+     * silently dropped, and the picker returns the WHOLE list while looking
+     * exactly like it filtered (Root Cause #62).
+     */
+    label: { canFilter: true, canSort: true },
+    kind: { canFilter: true, canSort: false },
+    isActive: { canFilter: true, canSort: false },
+    createdByUid: { canFilter: true, canSort: false },
+};
+export const disputeReasonsRepository = new DisputeReasonsRepository();