@classytic/validation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Classytic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @classytic/validation
+
+Isomorphic **zod** validation schemas shared server↔client. Framework-agnostic
+(`zod` is the only peer), so the same rules run in the catalog kernel (Arc
+auto-CRUD, repository writes) and in admin/storefront forms — one
+implementation, zero drift.
+
+**Charter:** zod-based validation shared between server and client lives here.
+Zod-free value objects / pure functions belong in `@classytic/primitives`;
+wire/transport types in `@classytic/repo-core`.
+
+## Modules
+
+### `@classytic/validation/barcode`
+
+```ts
+import {
+  validateGTIN,
+  validateISBN,
+  detectBarcodeFormat,
+  optionalScannableBarcodeSchema,
+} from "@classytic/validation/barcode";
+
+validateGTIN("4006381333931");        // true
+detectBarcodeFormat("9780306406157"); // "ISBN13"
+const product = z.object({ barcode: optionalScannableBarcodeSchema });
+```
+
+| Format | Length | Checksum |
+|---|---|---|
+| EAN-13 | 13 | mod-10 (1,3,1,3…) |
+| EAN-8 | 8 | mod-10 (3,1,3,1…) |
+| UPC-A | 12 | mod-10 (3,1,3,1…) |
+| GTIN-14 | 14 | mod-10 (3,1,3,1…) |
+| ISBN-10 | 10 (or 9+`X`) | mod-11 |
+| ISBN-13 | 13 (`978`/`979`) | EAN-13 |
+| CODE128 | ≥4 | printable ASCII (no checksum) |
+
+### `@classytic/validation/identifiers`
+
+`productIdentifiersSchema` — a product's standard IDs (`gtin`/`upc`/`ean`/`isbn`
+checksum-validated, `mpn`/`plu` length-only, `custom` open map).
+
+Both modules are also re-exported flat from the package root
+(`@classytic/validation`).

package/dist/barcode.d.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+//#region src/barcode.d.ts
+/**
+ * Barcode primitives — pure checksum + format detection.
+ *
+ * These are framework-agnostic predicates. Zod schemas in this file compose
+ * them via `.refine()`/`.superRefine()` so the same validation runs on the
+ * server (Arc auto-CRUD, Express, Nest, direct `repository.create()`) AND in
+ * the browser (admin product forms, storefront) — one implementation, zero
+ * drift.
+ *
+ * Format coverage (the formats POS scanners actually emit):
+ *   - EAN-13   — 13 digits, mod-10 with positions weighted 1,3,1,3,…
+ *   - EAN-8    —  8 digits, mod-10 with positions weighted 3,1,3,1,…
+ *   - UPC-A    — 12 digits, mod-10 with positions weighted 3,1,3,1,…
+ *   - GTIN-14  — 14 digits, mod-10 with positions weighted 3,1,3,1,…
+ *   - ISBN-10  — 10 digits or 9 digits + 'X', mod-11 weighted 10..1
+ *   - ISBN-13  — 13 digits with '978'/'979' prefix, EAN-13 checksum
+ *
+ * For non-numeric scan codes (CODE128, internal alphanumerics) we accept
+ * any printable ASCII >= 4 chars — JsBarcode and most retail scanners
+ * round-trip those losslessly.
+ */
+/**
+ * EAN-13 mod-10 checksum.
+ *
+ * Sum of digits at odd positions × 1 + digits at even positions × 3, then
+ * the check digit is `(10 - sum % 10) % 10`. Used for EAN-13 and ISBN-13.
+ */
+declare function validateEAN13(value: string): boolean;
+declare function validateUPCA(value: string): boolean;
+declare function validateEAN8(value: string): boolean;
+declare function validateGTIN14(value: string): boolean;
+/**
+ * GTIN — accepts 8, 12, 13, or 14 digits and routes to the corresponding
+ * mod-10 validator. GTIN is the umbrella standard; EAN-13 is GTIN-13 with
+ * a leading zero, UPC-A is GTIN-12 with a leading zero, etc.
+ */
+declare function validateGTIN(value: string): boolean;
+/**
+ * ISBN-10 mod-11 checksum. Last position can be 'X' representing 10.
+ */
+declare function validateISBN10(value: string): boolean;
+/**
+ * ISBN-13 — must start with 978 or 979 and pass the EAN-13 checksum.
+ */
+declare function validateISBN13(value: string): boolean;
+/**
+ * Accepts ISBN-10 or ISBN-13. Allows hyphens for human readability — they
+ * are stripped before validation. Caller decides whether to persist the
+ * stripped or original form.
+ */
+declare function validateISBN(value: string): boolean;
+type BarcodeFormat = 'EAN13' | 'EAN8' | 'UPCA' | 'GTIN14' | 'ISBN10' | 'ISBN13' | 'CODE128' | 'UNKNOWN';
+/**
+ * Detect the most specific scannable format that matches `value`.
+ * Returns `'UNKNOWN'` for values that don't match any standard format.
+ */
+declare function detectBarcodeFormat(value: string): BarcodeFormat;
+/**
+ * Validate any user-entered scannable barcode value.
+ *
+ *   - Empty string → invalid (callers should mark the field optional and
+ *     skip empties before calling).
+ *   - Any recognised format → must pass its checksum.
+ *   - Numeric strings of an unrecognised length (9, 10, 11, 14+ digits not
+ *     matching ISBN/GTIN-14) → rejected — POS scanners can't read them.
+ *   - Printable ASCII ≥ 4 chars → accepted as CODE128.
+ *
+ * Returns `null` for valid input, otherwise a human-readable reason.
+ */
+declare function validateScannableBarcode(value: string): string | null;
+/**
+ * A scannable barcode value. Empty strings are rejected — callers wanting
+ * an optional field wrap this in `.optional()` (or pass `undefined`/omit
+ * the field). Length and checksum errors surface a human-readable reason
+ * via Zod's standard error message channel.
+ */
+declare const scannableBarcodeSchema: z.ZodString;
+/**
+ * Optional variant of the above. Use this on schema fields where the
+ * barcode may be unset — `barcode?: string` style.
+ */
+declare const optionalScannableBarcodeSchema: z.ZodOptional<z.ZodString>;
+/** GTIN — 8/12/13/14 digits, checksum-validated. */
+declare const gtinSchema: z.ZodString;
+/** UPC-A — 12 digits, mod-10 checksum. */
+declare const upcaSchema: z.ZodString;
+/** EAN-13 — 13 digits, mod-10 checksum. */
+declare const ean13Schema: z.ZodString;
+/** EAN-8 — 8 digits, mod-10 checksum. */
+declare const ean8Schema: z.ZodString;
+/**
+ * ISBN — accepts ISBN-10 or ISBN-13 (with or without hyphens). The stored
+ * value is whatever the caller passed; downstream consumers can normalise.
+ */
+declare const isbnSchema: z.ZodString;
+//#endregion
+export { BarcodeFormat, detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA };

package/dist/barcode.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+//#region src/barcode.ts
+/**
+* Barcode primitives — pure checksum + format detection.
+*
+* These are framework-agnostic predicates. Zod schemas in this file compose
+* them via `.refine()`/`.superRefine()` so the same validation runs on the
+* server (Arc auto-CRUD, Express, Nest, direct `repository.create()`) AND in
+* the browser (admin product forms, storefront) — one implementation, zero
+* drift.
+*
+* Format coverage (the formats POS scanners actually emit):
+*   - EAN-13   — 13 digits, mod-10 with positions weighted 1,3,1,3,…
+*   - EAN-8    —  8 digits, mod-10 with positions weighted 3,1,3,1,…
+*   - UPC-A    — 12 digits, mod-10 with positions weighted 3,1,3,1,…
+*   - GTIN-14  — 14 digits, mod-10 with positions weighted 3,1,3,1,…
+*   - ISBN-10  — 10 digits or 9 digits + 'X', mod-11 weighted 10..1
+*   - ISBN-13  — 13 digits with '978'/'979' prefix, EAN-13 checksum
+*
+* For non-numeric scan codes (CODE128, internal alphanumerics) we accept
+* any printable ASCII >= 4 chars — JsBarcode and most retail scanners
+* round-trip those losslessly.
+*/
+/**
+* EAN-13 mod-10 checksum.
+*
+* Sum of digits at odd positions × 1 + digits at even positions × 3, then
+* the check digit is `(10 - sum % 10) % 10`. Used for EAN-13 and ISBN-13.
+*/
+function validateEAN13(value) {
+	if (!/^\d{13}$/.test(value)) return false;
+	const digits = value.split("").map(Number);
+	const check = digits.pop();
+	let sum = 0;
+	for (let i = 0; i < 12; i++) sum += digits[i] * (i % 2 === 0 ? 1 : 3);
+	return (10 - sum % 10) % 10 === check;
+}
+/**
+* UPC-A mod-10 checksum (and GTIN-14, EAN-8 — same mod-10, different length
+* with 3,1,3,1 weighting starting from the leftmost digit).
+*/
+function mod10WithLeading3(digits) {
+	let sum = 0;
+	for (let i = 0; i < digits.length; i++) sum += digits[i] * (i % 2 === 0 ? 3 : 1);
+	return (10 - sum % 10) % 10;
+}
+function validateUPCA(value) {
+	if (!/^\d{12}$/.test(value)) return false;
+	const digits = value.split("").map(Number);
+	const check = digits.pop();
+	return mod10WithLeading3(digits) === check;
+}
+function validateEAN8(value) {
+	if (!/^\d{8}$/.test(value)) return false;
+	const digits = value.split("").map(Number);
+	const check = digits.pop();
+	return mod10WithLeading3(digits) === check;
+}
+function validateGTIN14(value) {
+	if (!/^\d{14}$/.test(value)) return false;
+	const digits = value.split("").map(Number);
+	const check = digits.pop();
+	return mod10WithLeading3(digits) === check;
+}
+/**
+* GTIN — accepts 8, 12, 13, or 14 digits and routes to the corresponding
+* mod-10 validator. GTIN is the umbrella standard; EAN-13 is GTIN-13 with
+* a leading zero, UPC-A is GTIN-12 with a leading zero, etc.
+*/
+function validateGTIN(value) {
+	switch (value.length) {
+		case 8: return validateEAN8(value);
+		case 12: return validateUPCA(value);
+		case 13: return validateEAN13(value);
+		case 14: return validateGTIN14(value);
+		default: return false;
+	}
+}
+/**
+* ISBN-10 mod-11 checksum. Last position can be 'X' representing 10.
+*/
+function validateISBN10(value) {
+	if (!/^\d{9}[\dX]$/.test(value)) return false;
+	let sum = 0;
+	for (let i = 0; i < 9; i++) sum += Number(value[i]) * (10 - i);
+	const last = value[9] === "X" ? 10 : Number(value[9]);
+	sum += last;
+	return sum % 11 === 0;
+}
+/**
+* ISBN-13 — must start with 978 or 979 and pass the EAN-13 checksum.
+*/
+function validateISBN13(value) {
+	if (!/^97[89]\d{10}$/.test(value)) return false;
+	return validateEAN13(value);
+}
+/**
+* Accepts ISBN-10 or ISBN-13. Allows hyphens for human readability — they
+* are stripped before validation. Caller decides whether to persist the
+* stripped or original form.
+*/
+function validateISBN(value) {
+	const stripped = value.replace(/-/g, "");
+	return validateISBN10(stripped) || validateISBN13(stripped);
+}
+/**
+* Detect the most specific scannable format that matches `value`.
+* Returns `'UNKNOWN'` for values that don't match any standard format.
+*/
+function detectBarcodeFormat(value) {
+	if (!value) return "UNKNOWN";
+	if (/^\d{14}$/.test(value)) return validateGTIN14(value) ? "GTIN14" : "UNKNOWN";
+	if (/^97[89]\d{10}$/.test(value)) return validateISBN13(value) ? "ISBN13" : "UNKNOWN";
+	if (/^\d{13}$/.test(value)) return validateEAN13(value) ? "EAN13" : "UNKNOWN";
+	if (/^\d{12}$/.test(value)) return validateUPCA(value) ? "UPCA" : "UNKNOWN";
+	if (/^\d{9}[\dX]$/.test(value)) return validateISBN10(value) ? "ISBN10" : "UNKNOWN";
+	if (/^\d{8}$/.test(value)) return validateEAN8(value) ? "EAN8" : "UNKNOWN";
+	if (/^\d+$/.test(value)) return "UNKNOWN";
+	if (/^[\x20-\x7E]{4,}$/.test(value)) return "CODE128";
+	return "UNKNOWN";
+}
+/**
+* Validate any user-entered scannable barcode value.
+*
+*   - Empty string → invalid (callers should mark the field optional and
+*     skip empties before calling).
+*   - Any recognised format → must pass its checksum.
+*   - Numeric strings of an unrecognised length (9, 10, 11, 14+ digits not
+*     matching ISBN/GTIN-14) → rejected — POS scanners can't read them.
+*   - Printable ASCII ≥ 4 chars → accepted as CODE128.
+*
+* Returns `null` for valid input, otherwise a human-readable reason.
+*/
+function validateScannableBarcode(value) {
+	if (!value) return "Barcode is empty";
+	if (detectBarcodeFormat(value) === "UNKNOWN") {
+		if (/^\d+$/.test(value)) return `Numeric barcode of length ${value.length} is not a valid scannable format (expected 8/12/13/14 digits)`;
+		return "Barcode must be a recognised scannable format (EAN/UPC/GTIN/ISBN) or printable ASCII ≥ 4 characters";
+	}
+	return null;
+}
+/**
+* A scannable barcode value. Empty strings are rejected — callers wanting
+* an optional field wrap this in `.optional()` (or pass `undefined`/omit
+* the field). Length and checksum errors surface a human-readable reason
+* via Zod's standard error message channel.
+*/
+const scannableBarcodeSchema = z.string().min(1, "Barcode cannot be empty").superRefine((value, ctx) => {
+	const reason = validateScannableBarcode(value);
+	if (reason) ctx.addIssue({
+		code: "custom",
+		message: reason
+	});
+});
+/**
+* Optional variant of the above. Use this on schema fields where the
+* barcode may be unset — `barcode?: string` style.
+*/
+const optionalScannableBarcodeSchema = scannableBarcodeSchema.optional();
+/** GTIN — 8/12/13/14 digits, checksum-validated. */
+const gtinSchema = z.string().regex(/^\d{8,14}$/, "GTIN must be 8, 12, 13, or 14 digits").refine(validateGTIN, "Invalid GTIN checksum");
+/** UPC-A — 12 digits, mod-10 checksum. */
+const upcaSchema = z.string().regex(/^\d{12}$/, "UPC-A must be 12 digits").refine(validateUPCA, "Invalid UPC-A checksum");
+/** EAN-13 — 13 digits, mod-10 checksum. */
+const ean13Schema = z.string().regex(/^\d{13}$/, "EAN-13 must be 13 digits").refine(validateEAN13, "Invalid EAN-13 checksum");
+/** EAN-8 — 8 digits, mod-10 checksum. */
+const ean8Schema = z.string().regex(/^\d{8}$/, "EAN-8 must be 8 digits").refine(validateEAN8, "Invalid EAN-8 checksum");
+/**
+* ISBN — accepts ISBN-10 or ISBN-13 (with or without hyphens). The stored
+* value is whatever the caller passed; downstream consumers can normalise.
+*/
+const isbnSchema = z.string().regex(/^[\dX-]{10,17}$/, "ISBN must be 10 or 13 digits, optionally hyphenated").refine(validateISBN, "Invalid ISBN checksum");
+//#endregion
+export { detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA };

package/dist/identifiers.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+//#region src/identifiers.d.ts
+/**
+ * Zod schema for a product's standard identifiers.
+ *
+ * Each standard identifier (GTIN/UPC/EAN/ISBN) is length-validated AND
+ * checksum-validated — see `barcode.ts` for the math. A wrong check digit is
+ * rejected at the Zod boundary, so it is also rejected wherever this schema
+ * is composed: server-side auto-CRUD, Express/Nest handlers, direct
+ * `repository.create()`, and client-side product forms.
+ *
+ * `mpn` and `plu` carry no checksum standard, so they're length-only.
+ * `custom` is an open map for platform-specific IDs (Amazon ASIN, Shopify
+ * GID, etc.) that no global standard can validate.
+ */
+declare const productIdentifiersSchema: z.ZodObject<{
+  gtin: z.ZodOptional<z.ZodString>;
+  upc: z.ZodOptional<z.ZodString>;
+  ean: z.ZodOptional<z.ZodString>;
+  isbn: z.ZodOptional<z.ZodString>;
+  mpn: z.ZodOptional<z.ZodString>;
+  plu: z.ZodOptional<z.ZodString>;
+  custom: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+//#endregion
+export { productIdentifiersSchema };

package/dist/identifiers.js

@@ -0,0 +1,27 @@
+import { ean13Schema, gtinSchema, isbnSchema, upcaSchema } from "./barcode.js";
+import { z } from "zod";
+//#region src/identifiers.ts
+/**
+* Zod schema for a product's standard identifiers.
+*
+* Each standard identifier (GTIN/UPC/EAN/ISBN) is length-validated AND
+* checksum-validated — see `barcode.ts` for the math. A wrong check digit is
+* rejected at the Zod boundary, so it is also rejected wherever this schema
+* is composed: server-side auto-CRUD, Express/Nest handlers, direct
+* `repository.create()`, and client-side product forms.
+*
+* `mpn` and `plu` carry no checksum standard, so they're length-only.
+* `custom` is an open map for platform-specific IDs (Amazon ASIN, Shopify
+* GID, etc.) that no global standard can validate.
+*/
+const productIdentifiersSchema = z.object({
+	gtin: gtinSchema.optional(),
+	upc: upcaSchema.optional(),
+	ean: ean13Schema.optional(),
+	isbn: isbnSchema.optional(),
+	mpn: z.string().min(1).max(100).optional(),
+	plu: z.string().regex(/^\d{4,5}$/).optional(),
+	custom: z.record(z.string(), z.string()).optional()
+});
+//#endregion
+export { productIdentifiersSchema };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { BarcodeFormat, detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA } from "./barcode.js";
+import { productIdentifiersSchema } from "./identifiers.js";
+export { type BarcodeFormat, detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, productIdentifiersSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA } from "./barcode.js";
+import { productIdentifiersSchema } from "./identifiers.js";
+export { detectBarcodeFormat, ean13Schema, ean8Schema, gtinSchema, isbnSchema, optionalScannableBarcodeSchema, productIdentifiersSchema, scannableBarcodeSchema, upcaSchema, validateEAN13, validateEAN8, validateGTIN, validateGTIN14, validateISBN, validateISBN10, validateISBN13, validateScannableBarcode, validateUPCA };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@classytic/validation",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Isomorphic zod validation schemas shared server<->client. Framework-agnostic, zod the only peer, so the same rules run in the catalog kernel (server auto-CRUD, repository writes) and in admin/storefront forms (browser). First module: barcode (GTIN/EAN/UPC/ISBN predicates + schemas).",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./barcode": {
+      "types": "./dist/barcode.d.ts",
+      "default": "./dist/barcode.js"
+    },
+    "./identifiers": {
+      "types": "./dist/identifiers.d.ts",
+      "default": "./dist/identifiers.js"
+    },
+    "./package.json": "./package.json"
+  }
+}