@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/shared/cache/revalidate-targets.d.ts

@@ -31,7 +31,6 @@
  * render). Under-revalidating is the failure that shows a buyer a sold-out
  * listing as in stock, so when in doubt this returns MORE paths, not fewer.
  */
-/** What the caller knows about the written document, when it knows anything. */
 export interface RevalidateHints {
     /** `standard` | `auction` | `pre-order` | … — picks the right detail route. */
     listingType?: string;

package/dist/_internal/shared/cache/revalidate-targets.js

@@ -31,6 +31,8 @@
  * render). Under-revalidating is the failure that shows a buyer a sold-out
  * listing as in stock, so when in doubt this returns MORE paths, not fewer.
  */
+/** What the caller knows about the written document, when it knows anything. */
+import { ROUTES } from "../../../next/routing/route-map.js";
 /** Detail route per listing type. Mirrors `ListingTypePlugin.detailRoute`. */
 const PRODUCT_DETAIL_BY_TYPE = {
     standard: (id) => `/products/${id}`,
@@ -73,7 +75,7 @@ function listingTypeFromId(id) {
     return undefined;
 }
 function productTargets(id, hints) {
-    const out = ["/", "/products"];
+    const out = [ROUTES.HOME, ROUTES.PUBLIC.PRODUCTS];
     if (!id)
         return out;
     const type = hints?.listingType ?? listingTypeFromId(id);
@@ -81,7 +83,7 @@ function productTargets(id, hints) {
         out.push(PRODUCT_DETAIL_BY_TYPE[type](id));
         // The type's own browse page, when it has one distinct from /products.
         const browse = PRODUCT_DETAIL_BY_TYPE[type](id).replace(/\/[^/]+$/, "");
-        if (browse && browse !== "/products")
+        if (browse && browse !== ROUTES.PUBLIC.PRODUCTS)
             out.push(browse);
     }
     else {
@@ -119,26 +121,26 @@ export function revalidateTargetsFor(collection, id, hints) {
         case "categories":
             // Brands and pricing bundles are `categories` rows discriminated by
             // `categoryType`, so all three detail shapes are marked.
-            paths = ["/", "/categories"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.CATEGORIES];
             if (id)
                 paths.push(`/categories/${id}`, `/brands/${id}`, `/bundles/${id}`);
             break;
         case "blogPosts":
-            paths = ["/", "/blog"];
+            paths = [ROUTES.HOME, ROUTES.BLOG.LIST];
             if (id)
                 paths.push(`/blog/${id}`);
             break;
         case "events":
-            paths = ["/", "/events"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.EVENTS];
             if (id)
                 paths.push(`/events/${id}`);
             break;
         case "reviews":
             // A new review changes the product's rating and the homepage stat.
-            paths = ["/", "/reviews"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.REVIEWS];
             break;
         case "stores":
-            paths = ["/", "/stores"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.STORES];
             if (id)
                 paths.push(`/stores/${id}`);
             break;
@@ -148,7 +150,7 @@ export function revalidateTargetsFor(collection, id, hints) {
             paths = ["/"];
             break;
         case "faqs":
-            paths = ["/", "/faqs"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.FAQS];
             break;
         default:
             paths = [];

package/dist/_internal/shared/checkout/rules/_defaults.js

@@ -1,12 +1,10 @@
 /** Default ListingCheckoutRule hook implementations. */
-import { STANDARD_MAX_QTY_PER_LINE } from "./_limits.js";
 export const DEFAULT_LISTING_RULE = {
     purchaseable: true,
     cartEligible: true,
     cartIneligibleHint: "This listing type cannot be added to the cart.",
     requiresShippingAddress: true,
     nonRefundable: false,
-    maxQuantityPerLine: STANDARD_MAX_QTY_PER_LINE,
     canMergeWithSameProduct: true,
     maxLinesPerOrder: Infinity,
     refundPolicy: { full: true, partial: true, partialGranularity: "item" },

package/dist/_internal/shared/checkout/rules/_limits.d.ts

@@ -28,5 +28,18 @@ export declare const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export declare const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export declare const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export declare const STANDARD_MAX_QTY_PER_LINE = 99;

package/dist/_internal/shared/checkout/rules/_limits.js

@@ -28,5 +28,18 @@ export const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export const STANDARD_MAX_QTY_PER_LINE = 99;

package/dist/_internal/shared/checkout/rules/_registry.js

@@ -20,6 +20,7 @@ import { digitalCodeRule } from "./digital-code.rule.js";
 import { liveRule } from "./live.rule.js";
 import { artRule } from "./art.rule.js";
 import { stickersRule } from "./stickers.rule.js";
+import { sparesRule } from "./spares.rule.js";
 export const CHECKOUT_RULES = {
     standard: standardRule,
     auction: auctionRule,
@@ -30,6 +31,7 @@ export const CHECKOUT_RULES = {
     live: liveRule,
     art: artRule,
     stickers: stickersRule,
+    spares: sparesRule,
 };
 export const CATEGORY_CHECKOUT_RULES = {
     bundle: bundleRule,

package/dist/_internal/shared/checkout/rules/auction.rule.js

@@ -4,7 +4,15 @@ export const auctionRule = {
     orderType: "auction",
     cartEligible: false, // bid-only; add-to-cart is blocked at the action layer
     cartIneligibleHint: "Place a bid on the auction page instead.",
-    maxQuantityPerLine: 1,
+    /*
+     * 🛑 cod + cash, NOT emi. An auction win is a committed sale of a unique lot:
+     * a buyer who never pays on delivery costs the seller the item and the
+     * auction both, and there is no second-highest bidder to fall back to once
+     * it has been marked sold. EMI is confirmed-at-order financing rather than a
+     * deferred payment, so it carries none of that risk and stays available.
+     */
+    blockedPaymentMethods: ["cod", "cash"],
+    blockedPaymentMessage: "An auction win cannot be paid for on delivery or in cash — the lot is one of a kind and is held for you from the moment the auction closes.",
     canMergeWithSameProduct: false,
     refundPolicy: { full: true, partial: false, partialGranularity: "none" },
     splitKey: (item) => `auction:${item.itemId}`,

package/dist/_internal/shared/checkout/rules/bundle.rule.js

@@ -3,4 +3,17 @@ export const bundleRule = {
     cartEligible: false, // direct-checkout-only; addBundleToCart has been removed
     orderType: "standard", // bundle orders resolve to standard orderType
     requiresShippingAddress: true,
+    /*
+     * 🛑 cod + cash, NOT emi. A bundle is priced BELOW the sum of its members —
+     * that discount is the whole product — so a no-show on delivery costs the
+     * seller several items at once, and the bundle has meanwhile been held out of
+     * every member's own availability. EMI is confirmed-at-order financing rather
+     * than a deferred payment, so it carries none of that and stays available.
+     *
+     * 🛑 Honoured by `assertPaymentMethodAllowed`, NOT by `runSyncPreflight` —
+     * which skips multi-member lines, and a bundle line is always one. A value
+     * here relying on preflight would be a silent no-op.
+     */
+    blockedPaymentMethods: ["cod", "cash"],
+    blockedPaymentMessage: "Bundles cannot be paid for on delivery or in cash — a bundle is priced below the sum of its parts and is reserved when you order.",
 };

package/dist/_internal/shared/checkout/rules/index.d.ts

@@ -1,5 +1,6 @@
 export type { ListingCheckoutRule, CategoryCheckoutRule, CartItemProductPair, OrderItemInput, RefundPolicy, } from "./types";
 export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRule, pickOrderType, getSplitKey, runSyncPreflight, } from "./_registry";
+export { assertPaymentMethodAllowed, blockedMethodsForCart, type BlockedMethod, } from "./payment-gate";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits";
 export { standardRule } from "./standard.rule";
 export { auctionRule } from "./auction.rule";
@@ -12,3 +13,4 @@ export { digitalCodeRule } from "./digital-code.rule";
 export { liveRule } from "./live.rule";
 export { artRule } from "./art.rule";
 export { stickersRule } from "./stickers.rule";
+export { sparesRule } from "./spares.rule";

package/dist/_internal/shared/checkout/rules/index.js

@@ -1,4 +1,12 @@
 export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRule, pickOrderType, getSplitKey, runSyncPreflight, } from "./_registry.js";
+/*
+ * The payment gate is a SEPARATE module from `_registry`, on purpose: it is the
+ * one rule check that cannot be expressed as a per-listing-type pass over
+ * single-member lines, which is all `runSyncPreflight` can see. Keeping them
+ * apart is what stops someone folding it back into preflight, where it would
+ * silently stop covering bundles and grouped lines.
+ */
+export { assertPaymentMethodAllowed, blockedMethodsForCart, } from "./payment-gate.js";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits.js";
 // Individual rules — exported for tests and direct access.
 export { standardRule } from "./standard.rule.js";
@@ -12,3 +20,4 @@ export { digitalCodeRule } from "./digital-code.rule.js";
 export { liveRule } from "./live.rule.js";
 export { artRule } from "./art.rule.js";
 export { stickersRule } from "./stickers.rule.js";
+export { sparesRule } from "./spares.rule.js";

package/dist/_internal/shared/checkout/rules/offer.rule.js

@@ -2,7 +2,6 @@ import { DEFAULT_LISTING_RULE } from "./_defaults.js";
 export const offerRule = {
     ...DEFAULT_LISTING_RULE,
     orderType: "offer",
-    maxQuantityPerLine: 1,
     canMergeWithSameProduct: false,
     refundPolicy: { full: true, partial: false, partialGranularity: "none" },
     splitKey: (item) => `offer:${item.itemId}`,

package/dist/_internal/shared/checkout/rules/payment-gate.d.ts

@@ -0,0 +1,26 @@
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import { type CheckoutPaymentMethod } from "../../features/checkout/config";
+/** Why one method is unavailable, and which listing said so. */
+export interface BlockedMethod {
+    /** The listing's own wording when it has one, else a generated sentence. */
+    message: string;
+    /** For logs and for the generated wording. */
+    label: string;
+}
+/**
+ * Which methods this cart forbids.
+ *
+ * Returned rather than thrown so the same answer can also DISABLE a payment
+ * control — one source for the refusal and the affordance, instead of a
+ * client-side guess that drifts from the server.
+ */
+export declare function blockedMethodsForCart(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>): Map<CheckoutPaymentMethod, BlockedMethod>;
+/**
+ * Throw when the chosen method is forbidden by anything in the cart.
+ *
+ * One error, not one per offending line: a buyer changes the payment method
+ * once, and listing every blocked item would be a wall of text about a single
+ * decision.
+ */
+export declare function assertPaymentMethodAllowed(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>, paymentMethod: CheckoutPaymentMethod | undefined): void;

package/dist/_internal/shared/checkout/rules/payment-gate.js

@@ -0,0 +1,133 @@
+/*
+ * WHY: Some listings must not be bought with a pay-later method. An auction win
+ *      or a bundle is a committed sale — a buyer who never pays on delivery
+ *      costs the seller the lot, and for a unique auction lot there is no
+ *      second-highest bidder to fall back on once it is marked sold. The rule
+ *      registry has a field for this (`blockedPaymentMethods`) and nothing
+ *      reachable enforced it for every line.
+ * WHAT: One cart-wide payment check, run BEFORE the transaction.
+ *
+ * 🛑 `runSyncPreflight` STRUCTURALLY CANNOT DO THIS, and that is not a bug in
+ * preflight. It does `if (isMultiMemberLine(pair.item)) continue;` for a good
+ * reason: a bundle or grouped line's own `listingType` describes the WRAPPER,
+ * not its members, so a per-type rule applied there would be applied to the
+ * wrong thing. Both of its call sites repeat the skip independently, and the
+ * online path additionally reduces each line to `getCartItemMemberIds(item)[0]`
+ * — its FIRST member only. So a `blockedPaymentMethods` set on `bundleRule` and
+ * left to preflight would be a silent no-op: the field would be set, reviewed,
+ * and never read.
+ *
+ * This resolves every line to ALL its members, so a grouped line containing one
+ * blocked listing is caught.
+ *
+ * 🛑 IT RUNS OUTSIDE THE TRANSACTION. Preflight is invoked inside the
+ * transaction callback, so a payment-method rejection there spends a full
+ * transaction attempt to produce an answer that depends on nothing the
+ * transaction reads.
+ *
+ * EXPORTS: assertPaymentMethodAllowed, blockedMethodsForCart
+ *
+ * @tag domain:checkout
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:server/features/checkout
+ * @tag sideEffects:none
+ */
+import { ValidationError } from "../../../../errors/index.js";
+import { CHECKOUT_PAYMENT_METHODS, } from "../../features/checkout/config.js";
+import { getCartItemMemberIds } from "../line-members.js";
+import { getCategoryRule, getListingRule } from "./_registry.js";
+/**
+ * Which methods this cart forbids.
+ *
+ * Returned rather than thrown so the same answer can also DISABLE a payment
+ * control — one source for the refusal and the affordance, instead of a
+ * client-side guess that drifts from the server.
+ */
+export function blockedMethodsForCart(items, productById) {
+    const blocked = new Map();
+    const claim = (methods, label, message) => {
+        for (const m of methods ?? []) {
+            // First claimant wins, so the message names a real listing rather than
+            // whichever happened to be last in the cart.
+            if (blocked.has(m))
+                continue;
+            blocked.set(m, {
+                label,
+                message: message ??
+                    `"${label}" cannot be paid for with ${PAYMENT_METHOD_LABEL[m] ?? m}.`,
+            });
+        }
+    };
+    for (const item of items) {
+        /*
+         * A bundle's restriction lives on its CategoryCheckoutRule, not on any
+         * listing type — its members are ordinary products whose own types would
+         * otherwise answer for it. Checked first for that reason.
+         */
+        if (item.bundleCategorySlug) {
+            const rule = getCategoryRule("bundle");
+            claim(rule?.blockedPaymentMethods, item.groupTitle ?? item.productTitle ?? "this bundle", rule?.blockedPaymentMessage);
+        }
+        /*
+         * EVERY member, not the first. `getCartItemMemberIds` returns the line's
+         * own product for a plain line and all members for a bundle or group, so
+         * one blocked member blocks the line.
+         */
+        for (const productId of getCartItemMemberIds(item)) {
+            const product = productById.get(productId);
+            /*
+             * An unresolved member is NOT treated as unrestricted here. It is left to
+             * the stock and existence checks that already run on the same cart and
+             * fail loudly — inventing a payment refusal for a missing product would
+             * report the wrong problem.
+             */
+            if (!product)
+                continue;
+            const type = (product.listingType ?? "standard");
+            const rule = getListingRule(type);
+            claim(rule.blockedPaymentMethods, product.title ?? type, rule.blockedPaymentMessage);
+        }
+    }
+    return blocked;
+}
+/** Human wording for the generated message. */
+const PAYMENT_METHOD_LABEL = {
+    cod: "cash on delivery",
+    cash: "cash on pickup",
+    emi: "EMI",
+    online: "online payment",
+    upi_manual: "manual bank/UPI transfer",
+};
+/**
+ * Throw when the chosen method is forbidden by anything in the cart.
+ *
+ * One error, not one per offending line: a buyer changes the payment method
+ * once, and listing every blocked item would be a wall of text about a single
+ * decision.
+ */
+export function assertPaymentMethodAllowed(items, productById, paymentMethod) {
+    if (!paymentMethod)
+        return;
+    /*
+     * 🛑 `admin_bypass` is exempt, deliberately. It exists so an admin can reach
+     * an order state without a real payment, is gated by a site-settings flag
+     * plus an admin role, and logs every use. Blocking it would make the one tool
+     * for testing these flows unable to test them.
+     */
+    if (paymentMethod === "admin_bypass")
+        return;
+    const blocked = blockedMethodsForCart(items, productById);
+    const offender = blocked.get(paymentMethod);
+    if (!offender)
+        return;
+    /*
+     * The methods that remain, derived from the union rather than a second list —
+     * a seventh payment method must not quietly go unmentioned here.
+     */
+    const allowed = CHECKOUT_PAYMENT_METHODS.filter((m) => m !== "admin_bypass" && !blocked.has(m)).map((m) => PAYMENT_METHOD_LABEL[m] ?? m);
+    throw Object.assign(new ValidationError(allowed.length > 0
+        ? `${offender.message} Available instead: ${allowed.join(", ")}.`
+        : `${offender.message} Nothing in this cart's combination can be paid for — remove the item and buy it on its own.`), { code: "PAYMENT_METHOD_BLOCKED" });
+}

package/dist/_internal/shared/checkout/rules/prize-draw.rule.js

@@ -10,15 +10,26 @@ import { PRIZE_DRAW_MAX_REVEALS_PER_ORDER } from "./_limits.js";
  * "admin_bypass" stays usable for QA regardless.
  */
 const PRIZE_DRAW_BLOCKED_PAYMENT_METHODS = ["cod", "cash", "emi"];
+/**
+ * The refusal, kept VERBATIM when this check moved out of `preflightChecks`
+ * into `assertPaymentMethodAllowed`.
+ *
+ * 🛑 The gate can generate a correct sentence on its own, and a generated one
+ * would have been a regression here: this wording names the REASON (winner
+ * assignment waits on confirmed payment) rather than just the refusal, and the
+ * reason is the thing a buyer needs in order to pick a different method rather
+ * than abandon the entry.
+ */
+const PRIZE_DRAW_BLOCKED_PAYMENT_MESSAGE = "Prize-draw entries can only be paid by manual bank/UPI transfer or PhonePe — cash on delivery and EMI are not available for this listing type.";
 export const prizeDrawRule = {
     ...DEFAULT_LISTING_RULE,
     orderType: "prize-draw",
     nonRefundable: true,
-    maxQuantityPerLine: 1,
     canMergeWithSameProduct: false,
     maxLinesPerOrder: PRIZE_DRAW_MAX_REVEALS_PER_ORDER,
     refundPolicy: { full: false, partial: false, partialGranularity: "none" },
     blockedPaymentMethods: PRIZE_DRAW_BLOCKED_PAYMENT_METHODS,
+    blockedPaymentMessage: PRIZE_DRAW_BLOCKED_PAYMENT_MESSAGE,
     splitKey: (item) => `prize-draw:${item.itemId}`,
     /**
      * Slice a high-quantity prize-draw entry into chunks of
@@ -43,13 +54,23 @@ export const prizeDrawRule = {
         }
         return chunks;
     },
-    preflightChecks: (pairs, paymentMethod) => {
-        if (paymentMethod && PRIZE_DRAW_BLOCKED_PAYMENT_METHODS.includes(paymentMethod)) {
-            const hasPrizeDraw = pairs.some((p) => p.product.listingType === "prize-draw");
-            if (hasPrizeDraw) {
-                throw Object.assign(new ValidationError("Prize-draw entries can only be paid by manual bank/UPI transfer or PhonePe — cash on delivery and EMI are not available for this listing type."), { code: "PRIZE_DRAW_PAYMENT_METHOD_BLOCKED" });
-            }
-        }
+    preflightChecks: (pairs) => {
+        /*
+         * The payment-method check USED to live here and is now in
+         * `assertPaymentMethodAllowed`, which runs cart-wide before the
+         * transaction.
+         *
+         * 🛑 This is not a tidy-up. The copy here could only ever see
+         * single-member lines — `runSyncPreflight` skips a bundle or grouped line,
+         * and its online call site reduces each line to its FIRST member — so a
+         * prize-draw entry reachable through a grouped selection was never
+         * checked. Re-adding a copy here would be a second answer to one question
+         * (Root Cause #75), and the one that is easier to find is the one that
+         * cannot see every line.
+         *
+         * `blockedPaymentMethods` + `blockedPaymentMessage` on this rule are what
+         * the gate reads, so the wording is unchanged.
+         */
         for (const { item, product } of pairs) {
             if (product.listingType !== "prize-draw")
                 continue;

package/dist/_internal/shared/checkout/rules/spares.rule.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Spares listing rule — one component off a disassembled item, standard-like
+ * checkout.
+ *
+ * No bespoke behaviour: cart/order grouping, stock decrement and refund policy
+ * all follow the standard defaults, and `pluginFor()` carries everything that
+ * differs (badge, browse route, seller form fields).
+ *
+ * 🛑 `orderType: "standard"` is deliberate rather than lazy. A new `OrderType`
+ * member fans out into the order-status tabs, the order filters and the
+ * splitter's own keys — and buys nothing here, because a spare is fulfilled,
+ * refunded and reported exactly like any other physical item. A buyer looking
+ * at their orders wants "the attack ring I bought", not a separate tab for it.
+ */
+import type { ListingCheckoutRule } from "./types";
+export declare const sparesRule: ListingCheckoutRule;

package/dist/_internal/shared/checkout/rules/spares.rule.js

@@ -0,0 +1,5 @@
+import { DEFAULT_LISTING_RULE } from "./_defaults.js";
+export const sparesRule = {
+    ...DEFAULT_LISTING_RULE,
+    orderType: "standard",
+};

package/dist/_internal/shared/checkout/rules/types.d.ts

@@ -62,8 +62,6 @@ export interface ListingCheckoutRule {
      * Set true for prize-draw entries.
      */
     nonRefundable: boolean;
-    /** Hard qty cap per single cart line. Auction/offer/prize-draw-per-line = 1. */
-    maxQuantityPerLine: number;
     /**
      * When false the checkout pipeline issues one order per cart line (even when
      * multiple lines share the same product).  Auctions and offers set this to
@@ -83,8 +81,20 @@ export interface ListingCheckoutRule {
      * all methods allowed. Prize-draw blocks cod/cash/emi — winner assignment
      * depends on the order's payment actually being confirmed, which those
      * deferred-payment methods don't guarantee.
+     *
+     * 🛑 Enforced by `assertPaymentMethodAllowed`, NOT by `runSyncPreflight`. A
+     * rule may only trust preflight for a single-member line; a type that can
+     * appear inside a bundle or a grouped selection is skipped there entirely.
+     * The gate runs over every member of every line, once, before the
+     * transaction.
      */
     blockedPaymentMethods?: CheckoutPaymentMethod[];
+    /**
+     * The refusal, in this type's own words. Optional — the gate generates a
+     * correct sentence without it. Supply one when the REASON is worth saying,
+     * as prize-draw's does.
+     */
+    blockedPaymentMessage?: string;
     /**
      * Return the grouping key used by the order splitter. Items with the same
      * key land in the same OrderGroup and produce one order document.
@@ -150,4 +160,18 @@ export interface CategoryCheckoutRule {
     cartEligible: boolean;
     orderType: OrderType;
     requiresShippingAddress: boolean;
+    /**
+     * Payment methods this category cannot be paid with.
+     *
+     * 🛑 NOT enforced by `runSyncPreflight`. That function skips multi-member
+     * lines by design, and a bundle is always one — so a value here would be set,
+     * reviewed, and never read. `assertPaymentMethodAllowed` is what honours it,
+     * and it runs cart-wide before the transaction.
+     */
+    blockedPaymentMethods?: CheckoutPaymentMethod[];
+    /**
+     * The refusal, in this category's own words. Optional — the gate generates a
+     * correct sentence without it. Supply one when the REASON is worth saying.
+     */
+    blockedPaymentMessage?: string;
 }

package/dist/_internal/shared/config/schema.d.ts

@@ -119,6 +119,120 @@ export interface AppkitSeoConfig {
     /** BCP 47 locale tag for OG/schema.org, e.g. "en-IN" */
     locale?: string;
 }
+/**
+ * A value the business has not decided yet.
+ *
+ * 🛑 `null`, deliberately, rather than `undefined` or an empty string. All
+ * three would render the same blank space, and only this one is distinguishable
+ * from "the key is missing" at a glance in the config file — which matters
+ * because every field typed this way appears on a page whose purpose is legal
+ * disclosure. A renderer is expected to show a visible `[to be confirmed]`
+ * marker (`<PendingValue>`), never an empty gap, so that an unfilled statutory
+ * field is obvious to whoever looks at the page rather than reading as absent.
+ */
+export type PendingString = string | null;
+/** Registered postal address of the legal entity. */
+export interface AppkitBusinessAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    /**
+     * GST state code, e.g. "27" for Maharashtra.
+     *
+     * 🛑 Must match the first two digits of `AppkitBusinessConfig.gstin`, and is
+     * an INPUT to the intra- vs inter-state supply decision that picks CGST+SGST
+     * over IGST. Wrong here means wrong tax on every invoice.
+     */
+    stateCode: string;
+    postalCode: string;
+    country: string;
+}
+export interface AppkitBusinessSupport {
+    email?: PendingString;
+    phone?: PendingString;
+    /** WhatsApp number with country code, digits only, e.g. "918919665811". */
+    whatsapp?: PendingString;
+    /** Human-readable, e.g. "Mon-Sat, 10:00-19:00 IST". */
+    hours?: PendingString;
+}
+/**
+ * Grievance officer. A mandatory published disclosure for an Indian
+ * e-commerce platform under the Consumer Protection (E-Commerce) Rules 2020
+ * and the IT Rules 2021 — name, designation and a working contact.
+ */
+export interface AppkitBusinessGrievance {
+    name?: PendingString;
+    designation?: PendingString;
+    email?: PendingString;
+    phone?: PendingString;
+}
+/**
+ * Published policy terms, as PROSE rather than numbers.
+ *
+ * "2-3 business days" carries its own unit; a bare `3` forces every renderer
+ * to re-invent one, and they will not agree.
+ */
+export interface AppkitBusinessPolicy {
+    processingTime?: PendingString;
+    deliveryEstimate?: PendingString;
+    shippingCharges?: PendingString;
+    cancellationWindow?: PendingString;
+    returnWindow?: PendingString;
+    refundTimeline?: PendingString;
+}
+/** Where buyers paying by bank transfer or UPI send money. */
+export interface AppkitBusinessBank {
+    name?: PendingString;
+    accountName?: PendingString;
+    /**
+     * Home branch, e.g. "Koramangala, Bangalore". Buyer-facing and NOT private:
+     * it identifies a public bank location, carries no account identifier, and
+     * some transfer forms still ask for it. Contrast `accountNumber`/`ifsc`
+     * below, which do identify the account and are withheld.
+     */
+    branchName?: PendingString;
+    /** 🛑 PRIVATE. Never on the public GET /api/site-settings. */
+    accountNumber?: PendingString;
+    /** 🛑 PRIVATE. Never on the public GET /api/site-settings. */
+    ifsc?: PendingString;
+    /** UPI Virtual Payment Address, e.g. "name@bank". Buyer-facing. */
+    upiVpa?: PendingString;
+    /**
+     * Root-relative path to the payment QR image.
+     *
+     * 🛑 A STATIC asset under public/, never a `/media/<slug>`. The media proxy
+     * composites a watermark onto every image it serves and has no skip
+     * mechanism, and a mark over a QR can corrupt enough modules to break the
+     * scan. `resolveMediaUrl` returns a relative path untouched, which is what
+     * makes a static path safe here.
+     */
+    qrImagePath?: string;
+}
+/**
+ * Statutory identity of the legal entity behind the site.
+ *
+ * This is the ONE owner of these facts. They are published by law, so none of
+ * it is secret and all of it belongs in a committed, reviewable file; the
+ * corresponding `BUSINESS_*` env vars exist to override per deployment.
+ */
+export interface AppkitBusinessConfig {
+    /** Registered legal name, e.g. "Let It Rip India". */
+    legalName: string;
+    /** Proprietor / authorised signatory. */
+    proprietor?: string;
+    /** e.g. "Sole proprietorship", "Private limited company". */
+    structure?: string;
+    /** 15-character GSTIN. Validate with `isValidGstin` — shape AND checksum. */
+    gstin?: PendingString;
+    /** Udyam (MSME) registration number. */
+    udyamNumber?: PendingString;
+    registeredAddress?: AppkitBusinessAddress;
+    support?: AppkitBusinessSupport;
+    grievance?: AppkitBusinessGrievance;
+    policy?: AppkitBusinessPolicy;
+    bank?: AppkitBusinessBank;
+}
 export interface AppkitI18nConfig {
     /** next-intl localePrefix strategy (default: "never") */
     localePrefix?: "never" | "always" | "as-needed";
@@ -146,6 +260,14 @@ export interface AppkitConfig {
     locales?: string[];
     /** Brand identity — name, social URLs, taglines */
     brand?: AppkitBrandConfig;
+    /**
+     * Statutory identity of the legal entity — legal name, GSTIN, registered
+     * address, support channels, grievance officer, published policy terms.
+     *
+     * Distinct from `brand`, which is how the site PRESENTS itself. "LetItRip"
+     * is the brand; "Let It Rip India" is the entity that issues the invoice.
+     */
+    business?: AppkitBusinessConfig;
     /** SEO defaults — siteUrl, defaultTitle, OG image, Twitter handle */
     seo?: AppkitSeoConfig;
     /** i18n / next-intl routing options */