@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/shared/fees/payout-hold.js

@@ -0,0 +1,74 @@
+/**
+ * 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 { businessDayCutoff, } from "../time/business-days.js";
+/**
+ * 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 const PAYOUT_HOLD_FLOOR_DAYS = 7;
+/**
+ * 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 function resolvePayoutHoldDays(inputs) {
+    const claimDays = inputs.maxClaimWindowHours
+        ? Math.ceil(inputs.maxClaimWindowHours / 24)
+        : 0;
+    const floor = Math.max(PAYOUT_HOLD_FLOOR_DAYS, inputs.returnWindowDays ?? 0, claimDays);
+    const configured = inputs.payoutHoldDays;
+    if (typeof configured === "number" && Number.isFinite(configured) && configured > floor) {
+        return { days: Math.floor(configured), source: "setting", floor };
+    }
+    return { days: floor, source: "floor", floor };
+}
+/**
+ * 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 function payoutCutoff(inputs, opts, now) {
+    const hold = resolvePayoutHoldDays(inputs);
+    return { cutoff: businessDayCutoff(hold.days, opts, now), hold };
+}

package/dist/_internal/shared/obligations/deadlines.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `deadlinesFor(order)` — every deadline an order currently owes, derived.
+ *
+ * ## Pure, so a page can render it for free
+ *
+ * No reads, no writes, no `obligations` lookup. A buyer or seller page calls
+ * this on an order it already has and renders "Dispatch by Thu 3 Nov".
+ *
+ * 🛑 That is why deadlines are DERIVED rather than stored on the order. A
+ * stored `dispatchDueAt` would need a backfill for every existing order, and
+ * would drift from the policy the moment an admin changed the duration — the
+ * denormalised-mirror trap (Root Cause #42). The `obligations` collection
+ * stores one too, and that copy is explicitly a due-date INDEX for the sweep
+ * to query, not the answer.
+ *
+ * ## Test-window compression is PER SUBJECT
+ *
+ * 🛑 A tester run must be able to watch a 3-day acceptance window close inside
+ * a 90-minute session, and a hard-coded duration cannot be shortened — which is
+ * what made those cases untestable in any run shorter than the literal. So
+ * durations scale by `TESTER_WINDOW_MINUTES`, but **only when the subject
+ * itself carries `isTestData: true`.** A global switch would compress every
+ * live buyer's deadline the moment somebody ran the tester, which is the one
+ * mistake this must not make.
+ */
+import { type Duration, type ObligationPolicy } from "../../../features/obligations/constants/policies";
+import { type ObligationKind } from "../../../features/obligations/schemas/firestore";
+import type { OrderDocument } from "../../../features/orders/schemas/firestore";
+export interface ResolvedDeadline {
+    kind: ObligationKind;
+    dueAt: Date;
+    /** The fact the clock started from. */
+    anchoredAt: Date;
+    policy: ObligationPolicy;
+}
+/**
+ * Resolve one duration into an absolute date.
+ *
+ * 🛑 `business` goes through `addBusinessDays`, which counts weekends AND the
+ * Indian holiday calendar. The predecessor helper subtracted CALENDAR days and
+ * called them business days, so the "7-business-day" payout hold was really
+ * about 5 — and a missed holiday silently SHORTENS a deadline, which is why
+ * the calendar has an owner and a horizon warning.
+ */
+export declare function resolveDueAt(anchor: Date, duration: Duration, opts?: {
+    isTestData?: boolean;
+}): Date;
+/**
+ * Every deadline this order currently owes.
+ *
+ * Only kinds whose `precondition` holds AND whose `anchor` has fired appear —
+ * an order that has not shipped owes no delivery confirmation, and that is the
+ * difference between "not yet" and "overdue".
+ */
+export declare function deadlinesFor(order: OrderDocument): ResolvedDeadline[];
+/**
+ * Which obligations this order should have open, and which should be closed.
+ *
+ * Called from the order's own write (`updateWithHistory`), where the current
+ * document is already in hand — so reconciling costs **zero extra reads**.
+ *
+ * 🛑 Derived from the POLICY's own `precondition`, not from a hand-written
+ * `Record<OrderStatus, {opens, closes}>` table.
+ *
+ * The plan proposed that table, and building it this way instead is a
+ * deliberate departure worth stating: a status→opens/closes map is a SECOND
+ * encoding of the same facts the preconditions already express, and the two
+ * would drift exactly as the plan's own proposed transition map had already
+ * drifted from the census (it omitted `pending → processing`, which a live
+ * sweep writes). One source, evaluated twice — once for display, once for
+ * reconciliation — cannot disagree with itself.
+ */
+export declare function reconcileObligations(order: OrderDocument, 
+/**
+ * The order as it was BEFORE this write, when the caller has it.
+ *
+ * 🛑 THIS PARAMETER IS A COST FIX, not an optimisation. My first version
+ * closed "every kind not currently open", which on an 11-kind union meant
+ * **11 Firestore update attempts on every single order write** — each one a
+ * billed write against a document that mostly does not exist, on the hottest
+ * collection in the project. Rule #6 exists for exactly that.
+ *
+ * With `previous` in hand the close set is `was-open MINUS is-open`, which is
+ * usually empty and never larger than the number of obligations that
+ * genuinely just completed. Zero reads either way, because `updateWithHistory`
+ * already holds the pre-write document.
+ *
+ * Omitting it falls back to the full set, which is correct for a deliberate
+ * backfill over existing orders and wrong for the write path.
+ */
+previous?: OrderDocument | null): {
+    open: ResolvedDeadline[];
+    close: ObligationKind[];
+};

package/dist/_internal/shared/obligations/deadlines.js

@@ -0,0 +1,155 @@
+/**
+ * `deadlinesFor(order)` — every deadline an order currently owes, derived.
+ *
+ * ## Pure, so a page can render it for free
+ *
+ * No reads, no writes, no `obligations` lookup. A buyer or seller page calls
+ * this on an order it already has and renders "Dispatch by Thu 3 Nov".
+ *
+ * 🛑 That is why deadlines are DERIVED rather than stored on the order. A
+ * stored `dispatchDueAt` would need a backfill for every existing order, and
+ * would drift from the policy the moment an admin changed the duration — the
+ * denormalised-mirror trap (Root Cause #42). The `obligations` collection
+ * stores one too, and that copy is explicitly a due-date INDEX for the sweep
+ * to query, not the answer.
+ *
+ * ## Test-window compression is PER SUBJECT
+ *
+ * 🛑 A tester run must be able to watch a 3-day acceptance window close inside
+ * a 90-minute session, and a hard-coded duration cannot be shortened — which is
+ * what made those cases untestable in any run shorter than the literal. So
+ * durations scale by `TESTER_WINDOW_MINUTES`, but **only when the subject
+ * itself carries `isTestData: true`.** A global switch would compress every
+ * live buyer's deadline the moment somebody ran the tester, which is the one
+ * mistake this must not make.
+ */
+/*
+ * 🛑 `addBusinessDays` ONLY — `resolveHolidays` is module-private and takes
+ * `(startYear, endYear, opts)`, not a Date. I imported it first and it would
+ * not have compiled; `addBusinessDays` already resolves the holiday set
+ * internally for every year the window spans, so the correct call passes no
+ * holiday argument at all.
+ */
+import { addBusinessDays } from "../time/business-days.js";
+import { OBLIGATION_POLICIES, durationToMinutes, } from "../../../features/obligations/constants/policies.js";
+import { ALL_OBLIGATION_KINDS, } from "../../../features/obligations/schemas/firestore.js";
+import { windowMinutes } from "../../../features/tester/seed-data/tester-window.js";
+/**
+ * How much a test fixture's deadlines are compressed.
+ *
+ * The real window is scaled so the LONGEST obligation (14-day delivery
+ * confirmation) still fits inside one tester window, while the shortest
+ * (24-hour proof re-upload) stays long enough to observe. Expressed as a
+ * fraction of `TESTER_WINDOW_MINUTES` per real day.
+ */
+const TEST_MINUTES_PER_REAL_DAY = 1 / 14;
+function compressForTest(minutes) {
+    const realDays = minutes / (24 * 60);
+    const scaled = realDays * windowMinutes() * TEST_MINUTES_PER_REAL_DAY;
+    /*
+     * Floored at one minute. A deadline computed as zero would fire on the same
+     * sweep tick that created it, so the tester could never observe the BEFORE
+     * state — and a case written as "before → after" needs both halves.
+     */
+    return Math.max(1, scaled);
+}
+/**
+ * Resolve one duration into an absolute date.
+ *
+ * 🛑 `business` goes through `addBusinessDays`, which counts weekends AND the
+ * Indian holiday calendar. The predecessor helper subtracted CALENDAR days and
+ * called them business days, so the "7-business-day" payout hold was really
+ * about 5 — and a missed holiday silently SHORTENS a deadline, which is why
+ * the calendar has an owner and a horizon warning.
+ */
+export function resolveDueAt(anchor, duration, opts) {
+    if (opts?.isTestData) {
+        /*
+         * A compressed fixture is always wall-clock. Business-day arithmetic on a
+         * 6-minute window is meaningless, and worse: a fixture seeded on a Friday
+         * would land its "2 business day" deadline on Tuesday regardless of
+         * compression, so the case could never run.
+         */
+        return new Date(anchor.getTime() + compressForTest(durationToMinutes(duration)) * 60000);
+    }
+    if (duration.calendar === "business" && duration.unit === "days") {
+        return addBusinessDays(anchor, duration.value);
+    }
+    return new Date(anchor.getTime() + durationToMinutes(duration) * 60000);
+}
+/**
+ * Every deadline this order currently owes.
+ *
+ * Only kinds whose `precondition` holds AND whose `anchor` has fired appear —
+ * an order that has not shipped owes no delivery confirmation, and that is the
+ * difference between "not yet" and "overdue".
+ */
+export function deadlinesFor(order) {
+    const out = [];
+    const isTestData = order.isTestData === true;
+    for (const kind of ALL_OBLIGATION_KINDS) {
+        const policy = OBLIGATION_POLICIES[kind];
+        const anchor = policy.anchor(order);
+        if (!anchor)
+            continue;
+        if (!policy.precondition(order))
+            continue;
+        out.push({
+            kind,
+            anchoredAt: anchor,
+            dueAt: resolveDueAt(anchor, policy.duration, { isTestData }),
+            policy,
+        });
+    }
+    return out.sort((a, b) => a.dueAt.getTime() - b.dueAt.getTime());
+}
+/**
+ * Which obligations this order should have open, and which should be closed.
+ *
+ * Called from the order's own write (`updateWithHistory`), where the current
+ * document is already in hand — so reconciling costs **zero extra reads**.
+ *
+ * 🛑 Derived from the POLICY's own `precondition`, not from a hand-written
+ * `Record<OrderStatus, {opens, closes}>` table.
+ *
+ * The plan proposed that table, and building it this way instead is a
+ * deliberate departure worth stating: a status→opens/closes map is a SECOND
+ * encoding of the same facts the preconditions already express, and the two
+ * would drift exactly as the plan's own proposed transition map had already
+ * drifted from the census (it omitted `pending → processing`, which a live
+ * sweep writes). One source, evaluated twice — once for display, once for
+ * reconciliation — cannot disagree with itself.
+ */
+export function reconcileObligations(order, 
+/**
+ * The order as it was BEFORE this write, when the caller has it.
+ *
+ * 🛑 THIS PARAMETER IS A COST FIX, not an optimisation. My first version
+ * closed "every kind not currently open", which on an 11-kind union meant
+ * **11 Firestore update attempts on every single order write** — each one a
+ * billed write against a document that mostly does not exist, on the hottest
+ * collection in the project. Rule #6 exists for exactly that.
+ *
+ * With `previous` in hand the close set is `was-open MINUS is-open`, which is
+ * usually empty and never larger than the number of obligations that
+ * genuinely just completed. Zero reads either way, because `updateWithHistory`
+ * already holds the pre-write document.
+ *
+ * Omitting it falls back to the full set, which is correct for a deliberate
+ * backfill over existing orders and wrong for the write path.
+ */
+previous) {
+    const shouldBeOpen = deadlinesFor(order);
+    const openKinds = new Set(shouldBeOpen.map((d) => d.kind));
+    if (previous) {
+        const wasOpen = deadlinesFor(previous).map((d) => d.kind);
+        return {
+            open: shouldBeOpen,
+            close: wasOpen.filter((k) => !openKinds.has(k)),
+        };
+    }
+    return {
+        open: shouldBeOpen,
+        close: ALL_OBLIGATION_KINDS.filter((k) => !openKinds.has(k)),
+    };
+}

package/dist/_internal/shared/shipping/quote.d.ts

@@ -114,6 +114,45 @@ export interface ShippingReconciliation {
     sellerAbsorbs: number;
     /** Points credited to the buyer, 1 point = ₹1. */
     buyerPoints: number;
+    /**
+     * Rupees the seller is REIMBURSED for postage — `min(spent, charged)`.
+     *
+     * ## 🛑 This is the D45 decision, and it applies to BOTH branches
+     *
+     * Owner, 2026-10-21: *"if seller ships on their own then they have to upload
+     * the receipt of the shipment with the tracking number so that it is paid to
+     * them directly; if they use our platform's integration (Shiprocket) they do
+     * not get the money, the platform keeps it."* Plus: reimbursement **capped at
+     * what the buyer paid**, and the saving goes to the **buyer as points**.
+     *
+     * So shipping stops being revenue to allocate and becomes a COST TO
+     * REIMBURSE. The third output completes a formula whose other two terms this
+     * function already computed from the same two inputs:
+     *
+     * ```
+     * reimbursable  = min(spent, charged)
+     * sellerAbsorbs = max(0, spent − charged)
+     * buyerPoints   = max(0, charged − spent)
+     * ```
+     *
+     * 🛑 **The platform nets exactly zero on shipping in every case**, which is
+     * the property that makes it defensible to both sides and is worth stating as
+     * an invariant rather than leaving to be inferred:
+     *
+     * | buyer paid | receipt | seller gets | buyer gets | platform |
+     * |---|---|---|---|---|
+     * | ₹120 | ₹80 | ₹80 | ₹40 points | **₹0** |
+     * | ₹80 | ₹120 | ₹80 | — | **₹0** |
+     * | ₹100 | ₹100 | ₹100 | — | **₹0** |
+     *
+     * It is computed here for every order rather than only on the self-shipped
+     * branch, because today the platform keeps shipping in the QUOTED path too —
+     * so this is the fix for both, not a new rule for one. Whether it is actually
+     * PAID is gated separately: a Shiprocket-booked parcel was paid for by us, so
+     * `reimbursable` must not reach the payout base there. See
+     * `isReimbursableShipment`.
+     */
+    reimbursable: number;
     /** True when the seller shipped with a courier the buyer did not choose. */
     courierChanged: boolean;
 }
@@ -133,6 +172,63 @@ export interface ShippingReconciliation {
  * buyer's (rounding down).
  */
 export declare function reconcileShipping(quote: Pick<SelectedShippingQuote, "chargedRate" | "courierId">, actual: ActualShipmentCost): ShippingReconciliation;
+/**
+ * May this order's postage be reimbursed to the seller at all?
+ *
+ * ## 🛑 Gated on WHO BOOKED, never on whether a receipt exists
+ *
+ * Owner's rule: a seller who ships themselves is paid the approved amount on
+ * proof; a seller who uses our Shiprocket integration gets nothing, because we
+ * already paid the courier.
+ *
+ * Testing for a receipt instead would be the exploitable version — a seller
+ * could upload a receipt for a parcel the platform paid for and be reimbursed
+ * for someone else's spend. The discriminator has to be the booking, which is
+ * a fact about how the shipment was created and not something the claimant
+ * supplies.
+ *
+ * ## 🛑 It fails OPEN on an unknown booker, and the previous docstring claimed
+ * the opposite
+ *
+ * That text read: *"It returns FALSE when the booker is unknown, and that
+ * direction is deliberate: paying out on an unverified premise is the error
+ * that cannot be undone."* **The code has always returned TRUE.** Corrected
+ * 2026-10-21 — the code is right and the comment was wrong, which is the
+ * dangerous way round: a reader trusted a safety property that was not there.
+ *
+ * Fail-open is correct here because **nothing writes
+ * `platformBookedShipment`.** A self-shipped parcel has no flag to set, so a
+ * fail-closed gate would refuse every seller and the reimbursement feature
+ * would be entirely dead. Absence means "self-shipped", which is the common
+ * case, and the real protection on that path is the evidence-plus-approval
+ * step — a seller is paid the amount an admin approves from an uploaded
+ * receipt, never an amount they assert.
+ *
+ * ## 🛑 THE GATE IS THEREFORE INERT, and that is a prerequisite, not a bug
+ *
+ * Measured 2026-10-21: `platformBookedShipment` has ZERO writers — only this
+ * declaration, the `ShippingReconciliation` field and the order schema. The
+ * exposure is nil **today** because nothing creates a platform booking either:
+ * `ShiprocketShippingProvider` is registered in `providers.config.ts` but
+ * nothing calls its `createShipment`.
+ *
+ * So the day that booking path is wired, THE SAME COMMIT must write this flag.
+ * Otherwise the gate fails open on a parcel the platform paid for and the
+ * seller is reimbursed for our spend — the exact double-payment this function
+ * exists to prevent.
+ *
+ * Gated on WHO BOOKED rather than on whether a receipt exists, because testing
+ * for a receipt is the exploitable version: a seller could upload a receipt for
+ * a parcel the platform paid for. The discriminator has to be a fact about how
+ * the shipment was created, not something the claimant supplies — which is
+ * also why this function deliberately does NOT look at
+ * `shippingReimbursement`. That parameter was accepted and never read, and an
+ * unread parameter invites exactly the misuse it was meant to forbid, so it is
+ * gone.
+ */
+export declare function isReimbursableShipment(order: {
+    platformBookedShipment?: boolean;
+}): boolean;
 /**
  * Turn carrier serviceability results into offerable options.
  *

package/dist/_internal/shared/shipping/quote.js

@@ -82,9 +82,76 @@ export function reconcileShipping(quote, actual) {
     return {
         sellerAbsorbs: delta < 0 ? Math.abs(delta) : 0,
         buyerPoints: delta > 0 ? delta : 0,
+        /*
+         * `min(spent, charged)` — capped at what the buyer paid, per the owner's
+         * decision. Rounded through the same helper as the others: a bare
+         * `Math.min` of two 2dp figures is safe, but keeping all three terms on one
+         * rounding path is what stops `reimbursable + buyerPoints` drifting a paisa
+         * away from `charged`, which is the invariant an auditor would check.
+         */
+        reimbursable: roundMoney(Math.min(spent, charged)),
         courierChanged: quote.courierId !== actual.courierId,
     };
 }
+/**
+ * May this order's postage be reimbursed to the seller at all?
+ *
+ * ## 🛑 Gated on WHO BOOKED, never on whether a receipt exists
+ *
+ * Owner's rule: a seller who ships themselves is paid the approved amount on
+ * proof; a seller who uses our Shiprocket integration gets nothing, because we
+ * already paid the courier.
+ *
+ * Testing for a receipt instead would be the exploitable version — a seller
+ * could upload a receipt for a parcel the platform paid for and be reimbursed
+ * for someone else's spend. The discriminator has to be the booking, which is
+ * a fact about how the shipment was created and not something the claimant
+ * supplies.
+ *
+ * ## 🛑 It fails OPEN on an unknown booker, and the previous docstring claimed
+ * the opposite
+ *
+ * That text read: *"It returns FALSE when the booker is unknown, and that
+ * direction is deliberate: paying out on an unverified premise is the error
+ * that cannot be undone."* **The code has always returned TRUE.** Corrected
+ * 2026-10-21 — the code is right and the comment was wrong, which is the
+ * dangerous way round: a reader trusted a safety property that was not there.
+ *
+ * Fail-open is correct here because **nothing writes
+ * `platformBookedShipment`.** A self-shipped parcel has no flag to set, so a
+ * fail-closed gate would refuse every seller and the reimbursement feature
+ * would be entirely dead. Absence means "self-shipped", which is the common
+ * case, and the real protection on that path is the evidence-plus-approval
+ * step — a seller is paid the amount an admin approves from an uploaded
+ * receipt, never an amount they assert.
+ *
+ * ## 🛑 THE GATE IS THEREFORE INERT, and that is a prerequisite, not a bug
+ *
+ * Measured 2026-10-21: `platformBookedShipment` has ZERO writers — only this
+ * declaration, the `ShippingReconciliation` field and the order schema. The
+ * exposure is nil **today** because nothing creates a platform booking either:
+ * `ShiprocketShippingProvider` is registered in `providers.config.ts` but
+ * nothing calls its `createShipment`.
+ *
+ * So the day that booking path is wired, THE SAME COMMIT must write this flag.
+ * Otherwise the gate fails open on a parcel the platform paid for and the
+ * seller is reimbursed for our spend — the exact double-payment this function
+ * exists to prevent.
+ *
+ * Gated on WHO BOOKED rather than on whether a receipt exists, because testing
+ * for a receipt is the exploitable version: a seller could upload a receipt for
+ * a parcel the platform paid for. The discriminator has to be a fact about how
+ * the shipment was created, not something the claimant supplies — which is
+ * also why this function deliberately does NOT look at
+ * `shippingReimbursement`. That parameter was accepted and never read, and an
+ * unread parameter invites exactly the misuse it was meant to forbid, so it is
+ * gone.
+ */
+export function isReimbursableShipment(order) {
+    if (order.platformBookedShipment === true)
+        return false;
+    return true;
+}
 /**
  * Two decimal places.
  *

package/dist/_internal/shared/time/business-days.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Business-day arithmetic for India, with an admin-maintained holiday list.
+ *
+ * WHY: every deadline in the order lifecycle that matters commercially is
+ *      quoted in *business* days — the payout hold, the seller dispatch
+ *      window, the return-response window, the inspection window. Before this
+ *      module the only implementation was `getBusinessDayCutoff` in
+ *      `autoPayoutEligibility.ts`, which did this:
+ *
+ *        cutoff.setUTCDate(cutoff.getUTCDate() - daysAgo)
+ *
+ *      i.e. it subtracted CALENDAR days and called them business days. A
+ *      7-"business"-day hold computed on a Monday reached back to the previous
+ *      Monday — 5 business days, not 7 — so every payout over a weekend was
+ *      released two business days early, in the seller's favour, with no
+ *      record that the stated hold had not been honoured.
+ *
+ * WHAT: `addBusinessDays` / `subBusinessDays` / `isBusinessDay` /
+ *       `businessDaysBetween`, all operating on IST calendar days and all
+ *       taking the holiday list as an explicit parameter.
+ *
+ * 🛑 A MISSED HOLIDAY SILENTLY SHORTENS A DEADLINE. There is no error, no
+ * log, and nothing to notice — the hold simply releases a day early. So the
+ * list below needs an owner and a review before each financial year; it is
+ * not fire-and-forget config. That hazard is the reason the list is DATA
+ * (admin-editable, see `resolveHolidays`) rather than a constant someone has
+ * to ship a release to change.
+ */
+/**
+ * 🛑 IST, not UTC, and this is not a preference.
+ *
+ * A business day is a property of the *place the business operates in*. India
+ * is UTC+5:30, so 23:00 UTC on a Friday is already Saturday morning in
+ * Mumbai. Computing weekends in UTC therefore misclassifies a 5.5-hour band
+ * at the edge of every single day — which is 23% of a working Friday evening
+ * treated as a working day when the office is shut, and the inverse on Sunday
+ * night.
+ *
+ * The old helper's `setUTCHours(4, 30, 0, 0)` was reaching for exactly this
+ * (04:30 UTC = 10:00 IST) without saying so. Making the offset explicit is
+ * what lets the weekend test be correct rather than approximately correct.
+ */
+import type { JsonValue } from "../../../schemas/types";
+/** `YYYY-MM-DD` in IST. The key format the holiday list uses. */
+export declare function toIstDateKey(d: Date): string;
+/**
+ * Indian public holidays on which we do not count a business day.
+ *
+ * Deliberately NARROW: only the days on which banking and courier movement
+ * genuinely stop nationwide. A regional festival that closes one state's
+ * offices is not here, because treating it as a national holiday would
+ * *lengthen* every seller's deadline across the country — and unlike a missed
+ * holiday, that error is invisible in the seller's favour and compounds.
+ *
+ * 🛑 Dates are LITERAL, never computed. Several of these move year to year
+ * (they follow lunar calendars), so a formula would be wrong rather than
+ * stale — and stale is detectable while wrong is not. Entries end at the last
+ * declared year on purpose: `resolveHolidays` warns past that horizon instead
+ * of silently treating an unlisted Diwali as a working day.
+ */
+export declare const INDIA_HOLIDAYS_BY_YEAR: Readonly<Record<number, readonly string[]>>;
+/** The last year with a curated list — past this, `resolveHolidays` warns. */
+export declare const HOLIDAY_HORIZON_YEAR: number;
+export interface BusinessDayOptions {
+    /**
+     * Extra closure dates (`YYYY-MM-DD`, IST), from
+     * `siteSettings.platformLimits.businessHolidays` once that field exists.
+     * Merged with the built-in list rather than replacing it, so an admin
+     * cannot accidentally delete Independence Day by saving an empty field.
+     */
+    extraHolidays?: readonly string[];
+    /** Injected for the warning path; defaults to no-op so pure callers stay pure. */
+    onWarn?: (message: string, meta?: Record<string, JsonValue>) => void;
+}
+/** Saturday/Sunday in IST, or a listed holiday. */
+export declare function isBusinessDay(d: Date, holidays: ReadonlySet<string>): boolean;
+/** A deadline: `count` business days after `start`. */
+export declare function addBusinessDays(start: Date, count: number, opts?: BusinessDayOptions): Date;
+/** A cutoff: `count` business days before `start`. */
+export declare function subBusinessDays(start: Date, count: number, opts?: BusinessDayOptions): Date;
+/**
+ * The cutoff instant for "delivered at least `days` business days ago".
+ *
+ * Normalised to **10:00 IST** on the cutoff day, which is what the old helper's
+ * unexplained `setUTCHours(4, 30)` meant. It matters: without a fixed
+ * time-of-day the cutoff drifts with the hour the job happens to run, so an
+ * order can be eligible on one run and not the next.
+ */
+export declare function businessDayCutoff(days: number, opts?: BusinessDayOptions, now?: Date): Date;
+/** Inclusive-of-neither count of business days in `[from, to)`. */
+export declare function businessDaysBetween(from: Date, to: Date, opts?: BusinessDayOptions): number;