@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/features/seller/utils/product-draft-mapping.d.ts

@@ -49,6 +49,19 @@ import type { SellerProductDraft } from "../components/SellerProductShell";
 export interface StoredProductBlocks {
     finalSale?: boolean;
     returnPolicy?: string;
+    authenticity?: "original" | "reproduction" | "unverified";
+    specifications?: {
+        name: string;
+        value: string;
+        unit?: string;
+    }[];
+    features?: string[];
+    weightG?: number;
+    dimensionsCm?: {
+        l: number;
+        w: number;
+        h: number;
+    };
     classified?: {
         meetupArea?: {
             city?: string;

package/dist/features/seller/utils/product-draft-mapping.js

@@ -120,6 +120,23 @@ export function productToDraft(product) {
          */
         finalSale: product.finalSale,
         returnPolicy: product.returnPolicy,
+        /*
+         * The inherited-but-editable fields (C2c). Same category as `finalSale`:
+         * flat, stored, and absent from the ten hand-written `initialValues`
+         * literals — so the Details section would open EMPTY on a listing that
+         * already carries them, and a seller saving anything else would appear to
+         * have cleared their own specifications.
+         *
+         * (The write is partial, so an untouched save does not actually clear
+         * them. But a form that shows a listing's authenticity as unanswered when
+         * it is answered is telling the seller something untrue, which is exactly
+         * the argument `finalSale` above is making.)
+         */
+        authenticity: product.authenticity,
+        specifications: product.specifications,
+        features: product.features,
+        weightG: product.weightG,
+        dimensionsCm: product.dimensionsCm,
         classifiedCity: classified?.meetupArea?.city,
         classifiedLocality: classified?.meetupArea?.locality,
         classifiedPincode: classified?.meetupArea?.pincode,

package/dist/features/store-extensions/constants/alert-metrics.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ONE alert-metric vocabulary — C3a.
+ *
+ * ## The defect this closes
+ *
+ * `AnalyticsAlertDocument.metric` was `z.string()`, and the two places that
+ * produce one shared **ZERO tokens**:
+ *
+ *   the seller UI offered  daily_revenue · daily_orders · low_stock ·
+ *                          cancelled_orders · pending_payouts · avg_rating ·
+ *                          reviews_count          (7, snake_case)
+ *   the seed wrote         min-stock · orders-window · api-error-rate ·
+ *                          reports-1h             (4, kebab-case)
+ *
+ * Not a near-miss — no value in one list appears in the other. And because
+ * nothing validated the field, every seeded alert rendered its raw string in
+ * the seller's list (`METRIC_OPTIONS.find(...)?.label ?? alert.metric`) while
+ * every alert a seller created was equally unrecognised by anything else.
+ *
+ * It stayed invisible for one reason: **nothing read either value**. There was
+ * no evaluator anywhere — zero references across all 59 job files and
+ * `functions/` — so `lastTriggeredAt` was declared and written nowhere, and
+ * sellers configured alerts that could never fire.
+ *
+ * ## 🛑 The rule that keeps it closed
+ *
+ * **A metric is in this map only if the evaluator computes it.** Offering one
+ * it cannot is how the original dead promise was built — a dropdown is a
+ * commitment, and `low_stock` sitting in a picker with no evaluator behind it
+ * is worse than its absence, because the seller stops watching their stock.
+ *
+ * So `ALERT_METRICS` is a `Record<AlertMetric, AlertMetricDef>`: adding a
+ * union member without a definition is a compile error, and the evaluator's
+ * own switch is exhaustive over the same union, so adding a member without an
+ * implementation is a compile error too. Root Cause #61 — a `Record<Union, T>`
+ * is compile-safe where an array literal is not, and this vocabulary existed
+ * as two array literals.
+ */
+/** Who may set an alert on this metric. */
+export type AlertMetricScope = "seller" | "admin";
+/** How to render the threshold the seller types. */
+export type AlertMetricUnit = "count" | "currency" | "rating";
+export interface AlertMetricDef {
+    label: string;
+    /** What the number means, so the form can suffix it honestly. */
+    unit: AlertMetricUnit;
+    /** Which portals may offer it. Seller metrics are evaluated per store. */
+    scopes: readonly AlertMetricScope[];
+    /**
+     * Plain-English statement of what is counted, shown as helper text.
+     *
+     * Carried because "Daily Orders" does not say whether a cancelled order
+     * counts, and an alert whose definition the seller has to guess at is an
+     * alert they will not trust when it fires.
+     */
+    describes: string;
+}
+export declare const ALERT_METRIC_VALUES: readonly ["low_stock", "out_of_stock", "orders_count", "revenue_total", "cancelled_orders", "pending_payout_total", "avg_rating", "reviews_count", "open_reports", "pending_moderation"];
+export type AlertMetric = (typeof ALERT_METRIC_VALUES)[number];
+/**
+ * 🛑 `Record<AlertMetric, …>`, not a partial and not an array. A union member
+ * with no definition does not compile, and the evaluator switches over the
+ * same union exhaustively — so the picker, the evaluator and the stored value
+ * cannot drift the way the two array literals did.
+ */
+export declare const ALERT_METRICS: Record<AlertMetric, AlertMetricDef>;
+/** Narrow an arbitrary stored string. */
+export declare function isAlertMetric(value: unknown): value is AlertMetric;
+/**
+ * The metrics one portal may offer, derived — never a second hand-written list.
+ *
+ * That is the whole defect this file closes: the seller picker WAS a
+ * hand-written list, and it agreed with nothing.
+ */
+export declare function alertMetricsForScope(scope: AlertMetricScope): {
+    value: AlertMetric;
+    def: AlertMetricDef;
+}[];
+/**
+ * The stock level `low_stock` counts at or below.
+ *
+ * Exported so the alert, the products-list filter and the dashboard tile agree
+ * on what "low" means. Three surfaces each picking their own number is how a
+ * seller gets a warning from one and a clean bill from another.
+ */
+export declare const LOW_STOCK_THRESHOLD = 5;

package/dist/features/store-extensions/constants/alert-metrics.js

@@ -0,0 +1,142 @@
+/**
+ * ONE alert-metric vocabulary — C3a.
+ *
+ * ## The defect this closes
+ *
+ * `AnalyticsAlertDocument.metric` was `z.string()`, and the two places that
+ * produce one shared **ZERO tokens**:
+ *
+ *   the seller UI offered  daily_revenue · daily_orders · low_stock ·
+ *                          cancelled_orders · pending_payouts · avg_rating ·
+ *                          reviews_count          (7, snake_case)
+ *   the seed wrote         min-stock · orders-window · api-error-rate ·
+ *                          reports-1h             (4, kebab-case)
+ *
+ * Not a near-miss — no value in one list appears in the other. And because
+ * nothing validated the field, every seeded alert rendered its raw string in
+ * the seller's list (`METRIC_OPTIONS.find(...)?.label ?? alert.metric`) while
+ * every alert a seller created was equally unrecognised by anything else.
+ *
+ * It stayed invisible for one reason: **nothing read either value**. There was
+ * no evaluator anywhere — zero references across all 59 job files and
+ * `functions/` — so `lastTriggeredAt` was declared and written nowhere, and
+ * sellers configured alerts that could never fire.
+ *
+ * ## 🛑 The rule that keeps it closed
+ *
+ * **A metric is in this map only if the evaluator computes it.** Offering one
+ * it cannot is how the original dead promise was built — a dropdown is a
+ * commitment, and `low_stock` sitting in a picker with no evaluator behind it
+ * is worse than its absence, because the seller stops watching their stock.
+ *
+ * So `ALERT_METRICS` is a `Record<AlertMetric, AlertMetricDef>`: adding a
+ * union member without a definition is a compile error, and the evaluator's
+ * own switch is exhaustive over the same union, so adding a member without an
+ * implementation is a compile error too. Root Cause #61 — a `Record<Union, T>`
+ * is compile-safe where an array literal is not, and this vocabulary existed
+ * as two array literals.
+ */
+export const ALERT_METRIC_VALUES = [
+    "low_stock",
+    "out_of_stock",
+    "orders_count",
+    "revenue_total",
+    "cancelled_orders",
+    "pending_payout_total",
+    "avg_rating",
+    "reviews_count",
+    "open_reports",
+    "pending_moderation",
+];
+/**
+ * 🛑 `Record<AlertMetric, …>`, not a partial and not an array. A union member
+ * with no definition does not compile, and the evaluator switches over the
+ * same union exhaustively — so the picker, the evaluator and the stored value
+ * cannot drift the way the two array literals did.
+ */
+export const ALERT_METRICS = {
+    low_stock: {
+        label: "Products low on stock",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "How many of your published listings have available stock at or below 5. With 76–93% of competitor catalogues sold out, restock is the main lifecycle event.",
+    },
+    out_of_stock: {
+        label: "Products out of stock",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "How many published listings have zero available stock and cannot be bought.",
+    },
+    orders_count: {
+        label: "Orders in the window",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "Orders placed in the window, whatever their status. Set this to `== 0` to be told when nothing is selling.",
+    },
+    revenue_total: {
+        label: "Revenue in the window",
+        unit: "currency",
+        scopes: ["seller", "admin"],
+        describes: "Goods value of delivered, paid, unrefunded orders in the window — the same base a payout is computed from, not the grand total.",
+    },
+    cancelled_orders: {
+        label: "Cancelled orders in the window",
+        unit: "count",
+        scopes: ["seller", "admin"],
+        describes: "Orders cancelled in the window.",
+    },
+    pending_payout_total: {
+        label: "Pending payout amount",
+        unit: "currency",
+        scopes: ["seller", "admin"],
+        describes: "Total of payouts not yet marked paid. Not window-scoped — a backlog is a backlog.",
+    },
+    avg_rating: {
+        label: "Average rating",
+        unit: "rating",
+        scopes: ["seller"],
+        describes: "Mean of approved reviews across the whole store. Set this to `< 4` to hear about a slide early.",
+    },
+    reviews_count: {
+        label: "New reviews in the window",
+        unit: "count",
+        scopes: ["seller"],
+        describes: "Approved reviews published in the window.",
+    },
+    open_reports: {
+        label: "Open reports",
+        unit: "count",
+        scopes: ["admin"],
+        describes: "Reports awaiting moderation. Replaces the seeded `reports-1h`, which nothing read.",
+    },
+    pending_moderation: {
+        label: "Listings pending review",
+        unit: "count",
+        scopes: ["admin"],
+        describes: "Listings in `in_review`, waiting on a moderator.",
+    },
+};
+/** Narrow an arbitrary stored string. */
+export function isAlertMetric(value) {
+    return typeof value === "string" && ALERT_METRIC_VALUES.includes(value);
+}
+/**
+ * The metrics one portal may offer, derived — never a second hand-written list.
+ *
+ * That is the whole defect this file closes: the seller picker WAS a
+ * hand-written list, and it agreed with nothing.
+ */
+export function alertMetricsForScope(scope) {
+    return ALERT_METRIC_VALUES.filter((m) => ALERT_METRICS[m].scopes.includes(scope)).map((m) => ({
+        value: m,
+        def: ALERT_METRICS[m],
+    }));
+}
+/**
+ * The stock level `low_stock` counts at or below.
+ *
+ * Exported so the alert, the products-list filter and the dashboard tile agree
+ * on what "low" means. Three surfaces each picking their own number is how a
+ * seller gets a warning from one and a clean bill from another.
+ */
+export const LOW_STOCK_THRESHOLD = 5;

package/dist/features/store-extensions/schemas/firestore.d.ts

@@ -1,3 +1,4 @@
+import type { AlertMetric } from "../constants/alert-metrics";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 /**
@@ -76,13 +77,30 @@ export interface AnalyticsAlertDocument extends BaseDocument {
     scope: AnalyticsScope;
     ownerId: string;
     label: string;
-    metric: string;
+    /**
+     * 🛑 Was `string`, and that is what let the two producers share ZERO tokens:
+     * the seller picker offered seven snake_case values and the seed wrote four
+     * kebab-case ones, with no overlap and nothing to notice. Narrowed to the
+     * one vocabulary in `constants/alert-metrics.ts`, which the picker derives
+     * from and the evaluator switches over exhaustively.
+     */
+    metric: AlertMetric;
     operator: AlertOperator;
     threshold: number;
     windowHours: number;
     isActive: boolean;
     notifyChannels: Array<"in-app" | "email" | "whatsapp">;
+    /**
+     * When this alert last fired.
+     *
+     * Declared from the start and written NOWHERE until C3b, because there was
+     * no evaluator — which is also why nobody noticed the metric vocabulary was
+     * two disjoint lists. It is now the re-notify guard: an alert that is still
+     * true must not mail every run.
+     */
     lastTriggeredAt?: Date;
+    /** The value observed at `lastTriggeredAt`, so the message can quote it. */
+    lastObservedValue?: number;
 }
 export declare const ANALYTICS_ALERTS_COLLECTION: "analyticsAlerts";
 export declare const ANALYTICS_ALERT_INDEXED_FIELDS: readonly ["scope", "ownerId", "isActive", "metric", "createdAt"];

package/dist/features/stores/schemas/firestore.d.ts

@@ -53,9 +53,9 @@ export interface StoreDocument extends BaseDocument {
     searchTxt?: string[];
     storeSlug: string;
     ownerId: string;
-    /** Tester sandbox flag — set on the shared admin-seeded test store; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on the shared admin-seeded test store; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc. */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
     testDataExpiresAt?: Date;
     storeName: string;
     storeDescription?: string;
@@ -120,6 +120,35 @@ export interface StoreDocument extends BaseDocument {
      * true. Default false — sellers must explicitly opt in.
      */
     emiEnabled?: boolean;
+    /**
+     * How this seller THINKS about the prices they type. An authoring
+     * convenience, and nothing more.
+     *
+     * 🛑 **Every stored `price` in this system is tax-INCLUSIVE** — it is what
+     * the buyer pays, with GST inside it, remitted from it. No money path
+     * branches on this flag, and that is deliberate: a mode read in five places
+     * is five places to drift, which is the defect family C0/C0c spent its
+     * whole length removing.
+     *
+     * `true` (the default) — the seller types the buyer-facing price. ₹999 at 5%
+     * means the buyer pays ₹999 and the seller earns from a ₹951.43 taxable
+     * value.
+     *
+     * `false` — the seller types an EX-TAX price, and `ProductRepository`
+     * grosses it up **once, at write time**: ₹999 at 5% is stored as ₹1,048.95,
+     * so the buyer pays ₹1,048.95 and the seller earns from ₹999.00.
+     *
+     * Default `true`, which matters twice. It is the Indian B2C convention
+     * (and what worldhobbyshop asserts in its own JSON-LD via
+     * `valueAddedTaxIncluded: true`); and it means enabling GST changes no
+     * displayed price, where defaulting to `false` would raise every listing in
+     * the catalogue the moment the switch was flipped.
+     *
+     * 🛑 Flipping this does NOT re-price existing listings. The gross-up happens
+     * at write, so a seller who switches must re-save (or have re-derived) the
+     * products they want converted — see `ProductRepository`.
+     */
+    pricesIncludeGst?: boolean;
     whatsappConfig?: {
         /** Seller's WhatsApp Business phone number, digits-only with country code e.g. "919876543210" */
         phoneNumber?: string;

package/dist/features/tax-codes/repository/tax-codes.repository.d.ts

@@ -0,0 +1,55 @@
+import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { type TaxCodeCreateInput, type TaxCodeDocument, type TaxCodeUpdateInput } from "../schemas/firestore";
+/**
+ * The `taxCodes` collection.
+ *
+ * Small, read-mostly and read on a hot path — `deriveTaxonomy` resolves a
+ * category's `taxCodeId` on every product create and on any update that names
+ * a taxonomy field. So the two reads below are single-document and
+ * single-field-equality shaped on purpose; neither needs a composite index.
+ */
+export declare class TaxCodesRepository extends BaseRepository<TaxCodeDocument> {
+    constructor();
+    list(model: SieveModel): Promise<FirebaseSieveResult<TaxCodeDocument>>;
+    /**
+     * Every active code, chapter-then-rate ordered, for the picker.
+     *
+     * Unpaginated deliberately — this is ~10 rows and will be a few dozen at
+     * most. If it ever needs paging, the picker needs `searchTxt` first, and
+     * that is a different change.
+     */
+    listActive(): Promise<TaxCodeDocument[]>;
+    /**
+     * Every code including inactive ones, for the admin list.
+     *
+     * 🛑 EXPLICITLY bounded, even though the collection is five rows. Two
+     * reasons: `BaseRepository.findAll()` relies on a cap several layers away
+     * (`base.ts` clamps perPage at 500), and a route that reads "all of a
+     * collection" with no visible bound is the shape that has to be re-audited
+     * every time somebody wonders whether it is safe. 200 is far above any
+     * plausible number of HSN codes and far below anything that costs.
+     */
+    listAllBounded(): Promise<TaxCodeDocument[]>;
+    /**
+     * Resolve a code for derivation.
+     *
+     * 🛑 Returns `null` for an INACTIVE code as well as a missing one, and the
+     * caller must treat both the same way: leave the product's `gstRate` and
+     * `hsnCode` alone rather than writing a zero. Deactivating a code must not
+     * silently re-rate the next listing to 0% — that is indistinguishable from a
+     * deliberate exemption, which is the whole reason `gstRate` distinguishes
+     * `undefined` from `0`.
+     */
+    findResolvable(id: string): Promise<TaxCodeDocument | null>;
+    /**
+     * Create with a DERIVED id, so the same HSN cannot exist twice.
+     *
+     * Two rows for one HSN is the failure worth preventing structurally: an
+     * admin edits one, categories point at the other, and the rate that reaches
+     * an invoice is whichever the data happens to reference. A 409 here is the
+     * right answer — the request is well-formed and the world already has it.
+     */
+    create(input: TaxCodeCreateInput): Promise<TaxCodeDocument>;
+    update(id: string, data: TaxCodeUpdateInput): Promise<TaxCodeDocument>;
+}
+export declare const taxCodesRepository: TaxCodesRepository;

package/dist/features/tax-codes/repository/tax-codes.repository.js

@@ -0,0 +1,131 @@
+import { normalizeError } from "../../../errors/normalize";
+import { DatabaseError, ConflictError, ValidationError } from "../../../errors";
+import { BaseRepository, } from "../../../providers/db-firebase";
+import { TAX_CODES_COLLECTION, TAX_CODE_FIELDS, TAX_CODE_SIEVE_FIELDS, createTaxCodeId, isValidHsnCode, } from "../schemas/firestore";
+function failureMessage(prefix, error) {
+    return `${prefix}: ${error instanceof Error ? error.message : "Unknown error"}`;
+}
+/**
+ * The `taxCodes` collection.
+ *
+ * Small, read-mostly and read on a hot path — `deriveTaxonomy` resolves a
+ * category's `taxCodeId` on every product create and on any update that names
+ * a taxonomy field. So the two reads below are single-document and
+ * single-field-equality shaped on purpose; neither needs a composite index.
+ */
+export class TaxCodesRepository extends BaseRepository {
+    constructor() {
+        super(TAX_CODES_COLLECTION);
+    }
+    async list(model) {
+        return this.sieveQuery(model, TAX_CODE_SIEVE_FIELDS);
+    }
+    /**
+     * Every active code, chapter-then-rate ordered, for the picker.
+     *
+     * Unpaginated deliberately — this is ~10 rows and will be a few dozen at
+     * most. If it ever needs paging, the picker needs `searchTxt` first, and
+     * that is a different change.
+     */
+    async listActive() {
+        try {
+            const snap = await this.getCollection()
+                .where(TAX_CODE_FIELDS.IS_ACTIVE, "==", true)
+                .get();
+            return snap.docs
+                .map((d) => this.mapDoc(d))
+                .sort((a, b) => (a.chapter ?? "").localeCompare(b.chapter ?? "") ||
+                a.gstRate - b.gstRate ||
+                a.label.localeCompare(b.label));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(failureMessage("Failed to list tax codes", error));
+        }
+    }
+    /**
+     * Every code including inactive ones, for the admin list.
+     *
+     * 🛑 EXPLICITLY bounded, even though the collection is five rows. Two
+     * reasons: `BaseRepository.findAll()` relies on a cap several layers away
+     * (`base.ts` clamps perPage at 500), and a route that reads "all of a
+     * collection" with no visible bound is the shape that has to be re-audited
+     * every time somebody wonders whether it is safe. 200 is far above any
+     * plausible number of HSN codes and far below anything that costs.
+     */
+    async listAllBounded() {
+        try {
+            const snap = await this.getCollection().limit(200).get();
+            return snap.docs
+                .map((d) => this.mapDoc(d))
+                .sort((a, b) => a.label.localeCompare(b.label));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(failureMessage("Failed to list tax codes", error));
+        }
+    }
+    /**
+     * Resolve a code for derivation.
+     *
+     * 🛑 Returns `null` for an INACTIVE code as well as a missing one, and the
+     * caller must treat both the same way: leave the product's `gstRate` and
+     * `hsnCode` alone rather than writing a zero. Deactivating a code must not
+     * silently re-rate the next listing to 0% — that is indistinguishable from a
+     * deliberate exemption, which is the whole reason `gstRate` distinguishes
+     * `undefined` from `0`.
+     */
+    async findResolvable(id) {
+        try {
+            const snap = await this.getCollection().doc(id).get();
+            if (!snap.exists)
+                return null;
+            const doc = this.mapDoc(snap);
+            return doc.isActive ? doc : null;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(failureMessage("Failed to read tax code", error));
+        }
+    }
+    /**
+     * Create with a DERIVED id, so the same HSN cannot exist twice.
+     *
+     * Two rows for one HSN is the failure worth preventing structurally: an
+     * admin edits one, categories point at the other, and the rate that reaches
+     * an invoice is whichever the data happens to reference. A 409 here is the
+     * right answer — the request is well-formed and the world already has it.
+     */
+    async create(input) {
+        const hsn = input.hsnCode?.trim() ?? "";
+        if (hsn !== "" && !isValidHsnCode(hsn)) {
+            throw new ValidationError("An HSN code must be exactly 4, 6 or 8 digits.", { hsnCode: "Must be 4, 6 or 8 digits." });
+        }
+        if (hsn === "" && input.gstRate !== 0) {
+            throw new ValidationError("An HSN code is required for any rate above 0%.", { hsnCode: "Required unless the rate is 0%." });
+        }
+        const id = createTaxCodeId(hsn);
+        const existing = await this.getCollection().doc(id).get();
+        if (existing.exists) {
+            throw new ConflictError(`A tax code for HSN ${hsn || "(exempt)"} already exists. Edit it instead of creating a second one.`);
+        }
+        return this.createWithId(id, { ...input, hsnCode: hsn });
+    }
+    async update(id, data) {
+        /*
+         * 🛑 `hsnCode` is editable but the id is NOT re-derived from it. Changing
+         * the id would orphan every `CategoryProductDefaults.taxCodeId` pointing
+         * here — the mirror-drift shape of Root Cause #42, with an invoice at the
+         * end of it. To correct a wrong HSN: deactivate this row, create the right
+         * one, and repoint the categories.
+         */
+        if (data.hsnCode !== undefined) {
+            const hsn = data.hsnCode.trim();
+            if (hsn !== "" && !isValidHsnCode(hsn)) {
+                throw new ValidationError("An HSN code must be exactly 4, 6 or 8 digits.", { hsnCode: "Must be 4, 6 or 8 digits." });
+            }
+        }
+        return super.update(id, data);
+    }
+}
+export const taxCodesRepository = new TaxCodesRepository();

package/dist/features/tax-codes/schemas/firestore.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Tax codes — Firestore schema
+ *
+ * An HSN code and its GST rate, as an ENTITY rather than two fields repeated
+ * across every category. Changing a rate becomes one edit instead of ~330.
+ *
+ * ## 🛑 The reference is for AUTHORING. The scalars stay for CORRECTNESS.
+ *
+ * `CategoryProductDefaults.taxCodeId` points here, and `deriveTaxonomy`
+ * resolves it to `ProductDocument.gstRate` / `.hsnCode` **on the product**;
+ * the order item then snapshots from the product, exactly as it already does.
+ *
+ * That layering is not redundancy. Without it, editing a tax code would
+ * retroactively change the GST on orders already invoiced — a compliance
+ * problem, not a modelling preference. It is the same reason
+ * `OrderDocumentItem` already snapshots `hsnCode`/`gstRate`.
+ *
+ *   a category edit  -> changes future listings
+ *   a tax-code edit  -> changes future derivations
+ *   nothing          -> rewrites a past sale
+ *
+ * ## Why this exists at all
+ *
+ * GST has never been charged on goods here. Recorded in our own source
+ * (`_internal/server/features/checkout/actions.ts`): *"0 of 40 live orders had
+ * a `gstAmount`, and the order page's Tax row had never rendered."* And
+ * `gstRate` is set on zero of the current products.
+ *
+ * id === slug, prefix "tax-".
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const TAX_CODES_COLLECTION: "taxCodes";
+export declare const TAX_CODE_PREFIX: "tax-";
+/**
+ * The GST slabs. A closed union because a rate outside it is a data error, not
+ * a new option — and because `ProductDocument.gstRate` already declares this
+ * exact set, so a wider type here would not survive the derivation.
+ */
+export type GstRate = 0 | 5 | 12 | 18 | 28;
+export declare const GST_RATE_VALUES: readonly [0, 5, 12, 18, 28];
+/**
+ * HSN chapters this catalogue touches.
+ *
+ * 🛑 Only **9503** is verified. 4911 (printed cards/stickers/posters) and 9504
+ * (playing cards, board games) are the correct chapters for that merchandise
+ * and their CURRENT RATES ARE NOT CONFIRMED — the toys rates themselves moved
+ * in the 2025 revision. Verify before seeding a rate against either, because a
+ * wrong HSN on a real invoice is worse than an absent one.
+ */
+export type HsnChapter = "9503" | "4911" | "9504" | "exempt";
+export interface TaxCodeDocument extends BaseDocument {
+    /** 4, 6 or 8 digits. Empty for the exemption row, which has no HSN. */
+    hsnCode: string;
+    /** Picker label, e.g. "Toys, non-electronic (HSN 9503 0020) — 5%". */
+    label: string;
+    description?: string;
+    gstRate: GstRate;
+    /** Groups the picker. ~10 rows today, more once 4911/9504 are verified. */
+    chapter?: HsnChapter;
+    /**
+     * When the CURRENT rate took effect. Informational — it does NOT rewrite
+     * history, because history lives in the per-product and per-order-item
+     * snapshots. Recorded so an admin can tell a rate that has always been 5%
+     * from one that changed.
+     */
+    effectiveFrom?: Date;
+    isActive: boolean;
+    /** Why this rate, and what it covers — the thing a future admin will want. */
+    notes?: string;
+}
+export type TaxCodeCreateInput = Omit<TaxCodeDocument, "id" | "createdAt" | "updatedAt">;
+export declare const TAX_CODE_UPDATABLE_FIELDS: readonly ["hsnCode", "label", "description", "gstRate", "chapter", "effectiveFrom", "isActive", "notes"];
+export type TaxCodeUpdateInput = Partial<Pick<TaxCodeDocument, (typeof TAX_CODE_UPDATABLE_FIELDS)[number]>>;
+export declare const TAX_CODE_FIELDS: {
+    readonly ID: "id";
+    readonly HSN_CODE: "hsnCode";
+    readonly LABEL: "label";
+    readonly GST_RATE: "gstRate";
+    readonly CHAPTER: "chapter";
+    readonly IS_ACTIVE: "isActive";
+    readonly EFFECTIVE_FROM: "effectiveFrom";
+    readonly CREATED_AT: "createdAt";
+    readonly UPDATED_AT: "updatedAt";
+};
+export declare const TAX_CODE_SIEVE_FIELDS: {
+    readonly label: {
+        readonly canFilter: true;
+        readonly canSort: true;
+    };
+    readonly hsnCode: {
+        readonly canFilter: true;
+        readonly canSort: true;
+    };
+    readonly gstRate: {
+        readonly canFilter: true;
+        readonly canSort: true;
+    };
+    readonly chapter: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
+    readonly isActive: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
+    readonly createdAt: {
+        readonly canFilter: false;
+        readonly canSort: true;
+    };
+};
+/**
+ * Derive the document id from the HSN code.
+ *
+ * Deterministic, so a seed run is idempotent (Root Cause #25) and so the same
+ * HSN cannot be entered twice under two ids — which would give two rows one
+ * admin edits and the other serves.
+ */
+export declare function createTaxCodeId(hsnCode: string): string;
+/**
+ * India's HSN codes are 4, 6 or 8 digits. Checked rather than trusted because
+ * the inline-create path in the seller form reaches the same route as the
+ * admin editor, and a malformed code propagates onto every product derived
+ * from the category that points at it.
+ */
+export declare function isValidHsnCode(hsnCode: string): boolean;