@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -15,6 +15,7 @@
  * All money amounts are in decimal rupees.
  */
 import { roundRupees } from "../../../utils/number.formatter.js";
+import { resolveStateKey } from "./india-states.js";
 /** Buyer-facing platform commission ceiling, in decimal rupees. */
 const DEFAULT_PLATFORM_FEE_MAX = 10;
 /**
@@ -49,7 +50,34 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
     if (groupSubtotals.length === 0)
         return allocation;
     const total = groupSubtotals.reduce((sum, [, subtotal]) => sum + subtotal, 0);
-    let platformRemaining = fees.platformFee;
+    /*
+     * ── D41: THE `minimumTransactionFee` FLOOR IS APPLIED HERE, ONCE ──────────
+     *
+     * `computeCheckoutFees` computes `totalFee = max(platformFee + gstOnFee,
+     * minimumTransactionFee)` — and **`totalFee` had ZERO consumers.** Measured:
+     * the only references were its own declaration, its computation and its
+     * return. So the floor existed in a field nothing read.
+     *
+     * The capture route re-derived it by hand instead
+     * (`max(rawTotal, discountedSubtotal + minimumTransactionFee + …)`), while
+     * this allocator apportioned the UNFLOORED `platformFee`/`gstOnFee` to each
+     * order group. Consequence where the floor bit: **the gateway captured the
+     * floored amount and the orders recorded less than was collected.** The
+     * buyer's statement and our own records disagreed, by exactly the shortfall.
+     *
+     * The shortfall is treated as additional PLATFORM FEE, with no GST of its
+     * own, because the floor is defined on `platformFee + gstOnFee` COMBINED —
+     * so `flooredPlatformFee + gstOnFee` is exactly `totalFee`, which is exactly
+     * what the capture route charges. Adding GST on top of the shortfall would
+     * push the captured total above the floor and reintroduce the mismatch in
+     * the other direction.
+     *
+     * A floor nothing applies is not a floor; a floor applied in one of two
+     * places is worse, because the two then disagree about money.
+     */
+    const feeShortfall = Math.max(0, roundRupees(fees.totalFee - (fees.platformFee + fees.gstOnFee)));
+    const flooredPlatformFee = roundRupees(fees.platformFee + feeShortfall);
+    let platformRemaining = flooredPlatformFee;
     let gstRemaining = fees.gstOnFee;
     groupSubtotals.forEach(([storeId, subtotal], index) => {
         const isLast = index === groupSubtotals.length - 1;
@@ -57,7 +85,7 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
         // whole (necessarily zero-ish) fee to the last group rather than dividing
         // by zero.
         const share = total > 0 ? subtotal / total : 0;
-        const platformFee = isLast ? roundRupees(platformRemaining) : roundRupees(fees.platformFee * share);
+        const platformFee = isLast ? roundRupees(platformRemaining) : roundRupees(flooredPlatformFee * share);
         const gstOnFee = isLast ? roundRupees(gstRemaining) : roundRupees(fees.gstOnFee * share);
         platformRemaining = roundRupees(platformRemaining - platformFee);
         gstRemaining = roundRupees(gstRemaining - gstOnFee);
@@ -65,13 +93,45 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
     });
     return allocation;
 }
-export function computePayoutDeduction(grossAmount, commissions) {
+/**
+ * What a seller is actually paid.
+ *
+ * ## 🛑 `shippingReimbursement` is added AFTER the fee bases, never into them
+ *
+ * D45 makes postage a **cost being refunded**, not revenue. So it is the one
+ * term in this function that is added to `netAmount` while being excluded from
+ * `platformFee` and `gatewayFee` — because commissioning a seller's postage
+ * would mean charging them for the privilege of posting the parcel, and taking
+ * a gateway percentage of it would mean charging them a card fee on money that
+ * is reimbursing a cash outlay.
+ *
+ * That is also why it is a parameter here rather than something a caller adds
+ * to `grossAmount` before calling: `grossAmount` IS the commission base, so
+ * folding postage into it silently commissions it. Four payout paths call this
+ * (the seller's own earnings view, the manual request, and both jobs) and all
+ * four must agree to the rupee — a seller shown one number and paid another is
+ * worse than either number being wrong alone. One owner is what guarantees it.
+ *
+ * Defaulted to 0, so the three call sites that do not yet pass it keep their
+ * current behaviour exactly rather than silently gaining a term.
+ */
+export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0) {
     const platformFee = roundRupees(grossAmount * (commissions.platformFeePercent / 100));
     const gatewayFee = roundRupees(grossAmount * ((commissions.gatewayFeePercent ?? 0) / 100));
     const gstOnFee = roundRupees(platformFee * (commissions.gstPercent / 100));
     const totalDeduction = roundRupees(platformFee + gatewayFee + gstOnFee);
-    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction));
-    return { platformFee, gatewayFee, gstOnFee, totalDeduction, netAmount };
+    const postage = Number.isFinite(shippingReimbursement)
+        ? Math.max(0, shippingReimbursement)
+        : 0;
+    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage));
+    return {
+        platformFee,
+        gatewayFee,
+        gstOnFee,
+        totalDeduction,
+        netAmount,
+        shippingReimbursement: roundRupees(postage),
+    };
 }
 /** Buyer-facing COD handling ceiling, in decimal rupees. */
 const DEFAULT_COD_HANDLING_FEE_CAP = 200;
@@ -183,6 +243,44 @@ export const DEFAULT_GST_RATE = 5;
  * than guess.
  */
 export function isIntraStateSupply(storeState, buyerState) {
+    /*
+     * ── G2: resolve through the state TABLE first, not string equality ───────
+     *
+     * This was `normaliseStateName(a) === normaliseStateName(b)` — lowercase,
+     * strip non-letters, compare. Correct only when both sides happen to be
+     * spelled the same way, and they are not: a seller types their pickup
+     * state, a buyer types their delivery state, and a GSTIN carries the state
+     * as a two-digit CODE. So `"KA"` vs `"Karnataka"` compared unequal and the
+     * supply read as INTER-state, recording **IGST where CGST+SGST was due**.
+     *
+     * Worse, the old normaliser's `.replace(/[^a-z\s]/g, " ")` DESTROYED
+     * digits, so a state held as `"29"` — or a full GSTIN — normalised to the
+     * empty string and returned `null`, i.e. "place of supply undetermined",
+     * which both callers then resolve to IGST with a warning.
+     *
+     * None of this changed the TOTAL (IGST total == CGST+SGST total), which is
+     * precisely why it could live indefinitely: no figure in the system
+     * disagreed with any other. Only the split was wrong, and the split is what
+     * a GST return is built from.
+     *
+     * Verified against the table: "KA", "29", "29ABCDE1234F1Z5" and
+     * "karnataka." all resolve to one key; "AP" vs "Arunachal Pradesh", "MP" vs
+     * "Maharashtra" and "Punjab" vs "Puducherry" stay distinct (7 negative
+     * controls, 0 false positives).
+     */
+    const keyA = resolveStateKey(storeState);
+    const keyB = resolveStateKey(buyerState);
+    if (keyA && keyB)
+        return keyA === keyB;
+    /*
+     * 🛑 The string fallback STAYS, and it is a widening rather than a
+     * replacement. An input the table cannot resolve — a typo, a non-Indian
+     * state — used to be handled by plain equality, and for the case where BOTH
+     * sides carry the SAME unrecognised spelling ("Karnatka" twice) that
+     * produced the right answer. Dropping it would turn those into
+     * "undetermined", which resolves to IGST, so a pure replacement would
+     * REGRESS exactly the inputs the table was added to improve.
+     */
     const a = normaliseStateName(storeState);
     const b = normaliseStateName(buyerState);
     if (!a || !b)

package/dist/_internal/shared/fees/india-states.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Indian states and union territories, resolved to ONE canonical key from any
+ * of the three spellings that actually occur in our data.
+ *
+ * WHY (G2): place of supply was compared by normalised STRING EQUALITY —
+ * lowercase, strip punctuation, collapse whitespace, then `a === b`. That is
+ * correct only when both sides happen to be written the same way, and they are
+ * not:
+ *
+ *   · `StoreDocument`'s pickup address state is typed by a seller ("Karnataka",
+ *     "karnataka", "KA", "Karnatak")
+ *   · a buyer's delivery address is typed by the buyer
+ *   · a GSTIN carries the state as a two-digit CODE in its first two
+ *     characters ("29" = Karnataka) — and the old normaliser's
+ *     `.replace(/[^a-z\s]/g, " ")` stripped digits entirely, so a numeric
+ *     state resolved to `null`
+ *
+ * So `"KA"` vs `"Karnataka"` compared unequal, the supply read as INTER-state,
+ * and the order recorded **IGST where CGST+SGST was due**. Silently: there is
+ * no error, and the TOTAL is identical either way (IGST total == CGST+SGST
+ * total), so nothing downstream disagreed. Only the invoice's tax split was
+ * wrong, which is exactly the part a GST return is built from.
+ *
+ * 🛑 The total being unaffected is why this is a COMPLIANCE defect rather than
+ * a money defect, and why it could live indefinitely. Do not downgrade it on
+ * that basis: the split is what gets filed.
+ */
+/**
+ * Canonical key → the GST state code and the display name.
+ *
+ * Codes are the official GST state codes (the first two digits of a GSTIN).
+ * 🛑 They are LITERAL and ordered by code, so the table can be read against
+ * the published list rather than trusted.
+ */
+export declare const INDIA_STATES: {
+    readonly "jammu-kashmir": {
+        readonly code: "01";
+        readonly name: "Jammu and Kashmir";
+    };
+    readonly "himachal-pradesh": {
+        readonly code: "02";
+        readonly name: "Himachal Pradesh";
+    };
+    readonly punjab: {
+        readonly code: "03";
+        readonly name: "Punjab";
+    };
+    readonly chandigarh: {
+        readonly code: "04";
+        readonly name: "Chandigarh";
+    };
+    readonly uttarakhand: {
+        readonly code: "05";
+        readonly name: "Uttarakhand";
+    };
+    readonly haryana: {
+        readonly code: "06";
+        readonly name: "Haryana";
+    };
+    readonly delhi: {
+        readonly code: "07";
+        readonly name: "Delhi";
+    };
+    readonly rajasthan: {
+        readonly code: "08";
+        readonly name: "Rajasthan";
+    };
+    readonly "uttar-pradesh": {
+        readonly code: "09";
+        readonly name: "Uttar Pradesh";
+    };
+    readonly bihar: {
+        readonly code: "10";
+        readonly name: "Bihar";
+    };
+    readonly sikkim: {
+        readonly code: "11";
+        readonly name: "Sikkim";
+    };
+    readonly "arunachal-pradesh": {
+        readonly code: "12";
+        readonly name: "Arunachal Pradesh";
+    };
+    readonly nagaland: {
+        readonly code: "13";
+        readonly name: "Nagaland";
+    };
+    readonly manipur: {
+        readonly code: "14";
+        readonly name: "Manipur";
+    };
+    readonly mizoram: {
+        readonly code: "15";
+        readonly name: "Mizoram";
+    };
+    readonly tripura: {
+        readonly code: "16";
+        readonly name: "Tripura";
+    };
+    readonly meghalaya: {
+        readonly code: "17";
+        readonly name: "Meghalaya";
+    };
+    readonly assam: {
+        readonly code: "18";
+        readonly name: "Assam";
+    };
+    readonly "west-bengal": {
+        readonly code: "19";
+        readonly name: "West Bengal";
+    };
+    readonly jharkhand: {
+        readonly code: "20";
+        readonly name: "Jharkhand";
+    };
+    readonly odisha: {
+        readonly code: "21";
+        readonly name: "Odisha";
+    };
+    readonly chhattisgarh: {
+        readonly code: "22";
+        readonly name: "Chhattisgarh";
+    };
+    readonly "madhya-pradesh": {
+        readonly code: "23";
+        readonly name: "Madhya Pradesh";
+    };
+    readonly gujarat: {
+        readonly code: "24";
+        readonly name: "Gujarat";
+    };
+    readonly "dadra-nagar-haveli-daman-diu": {
+        readonly code: "26";
+        readonly name: "Dadra and Nagar Haveli and Daman and Diu";
+    };
+    readonly maharashtra: {
+        readonly code: "27";
+        readonly name: "Maharashtra";
+    };
+    readonly karnataka: {
+        readonly code: "29";
+        readonly name: "Karnataka";
+    };
+    readonly goa: {
+        readonly code: "30";
+        readonly name: "Goa";
+    };
+    readonly lakshadweep: {
+        readonly code: "31";
+        readonly name: "Lakshadweep";
+    };
+    readonly kerala: {
+        readonly code: "32";
+        readonly name: "Kerala";
+    };
+    readonly "tamil-nadu": {
+        readonly code: "33";
+        readonly name: "Tamil Nadu";
+    };
+    readonly puducherry: {
+        readonly code: "34";
+        readonly name: "Puducherry";
+    };
+    readonly "andaman-nicobar": {
+        readonly code: "35";
+        readonly name: "Andaman and Nicobar Islands";
+    };
+    readonly telangana: {
+        readonly code: "36";
+        readonly name: "Telangana";
+    };
+    readonly "andhra-pradesh": {
+        readonly code: "37";
+        readonly name: "Andhra Pradesh";
+    };
+    readonly ladakh: {
+        readonly code: "38";
+        readonly name: "Ladakh";
+    };
+};
+export type IndiaStateKey = keyof typeof INDIA_STATES;
+/**
+ * Resolve any spelling — canonical key, full name, abbreviation, former name,
+ * or a two-digit GST state code — to one canonical key, or `null`.
+ *
+ * 🛑 The numeric branch runs FIRST and before any letter-stripping, because
+ * the old normaliser destroyed digits. A state held as `"29"` or as a full
+ * GSTIN (`"29ABCDE1234F1Z5"`) is a real shape in this data: `resolveSupplierIdentity`
+ * reads a store's GSTIN, and its first two characters are the authoritative
+ * place of supply for the seller — more reliable than their typed pickup
+ * address, which is what G3 is about.
+ */
+export declare function resolveStateKey(raw: string | undefined | null): IndiaStateKey | null;
+/** The GST state code for any spelling, or `null`. */
+export declare function resolveStateCode(raw: string | undefined | null): string | null;

package/dist/_internal/shared/fees/india-states.js

@@ -0,0 +1,190 @@
+/**
+ * Indian states and union territories, resolved to ONE canonical key from any
+ * of the three spellings that actually occur in our data.
+ *
+ * WHY (G2): place of supply was compared by normalised STRING EQUALITY —
+ * lowercase, strip punctuation, collapse whitespace, then `a === b`. That is
+ * correct only when both sides happen to be written the same way, and they are
+ * not:
+ *
+ *   · `StoreDocument`'s pickup address state is typed by a seller ("Karnataka",
+ *     "karnataka", "KA", "Karnatak")
+ *   · a buyer's delivery address is typed by the buyer
+ *   · a GSTIN carries the state as a two-digit CODE in its first two
+ *     characters ("29" = Karnataka) — and the old normaliser's
+ *     `.replace(/[^a-z\s]/g, " ")` stripped digits entirely, so a numeric
+ *     state resolved to `null`
+ *
+ * So `"KA"` vs `"Karnataka"` compared unequal, the supply read as INTER-state,
+ * and the order recorded **IGST where CGST+SGST was due**. Silently: there is
+ * no error, and the TOTAL is identical either way (IGST total == CGST+SGST
+ * total), so nothing downstream disagreed. Only the invoice's tax split was
+ * wrong, which is exactly the part a GST return is built from.
+ *
+ * 🛑 The total being unaffected is why this is a COMPLIANCE defect rather than
+ * a money defect, and why it could live indefinitely. Do not downgrade it on
+ * that basis: the split is what gets filed.
+ */
+/**
+ * Canonical key → the GST state code and the display name.
+ *
+ * Codes are the official GST state codes (the first two digits of a GSTIN).
+ * 🛑 They are LITERAL and ordered by code, so the table can be read against
+ * the published list rather than trusted.
+ */
+export const INDIA_STATES = {
+    "jammu-kashmir": { code: "01", name: "Jammu and Kashmir" },
+    "himachal-pradesh": { code: "02", name: "Himachal Pradesh" },
+    punjab: { code: "03", name: "Punjab" },
+    chandigarh: { code: "04", name: "Chandigarh" },
+    uttarakhand: { code: "05", name: "Uttarakhand" },
+    haryana: { code: "06", name: "Haryana" },
+    delhi: { code: "07", name: "Delhi" },
+    rajasthan: { code: "08", name: "Rajasthan" },
+    "uttar-pradesh": { code: "09", name: "Uttar Pradesh" },
+    bihar: { code: "10", name: "Bihar" },
+    sikkim: { code: "11", name: "Sikkim" },
+    "arunachal-pradesh": { code: "12", name: "Arunachal Pradesh" },
+    nagaland: { code: "13", name: "Nagaland" },
+    manipur: { code: "14", name: "Manipur" },
+    mizoram: { code: "15", name: "Mizoram" },
+    tripura: { code: "16", name: "Tripura" },
+    meghalaya: { code: "17", name: "Meghalaya" },
+    assam: { code: "18", name: "Assam" },
+    "west-bengal": { code: "19", name: "West Bengal" },
+    jharkhand: { code: "20", name: "Jharkhand" },
+    odisha: { code: "21", name: "Odisha" },
+    chhattisgarh: { code: "22", name: "Chhattisgarh" },
+    "madhya-pradesh": { code: "23", name: "Madhya Pradesh" },
+    gujarat: { code: "24", name: "Gujarat" },
+    "dadra-nagar-haveli-daman-diu": {
+        code: "26",
+        name: "Dadra and Nagar Haveli and Daman and Diu",
+    },
+    maharashtra: { code: "27", name: "Maharashtra" },
+    karnataka: { code: "29", name: "Karnataka" },
+    goa: { code: "30", name: "Goa" },
+    lakshadweep: { code: "31", name: "Lakshadweep" },
+    kerala: { code: "32", name: "Kerala" },
+    "tamil-nadu": { code: "33", name: "Tamil Nadu" },
+    puducherry: { code: "34", name: "Puducherry" },
+    "andaman-nicobar": { code: "35", name: "Andaman and Nicobar Islands" },
+    telangana: { code: "36", name: "Telangana" },
+    "andhra-pradesh": { code: "37", name: "Andhra Pradesh" },
+    ladakh: { code: "38", name: "Ladakh" },
+};
+/**
+ * Every alternative spelling we accept, mapped to the canonical key.
+ *
+ * Deliberately NOT exhaustive-by-guessing: each entry is a form that plausibly
+ * appears in an address field or a dropdown — the two-letter postal
+ * abbreviation, the pre-2019 names (`orissa`, `pondicherry`), and the common
+ * run-together spellings. A form that is not here resolves to `null`, which is
+ * honest; a wrong guess resolves to the WRONG STATE, which is worse than
+ * unknown. See `resolveStateKey`'s undetermined handling.
+ */
+const ALIASES = {
+    // two-letter abbreviations
+    jk: "jammu-kashmir", hp: "himachal-pradesh", pb: "punjab", ch: "chandigarh",
+    uk: "uttarakhand", ua: "uttarakhand", hr: "haryana", dl: "delhi",
+    rj: "rajasthan", up: "uttar-pradesh", br: "bihar", sk: "sikkim",
+    ar: "arunachal-pradesh", nl: "nagaland", mn: "manipur", mz: "mizoram",
+    tr: "tripura", ml: "meghalaya", as: "assam", wb: "west-bengal",
+    jh: "jharkhand", or: "odisha", od: "odisha", cg: "chhattisgarh",
+    ct: "chhattisgarh", mp: "madhya-pradesh", gj: "gujarat", mh: "maharashtra",
+    ka: "karnataka", ga: "goa", ld: "lakshadweep", kl: "kerala",
+    tn: "tamil-nadu", py: "puducherry", pondy: "puducherry",
+    an: "andaman-nicobar", tg: "telangana", ts: "telangana",
+    ap: "andhra-pradesh", la: "ladakh", dn: "dadra-nagar-haveli-daman-diu",
+    dd: "dadra-nagar-haveli-daman-diu",
+    // former / alternative names
+    orissa: "odisha",
+    pondicherry: "puducherry",
+    uttaranchal: "uttarakhand",
+    "new delhi": "delhi",
+    "nct of delhi": "delhi",
+    "national capital territory of delhi": "delhi",
+    "jammu kashmir": "jammu-kashmir",
+    "andaman and nicobar": "andaman-nicobar",
+    "andaman nicobar islands": "andaman-nicobar",
+    "dadra and nagar haveli": "dadra-nagar-haveli-daman-diu",
+    "daman and diu": "dadra-nagar-haveli-daman-diu",
+};
+/** Collapse to a comparison form: lowercase, letters and spaces only. */
+function flatten(raw) {
+    return raw
+        .normalize("NFKD")
+        .toLowerCase()
+        .replace(/[^a-z\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Resolve any spelling — canonical key, full name, abbreviation, former name,
+ * or a two-digit GST state code — to one canonical key, or `null`.
+ *
+ * 🛑 The numeric branch runs FIRST and before any letter-stripping, because
+ * the old normaliser destroyed digits. A state held as `"29"` or as a full
+ * GSTIN (`"29ABCDE1234F1Z5"`) is a real shape in this data: `resolveSupplierIdentity`
+ * reads a store's GSTIN, and its first two characters are the authoritative
+ * place of supply for the seller — more reliable than their typed pickup
+ * address, which is what G3 is about.
+ */
+export function resolveStateKey(raw) {
+    if (!raw)
+        return null;
+    const trimmed = String(raw).trim();
+    if (!trimmed)
+        return null;
+    // A bare code, or the leading two digits of a GSTIN.
+    const codeMatch = /^(\d{2})/.exec(trimmed);
+    if (codeMatch) {
+        const code = codeMatch[1];
+        for (const [key, meta] of Object.entries(INDIA_STATES)) {
+            if (meta.code === code)
+                return key;
+        }
+        // A two-digit prefix that is not a valid state code is NOT a state.
+        return null;
+    }
+    const flat = flatten(trimmed);
+    if (!flat)
+        return null;
+    // Canonical key (hyphenated) → its flattened form is the key with spaces.
+    for (const key of Object.keys(INDIA_STATES)) {
+        if (flat === key.replace(/-/g, " "))
+            return key;
+    }
+    // Display name.
+    for (const [key, meta] of Object.entries(INDIA_STATES)) {
+        if (flat === flatten(meta.name))
+            return key;
+    }
+    // Alias table.
+    const alias = ALIASES[flat];
+    if (alias)
+        return alias;
+    /*
+     * A last resort: drop "and"/"&" joiners, which is the single most common
+     * divergence in real addresses ("Jammu and Kashmir" vs "Jammu Kashmir",
+     * "Andaman and Nicobar Islands" vs "Andaman Nicobar"). Compared against the
+     * same reduction of each display name, so it cannot match across states.
+     */
+    const noJoiners = flat.replace(/\band\b/g, " ").replace(/\s+/g, " ").trim();
+    if (noJoiners !== flat) {
+        for (const [key, meta] of Object.entries(INDIA_STATES)) {
+            const target = flatten(meta.name).replace(/\band\b/g, " ").replace(/\s+/g, " ").trim();
+            if (noJoiners === target)
+                return key;
+        }
+        const aliased = ALIASES[noJoiners];
+        if (aliased)
+            return aliased;
+    }
+    return null;
+}
+/** The GST state code for any spelling, or `null`. */
+export function resolveStateCode(raw) {
+    const key = resolveStateKey(raw);
+    return key ? INDIA_STATES[key].code : null;
+}

package/dist/_internal/shared/fees/payout-hold.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The payout hold — how long a seller's money is held after delivery, and the
+ * ONE place that number is decided.
+ *
+ * WHY: there were three payout paths and one intended hold, honoured by zero
+ *      of the three (D25).
+ *
+ *      · `weeklyPayoutEligibility` (Saturday) queried
+ *        `payoutStatus == "eligible" && status == "delivered"` with **no time
+ *        cutoff at all**, so it paid out an order delivered yesterday.
+ *      · `autoPayoutEligibility` (daily) applied a 7-day window, but computed
+ *        it with CALENDAR days while calling them business days — measured,
+ *        that reached 4 calendar days less far back than it should on a
+ *        Monday, so a "7 business day" hold was really about 5.
+ *      · The manual seller "Request payout" (`seller-actions.ts`) had no time
+ *        check whatsoever.
+ *
+ *      And `commissions.payoutHoldDays` — the admin-facing setting that looks
+ *      like it controls all this — was read by NOTHING. It is seeded **2**,
+ *      which is the trap below.
+ *
+ * WHAT: `resolvePayoutHoldDays(commissions, returns)` → the honoured number,
+ *       and `payoutCutoff(...)` → the instant to compare an order's delivery
+ *       anchor against.
+ */
+import { type BusinessDayOptions } from "../time/business-days";
+/**
+ * The hold can never be shorter than any window during which money can still
+ * flow back OUT of the order.
+ *
+ * 🛑 WIRING `payoutHoldDays` NAIVELY MAKES THINGS WORSE, which is why this
+ * function exists rather than a bare settings read. The setting is seeded at
+ * **2 days**; the hardcoded window it would replace is **7**; and the
+ * sale-protection claim window is **7 days** (168h). So honouring the stored
+ * value as-is would *shorten* the hold from 7 to 2 and release a seller's
+ * money four days before the buyer's protection claim window even closes —
+ * i.e. we would have sold cover we had already paid out against.
+ *
+ * The floor is therefore `max(returnWindow, claimWindow)`, and the setting can
+ * only ever EXTEND it. An admin who wants a shorter hold has to shorten the
+ * return window first, which is the honest ordering of that decision.
+ */
+export declare const PAYOUT_HOLD_FLOOR_DAYS = 7;
+export interface PayoutHoldInputs {
+    /** `siteSettings.commissions` — `payoutHoldDays` is the only field read. */
+    payoutHoldDays?: number;
+    /** `siteSettings.returns.windowDays` — the buyer's return window. */
+    returnWindowDays?: number;
+    /** Longest protection claim window in HOURS, if protections are enabled. */
+    maxClaimWindowHours?: number;
+}
+export interface ResolvedPayoutHold {
+    /** Business days actually honoured. */
+    days: number;
+    /** Which input won, so a log line can say why. */
+    source: "setting" | "floor";
+    /** The floor that applied, for the same reason. */
+    floor: number;
+}
+/**
+ * Resolve the honoured hold.
+ *
+ * Returns the SOURCE as well as the number, deliberately: a hold silently
+ * raised from the admin's configured 2 to a floor of 7 reads as a bug to
+ * whoever set it, so the job logs which one applied rather than leaving the
+ * seller and the admin to disagree about it.
+ */
+export declare function resolvePayoutHoldDays(inputs: PayoutHoldInputs): ResolvedPayoutHold;
+/**
+ * The cutoff instant: an order whose delivery anchor is at or before this is
+ * past its hold.
+ *
+ * 🛑 BUSINESS days, via `businessDayCutoff` — weekends and the Indian holiday
+ * list. The previous implementation subtracted calendar days, so every hold
+ * spanning a weekend released early.
+ */
+export declare function payoutCutoff(inputs: PayoutHoldInputs, opts?: BusinessDayOptions, now?: Date): {
+    cutoff: Date;
+    hold: ResolvedPayoutHold;
+};