@mohasinac/appkit 4.43.0 → 4.44.0

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;

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

@@ -107,6 +107,149 @@ export function computeShipmentProtectionFee(subtotal, addonSelected, rates) {
     const percentFee = roundRupees(subtotal * (percent / 100));
     return Math.max(min, percentFee);
 }
+/**
+ * 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 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 function isIntraStateSupply(storeState, buyerState) {
+    const a = normaliseStateName(storeState);
+    const b = normaliseStateName(buyerState);
+    if (!a || !b)
+        return null;
+    return a === b;
+}
+/** Lowercase, collapse whitespace, drop punctuation — "Tamil  Nadu." → "tamil nadu". */
+function normaliseStateName(raw) {
+    if (!raw)
+        return null;
+    const cleaned = raw
+        .normalize("NFKD")
+        .toLowerCase()
+        .replace(/[^a-z\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return cleaned.length > 0 ? cleaned : 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 function taxableFromInclusive(gross, rate) {
+    if (rate <= 0)
+        return roundRupees(gross);
+    return roundRupees((gross * 100) / (100 + rate)); // audit-money-units-ok: tax back-out, not a paise conversion
+}
+/**
+ * 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 function grossFromTaxable(taxable, rate) {
+    if (rate <= 0)
+        return roundRupees(taxable);
+    return roundRupees((taxable * (100 + rate)) / 100); // audit-money-units-ok: tax gross-up, not a paise conversion
+}
+/**
+ * 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 function calculateGstInclusive(rate, intraState, gross) {
+    if (rate <= 0) {
+        const t = roundRupees(gross);
+        return { taxableAmount: t, cgst: 0, sgst: 0, igst: 0, gstAmount: 0 };
+    }
+    const taxableAmount = taxableFromInclusive(gross, rate);
+    const gstAmount = roundRupees(gross - taxableAmount);
+    if (intraState) {
+        const cgst = roundRupees(gstAmount / 2); // audit-money-units-ok: halving a tax amount
+        return { taxableAmount, cgst, sgst: roundRupees(gstAmount - cgst), igst: 0, gstAmount };
+    }
+    return { taxableAmount, cgst: 0, sgst: 0, igst: gstAmount, gstAmount };
+}
 export function calculateGst(rate, intraState, taxableAmount) {
     const gstAmount = roundRupees(taxableAmount * (rate / 100));
     if (intraState) {

package/dist/_internal/shared/listing-types/art/config.d.ts

@@ -48,9 +48,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -70,9 +67,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/listing-types/classified/config.d.ts

@@ -48,9 +48,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -70,9 +67,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/listing-types/digital-code/config.d.ts

@@ -56,9 +56,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -78,9 +75,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/listing-types/live/config.d.ts

@@ -48,9 +48,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -70,9 +67,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/listing-types/standard/config.d.ts

@@ -48,9 +48,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -70,9 +67,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/listing-types/stickers/config.d.ts

@@ -48,9 +48,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Recently Updated";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     publicSortOptions: readonly [{
         readonly value: string;
@@ -70,9 +67,6 @@ export declare const config: {
     }, {
         readonly value: string;
         readonly label: "Name: Z–A";
-    }, {
-        readonly value: string;
-        readonly label: "Most Viewed";
     }];
     extraFacetKeys: readonly string[];
 };

package/dist/_internal/shared/templating/placeholders.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `{{placeholder}}` interpolation — the ONE implementation.
+ *
+ * Promoted out of `features/faq/schemas/firestore.ts`, where it had served 63
+ * FAQs since the feature shipped. Category description templates need exactly
+ * the same thing, and writing a second regex for it is Root Cause #75's shape:
+ * one of the two eventually learns about a case the other does not, and the
+ * copy a caller reaches is the one they happened to import.
+ *
+ * `features/faq/schemas/firestore.ts` re-exports these under its own names, so
+ * nothing in the FAQ feature changed and no FAQ call site moved.
+ *
+ * 🛑 NOT a template ENGINE. There are no conditionals, loops, filters or
+ * nesting, and none should be added here — a category body is author-facing
+ * copy with a handful of named slots, and a real engine would mean user input
+ * being evaluated. `\w+` is the whole grammar, which is also why it is safe to
+ * run over HTML.
+ */
+/**
+ * Every placeholder name in `text`, in source order, INCLUDING duplicates.
+ *
+ * Duplicates are kept deliberately: a caller counting unfilled slots wants to
+ * know a body says `{{year}}` three times, and `usedPlaceholders` below is the
+ * de-duplicated form for callers that want the set instead.
+ */
+export declare function extractPlaceholders(text: string): string[];
+/** The distinct placeholder names in `text`, in first-appearance order. */
+export declare function usedPlaceholders(text: string): string[];
+/**
+ * What a slot may resolve to.
+ *
+ * 🛑 Declared once and shared with `missingPlaceholders`, which only tests key
+ * PRESENCE and so does not care about the value type at all. It was
+ * `Record<string, unknown>` for exactly that reason, and
+ * `audit-unknown-leakage` was right to reject it: `unknown` at a boundary is
+ * how a caller ends up casting, and a cast is where this codebase's worst
+ * defects live. Sharing the real type costs nothing and means the two
+ * functions cannot disagree about what a value is.
+ */
+export type PlaceholderValues = Readonly<Record<string, string | number | null | undefined>>;
+export interface InterpolateResult {
+    /** The text with every slot replaced. */
+    text: string;
+    /** Slot names that had no value — the caller reports these to the author. */
+    unresolved: string[];
+}
+/**
+ * Replace every `{{slot}}` with its value.
+ *
+ * 🛑 An unresolved slot becomes the EMPTY STRING, never the literal
+ * `{{series}}`, and never a placeholder-ish stand-in like `[series]`. A
+ * literal brace pair reaching a published product description is the single
+ * most visible way this feature can fail, and it is what the `unresolved` list
+ * exists to prevent: the caller surfaces "2 of 9 slots could not be filled:
+ * {{year}}, {{type}}" rather than silently shipping the braces.
+ *
+ * A value that is present but empty/whitespace counts as UNRESOLVED. `{{brand}}`
+ * resolving to `""` because the brand lookup returned nothing is exactly the
+ * case an author needs told about, and treating it as resolved would hide it.
+ */
+export declare function interpolate(text: string, values: PlaceholderValues): InterpolateResult;
+/**
+ * Which of `text`'s slots have no value in `available`.
+ *
+ * Separate from `interpolate` because validation runs at AUTHORING time, when
+ * there is a schema to check against but no real product to fill from — the
+ * admin editor wants to know a template names `{{sereis}}` before anyone
+ * publishes from it.
+ */
+export declare function missingPlaceholders(text: string, available: PlaceholderValues): string[];

package/dist/_internal/shared/templating/placeholders.js

@@ -0,0 +1,73 @@
+/**
+ * `{{placeholder}}` interpolation — the ONE implementation.
+ *
+ * Promoted out of `features/faq/schemas/firestore.ts`, where it had served 63
+ * FAQs since the feature shipped. Category description templates need exactly
+ * the same thing, and writing a second regex for it is Root Cause #75's shape:
+ * one of the two eventually learns about a case the other does not, and the
+ * copy a caller reaches is the one they happened to import.
+ *
+ * `features/faq/schemas/firestore.ts` re-exports these under its own names, so
+ * nothing in the FAQ feature changed and no FAQ call site moved.
+ *
+ * 🛑 NOT a template ENGINE. There are no conditionals, loops, filters or
+ * nesting, and none should be added here — a category body is author-facing
+ * copy with a handful of named slots, and a real engine would mean user input
+ * being evaluated. `\w+` is the whole grammar, which is also why it is safe to
+ * run over HTML.
+ */
+/** The slot syntax. One capture group: the bare name, no braces. */
+const PLACEHOLDER_RE = /\{\{(\w+)\}\}/g;
+/**
+ * Every placeholder name in `text`, in source order, INCLUDING duplicates.
+ *
+ * Duplicates are kept deliberately: a caller counting unfilled slots wants to
+ * know a body says `{{year}}` three times, and `usedPlaceholders` below is the
+ * de-duplicated form for callers that want the set instead.
+ */
+export function extractPlaceholders(text) {
+    return Array.from(text.matchAll(PLACEHOLDER_RE), (m) => m[1]);
+}
+/** The distinct placeholder names in `text`, in first-appearance order. */
+export function usedPlaceholders(text) {
+    return Array.from(new Set(extractPlaceholders(text)));
+}
+/**
+ * Replace every `{{slot}}` with its value.
+ *
+ * 🛑 An unresolved slot becomes the EMPTY STRING, never the literal
+ * `{{series}}`, and never a placeholder-ish stand-in like `[series]`. A
+ * literal brace pair reaching a published product description is the single
+ * most visible way this feature can fail, and it is what the `unresolved` list
+ * exists to prevent: the caller surfaces "2 of 9 slots could not be filled:
+ * {{year}}, {{type}}" rather than silently shipping the braces.
+ *
+ * A value that is present but empty/whitespace counts as UNRESOLVED. `{{brand}}`
+ * resolving to `""` because the brand lookup returned nothing is exactly the
+ * case an author needs told about, and treating it as resolved would hide it.
+ */
+export function interpolate(text, values) {
+    const unresolved = [];
+    const out = text.replace(PLACEHOLDER_RE, (_match, name) => {
+        const raw = values[name];
+        const value = raw == null ? "" : String(raw);
+        if (value.trim() === "") {
+            if (!unresolved.includes(name))
+                unresolved.push(name);
+            return "";
+        }
+        return value;
+    });
+    return { text: out, unresolved };
+}
+/**
+ * Which of `text`'s slots have no value in `available`.
+ *
+ * Separate from `interpolate` because validation runs at AUTHORING time, when
+ * there is a schema to check against but no real product to fill from — the
+ * admin editor wants to know a template names `{{sereis}}` before anyone
+ * publishes from it.
+ */
+export function missingPlaceholders(text, available) {
+    return usedPlaceholders(text).filter((name) => !(name in available));
+}

package/dist/client.d.ts

@@ -488,6 +488,8 @@ export type { CodHandlingFeeRates, WhatsAppNotifyFeeRates, GiftWrapFeeRates, Shi
 export { FAQPageContent } from "./features/faq/index";
 export type { FAQCategory, FAQCategoryItem, FAQSortOption } from "./features/faq/index";
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect";
+export { CategoryTemplatePicker, variantForCondition } from "./features/categories/components/CategoryTemplatePicker";
+export type { CategoryTemplatePickerProps, CategoryTemplateApply } from "./features/categories/components/CategoryTemplatePicker";
 export { BrandInlineSelect } from "./features/seller/components/BrandInlineSelect";
 export { API_ENDPOINTS } from "./constants/index";
 export { SELLER_LISTING_TABS, type SellerListingTabId, } from "./features/products/constants/listing-tabs";

package/dist/client.js

@@ -486,6 +486,7 @@ export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator"; // reexport-from-internal-ok: pure fee-calc utility consumed directly by public checkout UI (CheckoutRouteClient.tsx), same category as the sibling computeEmiSchedule/checkEmiEligibility re-export two lines above
 export { FAQPageContent } from "./features/faq/index";
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect";
+export { CategoryTemplatePicker, variantForCondition } from "./features/categories/components/CategoryTemplatePicker";
 export { BrandInlineSelect } from "./features/seller/components/BrandInlineSelect";
 export { API_ENDPOINTS } from "./constants/index";
 // [CLIENT-SAFE] Pure, zero-import constant files — dashboard filter-tab