@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/shared/checkout/refundable-base.d.ts

@@ -0,0 +1,116 @@
+/**
+ * How much of an order can still be refunded, and what is withheld.
+ *
+ * ONE owner for two numbers that were previously computed four different ways
+ * and disagreed with each other and with the money actually moved.
+ *
+ * WHY:
+ *
+ * · **D1** — the over-refund guard compared `amount > order.totalPrice`, i.e.
+ *   against the ORDER TOTAL rather than the remaining balance, while its own
+ *   docstring promised "≤ remaining refundable amount". So ₹500 and then
+ *   another ₹500 both passed on a ₹600 order: **₹1,000 refunded, two real
+ *   gateway calls, both successful.**
+ *
+ * · **D3** — `isFull` was `amount >= order.totalPrice`, so a split refund
+ *   (₹300 + ₹200 of ₹500) never reached `status: "refunded"` and the order
+ *   stayed fully refundable forever.
+ *
+ * · **D32** — the platform fee is non-refundable by policy, and the only code
+ *   implementing that withheld ~10x too much (see `platformFeeWithheld`).
+ */
+/**
+ * Half a paisa. The tolerance exists because these are IEEE-754 sums of 2dp
+ * components: `0.1 + 0.2 > 0.3` is TRUE in floating point, so an exact
+ * comparison would reject a legitimate final refund that exactly exhausts the
+ * balance. Half a paisa is below the smallest representable money unit, so it
+ * cannot admit a real over-refund.
+ */
+export declare const MONEY_EPSILON = 0.005;
+/** The subset of an order this module needs. Keeps it testable and pure. */
+export interface RefundableOrderLike {
+    totalPrice: number;
+    platformFee?: number;
+    platformFeeGst?: number;
+    refunds?: ReadonlyArray<{
+        amount: number;
+        status?: string;
+    }>;
+}
+/**
+ * The platform fee actually withheld on a refund: the amount CHARGED, never a
+ * recomputed percentage.
+ *
+ * 🛑 This replaces the single worst money defect found in the audit (D32).
+ * `previewCancellationRefund` did:
+ *
+ *     const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+ *     const feeDeducted   = (grossRefund * effectiveRate) / 100;
+ *
+ * — a PERCENTAGE OF THE REFUND, which ignores `commissions.platformFeeMax`
+ * (default **₹10**) entirely and ignores `order.platformFee`, the amount that
+ * was actually collected and is stored on the order. On a ₹5,000 order at 2% +
+ * 18% GST it deducted **₹118** from a buyer who had paid **₹11.80** — keeping
+ * roughly ₹106 of their goods money and labelling it a platform fee. The
+ * overcharge grows with order value, so it is largest exactly where it is most
+ * noticeable.
+ *
+ * `platformFeeGst` is read from the order and only DERIVED for rows written
+ * before that field existed (2026-10-21). The derivation takes `gstPercent`
+ * from the caller rather than reading settings itself, so this stays pure and
+ * so a caller cannot accidentally reach for today's rate when the order is
+ * from last year — which is the mistake the whole function exists to undo.
+ */
+export declare function platformFeeWithheld(order: Pick<RefundableOrderLike, "platformFee" | "platformFeeGst">, 
+/** Only consulted for legacy orders with no stored `platformFeeGst`. */
+legacyGstPercent?: number): number;
+/**
+ * The ceiling every refund is measured against.
+ *
+ * 🛑 `totalPrice − platformFeeWithheld`, NOT `totalPrice`. The platform fee is
+ * non-refundable in every scenario — a decided policy, and one the product
+ * already states: `REFUND_COPY.request.acknowledgments[2]` tells the buyer
+ * "platform fees may be non-recoverable".
+ *
+ * This correction matters twice over. Phase 1's cumulative cap has to compare
+ * against THIS, or a refund can exceed what the buyer is owed; and `isFull`
+ * has to compare against THIS, or the largest possible refund is strictly less
+ * than `totalPrice` and **an order can never reach `status: "refunded"`** —
+ * which is what the old `amount >= totalPrice` test guaranteed.
+ */
+export declare function refundableBase(order: RefundableOrderLike, legacyGstPercent?: number): number;
+/**
+ * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.
+ *
+ * 🛑 A `reserved` entry counts. The two-phase write reserves before calling the
+ * provider and settles after, so between those two points the money may well
+ * have left — excluding reserved entries would let a concurrent request refund
+ * against a balance that is already spoken for, which is the TOCTOU the
+ * reservation exists to close. A `failed` entry releases its reservation by
+ * being skipped here, which is why no explicit release step is needed.
+ *
+ * `status` is optional on `OrderRefundEvent`: rows written before the
+ * two-phase scheme have none, and those are all committed refunds, so a
+ * missing status must count.
+ */
+export declare function committedRefundTotal(order: RefundableOrderLike): number;
+export interface RefundCapacity {
+    /** `totalPrice` less the non-refundable platform fee. */
+    base: number;
+    /** Already committed (processed or reserved). */
+    committed: number;
+    /** `base − committed`, floored at zero. */
+    remaining: number;
+    /** The non-refundable amount, for disclosure to the buyer. */
+    withheld: number;
+}
+/** Everything a caller needs to decide and to EXPLAIN a refund decision. */
+export declare function refundCapacity(order: RefundableOrderLike, legacyGstPercent?: number): RefundCapacity;
+/**
+ * Would this refund exhaust the refundable base?
+ *
+ * Measured against `base`, not `totalPrice` — see `refundableBase`. The
+ * epsilon makes an exactly-exhausting refund count as full rather than
+ * leaving a sub-paisa residue that keeps the order refundable forever.
+ */
+export declare function wouldBeFullRefund(order: RefundableOrderLike, amount: number, legacyGstPercent?: number): boolean;

package/dist/_internal/shared/checkout/refundable-base.js

@@ -0,0 +1,122 @@
+/**
+ * How much of an order can still be refunded, and what is withheld.
+ *
+ * ONE owner for two numbers that were previously computed four different ways
+ * and disagreed with each other and with the money actually moved.
+ *
+ * WHY:
+ *
+ * · **D1** — the over-refund guard compared `amount > order.totalPrice`, i.e.
+ *   against the ORDER TOTAL rather than the remaining balance, while its own
+ *   docstring promised "≤ remaining refundable amount". So ₹500 and then
+ *   another ₹500 both passed on a ₹600 order: **₹1,000 refunded, two real
+ *   gateway calls, both successful.**
+ *
+ * · **D3** — `isFull` was `amount >= order.totalPrice`, so a split refund
+ *   (₹300 + ₹200 of ₹500) never reached `status: "refunded"` and the order
+ *   stayed fully refundable forever.
+ *
+ * · **D32** — the platform fee is non-refundable by policy, and the only code
+ *   implementing that withheld ~10x too much (see `platformFeeWithheld`).
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+/**
+ * Half a paisa. The tolerance exists because these are IEEE-754 sums of 2dp
+ * components: `0.1 + 0.2 > 0.3` is TRUE in floating point, so an exact
+ * comparison would reject a legitimate final refund that exactly exhausts the
+ * balance. Half a paisa is below the smallest representable money unit, so it
+ * cannot admit a real over-refund.
+ */
+export const MONEY_EPSILON = 0.005;
+/**
+ * The platform fee actually withheld on a refund: the amount CHARGED, never a
+ * recomputed percentage.
+ *
+ * 🛑 This replaces the single worst money defect found in the audit (D32).
+ * `previewCancellationRefund` did:
+ *
+ *     const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+ *     const feeDeducted   = (grossRefund * effectiveRate) / 100;
+ *
+ * — a PERCENTAGE OF THE REFUND, which ignores `commissions.platformFeeMax`
+ * (default **₹10**) entirely and ignores `order.platformFee`, the amount that
+ * was actually collected and is stored on the order. On a ₹5,000 order at 2% +
+ * 18% GST it deducted **₹118** from a buyer who had paid **₹11.80** — keeping
+ * roughly ₹106 of their goods money and labelling it a platform fee. The
+ * overcharge grows with order value, so it is largest exactly where it is most
+ * noticeable.
+ *
+ * `platformFeeGst` is read from the order and only DERIVED for rows written
+ * before that field existed (2026-10-21). The derivation takes `gstPercent`
+ * from the caller rather than reading settings itself, so this stays pure and
+ * so a caller cannot accidentally reach for today's rate when the order is
+ * from last year — which is the mistake the whole function exists to undo.
+ */
+export function platformFeeWithheld(order, 
+/** Only consulted for legacy orders with no stored `platformFeeGst`. */
+legacyGstPercent) {
+    const fee = order.platformFee ?? 0;
+    if (fee <= 0)
+        return 0;
+    const gst = order.platformFeeGst ??
+        (typeof legacyGstPercent === "number" ? roundRupees((fee * legacyGstPercent) / 100) : 0);
+    return roundRupees(fee + gst);
+}
+/**
+ * The ceiling every refund is measured against.
+ *
+ * 🛑 `totalPrice − platformFeeWithheld`, NOT `totalPrice`. The platform fee is
+ * non-refundable in every scenario — a decided policy, and one the product
+ * already states: `REFUND_COPY.request.acknowledgments[2]` tells the buyer
+ * "platform fees may be non-recoverable".
+ *
+ * This correction matters twice over. Phase 1's cumulative cap has to compare
+ * against THIS, or a refund can exceed what the buyer is owed; and `isFull`
+ * has to compare against THIS, or the largest possible refund is strictly less
+ * than `totalPrice` and **an order can never reach `status: "refunded"`** —
+ * which is what the old `amount >= totalPrice` test guaranteed.
+ */
+export function refundableBase(order, legacyGstPercent) {
+    return roundRupees(Math.max(0, order.totalPrice - platformFeeWithheld(order, legacyGstPercent)));
+}
+/**
+ * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.
+ *
+ * 🛑 A `reserved` entry counts. The two-phase write reserves before calling the
+ * provider and settles after, so between those two points the money may well
+ * have left — excluding reserved entries would let a concurrent request refund
+ * against a balance that is already spoken for, which is the TOCTOU the
+ * reservation exists to close. A `failed` entry releases its reservation by
+ * being skipped here, which is why no explicit release step is needed.
+ *
+ * `status` is optional on `OrderRefundEvent`: rows written before the
+ * two-phase scheme have none, and those are all committed refunds, so a
+ * missing status must count.
+ */
+export function committedRefundTotal(order) {
+    return roundRupees((order.refunds ?? [])
+        .filter((r) => r.status !== "failed")
+        .reduce((sum, r) => sum + (r.amount ?? 0), 0));
+}
+/** Everything a caller needs to decide and to EXPLAIN a refund decision. */
+export function refundCapacity(order, legacyGstPercent) {
+    const base = refundableBase(order, legacyGstPercent);
+    const committed = committedRefundTotal(order);
+    return {
+        base,
+        committed,
+        remaining: roundRupees(Math.max(0, base - committed)),
+        withheld: platformFeeWithheld(order, legacyGstPercent),
+    };
+}
+/**
+ * Would this refund exhaust the refundable base?
+ *
+ * Measured against `base`, not `totalPrice` — see `refundableBase`. The
+ * epsilon makes an exactly-exhausting refund count as full rather than
+ * leaving a sub-paisa residue that keeps the order refundable forever.
+ */
+export function wouldBeFullRefund(order, amount, legacyGstPercent) {
+    const { base, committed } = refundCapacity(order, legacyGstPercent);
+    return committed + amount >= base - MONEY_EPSILON;
+}

package/dist/_internal/shared/features/auctions/config.d.ts

@@ -55,6 +55,19 @@ export interface BuyNowAvailabilityInput {
     currentBid: number | null | undefined;
     isEnded: boolean;
     isSold?: boolean;
+    /**
+     * The seller's floor for the item (D53). Buy-Now below it is refused.
+     *
+     * 🛑 OPTIONAL so every existing call site keeps compiling — but a caller
+     * that has the product and omits it silently reopens the hole, which is the
+     * weakness of this shape. The two server call sites that decide money
+     * (`placeBuyNow`, and the capability gate it consults) both pass it; a
+     * display-only caller that omits it renders a button the server will refuse,
+     * which is a worse UX than a hidden button but is not an exploit.
+     *
+     * Absent / 0 / non-finite means NO reserve — the common case.
+     */
+    reservePrice?: number | null;
 }
 /**
  * The single definition of "can this auction be bought outright right now".
@@ -75,7 +88,7 @@ export interface BuyNowAvailabilityInput {
  * `isSold` is optional because client callers rendering a live auction page
  * already know it isn't sold; server callers should always pass it.
  */
-export declare function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, }: BuyNowAvailabilityInput): boolean;
+export declare function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, reservePrice, }: BuyNowAvailabilityInput): boolean;
 /**
  * Preset step multipliers offered by the bid form, as multiples of the
  * effective minimum increment. With a ₹100 increment this renders

package/dist/_internal/shared/features/auctions/config.js

@@ -89,12 +89,41 @@ export function resolveMinBid(currentBidAmount, tiers, override, opts) {
  * `isSold` is optional because client callers rendering a live auction page
  * already know it isn't sold; server callers should always pass it.
  */
-export function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, }) {
+export function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, reservePrice, }) {
     if (isEnded || isSold === true)
         return false;
     if (typeof buyNowPrice !== "number" || !Number.isFinite(buyNowPrice) || buyNowPrice <= 0) {
         return false;
     }
+    /*
+     * ── D53: BUY-NOW MUST CLEAR THE RESERVE ─────────────────────────────────
+     *
+     * 🛑 This function consulted end state, sold state and the standing bid —
+     * and never `reservePrice`, which was enforced in ONE place:
+     * `auctionSettlement`, i.e. only on the competitive path. So a Buy-Now
+     * priced below the reserve completed, and the seller was bound to a price
+     * the reserve existed to refuse.
+     *
+     * The reserve is the seller's floor for the ITEM, not for a particular sale
+     * mechanism. A buyout that undercuts it defeats it entirely — and does so on
+     * the path with no competing bidders to push the price up, which is the one
+     * where the floor matters most.
+     *
+     * 🛑 Checked here rather than at the call site, deliberately: this is the
+     * gate `placeBuyNow` already consults AND the predicate the UI uses to
+     * decide whether to render the button at all, so one change closes the
+     * exploit and stops offering a control that must then refuse.
+     *
+     * Absent/zero/non-finite reserve means NO reserve — which is the common case
+     * and must stay permissive, or every reserve-less auction would lose its
+     * Buy-Now.
+     */
+    if (typeof reservePrice === "number" &&
+        Number.isFinite(reservePrice) &&
+        reservePrice > 0 &&
+        buyNowPrice < reservePrice) {
+        return false;
+    }
     return buyNowPrice > (currentBid ?? 0);
 }
 /**

package/dist/_internal/shared/features/brands/schema.d.ts

@@ -9,26 +9,47 @@ export declare const brandInputSchema: z.ZodObject<{
     founded: z.ZodOptional<z.ZodNumber>;
     isActive: z.ZodDefault<z.ZodBoolean>;
     displayOrder: z.ZodDefault<z.ZodNumber>;
+    highlights: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    faqs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        answer: string;
+    }, {
+        question: string;
+        answer: string;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     slug: string;
     isActive: boolean;
     displayOrder: number;
     country?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }, {
     name: string;
     slug: string;
     country?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }>;
 export declare const brandUpdateSchema: z.ZodObject<Omit<{
     name: z.ZodOptional<z.ZodString>;
@@ -40,24 +61,45 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     founded: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     displayOrder: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    highlights: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    faqs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        answer: string;
+    }, {
+        question: string;
+        answer: string;
+    }>, "many">>>;
 }, "slug">, "strip", z.ZodTypeAny, {
     country?: string | undefined;
     name?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }, {
     country?: string | undefined;
     name?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }>;
 export type BrandInput = z.infer<typeof brandInputSchema>;
 export type BrandUpdate = z.infer<typeof brandUpdateSchema>;

package/dist/_internal/shared/features/brands/schema.js

@@ -12,5 +12,23 @@ export const brandInputSchema = z.object({
     founded: z.number().int().min(1800).max(new Date().getFullYear()).optional(),
     isActive: z.boolean().default(true),
     displayOrder: z.number().int().min(0).default(0),
+    /*
+     * Editorial content, rendered by `CategoryHighlightsAndFaqSection` on the
+     * brand page and previously unauthorable — the form did not carry them, so
+     * this schema did not need them either.
+     *
+     * 🛑 CAPPED, both of them. These render in a fixed block above the fold on
+     * a public page, and an unbounded list is how a form becomes a way to break
+     * the page it feeds. The numbers match what the category editor already
+     * enforces for the same two fields on the same renderer.
+     */
+    highlights: z.array(z.string().min(1).max(200)).max(8).optional(),
+    faqs: z
+        .array(z.object({
+        question: z.string().min(1).max(300),
+        answer: z.string().min(1).max(2000),
+    }))
+        .max(8)
+        .optional(),
 });
 export const brandUpdateSchema = brandInputSchema.partial().omit({ slug: true });

package/dist/_internal/shared/features/orders/refund-copy.d.ts

@@ -40,6 +40,28 @@ export declare const REFUND_COPY: {
     readonly siblingPayments: {
         readonly heading: (count: number) => string;
     };
+    /**
+     * What to tell the buyer about the money, immediately after they cancel.
+     *
+     * 🛑 Here rather than inline in the route, because there are two cancel
+     * endpoints plus the buyer's cancel page, and three copies of "we owe you
+     * ₹X" is how a refund timeline comes to be published three different ways
+     * (D20/D31). It is a function of the OUTCOME, so the sentence cannot
+     * disagree with what actually happened — which is the specific failure D14
+     * was: the page said one thing and the money did another.
+     *
+     * 🛑 It deliberately quotes **no timeline**. "5–7 business days" is published
+     * in three contradicting places already and reconciling them is Phase 9; a
+     * fourth statement of it here would be a new owner of a number that needs
+     * fewer, not more.
+     */
+    readonly cancellation: {
+        readonly message: (outcome: {
+            moved: "none" | "gateway" | "owed";
+            amount: number;
+            why?: string;
+        }) => string;
+    };
     readonly shipping: {
         readonly noOptions: "No shipping options available for this item.";
         readonly freeLabel: "Free";

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

@@ -44,6 +44,40 @@ export const REFUND_COPY = {
     siblingPayments: {
         heading: (count) => `Other orders from this payment (${count})`,
     },
+    /**
+     * What to tell the buyer about the money, immediately after they cancel.
+     *
+     * 🛑 Here rather than inline in the route, because there are two cancel
+     * endpoints plus the buyer's cancel page, and three copies of "we owe you
+     * ₹X" is how a refund timeline comes to be published three different ways
+     * (D20/D31). It is a function of the OUTCOME, so the sentence cannot
+     * disagree with what actually happened — which is the specific failure D14
+     * was: the page said one thing and the money did another.
+     *
+     * 🛑 It deliberately quotes **no timeline**. "5–7 business days" is published
+     * in three contradicting places already and reconciling them is Phase 9; a
+     * fourth statement of it here would be a new owner of a number that needs
+     * fewer, not more.
+     */
+    cancellation: {
+        message: (outcome) => {
+            if (outcome.moved === "gateway") {
+                return `Order cancelled. A refund of ₹${outcome.amount.toFixed(2)} has been sent back to your original payment method.`;
+            }
+            if (outcome.moved === "owed") {
+                return `Order cancelled. We owe you ₹${outcome.amount.toFixed(2)} — it needs to be sent manually, and our team has been notified.`;
+            }
+            /*
+             * `none` splits two very different situations and must not blur them: an
+             * unpaid order has nothing to refund, while an already-refunded one has
+             * had its money returned. Telling the second buyer "no payment was
+             * taken" would read as a denial that they ever paid.
+             */
+            return outcome.why === "nothing-refundable"
+                ? "Order cancelled. Its payment had already been refunded in full, so nothing further is owed."
+                : "Order cancelled. No payment had been taken, so there is nothing to refund.";
+        },
+    },
     shipping: {
         noOptions: "No shipping options available for this item.",
         freeLabel: "Free",