kabo-contracts 0.0.0-stage → 1.0.3

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# kabo-contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The data contracts shared by `kabobee-frontend` and `kabobee-backend`: [zod](https://zod.dev) schemas
+and enums, in plain JavaScript. A rule written here is enforced in the browser (form errors) **and**
+on the server (400 responses) with the same Bulgarian message.
+
+## What is in it
+
+| File | Exports | Used by |
+|---|---|---|
+| `src/enums.js` | `DELIVERY_METHOD`, `PAYMENT_METHOD`, `INVOICE_TYPE`, `MESSAGE_TYPE`, `PRODUCT_CATEGORY`, `PRODUCT_AUDIENCE`, `CURRENCY`, `MAX_ITEM_QUANTITY` | both |
+| `src/common.js` | `MESSAGES` (Bulgarian error texts), `EMAIL_REGEX`, `PHONE_NUMBER_REGEX`, building blocks (`requiredText`, `optionalText`, `econtId`, …) | both |
+| `src/order.js` | `checkoutSchema` (checkout form), `createOrderSchema` (`POST /orders` = form + `products`) | form / API |
+| `src/cart.js` | `cartItemSchema`, `cartItemsSchema`, `deliveryPriceRequestSchema` (`POST /econt/delivery/price`) | API |
+| `src/message.js` | `contactMessageSchema`, `wholesaleMessageSchema` (forms), `createMessageSchema` (`POST /messages`) | form / API |
+| `src/product.js` | `productInputSchema` (seed script), `productSchema` (`GET /products`) | both |
+
+**Belongs here:** request bodies, response shapes and values that both sides must read the same way.
+**Does not:** React or UI code (→ `@kabo/shared` in the frontend), business logic such as prices or
+Econt calls (→ backend), secrets, environment config.
+
+## Install
+
+Published on npmjs.com as [`kabo-contracts`](https://www.npmjs.com/package/kabo-contracts); no login needed.
+Install it under the name the code imports, `@kabo/contracts`, with an npm alias:
+
+```bash
+npm install @kabo/contracts@npm:kabo-contracts@^1.0.3
+```
+
+```json
+"dependencies": { "@kabo/contracts": "npm:kabo-contracts@^1.0.3" }
+```
+
+`^1.0.3` takes new patch and minor versions on the next `npm update`; a major version (breaking
+change) needs an explicit bump. Plain ES modules, no build step. The backend (CommonJS) can
+`require()` it on Node ≥ 20.19.
+
+## Use
+
+```js
+// frontend – checkout form
+import { zodResolver } from '@hookform/resolvers/zod';
+import { checkoutSchema } from '@kabo/contracts';
+
+const form = useForm({ defaultValues, resolver: zodResolver(checkoutSchema) });
+```
+
+```js
+// backend – POST /orders
+const { createOrderSchema } = require('@kabo/contracts');
+
+const result = createOrderSchema.safeParse(req.body);
+if (!result.success) {
+    return res.status(400).json({ message: result.error.issues[0].message, issues: result.error.issues });
+}
+const order = result.data; // trimmed strings, numeric Econt ids, unknown fields removed
+```
+
+Editor types without TypeScript (VS Code reads JSDoc):
+
+```js
+/** @param {import('@kabo/contracts').CreateOrder} order */
+```
+
+### Two rules worth knowing
+
+- **All errors at once.** Zod skips an object's cross-field rules when any field fails, so the checkout
+  schema keeps its fields loose and checks every "required" rule in one `superRefine`. A customer who
+  submits an empty form sees every missing field, not just the first few.
+- **An empty required field gets only "required"**, never "required" plus "invalid email".
+
+## Change a rule
+
+1. Edit the schema and its test in `test/`; `npm test`.
+2. Bump `version` in `package.json`, add a line to `CHANGELOG.md`, commit, `git tag vX.Y.Z`, push with tags.
+   The **Publish to npm** GitHub Action tests and publishes it (the tag must equal the version).
+3. `npm update @kabo/contracts` in the **backend first**, then the frontend (for a major version,
+   change the range in `package.json`, e.g. `npm:kabo-contracts@^2.0.0`).
+
+| Change | Version | Example |
+|---|---|---|
+| Message text, bug fix | patch `1.0.1` | typo in an error message |
+| New optional field, new enum value | minor `1.1.0` | `orders.store` |
+| Field renamed, removed or newly required; enum value changed | major `2.0.0` | `phoneNumber` → `phone` – deploy backend before frontend |
+
+## Publishing setup (once)
+
+Releases are published by `.github/workflows/publish.yml` with npm **trusted publishing**: no token,
+nothing expires. Configured on npmjs.com → kabo-contracts → Settings → Trusted Publisher →
+GitHub Actions (`bobikoki99` / `kabo-contracts` / `publish.yml`), with publishing access set to
+"Require two-factor authentication and disallow tokens". Nobody needs to log in to npm locally.
+
+The very first version was published with a 7-day token in the `NPM_TOKEN` secret, because trusted
+publishing can only be enabled for a package that already exists; that secret is deleted afterwards.
+
+## Develop
+
+```bash
+npm install
+npm test
+```

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "kabo-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.3",
+  "description": "Data contracts shared by the Kabo frontend and backend: zod schemas and enums",
+  "keywords": [
+    "kabo",
+    "zod",
+    "contracts"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bobikoki99/kabo-contracts.git"
+  },
+  "homepage": "https://github.com/bobikoki99/kabo-contracts#readme",
+  "type": "module",
+  "exports": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "vitest": "^5.1.0"
+  }
+}

package/src/cart.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+import { MESSAGES, econtId, mongoId } from './common.js';
+import { MAX_ITEM_QUANTITY } from './enums.js';
+
+// What the client sends for each cart line; prices and weights always come from the database
+export const cartItemSchema = z.object({
+    _id: mongoId,
+    quantity: z.number().int().min(1).max(MAX_ITEM_QUANTITY)
+}, { error: MESSAGES.INVALID_CART_ITEM });
+
+export const cartItemsSchema = z
+    .array(cartItemSchema, { error: MESSAGES.CART_EMPTY })
+    .min(1, MESSAGES.CART_EMPTY);
+
+// POST /econt/delivery/price
+export const deliveryPriceRequestSchema = z.object({
+    city: econtId.refine(city => city !== null, MESSAGES.REQUIRED),
+    items: cartItemsSchema
+});
+
+/** @typedef {import('zod').infer<typeof cartItemSchema>} CartItem */
+/** @typedef {import('zod').infer<typeof deliveryPriceRequestSchema>} DeliveryPriceRequest */

package/src/common.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+// Error messages are shown to customers next to the form fields, so they are in Bulgarian
+export const MESSAGES = Object.freeze({
+    REQUIRED: 'Това поле е задължително.',
+    TOO_LONG: 'Текстът е твърде дълъг.',
+    INVALID_EMAIL: 'Невалиден имейл адрес.',
+    INVALID_PHONE: 'Въведете валиден български телефонен номер, напр. 0888 123 456.',
+    TERMS_REQUIRED: 'Необходимо е да приемете Общите условия.',
+    INVALID_CHOICE: 'Изберете една от възможностите.',
+    CART_EMPTY: 'Количката е празна.',
+    INVALID_CART_ITEM: 'Невалиден продукт в количката.'
+});
+
+export const MAX_TEXT_LENGTH = 300;
+
+// One address with a dot in the domain; deliberately simple, the same rule everywhere
+export const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Bulgarian mobile or landline number once spaces, dashes and brackets are removed:
+// 0888123456, +359888123456, 00359888123456, 029876543
+export const PHONE_NUMBER_REGEX = /^(\+359|00359|0)\d{8,9}$/;
+
+export const MONGO_ID_REGEX = /^[0-9a-f]{24}$/i;
+
+export const isEmail = (value) => EMAIL_REGEX.test(value);
+export const isPhoneNumber = (value) => PHONE_NUMBER_REGEX.test(value.replace(/[\s\-()]/g, ''));
+
+// Trimmed text that may be empty; missing becomes ''
+export const optionalText = (max = MAX_TEXT_LENGTH) => z.string().trim().max(max, MESSAGES.TOO_LONG).default('');
+
+// Trimmed text that must not be empty
+export const requiredText = (max = MAX_TEXT_LENGTH) => z
+    .string({ error: MESSAGES.REQUIRED })
+    .trim()
+    .min(1, { error: MESSAGES.REQUIRED, abort: true }) // an empty field gets only "required"
+    .max(max, MESSAGES.TOO_LONG);
+
+export const requiredEmail = (max = MAX_TEXT_LENGTH) => requiredText(max).refine(isEmail, MESSAGES.INVALID_EMAIL);
+
+export const optionalPhoneNumber = (max = MAX_TEXT_LENGTH) => optionalText(max)
+    .refine(value => !value || isPhoneNumber(value), MESSAGES.INVALID_PHONE);
+
+// Econt city and office ids: numbers, but forms hold them as '' until chosen.
+// Anything that is not a positive number becomes null, so "required" can be checked separately.
+// null is accepted as input too, so the parsed output can be parsed again (form → API).
+export const econtId = z
+    .union([z.number(), z.string(), z.null()])
+    .optional()
+    .transform(value => (Number(value) > 0 ? Number(value) : null));
+
+export const mongoId = z.string().regex(MONGO_ID_REGEX);

package/src/enums.js

@@ -0,0 +1,37 @@
+// Values the frontend and backend must agree on. Stored in the database as-is,
+// so changing a value is a breaking change (major version + data migration).
+
+export const DELIVERY_METHOD = Object.freeze({
+    ECONT_OFFICE: 'econt-office',
+    ECONT_ADDRESS: 'econt-address'
+});
+
+export const PAYMENT_METHOD = Object.freeze({
+    ON_DELIVERY: 'on-delivery'
+});
+
+export const INVOICE_TYPE = Object.freeze({
+    NATURAL_PERSON: 'NP',
+    LEGAL_ENTITY: 'LE'
+});
+
+export const MESSAGE_TYPE = Object.freeze({
+    CONTACT: 'contact',      // contacts page
+    WHOLESALE: 'wholesale'   // for-resellers page
+});
+
+// Which storefront sells a product (products.category)
+export const PRODUCT_CATEGORY = Object.freeze({
+    SUBLIMATOR: 'sublimator',
+    HONEY: 'honey'
+});
+
+// Who a sublimator model is for (products.audience)
+export const PRODUCT_AUDIENCE = Object.freeze({
+    HOBBY: 'hobby',
+    PRO: 'pro'
+});
+
+export const CURRENCY = 'EUR';
+
+export const MAX_ITEM_QUANTITY = 99;

package/src/index.js

@@ -0,0 +1,6 @@
+export * from './enums.js';
+export * from './common.js';
+export * from './cart.js';
+export * from './order.js';
+export * from './message.js';
+export * from './product.js';

package/src/message.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+import { MESSAGES, requiredText, requiredEmail, optionalText, optionalPhoneNumber } from './common.js';
+import { MESSAGE_TYPE } from './enums.js';
+
+const contactFields = {
+    name: requiredText(100),
+    email: requiredEmail(200),
+    phoneNumber: optionalPhoneNumber(30),
+    company: optionalText(150),
+    city: optionalText(100),
+    message: requiredText(5000)
+};
+
+// Contacts page form
+export const contactMessageSchema = z.object(contactFields);
+
+// For-resellers page form: the shop or company is required
+export const wholesaleMessageSchema = z.object({ ...contactFields, company: requiredText(150) });
+
+// POST /messages: either form, told apart by `type` (missing means a contact message)
+export const createMessageSchema = z.preprocess(
+    body => (body && typeof body === 'object' && body.type === undefined ? { ...body, type: MESSAGE_TYPE.CONTACT } : body),
+    z.discriminatedUnion('type', [
+        contactMessageSchema.extend({ type: z.literal(MESSAGE_TYPE.CONTACT) }),
+        wholesaleMessageSchema.extend({ type: z.literal(MESSAGE_TYPE.WHOLESALE) })
+    ], { error: MESSAGES.INVALID_CHOICE })
+);
+
+/** @typedef {import('zod').infer<typeof contactMessageSchema>} ContactMessage */
+/** @typedef {import('zod').infer<typeof wholesaleMessageSchema>} WholesaleMessage */
+/** @typedef {import('zod').infer<typeof createMessageSchema>} CreateMessage */

package/src/order.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+
+import { MESSAGES, optionalText, econtId, isEmail, isPhoneNumber } from './common.js';
+import { cartItemsSchema } from './cart.js';
+import { DELIVERY_METHOD, PAYMENT_METHOD, INVOICE_TYPE } from './enums.js';
+
+// The fields are deliberately loose (missing → '') and every "required" rule lives in
+// checkCheckout below. Zod skips an object's refinements when any field fails, so this
+// is what lets a customer see all missing fields at once after the first submit.
+
+const invoiceDetailsFields = z.object({
+    invoiceType: z.enum(Object.values(INVOICE_TYPE), { error: MESSAGES.INVALID_CHOICE }).default(INVOICE_TYPE.NATURAL_PERSON),
+    // Natural person (NP)
+    firstName: optionalText(),
+    lastName: optionalText(),
+    nationalIdentityNumber: optionalText(),   // ЕГН, optional on purpose (less personal data)
+    // Legal entity (LE)
+    companyName: optionalText(),
+    materialResponsiblePerson: optionalText(), // МОЛ
+    companyIdentificationNumber: optionalText(), // ЕИК
+    isVATRegistered: z.boolean().default(false),
+    vatNumber: optionalText(),
+    // Invoice address
+    city: econtId,
+    cityName: optionalText(),
+    regionName: optionalText(),
+    postCode: optionalText(),
+    countryCode: optionalText(),
+    countryName: optionalText(),
+    address: optionalText()
+});
+
+const checkoutFields = z.object({
+    // Contact
+    firstName: optionalText(),
+    lastName: optionalText(),
+    phoneNumber: optionalText(),
+    email: optionalText(),
+    // Delivery city (Econt city code + display data)
+    city: econtId,
+    cityName: optionalText(),
+    regionName: optionalText(),
+    postCode: optionalText(),
+    countryCode: optionalText(),
+    countryName: optionalText(),
+    // Delivery method: office fields or address
+    deliveryMethod: optionalText(),
+    office: econtId,
+    officeCode: optionalText(),
+    officeName: optionalText(),
+    officeAddress: optionalText(),
+    address: optionalText(),
+    // Payment and invoice
+    paymentMethod: z.enum(Object.values(PAYMENT_METHOD), { error: MESSAGES.INVALID_CHOICE }).default(PAYMENT_METHOD.ON_DELIVERY),
+    isInvoice: z.boolean().default(false),
+    invoiceDetails: invoiceDetailsFields.prefault({}),
+    termsAccepted: z.boolean().default(false)
+});
+
+const requireValue = (ctx, value, path, message = MESSAGES.REQUIRED) => {
+    if (value === '' || value === null) {
+        ctx.addIssue({ code: 'custom', path, message });
+        return false;
+    }
+    return true;
+};
+
+const checkCheckout = (order, ctx) => {
+    ['firstName', 'lastName'].forEach(field => requireValue(ctx, order[field], [field]));
+
+    if (requireValue(ctx, order.phoneNumber, ['phoneNumber']) && !isPhoneNumber(order.phoneNumber)) {
+        ctx.addIssue({ code: 'custom', path: ['phoneNumber'], message: MESSAGES.INVALID_PHONE });
+    }
+    if (requireValue(ctx, order.email, ['email']) && !isEmail(order.email)) {
+        ctx.addIssue({ code: 'custom', path: ['email'], message: MESSAGES.INVALID_EMAIL });
+    }
+
+    requireValue(ctx, order.city, ['city']);
+
+    if (requireValue(ctx, order.deliveryMethod, ['deliveryMethod']) && !Object.values(DELIVERY_METHOD).includes(order.deliveryMethod)) {
+        ctx.addIssue({ code: 'custom', path: ['deliveryMethod'], message: MESSAGES.INVALID_CHOICE });
+    }
+    if (order.deliveryMethod === DELIVERY_METHOD.ECONT_OFFICE) {
+        // The office is picked from a list that fills all three; any one missing means "no office chosen"
+        const hasOffice = order.office !== null && order.officeCode !== '' && order.officeName !== '';
+        requireValue(ctx, hasOffice ? order.office : null, ['office']);
+    }
+    if (order.deliveryMethod === DELIVERY_METHOD.ECONT_ADDRESS) {
+        requireValue(ctx, order.address, ['address']);
+    }
+
+    if (order.isInvoice) {
+        const invoice = order.invoiceDetails;
+        const at = field => ['invoiceDetails', field];
+
+        requireValue(ctx, invoice.city, at('city'));
+        requireValue(ctx, invoice.address, at('address'));
+
+        if (invoice.invoiceType === INVOICE_TYPE.NATURAL_PERSON) {
+            ['firstName', 'lastName'].forEach(field => requireValue(ctx, invoice[field], at(field)));
+        }
+        if (invoice.invoiceType === INVOICE_TYPE.LEGAL_ENTITY) {
+            ['companyName', 'materialResponsiblePerson', 'companyIdentificationNumber'].forEach(field => requireValue(ctx, invoice[field], at(field)));
+            if (invoice.isVATRegistered) {
+                requireValue(ctx, invoice.vatNumber, at('vatNumber'));
+            }
+        }
+    }
+
+    if (order.termsAccepted !== true) {
+        ctx.addIssue({ code: 'custom', path: ['termsAccepted'], message: MESSAGES.TERMS_REQUIRED });
+    }
+};
+
+// The checkout form (frontend): everything the customer fills in
+export const checkoutSchema = checkoutFields.superRefine(checkCheckout);
+
+// POST /orders: the checkout form plus the cart lines
+export const createOrderSchema = checkoutFields
+    .extend({ products: cartItemsSchema })
+    .superRefine(checkCheckout);
+
+/** @typedef {import('zod').infer<typeof checkoutSchema>} Checkout */
+/** @typedef {import('zod').infer<typeof createOrderSchema>} CreateOrder */

package/src/product.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+import { mongoId } from './common.js';
+import { PRODUCT_CATEGORY, PRODUCT_AUDIENCE } from './enums.js';
+
+// A product as stored by the seed script (kabobee-backend/scripts/seedPlaceholderModels.js).
+// Sublimators use audience, warrantyMonths and inTheBox; honey products leave them out.
+// `specs` keys differ per category (hives, powerSource… / honeyType, netWeight…), so they stay free-form.
+export const productInputSchema = z.object({
+    modelKey: z.string().min(1),
+    category: z.enum(Object.values(PRODUCT_CATEGORY)),
+    name: z.string().min(1),
+    tagline: z.string().default(''),
+    price: z.number().positive(),           // EUR incl. VAT
+    weight: z.number().positive(),          // kg incl. packaging, used for Econt prices
+    sortOrder: z.number().int(),
+    specs: z.record(z.string(), z.string()).default({}),
+    highlights: z.array(z.string()).default([]),
+    briefSummary: z.string().default(''),
+    description: z.string().default(''),
+    mainImage: z.string().default(''),
+    imageUrls: z.array(z.string()).default([]),
+    videoUrl: z.string().default(''),
+    audience: z.enum(Object.values(PRODUCT_AUDIENCE)).optional(),
+    warrantyMonths: z.number().int().positive().optional(),
+    inTheBox: z.array(z.string()).optional(),
+    isPlaceholder: z.boolean().optional()
+});
+
+// A product as returned by GET /products and GET /products/:productId
+export const productSchema = productInputSchema.extend({ _id: mongoId });
+
+/** @typedef {import('zod').infer<typeof productSchema>} Product */