@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/_internal/shared/checkout/order-math.js

@@ -1,5 +1,5 @@
 import { roundRupees } from "../../../utils/number.formatter";
-import { calculateGst } from "../fees/calculator";
+import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator";
 /**
  * The single source of truth for "what do we charge for ONE COPY of this line".
  *
@@ -88,7 +88,22 @@ export function lineTotalFor(item, product) {
  * `productById` supplies the live `gstRate`; each member's snapshotted rate is
  * the fallback for a member whose listing has since been archived.
  */
-export function lineTaxComponentsFor(item, productById) {
+export function lineTaxComponentsFor(item, 
+/*
+ * Tolerates a null value, and always did — every read below is
+ * `?.gstRate ?? 0` / `?? null`. The type was merely narrower than the
+ * behaviour, which forced the consumer's create-order route (whose
+ * `findById` map is honestly `| null`) to cast. `lineTotalFor` already
+ * declares `ProductDocument | null` for the same reason.
+ *
+ * 🛑 Caveat worth knowing: a MISSING product yields `gstRate ?? 0`, and
+ * since 2026-10-10 a 0 rate is accumulated into `exemptAmount` — so an
+ * unloadable product would be reported as exempt rather than as unknown.
+ * Every caller validates products before reaching here (the route throws on
+ * a missing or unpublished one), so this is theoretical; it would stop being
+ * theoretical if a caller ever skipped that check.
+ */
+productById) {
     const lineTotal = lineTotalFor(item, productById.get(item.productId) ?? null);
     const members = item.groupMembers;
     if (!members?.length) {
@@ -128,18 +143,94 @@ export function lineTaxComponentsFor(item, productById) {
  * one and not the other — here that would mean quoting one tax figure and
  * charging another.
  */
-export function sumGroupGst(items, productById, intraState) {
+export function sumGroupGst(items, 
+/* `| null` to match `lineTaxComponentsFor` and `lineTotalFor` — see the note
+ * there. The consumer's create-order route holds an honestly-nullable map. */
+productById, intraState) {
     let taxableAmount = 0;
+    let exemptAmount = 0;
+    let cgst = 0;
+    let sgst = 0;
+    let igst = 0;
     let gstAmount = 0;
+    const byRate = new Map();
     for (const item of items) {
         for (const slice of lineTaxComponentsFor(item, productById)) {
-            if (slice.gstRate <= 0)
+            /*
+             * 🛑 A 0%-rated slice is EXEMPT, not absent. It was `continue`d
+             * entirely, so `order.taxableAmount` excluded exempt goods while
+             * `items[]` included them — and no mixed exempt/taxed order could ever
+             * reconcile its own Taxable column against its own summary. It is
+             * accumulated separately instead: representable, without inflating the
+             * base the tax was actually charged on.
+             */
+            if (slice.gstRate <= 0) {
+                exemptAmount += slice.taxable;
                 continue;
-            taxableAmount += slice.taxable;
-            gstAmount += calculateGst(slice.gstRate, intraState, slice.taxable).gstAmount;
+            }
+            /*
+             * 🛑 `slice.taxable` is the line's GROSS share — prices are
+             * tax-INCLUSIVE — so the tax is backed OUT of it, never added on top.
+             * `lineTaxComponentsFor`'s documented invariant ("slices of a line sum
+             * to its line total") stays true of the gross, which is why the
+             * back-out lives here rather than in there.
+             *
+             * ₹999 @ 5% → taxable ₹951.43 + tax ₹47.57 = ₹999.00 exactly.
+             *
+             * `calculateGstInclusive`, not `calculateGst(…, taxableFromInclusive(…))`:
+             * that composition rounds twice and came to ₹999.01, so the invoice
+             * stopped reconciling with the amount charged. Under inclusive pricing
+             * the tax is a PARTITION of a fixed amount, not an addition to it.
+             */
+            const b = calculateGstInclusive(slice.gstRate, intraState, slice.taxable);
+            const slabTaxable = b.taxableAmount;
+            /*
+             * The split comes PER SLICE and is accumulated. `createOrderForGroup`
+             * used to re-derive it from the total with `Math.round(gstAmount / 2)` —
+             * whole rupees, so ₹161.82 split to 81.00/80.82 instead of 80.91/80.91,
+             * and ₹0.52 rounded to 0 and then `|| undefined` dropped the CGST line
+             * off the invoice entirely.
+             */
+            taxableAmount += slabTaxable;
+            cgst += b.cgst;
+            sgst += b.sgst;
+            igst += b.igst;
+            gstAmount += b.gstAmount;
+            /*
+             * Per-rate, because Rule 46 wants taxable value and tax PER RATE on the
+             * invoice. A mixed 5%+18% order cannot produce a compliant document from
+             * one aggregate triple, and re-deriving it downstream means a second
+             * implementation of this loop.
+             */
+            const prev = byRate.get(slice.gstRate);
+            if (prev) {
+                prev.taxableAmount = roundRupees(prev.taxableAmount + slabTaxable);
+                prev.cgst = roundRupees(prev.cgst + b.cgst);
+                prev.sgst = roundRupees(prev.sgst + b.sgst);
+                prev.igst = roundRupees(prev.igst + b.igst);
+                prev.gstAmount = roundRupees(prev.gstAmount + b.gstAmount);
+            }
+            else {
+                byRate.set(slice.gstRate, {
+                    gstRate: slice.gstRate,
+                    taxableAmount: roundRupees(slabTaxable),
+                    cgst: b.cgst,
+                    sgst: b.sgst,
+                    igst: b.igst,
+                    gstAmount: b.gstAmount,
+                });
+            }
         }
     }
-    return { taxableAmount, gstAmount };
+    return {
+        taxableAmount: roundRupees(taxableAmount),
+        exemptAmount: roundRupees(exemptAmount),
+        cgst: roundRupees(cgst),
+        sgst: roundRupees(sgst),
+        igst: roundRupees(igst),
+        gstAmount: roundRupees(gstAmount),
+        byRate: [...byRate.values()].sort((x, y) => x.gstRate - y.gstRate),
+    };
 }
 /**
  * Split `total` across members in proportion to their list prices, with the
@@ -166,6 +257,102 @@ export function allocateAcrossMembers(total, weights) {
     out.push(roundRupees(total - running));
     return out;
 }
+/**
+ * The GOODS VALUE of an order — the only correct base for a seller payout.
+ *
+ * 🛑 This is NOT `OrderDocument.totalPrice`, and conflating the two was a live
+ * money bug in all four payout paths (`autoPayoutEligibility`,
+ * `weeklyPayoutEligibility`, and both `seller-actions` entry points). That
+ * field is the GRAND TOTAL — `checkout/actions.ts` builds it as
+ * `goods − coupon + shipping + codHandling + whatsappNotify + giftWrap +
+ * shipmentProtection + platformFee + platformFeeGst + emiSurcharge + gstAmount`
+ * — so using it as the payout base did three wrong things at once:
+ *
+ *  1. **paid the seller the GST we collected** and must remit ourselves;
+ *  2. **took the platform fee twice** — the buyer already paid it as a term of
+ *     `totalPrice`, and `computePayoutDeduction` then charged the seller a
+ *     percentage of a figure that already included it;
+ *  3. **computed every percentage on an inflated base**, since shipping, COD
+ *     handling, add-on fees and the EMI surcharge were all inside it.
+ *
+ * The payout base is the **taxable value**, never the gross. That one sentence
+ * also covers GST-inclusive pricing: an inclusive ₹999 @5% backs out to a
+ * ₹951.43 taxable value and that is what is paid, while an exclusive ₹999
+ * charges the buyer ₹1,048.95 and pays ₹999.
+ *
+ * 🛑 Computed from `quantity − cancelledQuantity`, NOT from `item.totalPrice`.
+ * A partial cancellation sets `cancelledQuantity: item.quantity` and
+ * **deliberately leaves `totalPrice` untouched** (`order-actions.ts:97-106`),
+ * so summing `totalPrice` would pay the seller in full for lines the buyer
+ * cancelled. `stock-restore.ts:20` already derives the live quantity this way.
+ *
+ * 🛑 Falls back to the FLAT `quantity × unitPrice` when `items` is absent.
+ * `items?` is optional on `OrderDocument` and the flat fields are the primary
+ * shape, not legacy residue — a bare `Σ items[]` would silently pay **zero**
+ * on any flat-shaped order, which is indistinguishable from "this seller is
+ * owed nothing".
+ */
+export function orderGoodsValue(order) {
+    const items = order.items;
+    if (items?.length) {
+        const raw = items.reduce((sum, i) => {
+            const live = Math.max(0, i.quantity - (i.cancelledQuantity ?? 0));
+            return sum + live * i.unitPrice;
+        }, 0);
+        return roundRupees(raw);
+    }
+    return roundRupees((order.quantity ?? 0) * (order.unitPrice ?? 0));
+}
+/** Sum of `orderGoodsValue` across orders — the GROSS, not the payout base. */
+export function ordersGoodsValue(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderGoodsValue(o), 0));
+}
+/**
+ * The TAXABLE VALUE of an order — **the payout base.**
+ *
+ * 🛑 This is the second of two narrowings, and the distinction between them is
+ * worth keeping straight:
+ *
+ *  - C0 established the base is the **goods value**, not the order grand total
+ *    (which folded in GST, the platform fee the buyer already paid, shipping,
+ *    COD handling, add-ons and the EMI surcharge).
+ *  - This establishes it is the **taxable value**, not the gross goods value —
+ *    because every price here is tax-INCLUSIVE, so the goods value still has
+ *    our GST sitting inside it, and paying that out is the very thing C0 set
+ *    out to stop.
+ *
+ * The second narrowing was not possible until the pricing model was settled:
+ * under the old add-on-top math the goods value WAS the taxable value, so the
+ * two were indistinguishable and C0's fix was complete as written.
+ *
+ * One sentence covers both seller modes, which is the reason the flag is an
+ * authoring convenience and nothing more:
+ *
+ *   **the payout base is the taxable value, never the gross.**
+ *
+ *   - inclusive seller, ₹999 @5% → buyer pays ₹999, taxable ₹951.43, payout ₹951.43
+ *   - exclusive seller types ₹999 → grossed up on write to ₹1,048.95, buyer
+ *     pays ₹1,048.95, taxable ₹999.00, payout ₹999.00
+ *
+ * Per ITEM, using each line's own snapshotted `gstRate`: a mixed 5% + 18%
+ * order cannot be backed out with a single blended rate, and an order-level
+ * rate does not exist.
+ */
+export function orderTaxableValue(order) {
+    const items = order.items;
+    if (items?.length) {
+        const raw = items.reduce((sum, i) => {
+            const live = Math.max(0, i.quantity - (i.cancelledQuantity ?? 0));
+            return sum + taxableFromInclusive(live * i.unitPrice, i.gstRate ?? 0);
+        }, 0);
+        return roundRupees(raw);
+    }
+    return taxableFromInclusive((order.quantity ?? 0) * (order.unitPrice ?? 0), order.gstRate ?? 0);
+}
+/** Sum of `orderTaxableValue` across orders — the payout base for a batch. */
+export function ordersTaxableValue(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderTaxableValue(o), 0));
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/features/categories/price-guidance.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Price guidance, stated on the basis the SELLER is typing in.
+ *
+ * `CategoryPriceGuidance` is advisory — it renders as a hint beside the price
+ * input and is never written to `price`. This module answers the one question
+ * that hint cannot be rendered without: **inclusive of what?**
+ *
+ * ## The invariant
+ *
+ * 🛑 **Every figure in a guidance band is TAX-INCLUSIVE.** Both halves, for
+ * different reasons, and neither is a choice we get to make:
+ *
+ *   `market` — competitor ASKS. An Indian storefront's displayed price is
+ *              inclusive by market convention, and worldhobbyshop asserts it
+ *              outright in its own JSON-LD (`valueAddedTaxIncluded: true`).
+ *   `sold`   — our own completed sales, derived from `items[].unitPrice`, and
+ *              every stored price in this system is tax-inclusive.
+ *
+ * So the basis is a documented property of the data rather than a per-row
+ * field. A `basis: "inclusive"` column whose every value is the same string is
+ * a field that cannot answer a question, and the first row to carry the other
+ * value would be a bug rather than a variant.
+ *
+ * ## Why the hint still has to say so
+ *
+ * A seller with `pricesIncludeGst: false` types EX-TAX numbers. Their ₹999 and
+ * an inclusive ₹999 band are **different quantities** — comparing them is off
+ * by the rate, silently, in the direction that makes their listing look
+ * cheaper than the market when it is dearer. The hint therefore converts the
+ * band into the seller's own basis and labels which one it is on.
+ *
+ * Pure arithmetic and strings. No React, no Firestore.
+ */
+import type { CategoryPriceGuidance } from "../../../../features/categories/schemas/category-content";
+/**
+ * The basis every stored and crawled guidance figure is on.
+ *
+ * Exported as a named constant so the claim is greppable from the places that
+ * depend on it, and so a future change is one edit rather than an archaeology
+ * exercise across the renderer, the seed helper and the rollup job.
+ */
+export declare const PRICE_GUIDANCE_TAX_BASIS: "inclusive";
+export interface PriceGuidanceBasis {
+    /**
+     * How the seller types prices — `StoreDocument.pricesIncludeGst`.
+     *
+     * 🛑 ABSENT means `true`, matching the schema default and the store route's
+     * `?? true`. Three places now agree on that reading; a fourth that treated
+     * absence as `false` would convert a band for a seller who never asked.
+     */
+    sellerIncludesGst?: boolean;
+    /**
+     * The rate that will be written onto this listing, resolved the same way
+     * `deriveTaxonomy` resolves it (product → category tax code → default).
+     *
+     * `0` is a deliberate exemption and `undefined` is "we could not resolve
+     * one" — and the two must not be collapsed here any more than anywhere else
+     * in this codebase. See `describePriceGuidanceBasis`.
+     */
+    gstRate?: number;
+}
+/**
+ * One guidance amount, restated on the seller's basis.
+ *
+ * Inclusive seller, exempt item, or an unresolved rate → unchanged. The last
+ * of those is deliberate: converting at `DEFAULT_GST_RATE` would be a guess
+ * presented as arithmetic, and the label says so instead.
+ */
+export declare function priceGuidanceAmountOnSellerBasis(amount: number, basis: PriceGuidanceBasis): number;
+/** The inverse — a seller's typed figure, restated as the band's basis. */
+export declare function sellerAmountOnGuidanceBasis(amount: number, basis: PriceGuidanceBasis): number;
+/**
+ * The whole guidance object, restated on the seller's basis.
+ *
+ * 🛑 `sampleSize`, `windowDays`, `soldOutShare` and `asOf` are NOT money and
+ * pass through untouched. Mapping every numeric field would silently divide a
+ * sample size by 1.05 — the kind of defect that produces a plausible number
+ * nobody can trace, which is the failure mode this plan keeps finding.
+ */
+export declare function priceGuidanceOnSellerBasis(guidance: CategoryPriceGuidance, basis: PriceGuidanceBasis): CategoryPriceGuidance;
+/** What the hint must say about which basis its figures are on. */
+export interface PriceGuidanceBasisNote {
+    /** A short suffix for the figures themselves — "incl. GST", "before GST". */
+    suffix: string;
+    /**
+     * The longer explanation, or `null` when there is nothing worth saying.
+     *
+     * `null` for the common case — an inclusive seller on a taxed item is
+     * already comparing like with like, so a sentence telling them so is noise
+     * that trains people to stop reading hints.
+     */
+    note: string | null;
+    /** True when the figures were restated rather than shown as stored. */
+    converted: boolean;
+}
+/**
+ * Four cases, and the fourth is the one worth having this function for.
+ *
+ * | seller basis | rate        | figures   | says |
+ * |---|---|---|---|
+ * | inclusive    | > 0         | unchanged | "incl. GST" |
+ * | exclusive    | > 0         | CONVERTED | "before GST", and that it was converted |
+ * | either       | 0           | unchanged | nothing about tax — an exempt item has none |
+ * | exclusive    | unresolved  | unchanged | 🛑 that they are NOT comparable |
+ *
+ * 🛑 The exempt case must not say "incl. GST". The figure is a bare amount and
+ * claiming a tax basis on it is false — which is precisely the lie the seller
+ * form's old `?? 0` default told on every listing before C0c defect 6.
+ */
+export declare function describePriceGuidanceBasis(basis: PriceGuidanceBasis): PriceGuidanceBasisNote;

package/dist/_internal/shared/features/categories/price-guidance.js

@@ -0,0 +1,136 @@
+/**
+ * Price guidance, stated on the basis the SELLER is typing in.
+ *
+ * `CategoryPriceGuidance` is advisory — it renders as a hint beside the price
+ * input and is never written to `price`. This module answers the one question
+ * that hint cannot be rendered without: **inclusive of what?**
+ *
+ * ## The invariant
+ *
+ * 🛑 **Every figure in a guidance band is TAX-INCLUSIVE.** Both halves, for
+ * different reasons, and neither is a choice we get to make:
+ *
+ *   `market` — competitor ASKS. An Indian storefront's displayed price is
+ *              inclusive by market convention, and worldhobbyshop asserts it
+ *              outright in its own JSON-LD (`valueAddedTaxIncluded: true`).
+ *   `sold`   — our own completed sales, derived from `items[].unitPrice`, and
+ *              every stored price in this system is tax-inclusive.
+ *
+ * So the basis is a documented property of the data rather than a per-row
+ * field. A `basis: "inclusive"` column whose every value is the same string is
+ * a field that cannot answer a question, and the first row to carry the other
+ * value would be a bug rather than a variant.
+ *
+ * ## Why the hint still has to say so
+ *
+ * A seller with `pricesIncludeGst: false` types EX-TAX numbers. Their ₹999 and
+ * an inclusive ₹999 band are **different quantities** — comparing them is off
+ * by the rate, silently, in the direction that makes their listing look
+ * cheaper than the market when it is dearer. The hint therefore converts the
+ * band into the seller's own basis and labels which one it is on.
+ *
+ * Pure arithmetic and strings. No React, no Firestore.
+ */
+import { taxableFromInclusive, grossFromTaxable, } from "../../fees/calculator";
+/**
+ * The basis every stored and crawled guidance figure is on.
+ *
+ * Exported as a named constant so the claim is greppable from the places that
+ * depend on it, and so a future change is one edit rather than an archaeology
+ * exercise across the renderer, the seed helper and the rollup job.
+ */
+export const PRICE_GUIDANCE_TAX_BASIS = "inclusive";
+/** Whether a conversion is needed at all, and possible. */
+function shouldConvert(basis) {
+    const includes = basis.sellerIncludesGst ?? true;
+    return !includes && typeof basis.gstRate === "number" && basis.gstRate > 0;
+}
+/**
+ * One guidance amount, restated on the seller's basis.
+ *
+ * Inclusive seller, exempt item, or an unresolved rate → unchanged. The last
+ * of those is deliberate: converting at `DEFAULT_GST_RATE` would be a guess
+ * presented as arithmetic, and the label says so instead.
+ */
+export function priceGuidanceAmountOnSellerBasis(amount, basis) {
+    if (!shouldConvert(basis))
+        return amount;
+    return taxableFromInclusive(amount, basis.gstRate);
+}
+/** The inverse — a seller's typed figure, restated as the band's basis. */
+export function sellerAmountOnGuidanceBasis(amount, basis) {
+    if (!shouldConvert(basis))
+        return amount;
+    return grossFromTaxable(amount, basis.gstRate);
+}
+/**
+ * The whole guidance object, restated on the seller's basis.
+ *
+ * 🛑 `sampleSize`, `windowDays`, `soldOutShare` and `asOf` are NOT money and
+ * pass through untouched. Mapping every numeric field would silently divide a
+ * sample size by 1.05 — the kind of defect that produces a plausible number
+ * nobody can trace, which is the failure mode this plan keeps finding.
+ */
+export function priceGuidanceOnSellerBasis(guidance, basis) {
+    if (!shouldConvert(basis))
+        return guidance;
+    const on = (n) => priceGuidanceAmountOnSellerBasis(n, basis);
+    return {
+        ...guidance,
+        market: guidance.market
+            ? {
+                ...guidance.market,
+                median: on(guidance.market.median),
+                ...(guidance.market.p25 === undefined ? {} : { p25: on(guidance.market.p25) }),
+                ...(guidance.market.p75 === undefined ? {} : { p75: on(guidance.market.p75) }),
+            }
+            : undefined,
+        sold: guidance.sold
+            ? {
+                ...guidance.sold,
+                min: on(guidance.sold.min),
+                median: on(guidance.sold.median),
+                max: on(guidance.sold.max),
+            }
+            : undefined,
+        lastSold: guidance.lastSold
+            ? { ...guidance.lastSold, amount: on(guidance.lastSold.amount) }
+            : undefined,
+    };
+}
+/**
+ * Four cases, and the fourth is the one worth having this function for.
+ *
+ * | seller basis | rate        | figures   | says |
+ * |---|---|---|---|
+ * | inclusive    | > 0         | unchanged | "incl. GST" |
+ * | exclusive    | > 0         | CONVERTED | "before GST", and that it was converted |
+ * | either       | 0           | unchanged | nothing about tax — an exempt item has none |
+ * | exclusive    | unresolved  | unchanged | 🛑 that they are NOT comparable |
+ *
+ * 🛑 The exempt case must not say "incl. GST". The figure is a bare amount and
+ * claiming a tax basis on it is false — which is precisely the lie the seller
+ * form's old `?? 0` default told on every listing before C0c defect 6.
+ */
+export function describePriceGuidanceBasis(basis) {
+    const includes = basis.sellerIncludesGst ?? true;
+    const rate = basis.gstRate;
+    if (rate === 0) {
+        return { suffix: "", note: null, converted: false };
+    }
+    if (includes) {
+        return { suffix: "incl. GST", note: null, converted: false };
+    }
+    if (typeof rate !== "number" || rate <= 0) {
+        return {
+            suffix: "incl. GST",
+            note: "Your store prices exclude GST, so these figures are not directly comparable to what you type — the tax rate for this category could not be resolved.",
+            converted: false,
+        };
+    }
+    return {
+        suffix: "before GST",
+        note: `Market figures are tax-inclusive; shown here with ${rate}% GST removed to match how your store prices.`,
+        converted: true,
+    };
+}

package/dist/_internal/shared/features/site-settings/gst-registration.d.ts

@@ -0,0 +1,90 @@
+/**
+ * GST registration validity — the gate on turning product GST ON.
+ *
+ * ## Why this exists
+ *
+ * `siteSettings.gst.enabled` decides whether product GST is charged at all
+ * (`createOrderForGroup` computes a breakdown only when `gstSettings?.enabled`
+ * and a buyer state are both present). Until now the admin form sent
+ * `{ enabled, gstin: gstin.trim().toUpperCase(), legalName, address }` with
+ * **no validation of any kind**, and `/api/admin/site` types every group as
+ * `z.unknown()` — so GST collection could be switched on with an **empty or
+ * malformed GSTIN**, after which every invoice charges tax under no valid
+ * registration and prints whatever string was typed.
+ *
+ * That is the same class as C0c defect 4 (`SETTINGS_ENCRYPTION_KEY` unset must
+ * fail LOUDLY rather than storing plaintext): a compliance precondition has to
+ * be refused at the write, not discovered on an invoice.
+ *
+ * ## Shape
+ *
+ * 15 characters: `99AAAAA9999A9Z9`
+ *
+ *   `[0-9]{2}`    state code
+ *   `[A-Z]{5}`    first five of the holder's PAN
+ *   `[0-9]{4}`    PAN digits
+ *   `[A-Z]`       PAN entity letter
+ *   `[0-9A-Z]`    registration number within the state
+ *   `Z`           fixed
+ *   `[0-9A-Z]`    checksum
+ *
+ * ## Why the checksum is BLOCKING and not advisory
+ *
+ * It was verified against the GSTIN that India's own GST material uses as its
+ * worked example (`27AAPFU0939F1ZV`) plus five more real-format registrations,
+ * and against every single-character mutation of them. A regex alone accepts a
+ * transposed digit, which is the realistic typo on a 15-character code copied
+ * off a certificate.
+ *
+ * 🛑 The risk runs the other way too, and it is why this was measured rather
+ * than assumed: a wrong checksum implementation would refuse a LEGITIMATE
+ * registration and leave a real business unable to invoice at all — strictly
+ * worse than accepting a typo. Do not change the algorithm without re-running
+ * the assertions.
+ *
+ * Pure. No React, no Firestore, no env.
+ */
+/** `99AAAAA9999A9Z9` — shape only; see `isValidGstin` for the checksum. */
+export declare const GSTIN_PATTERN: RegExp;
+/**
+ * The published GSTIN check character for the first 14 characters.
+ *
+ * Base-36 positional weights alternate 1, 2 from the left. For each character:
+ * multiply its value by its weight, then add the quotient and the remainder of
+ * that product divided by 36. The check value is `(36 - sum % 36) % 36`.
+ *
+ * Returns `null` when the prefix is not 14 characters of the alphabet — a
+ * caller must not treat that as "checksum failed", because it is a different
+ * fault with a different message.
+ */
+export declare function gstinCheckCharacter(first14: string): string | null;
+/** Shape AND checksum. Whitespace and case are the caller's to normalise. */
+export declare function isValidGstin(raw: string | undefined | null): boolean;
+export interface GstEnablementInput {
+    enabled?: boolean;
+    gstin?: string;
+    legalName?: string;
+    address?: string;
+}
+/**
+ * One problem per field, keyed by the field that owns it, so a caller can pipe
+ * each straight into `setFieldError(key, message)` per Rule #9 — rather than a
+ * single banner the admin has to map back onto four inputs themselves.
+ */
+export type GstEnablementProblems = Partial<Record<"gstin" | "legalName" | "address", string>>;
+/**
+ * What must be true before product GST may be charged.
+ *
+ * 🛑 Only checked when `enabled` is being set to `true`. Turning GST **off**
+ * must never be blocked by the state of the fields it is turning off — that
+ * would trap an admin who enabled it with bad data in exactly the state they
+ * are trying to leave.
+ *
+ * `legalName` and `address` are required alongside the number because a tax
+ * invoice carries all three, and the invoice renderer snapshots all three onto
+ * the order. Enabling with two of them produces an invoice with a blank
+ * supplier block, which is not a lesser version of compliance.
+ */
+export declare function validateGstEnablement(input: GstEnablementInput): GstEnablementProblems;
+/** `true` when GST may be enabled with this input. */
+export declare function canEnableGst(input: GstEnablementInput): boolean;