@mohasinac/appkit 4.42.18 → 4.44.0

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;

package/dist/features/tax-codes/schemas/firestore.js

@@ -0,0 +1,82 @@
+/**
+ * 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-".
+ */
+export const TAX_CODES_COLLECTION = "taxCodes";
+export const TAX_CODE_PREFIX = "tax-";
+export const GST_RATE_VALUES = [0, 5, 12, 18, 28];
+export const TAX_CODE_UPDATABLE_FIELDS = [
+    "hsnCode",
+    "label",
+    "description",
+    "gstRate",
+    "chapter",
+    "effectiveFrom",
+    "isActive",
+    "notes",
+];
+export const TAX_CODE_FIELDS = {
+    ID: "id",
+    HSN_CODE: "hsnCode",
+    LABEL: "label",
+    GST_RATE: "gstRate",
+    CHAPTER: "chapter",
+    IS_ACTIVE: "isActive",
+    EFFECTIVE_FROM: "effectiveFrom",
+    CREATED_AT: "createdAt",
+    UPDATED_AT: "updatedAt",
+};
+export const TAX_CODE_SIEVE_FIELDS = {
+    label: { canFilter: true, canSort: true },
+    hsnCode: { canFilter: true, canSort: true },
+    gstRate: { canFilter: true, canSort: true },
+    chapter: { canFilter: true, canSort: false },
+    isActive: { canFilter: true, canSort: false },
+    createdAt: { canFilter: false, 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 function createTaxCodeId(hsnCode) {
+    const digits = hsnCode.replace(/\D/g, "");
+    return digits ? `${TAX_CODE_PREFIX}hsn-${digits}` : `${TAX_CODE_PREFIX}exempt-0`;
+}
+/**
+ * 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 function isValidHsnCode(hsnCode) {
+    return /^(\d{4}|\d{6}|\d{8})$/.test(hsnCode.trim());
+}

package/dist/features/tax-codes/schemas/tax-code-form.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+/** The GST slabs, as the rate select offers them. */
+export declare const GST_RATE_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/**
+ * Chapter options.
+ *
+ * 🛑 The two non-9503 chapters are offered because the merchandise exists
+ * (printed cards and stickers; playing cards), and their labels say the rate is
+ * unverified rather than implying one. Picking a chapter does not set a rate.
+ */
+export declare const HSN_CHAPTER_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const taxCodeFormSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    hsnCode: z.ZodOptional<z.ZodString>;
+    gstRate: z.ZodEffects<z.ZodNumber, number, number>;
+    chapter: z.ZodOptional<z.ZodEnum<["9503", "4911", "9504", "exempt"]>>;
+    description: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    isActive: boolean;
+    gstRate: number;
+    description?: string | undefined;
+    notes?: string | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+}, {
+    label: string;
+    isActive: boolean;
+    gstRate: number;
+    description?: string | undefined;
+    notes?: string | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+}>, {
+    label: string;
+    isActive: boolean;
+    gstRate: number;
+    description?: string | undefined;
+    notes?: string | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+}, {
+    label: string;
+    isActive: boolean;
+    gstRate: number;
+    description?: string | undefined;
+    notes?: string | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+}>;
+export type TaxCodeFormValues = z.infer<typeof taxCodeFormSchema>;

package/dist/features/tax-codes/schemas/tax-code-form.js

@@ -0,0 +1,152 @@
+/*
+ * WHAT: The tax-code editor's schema — the field set, annotated for
+ *       `buildSectionsFromSchema`, with the HSN-format rule as a refinement
+ *       rather than a hint under the input.
+ *
+ * ## 🛑 Why the HSN rule is a refinement and not placeholder text
+ *
+ * A malformed HSN does not fail loudly. It propagates: a category points at
+ * the tax code, `deriveTaxonomy` writes `hsnCode` onto every product derived
+ * from that category, and the order item snapshots it onto a GST invoice.
+ * Nothing in that chain validates the string again, and the invoice is the
+ * first place a human might notice — by which point the sale is recorded.
+ *
+ * So the format is checked at the one place it enters the system. The same
+ * route serves the inline-create path in the seller form, which is the busiest
+ * surface and the one most likely to be used in a hurry.
+ *
+ * ## The exemption row is the reason `hsnCode` is not simply required
+ *
+ * A 0% row (live plants, live animals) has no HSN. Requiring one would force
+ * an author to invent a code to express an exemption, and an invented HSN on
+ * an invoice is exactly the failure above. So the refinement is conditional:
+ * blank is legal only at rate 0.
+ *
+ * 🛑 The two option arrays are exported for the VIEW to pass as
+ * `options: { gstRate: GST_RATE_OPTIONS, chapter: HSN_CHAPTER_OPTIONS }` —
+ * `FieldUiMeta` has no `options` key, and `annotate` would silently accept
+ * neither. That split follows `AdminBundleEditorView`, which supplies
+ * `BUNDLE_RULE_TYPE_OPTIONS` the same way: a select's VALUES are schema, its
+ * option list is often runtime data (brands, categories) and so belongs to
+ * whoever can fetch it.
+ *
+ * EXPORTS:
+ *   taxCodeFormSchema, type TaxCodeFormValues, GST_RATE_OPTIONS,
+ *   HSN_CHAPTER_OPTIONS
+ *
+ * @tag domain:tax-codes
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminTaxCodeEditorView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { GST_RATE_VALUES, isValidHsnCode } from "./firestore";
+/** The GST slabs, as the rate select offers them. */
+export const GST_RATE_OPTIONS = GST_RATE_VALUES.map((r) => ({
+    value: String(r),
+    label: r === 0 ? "0% — exempt" : `${r}%`,
+}));
+/**
+ * Chapter options.
+ *
+ * 🛑 The two non-9503 chapters are offered because the merchandise exists
+ * (printed cards and stickers; playing cards), and their labels say the rate is
+ * unverified rather than implying one. Picking a chapter does not set a rate.
+ */
+export const HSN_CHAPTER_OPTIONS = [
+    { value: "9503", label: "9503 — Toys (verified)" },
+    { value: "4911", label: "4911 — Printed matter: cards, stickers, posters (rate unverified)" },
+    { value: "9504", label: "9504 — Playing cards, board games (rate unverified)" },
+    { value: "exempt", label: "Exempt — no HSN" },
+];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const taxCodeFormSchema = z
+    .object({
+    label: annotate(z
+        .string()
+        .min(1, "Give the code a label an admin will recognise in a picker.")
+        .max(150, "Keep the label under 150 characters."), {
+        section: "basics",
+        sectionLabel: "Tax code",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        label: "Label",
+        help: 'What the picker shows, e.g. "Toys, non-electronic (HSN 9503 0020) — 5%".',
+    }),
+    /*
+     * A STRING, not a number: leading zeros are significant in an HSN code
+     * (`04` is not `4`) and a numeric input would eat them. Digits-only is
+     * enforced by the refinement below, against the real 4/6/8-digit rule.
+     */
+    hsnCode: annotate(z.string().trim().max(8, "An HSN code is at most 8 digits.").optional(), {
+        section: "basics",
+        quick: true,
+        order: 2,
+        row: "pair",
+        label: "HSN code",
+        help: "4, 6 or 8 digits. Leave blank only for a 0% exemption.",
+    }),
+    gstRate: annotate(z.coerce
+        .number()
+        .refine((v) => GST_RATE_VALUES.includes(v), {
+        message: "Pick one of the GST slabs: 0, 5, 12, 18 or 28.",
+    }), {
+        section: "basics",
+        sectionRequired: true,
+        quick: true,
+        order: 3,
+        row: "pair",
+        kind: "select",
+        label: "GST rate",
+    }),
+    chapter: annotate(z.enum(["9503", "4911", "9504", "exempt"]).optional(), {
+        section: "basics",
+        order: 4,
+        kind: "select",
+        label: "Chapter",
+        help: "Groups the picker. Only chapter 9503's rates are verified.",
+    }),
+    description: annotate(z.string().max(500).optional(), { section: "detail", sectionLabel: "Detail", order: 1, kind: "textarea", label: "Description" }),
+    notes: annotate(z.string().max(1000).optional(), {
+        section: "detail",
+        order: 2,
+        kind: "textarea",
+        label: "Notes",
+        help: "Why this rate, and what it covers. The thing a future admin will want.",
+    }),
+    isActive: annotate(z.boolean(), {
+        section: "detail",
+        order: 3,
+        label: "Active",
+        help: "An inactive code is never resolved onto a product, and disappears from the picker.",
+    }),
+})
+    .superRefine((values, ctx) => {
+    const hsn = values.hsnCode?.trim() ?? "";
+    // Blank is legal ONLY at 0%. See the header: forcing an HSN on an exemption
+    // is what gets a code invented, and an invented code reaches an invoice.
+    if (hsn === "") {
+        if (values.gstRate !== 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["hsnCode"],
+                message: "An HSN code is required for any rate above 0%. Leave it blank only to record an exemption.",
+            });
+        }
+        return;
+    }
+    if (!isValidHsnCode(hsn)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["hsnCode"],
+            message: "An HSN code must be exactly 4, 6 or 8 digits — no spaces or dots.",
+        });
+    }
+});

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

@@ -0,0 +1,107 @@
+/**
+ * Zod validators for the `/api/admin/tax-codes` route handlers.
+ *
+ * Separate from `tax-code-form.ts`, which is the EDITOR's schema: that one is
+ * annotated for `buildSectionsFromSchema`, takes strings from inputs, and
+ * coerces. These are the wire contracts, and they are `.strict()`.
+ *
+ * ## 🛑 `.strict()`, not `z.object()` and not `.passthrough()`
+ *
+ * `z.object()` STRIPS unknown keys, which is how a PATCH returns 200 having
+ * written nothing (Root Cause #40's shape, and the admin grouped-listings
+ * route's documented bug). `.passthrough()` writes whatever arrives, which is
+ * how a form overwrote booked lottery slots. `.strict()` 400s on a field the
+ * contract does not name — the caller is told, and nothing silently vanishes.
+ *
+ * ## The id is NOT accepted on update
+ *
+ * `createTaxCodeId` derives the id from the HSN code, so accepting an id (or
+ * re-deriving one on update) would let an edit orphan every
+ * `CategoryProductDefaults.taxCodeId` pointing at the old one — with a GST
+ * invoice at the end of that chain. To correct a wrong HSN: deactivate, create
+ * the right row, repoint the categories.
+ */
+import { z } from "zod";
+/**
+ * 🛑 `z.custom<GstRate>`, not `z.number().refine(...)`.
+ *
+ * A `.refine()` validates at runtime and does NOT narrow the inferred type —
+ * the payload still types as `number`, so `repository.create(body)` fails to
+ * compile against `gstRate: GstRate`, and the obvious unblock is a cast. A
+ * cast at a request boundary is where this codebase's worst bugs live (an
+ * `ActionResult` envelope spread as a product, a raw `StoreDocument` published
+ * as HTML), so the type is narrowed here instead.
+ *
+ * And `z.custom` rather than a hand-written `z.union([z.literal(0), …])`
+ * because the slab list then has ONE definition — `GST_RATE_VALUES`, which
+ * `ProductDocument.gstRate` and the form's option list also derive from. A
+ * literal union here would be a second enumeration of the same union, which is
+ * Root Cause #61's shape.
+ */
+export declare const GST_RATE_ENUM: z.ZodType<0 | 5 | 12 | 18 | 28, z.ZodTypeDef, 0 | 5 | 12 | 18 | 28>;
+export declare const HSN_CHAPTER_ENUM: z.ZodEnum<["9503", "4911", "9504", "exempt"]>;
+/**
+ * 🛑 `hsnCode` is OPTIONAL here and the blank-only-at-0% rule lives in the
+ * repository, not this schema. Deliberate: the same rule has to hold for the
+ * seed path and any future importer, neither of which goes through a Zod
+ * request schema. A rule enforced only at the HTTP edge is a rule with a side
+ * door.
+ */
+export declare const taxCodeCreateSchema: z.ZodObject<{
+    hsnCode: z.ZodDefault<z.ZodString>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    gstRate: z.ZodType<0 | 5 | 12 | 18 | 28, z.ZodTypeDef, 0 | 5 | 12 | 18 | 28>;
+    chapter: z.ZodOptional<z.ZodEnum<["9503", "4911", "9504", "exempt"]>>;
+    effectiveFrom: z.ZodOptional<z.ZodDate>;
+    isActive: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    label: string;
+    isActive: boolean;
+    gstRate: 0 | 5 | 12 | 18 | 28;
+    hsnCode: string;
+    description?: string | undefined;
+    notes?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+    effectiveFrom?: Date | undefined;
+}, {
+    label: string;
+    gstRate: 0 | 5 | 12 | 18 | 28;
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    notes?: string | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+    effectiveFrom?: Date | undefined;
+}>;
+export type TaxCodeCreatePayload = z.infer<typeof taxCodeCreateSchema>;
+export declare const taxCodeUpdateSchema: z.ZodObject<{
+    hsnCode: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    gstRate: z.ZodOptional<z.ZodType<0 | 5 | 12 | 18 | 28, z.ZodTypeDef, 0 | 5 | 12 | 18 | 28>>;
+    chapter: z.ZodOptional<z.ZodEnum<["9503", "4911", "9504", "exempt"]>>;
+    effectiveFrom: z.ZodOptional<z.ZodDate>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    label?: string | undefined;
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    notes?: string | undefined;
+    gstRate?: 0 | 5 | 12 | 18 | 28 | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+    effectiveFrom?: Date | undefined;
+}, {
+    label?: string | undefined;
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    notes?: string | undefined;
+    gstRate?: 0 | 5 | 12 | 18 | 28 | undefined;
+    hsnCode?: string | undefined;
+    chapter?: "9503" | "4911" | "9504" | "exempt" | undefined;
+    effectiveFrom?: Date | undefined;
+}>;
+export type TaxCodeUpdatePayload = z.infer<typeof taxCodeUpdateSchema>;