@mohasinac/appkit 4.42.18 → 4.44.0

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;

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

@@ -0,0 +1,126 @@
+/**
+ * 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 const GSTIN_PATTERN = /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$/;
+/** The 36 symbols GSTIN checksum arithmetic runs in, in value order. */
+const GSTIN_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * 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 function gstinCheckCharacter(first14) {
+    if (first14.length !== 14)
+        return null;
+    let sum = 0;
+    for (let i = 0; i < 14; i += 1) {
+        const value = GSTIN_ALPHABET.indexOf(first14[i]);
+        if (value < 0)
+            return null;
+        const product = value * (i % 2 === 0 ? 1 : 2);
+        sum += Math.floor(product / 36) + (product % 36);
+    }
+    return GSTIN_ALPHABET[(36 - (sum % 36)) % 36];
+}
+/** Shape AND checksum. Whitespace and case are the caller's to normalise. */
+export function isValidGstin(raw) {
+    if (!raw)
+        return false;
+    const value = raw.trim().toUpperCase();
+    if (!GSTIN_PATTERN.test(value))
+        return false;
+    return gstinCheckCharacter(value.slice(0, 14)) === value[14];
+}
+/**
+ * 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 function validateGstEnablement(input) {
+    if (input.enabled !== true)
+        return {};
+    const problems = {};
+    const gstin = (input.gstin ?? "").trim().toUpperCase();
+    if (gstin.length === 0) {
+        problems.gstin = "A GSTIN is required before GST can be charged.";
+    }
+    else if (!GSTIN_PATTERN.test(gstin)) {
+        problems.gstin =
+            "A GSTIN is 15 characters in the form 99AAAAA9999A9Z9 — check it against your registration certificate.";
+    }
+    else if (gstinCheckCharacter(gstin.slice(0, 14)) !== gstin[14]) {
+        problems.gstin =
+            "That GSTIN fails its own check digit, so it contains a typo. Compare it character by character with your certificate.";
+    }
+    if ((input.legalName ?? "").trim().length === 0) {
+        problems.legalName =
+            "The registered legal name is required — it is printed on every tax invoice.";
+    }
+    if ((input.address ?? "").trim().length === 0) {
+        problems.address =
+            "The registered address is required — it is printed on every tax invoice.";
+    }
+    return problems;
+}
+/** `true` when GST may be enabled with this input. */
+export function canEnableGst(input) {
+    return Object.keys(validateGstEnablement(input)).length === 0;
+}

package/dist/_internal/shared/fees/calculator.d.ts

@@ -120,4 +120,109 @@ export interface GstBreakdown {
     igst: number;
     gstAmount: number;
 }
+/**
+ * The rate used when nobody has determined one — HSN 95030020, non-electronic
+ * toys, which is nearly this whole catalogue.
+ *
+ * 🛑 A LAST RESORT, not a mechanism. The real resolution order is the
+ * product's own `gstRate` → the category's `taxCodeId` → this. A listing that
+ * reaches this constant means its category has no tax code, and THAT is the
+ * defect to fix; every use must warn and flag the product for triage. The
+ * measure of success is that it fires for nothing.
+ *
+ * It exists because the alternative is worse in one direction specifically:
+ * under GST-inclusive pricing the tax is already inside the price, so backing
+ * out 0% would treat the whole amount as taxable value, pay the seller all of
+ * it, and leave us owing tax on money already handed over. Exclusive pricing
+ * merely fails to collect, which does not lose money we hold.
+ *
+ * Belongs in `siteSettings.gst` the day a rate revision has to land without a
+ * deploy — `TaxCodeDocument.effectiveFrom` records that toys have already
+ * moved once — but a constant is the honest starting point rather than a
+ * settings field nobody has a reason to change.
+ */
+export declare const DEFAULT_GST_RATE = 5;
+/**
+ * Whether this is an intra-state supply (CGST+SGST) or inter-state (IGST).
+ *
+ * 🛑 NOT a raw `===` on two strings, which is what `createOrderForGroup` and
+ * `previewCheckoutPricing` both did. `constants/geo/subdivisions.ts` opens by
+ * recording why that fails: the same `state` field held *"Karnataka",
+ * "karnataka", "KA" and "Karnatka" depending on which of the three surfaces
+ * created the row*. A picker now fixes new addresses, but the store's state
+ * and every pre-picker row still arrive unnormalised.
+ *
+ * 🛑 Returns `null` for "cannot tell", and the distinction matters. The old
+ * expression was `!!storeState && storeState === buyerState`, so a store with
+ * no address resolved to `false` — i.e. **silently inter-state**, reported as
+ * full IGST. Note what this defect is and is not: IGST total equals
+ * CGST+SGST total, so **the buyer pays exactly the same amount either way**.
+ * It is a compliance and reporting defect on the invoice, not an overcharge —
+ * which is why it is safe to surface as `null` and let the caller log rather
+ * than guess.
+ */
+export declare function isIntraStateSupply(storeState: string | undefined | null, buyerState: string | undefined | null): boolean | null;
+/**
+ * Back the tax OUT of a tax-inclusive amount: `gross × 100 / (100 + rate)`.
+ *
+ * 🛑 **Every price in this system is tax-inclusive.** A listing's `price` is
+ * what the buyer pays; the GST is inside it and is remitted from it. That is
+ * the Indian B2C convention, it is what worldhobbyshop asserts in its own
+ * JSON-LD (`valueAddedTaxIncluded: true`), and it is what makes two listings
+ * at ₹999 cost the same regardless of which seller posted them.
+ *
+ * A seller who would rather think in ex-tax terms sets
+ * `StoreDocument.pricesIncludeGst: false`, and their typed price is grossed up
+ * **once, at write time**, by `ProductRepository`. So the flag is an
+ * AUTHORING convenience and never a display or checkout mode — the money
+ * paths have no branch on it at all, which is the whole point: a mode flag
+ * read in five places is five places to drift.
+ *
+ * `rate <= 0` returns the amount unchanged — an exempt supply has no tax to
+ * back out, and dividing by 100 would be a silent no-op that merely looked
+ * like arithmetic.
+ */
+export declare function taxableFromInclusive(gross: number, rate: number): number;
+/**
+ * The inverse: gross an EX-TAX amount up to its tax-inclusive equivalent,
+ * `taxable × (100 + rate) / 100`.
+ *
+ * Used in exactly one place — `ProductRepository`, when a store with
+ * `pricesIncludeGst: false` saves a price. That is the whole extent of the
+ * flag: one conversion, at write time, after which the stored price is
+ * tax-inclusive like every other and no money path can tell the difference.
+ *
+ * ₹999 ex-tax at 5% → ₹1,048.95 inclusive, which backs out to ₹999.00 again.
+ * The round trip is exact at 2dp for every rate in the union, asserted rather
+ * than assumed.
+ */
+export declare function grossFromTaxable(taxable: number, rate: number): number;
+/**
+ * The breakdown of a tax-INCLUSIVE amount, with two invariants guaranteed by
+ * construction rather than by arithmetic luck:
+ *
+ *   **taxable + gstAmount === gross**      (to the paisa)
+ *   **cgst + sgst === gstAmount**          (to the paisa)
+ *
+ * 🛑 Why this exists instead of `calculateGst(rate, intra, taxableFromInclusive(...))`.
+ *
+ * That composition rounds TWICE and overshoots. Measured on the ₹999 @ 5% case
+ * the plan itself specifies: the taxable rounds UP to 951.43, then
+ * `calculateGst`'s intra branch takes `half = round(47.5715 / 2) = 23.79` and
+ * returns `round(half × 2) = 47.58` — so taxable + tax came to **₹999.01** and
+ * the invoice no longer reconciled with the ₹999 the buyer was charged.
+ *
+ * Under the old add-on-top model that could not happen: the tax was whatever
+ * it was and the total was defined as price + tax, so the invariant was free.
+ * Making prices inclusive is what turns it into something that must be
+ * enforced — the tax is now a PARTITION of a fixed amount, not an addition to
+ * it.
+ *
+ * So the tax is the **exact complement** of the taxable value, and the split
+ * assigns the remainder to the second half rather than rounding both. This is
+ * the same discipline `allocateAcrossMembers` already applies, and the same
+ * class of defect as the `Math.round(gstAmount / 2)` split that C0c's defect 2
+ * removed — one level further out.
+ */
+export declare function calculateGstInclusive(rate: number, intraState: boolean, gross: number): GstBreakdown;
 export declare function calculateGst(rate: number, intraState: boolean, taxableAmount: number): GstBreakdown;