kcommons 18.26.1 → 18.26.3

package/build/typings/asn.typings.d.ts

@@ -67,6 +67,8 @@ export declare enum VEHICLE_TYPE {
     TRAILER = "TRAILER",
     TEMPO = "TEMPO",
     CONTAINER = "CONTAINER",
+    TANKER = "TANKER",
+    TWO_WHEELER = "TWO_WHEELER",
     OTHER = "OTHER"
 }
 export declare enum COURIER_SERVICE_TYPE {
@@ -389,3 +391,4 @@ export interface IFastagTrackingEvent {
     vehicleType: string | null;
     vehicleRegNo: string | null;
 }
+export declare const VEHICLE_TYPE_ICONS: Record<VEHICLE_TYPE, string>;

package/build/typings/asn.typings.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ASN_METAFIELDS_INCLUDE = exports.ASN_SORTING_ORDER = exports.ASN_VIEW_PAGE_TYPE = exports.ASN_ITEM_INCLUDE = exports.ASN_HAND_DELIVERY_TRANSPORT_FIELD_PREFIX = exports.ASN_COURIER_TRANSPORT_FIELD_PREFIX = exports.ASN_AIR_TRANSPORT_FIELD_PREFIX = exports.ASN_SEA_TRANSPORT_FIELD_PREFIX = exports.ASN_RAIL_TRANSPORT_FIELD_PREFIX = exports.ASN_ROAD_TRANSPORT_FIELD_PREFIX = exports.ASN_MODE_OF_TRANSPORT_FIELDS = exports.ASN_INCLUDE = exports.IDENTIFICATION_DOCUMENT_TYPE = exports.COURIER_SERVICE_TYPE = exports.VEHICLE_TYPE = exports.MODE_OF_TRANSPORT = exports.SHIPMENT_TYPE = exports.ASN_STATUS = exports.ASN_LIST_TYPES = exports.ASN_APPROVALS_TABS = exports.ASN_VIEW_TABS = exports.ASN_CANCELLED_BY_ENTITY = void 0;
+exports.VEHICLE_TYPE_ICONS = exports.ASN_METAFIELDS_INCLUDE = exports.ASN_SORTING_ORDER = exports.ASN_VIEW_PAGE_TYPE = exports.ASN_ITEM_INCLUDE = exports.ASN_HAND_DELIVERY_TRANSPORT_FIELD_PREFIX = exports.ASN_COURIER_TRANSPORT_FIELD_PREFIX = exports.ASN_AIR_TRANSPORT_FIELD_PREFIX = exports.ASN_SEA_TRANSPORT_FIELD_PREFIX = exports.ASN_RAIL_TRANSPORT_FIELD_PREFIX = exports.ASN_ROAD_TRANSPORT_FIELD_PREFIX = exports.ASN_MODE_OF_TRANSPORT_FIELDS = exports.ASN_INCLUDE = exports.IDENTIFICATION_DOCUMENT_TYPE = exports.COURIER_SERVICE_TYPE = exports.VEHICLE_TYPE = exports.MODE_OF_TRANSPORT = exports.SHIPMENT_TYPE = exports.ASN_STATUS = exports.ASN_LIST_TYPES = exports.ASN_APPROVALS_TABS = exports.ASN_VIEW_TABS = exports.ASN_CANCELLED_BY_ENTITY = void 0;
 var ASN_CANCELLED_BY_ENTITY;
 (function (ASN_CANCELLED_BY_ENTITY) {
     ASN_CANCELLED_BY_ENTITY["COMPANY"] = "COMPANY";
@@ -60,6 +60,8 @@ var VEHICLE_TYPE;
     VEHICLE_TYPE["TRAILER"] = "TRAILER";
     VEHICLE_TYPE["TEMPO"] = "TEMPO";
     VEHICLE_TYPE["CONTAINER"] = "CONTAINER";
+    VEHICLE_TYPE["TANKER"] = "TANKER";
+    VEHICLE_TYPE["TWO_WHEELER"] = "TWO_WHEELER";
     VEHICLE_TYPE["OTHER"] = "OTHER";
 })(VEHICLE_TYPE || (exports.VEHICLE_TYPE = VEHICLE_TYPE = {}));
 var COURIER_SERVICE_TYPE;
@@ -184,3 +186,14 @@ var ASN_METAFIELDS_INCLUDE;
     ASN_METAFIELDS_INCLUDE["approval_logs"] = "approval_logs";
     ASN_METAFIELDS_INCLUDE["approval_chain_stage_names"] = "approval_chain_stage_names";
 })(ASN_METAFIELDS_INCLUDE || (exports.ASN_METAFIELDS_INCLUDE = ASN_METAFIELDS_INCLUDE = {}));
+exports.VEHICLE_TYPE_ICONS = {
+    [VEHICLE_TYPE.TRUCK]: "mdi:truck",
+    [VEHICLE_TYPE.MINI_TRUCK]: "mdi:truck-delivery",
+    [VEHICLE_TYPE.PICKUP]: "mdi:car-pickup",
+    [VEHICLE_TYPE.TRAILER]: "mdi:truck-trailer",
+    [VEHICLE_TYPE.TEMPO]: "mdi:rickshaw",
+    [VEHICLE_TYPE.CONTAINER]: "andrsrxn:container-cuboid",
+    [VEHICLE_TYPE.TANKER]: "mdi:fuel-truck",
+    [VEHICLE_TYPE.TWO_WHEELER]: "mdi:motorbike",
+    [VEHICLE_TYPE.OTHER]: "mdi:dots-horizontal-circle-outline",
+};

package/build/typings/reports/hsfpl/hsfpl_haltingVehicles.typings.d.ts

@@ -90,6 +90,17 @@ export interface IHSFPL_HaltingVehiclesMaterialRow {
     is_others: boolean;
     others_materials: string[];
 }
+export interface IHSFPL_HaltingVehiclesMaterialStockRow {
+    material: string;
+    material_code: string | null;
+    uom: string;
+    vehicles_at_nly: number;
+    in_transit: number | null;
+    at_nly: number | null;
+    standing_at_plant: number | null;
+    in_inventory: number | null;
+    total_incoming: number;
+}
 export interface IHSFPL_HaltingVehiclesInvalidInvoiceRow {
     ves_no: string;
     plant_name: string;
@@ -144,6 +155,7 @@ export interface IHSFPL_HaltingVehiclesReport {
     plants_without_vehicles: string[];
     agewise: IHSFPL_HaltingVehiclesAgewise;
     materialwise: IHSFPL_HaltingVehiclesMaterialRow[];
+    material_stock: IHSFPL_HaltingVehiclesMaterialStockRow[];
     invoice_status: IHSFPL_HaltingVehiclesInvoiceSection;
     vehicles_by_plant: IHSFPL_HaltingVehiclesPlantGroup[];
     consistency: IHSFPL_HaltingVehiclesConsistency;

package/build/typings/system/queueJob.typings.d.ts

@@ -70,8 +70,13 @@ export interface IQueueJobMetadata extends Pick<IQueueJob, "job_type"> {
 }
 export interface IHaldiramsPurchaseOrderItems {
     item_code: string | null;
+    po_line_item_number: string | null;
     remark: string | null;
     quantity: string | null;
+    price_per_unit: string | null;
+    po_uom: string | null;
+    base_uom: string | null;
+    qty_converted_to_base_uom: string | null;
     gst_percentage: string | null;
     total: string | null;
     per_unit_rate: string | null;
@@ -82,6 +87,7 @@ export interface IHaldiramsPurchaseOrderItems {
     under_tolerance_percentage: string | null;
     line_item_number: number | null;
     Delivery_Completed: string | null;
+    Control_code: string | null;
 }
 export interface IHaldiramsPODataFetchedFromERPData {
     purchase_order_number: number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcommons",
-  "version": "18.26.1",
+  "version": "18.26.3",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/readme.md

@@ -1,6 +1,534 @@
-TO publish:
+# kcommons
 
-1. tsc
-2. push to github
-3. npm version patch
-4. npm publish
+> Who is this for? Anyone who is new to this project.
+> Read it once from top to bottom. After that, you should be able to build the package, find your way around it, add new types and helpers the same way everyone else does, and get your change into the projects that use it.
+
+---
+
+## Table of Contents
+
+1. What is this project?
+2. Words you will see everywhere
+3. Tools we use
+4. Getting started on your machine
+5. The folder map
+6. How a change travels to the other projects
+7. The big ideas
+8. Naming rules
+9. Coding rules and style
+10. Recipes: step-by-step guides
+11. Testing
+12. Using your local copy in another project
+13. Publishing a new version
+14. Git and teamwork
+15. Troubleshooting and FAQ
+16. Things that don't follow the rules yet
+17. Cheat sheet
+
+---
+
+## 1. What is this project?
+
+Kraya is made of several projects:
+
+| Project                    | What it is                                         |
+| -------------------------- | -------------------------------------------------- |
+| Kraya backend              | The main server (NestJS)                           |
+| Company panel (frontend)   | The website companies use                          |
+| Vendor panel (frontend)    | The website vendors use                            |
+| ERP Integration Server     | Talks to company ERPs, builds and mails reports    |
+| Report Generation Engine   | Turns report data into PDFs                        |
+
+All of them talk about the same things: a PO, a GRN, a vendor, a report schedule. If every project wrote its own `IPo` type, they would slowly drift apart, and one day the backend would send a field the frontend doesn't know about.
+
+kcommons (this repo, `kraya_common`) is the one place where those shared things live. It is an npm package called `kcommons`. It holds:
+
+- Types (TypeScript interfaces) for every table and API response
+- Enums and constants (statuses, permissions, routes, upload paths, …)
+- Small helper functions that must work the same everywhere (taxes, dates, IDs, validators, report scheduling)
+
+```
+                         ┌───────────────────┐
+                         │     kcommons      │
+                         │  types · enums ·  │
+                         │  constants · utils│
+                         └─────────┬─────────┘
+          ┌──────────────┬─────────┼──────────────┬───────────────────┐
+          ▼              ▼         ▼              ▼                   ▼
+   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ ┌──────────────┐
+   │   Kraya    │ │  Company   │ │   Vendor   │ │ ERP          │ │ Report       │
+   │  backend   │ │  panel FE  │ │  panel FE  │ │ Integration  │ │ Generation   │
+   │            │ │            │ │            │ │ Server       │ │ Engine       │
+   └────────────┘ └────────────┘ └────────────┘ └──────────────┘ └──────────────┘
+```
+
+kcommons has no server, no database and no UI. It is only code that other projects import:
+
+```ts
+import { IPo, STATUSES, calculateNextRunAt } from 'kcommons';
+```
+
+Because the frontends import it too, everything in here must run in a browser as well as in Node (see section 9).
+
+---
+
+## 2. Words you will see everywhere
+
+| Word                | What it means in simple words                                                                                     |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Typing              | A TypeScript interface or type. It describes the shape of data. It doesn't exist at runtime.                      |
+| `I<Name>`           | The full shape of one table row, including its relations. Example: `IGRN`.                                        |
+| `INested<Name>`     | The same row without its relations. Used when the row appears inside another row. Example: `INestedGRN`.          |
+| `<NAME>_INCLUDE`    | An enum listing the relations you can ask the backend to include. Example: `REPORTS_PLUGIN_CONFIG_COMPANY_INCLUDE`. |
+| Barrel (`index.ts`) | The one file that re-exports everything. If something isn't exported there, other projects can't import it.     |
+| Build               | The compiled JavaScript + `.d.ts` files in `build/`. This is what other projects actually load.                 |
+| Publish             | Uploading a new version of the package to npm so other projects can install it.                                  |
+| Link / symlink      | Pointing another project's `node_modules/kcommons` at your local folder, so it uses your code without publishing. |
+| Report plugin       | One kind of report, for example `HALTING_VEHICLES_REPORTS` (`REPORTS_PLUGIN` enum).                               |
+| Company code        | Short name of a customer company. Company-specific types use it as a prefix. Example: `IABC_HaltingVehiclesReport`. |
+
+> Examples in this guide use `ABC` as the company code, the same as the ERP server and engine READMEs. In the real code you will see the real company prefix (for example `HSFPL_`).
+
+---
+
+## 3. Tools we use
+
+| Tool              | What it does for us                                                                    |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| TypeScript 5      | Everything is written in TypeScript and compiled with `tsc` (CommonJS, ES2017).        |
+| Jest + ts-jest    | Unit tests for the helper functions.                                                   |
+| date-fns          | Date helpers. kcommons re-exports the whole library, so `import { format } from 'kcommons'` works. |
+| zod               | Schema validation, used by the extra-form helpers and `zod.constant.ts`.               |
+| uuid              | ID generation (`generateId.util.ts`).                                                  |
+| npm               | Package manager and the registry we publish to.                                        |
+
+There is no ESLint or Prettier config in this repo. Match the style of the files around you (double quotes, 2 spaces, trailing commas).
+
+---
+
+## 4. Getting started on your machine
+
+### 4.1 What you need
+
+- Node.js 22 and npm
+- Git access to `Kraya-Vkraya/kraya_common`
+- npm publish rights, only if you will publish (ask the team)
+
+### 4.2 First-time setup
+
+Clone it next to the other projects. The other repos link to it with the relative path `../../kraya_common`, so the folder name and place matter:
+
+```bash
+cd ~/code/kraya/code          # the folder that also holds backend/, erp-integration-server/, ...
+git clone https://github.com/Kraya-Vkraya/kraya_common.git
+cd kraya_common
+npm install                   # also runs "prepare", which builds into build/
+```
+
+### 4.3 npm commands
+
+| Command             | What it does                                                         |
+| ------------------- | -------------------------------------------------------------------- |
+| `npx tsc`           | Compiles everything into `build/`. Run it after every change.         |
+| `npm run prepare`   | Same as above (runs `npx tsc`). npm also runs it on `install` and before `publish`. |
+| `npm test`          | Runs all `*.spec.ts` tests.                                          |
+| `npm run test:watch`| Runs tests again on every save.                                      |
+| `npm run test:cov`  | Runs tests and shows coverage.                                       |
+
+### 4.4 Is it working?
+
+- `npx tsc` finishes with no errors.
+- `build/index.js` and `build/index.d.ts` exist and have today's time.
+- `npm test` passes.
+
+---
+
+## 5. The folder map
+
+There is no `src/` folder. The source folders sit at the top level, and `tsc` writes the output to `build/`.
+
+```
+kraya_common/
+├── index.ts          ← THE BARREL. Re-exports everything. package.json "main"/"types" point at build/index.*
+├── typings/          ← Types for tables, API responses and reports (~180 files). Most of your work is here.
+│   ├── <entity>.typings.ts         ← Older entities live at the top level (grn, mrn, vendor, …)
+│   ├── company/                    ← Company-side entities
+│   │   ├── masters/                ← po, ves, checkpoints, …
+│   │   ├── inventory/  istd/  iad/  settings/  _junctions/  vendorOnboardingRequest/
+│   ├── vendor/                     ← Vendor-panel types
+│   ├── system/                     ← System config tables (erp plugins, report schedules, recipients)
+│   ├── plugins/                    ← Plugin enums (REPORTS_PLUGIN, REPORT_FREQUENCY)
+│   ├── reports/<company>/          ← Report data shapes, one folder per company (e.g. reports/hsfpl/)
+│   ├── integrations/erp/           ← ERP integration types
+│   ├── kpis/                       ← Dashboard KPI types, grouped by dashboard
+│   ├── settings/form/              ← Extra (configurable) form types
+│   ├── verification_apis/          ← GST / PAN / … verification responses
+│   └── common/                     ← Shared pieces (pagination, ULIP, configurable forms)
+├── enums/            ← Stand-alone enums (priority, upload)
+├── constants/        ← Fixed values: statuses, permissions, routes, upload paths, socket events, UOMs, …
+├── configs/          ← response.typings.ts (shape of every API response)
+├── classes/          ← The few real classes (ASNWrapper, vendor quote ➜ quote item adapter)
+├── helpers/          ← Tiny generic helpers (padNumber)
+├── utils/            ← Helper functions with real logic, each with a .spec.ts next to it
+│   ├── validators/                 ← gst, pan, cin, udyam
+│   └── extra-form/                 ← Build/parse configurable forms
+├── build/            ← Compiled output. Generated by tsc, but committed (see section 16)
+├── jest.config.js
+├── tsconfig.json     ← strict, commonjs, ES2017, declaration: true, outDir: ./build
+└── package.json
+```
+
+---
+
+## 6. How a change travels to the other projects
+
+```
+ 1. Change a file in kraya_common (for example add a field to IGRN)
+        │
+        ▼
+ 2. Export it from index.ts (if it's a new file)
+        │
+        ▼
+ 3. npx tsc  ──►  build/  (JavaScript + .d.ts)
+        │
+        ├──────────────► 4a. Local: projects that link to ../../kraya_common
+        │                    see the new build straight away (section 12)
+        │
+        ▼
+ 4b. Commit, push, npm version patch, npm publish   (section 13)
+        │
+        ▼
+ 5. In each project that needs it: npm install kcommons@<new version>
+    and commit "CHORE: updated kcommons to <version>"
+```
+
+Most features touch kcommons plus one or more projects. Use the same branch name in every repo (for example `feat/plugins-for-reports`) and merge kcommons first, because the other projects depend on it.
+
+---
+
+## 7. The big ideas
+
+### 7.1 One table = one typings file with three parts
+
+Every database table gets a typings file with the same three parts. Example, `typings/system/reportScheduleRecipient.typings.ts`:
+
+```ts
+import { INestedReportsPluginConfigCompany } from "./reportsPluginConfigCompany.typings";
+
+// Part 1 — which relations can be included
+export enum REPORT_SCHEDULE_RECIPIENT_INCLUDE {
+  schedule = "schedule",
+}
+
+// Part 2 — the full row, WITH its relations
+export interface IReportScheduleRecipient {
+  id: string;
+  schedule_id: string;
+  to_emails: string[];
+  // ...
+  created_at: string;
+  updated_at: string;
+
+  schedule: INestedReportsPluginConfigCompany;   // relation
+}
+
+// Part 3 — the row WITHOUT relations, for use inside other types
+export interface INestedReportScheduleRecipient
+  extends Omit<IReportScheduleRecipient, "schedule"> {}
+```
+
+Rules:
+
+- Field names are snake_case and match the database columns exactly.
+- Relations inside `I<Name>` always use the other table's `INested<...>` type. This stops types from nesting forever.
+- `INested<Name>` = `Omit<I<Name>, every relation key>`. When you add a relation, add it to the `Omit` list too.
+- Dates are `string` (they arrive as JSON). Nullable columns are `T | null`.
+
+### 7.2 The types follow the database, not the other way round
+
+The Kraya backend's Prisma schema owns the database. When a column, table or enum value changes there, update the matching typing here in the same feature branch. Enums that exist in Prisma (for example `REPORTS_PLUGIN`, `REPORT_FREQUENCY`) must have exactly the same values here.
+
+### 7.3 The barrel (`index.ts`)
+
+Other projects only ever import from `'kcommons'`, never from a deep path. So:
+
+- Every new file must get an `export * from "./path/to/file";` line in `index.ts`, under the right comment heading (`// Constants`, `// Utils`, `// For Reports`, …).
+- Export names must be unique across the whole package. Two files exporting the same name will clash in the barrel.
+- `index.ts` also re-exports all of `date-fns`, so don't create exports with date-fns names (`format`, `addDays`, …).
+
+### 7.4 Report data types
+
+Report data is built by the ERP Integration Server and drawn by the Report Generation Engine. Both import the shape from here, so the shape is the contract between them.
+
+- Folder: `typings/reports/<company>/`, file `<company>_<reportName>.typings.ts`. Example: `reports/hsfpl/hsfpl_haltingVehicles.typings.ts`.
+- Every type and enum in it gets the company prefix: `IABC_HaltingVehiclesReport`, `ABC_HALTING_VEHICLE_APPROVAL`.
+- The top-level type is `I<COMPANY>_<Name>Report`. That is what the ERP server returns as `report_data`.
+- Change the shape here first, then the ERP server (data), then the engine (PDF).
+
+Schedules and their history are typed in `typings/system/` (`IReportsPluginConfigCompany`, `IReportScheduleRecipient`), and the plugin enums are in `typings/plugins/reports.plugins.ts`.
+
+### 7.5 Shared logic lives in `utils/`
+
+Put a function here only when more than one project needs the exact same answer. Good examples:
+
+- `calculateNextRunAt(schedule, after)`: the next time a report schedule should run. `send_time`, `day_of_week` and `date_of_month` are read as IST; the result is a UTC `Date`. MONTHLY clamps day 31 to the last day of shorter months. Returns `null` for an unknown frequency. The ERP server's scheduler uses it.
+- `taxes.util.ts`: tax and discount maths, so the frontend total matches the backend total.
+- `businessTime.util.ts`, `convertDurationToreadableFormat.util.ts`, `toFixedDecimal.util.ts`, `convertToINS.util.ts`: formatting that must look the same everywhere.
+- `validators/`: GST, PAN, CIN and Udyam format checks.
+
+Every util must be a pure function: same input, same output, no database, no network, no global state.
+
+---
+
+## 8. Naming rules
+
+> The golden rule: look at the files next to yours and name things the same way.
+
+### 8.1 Files
+
+Format: `<name>.<type>.ts`, with `<name>` in camelCase.
+
+| Suffix           | What is inside                    | Example                                  |
+| ---------------- | --------------------------------- | ---------------------------------------- |
+| `.typings.ts`    | Interfaces, types, `_INCLUDE` enums | `grn.typings.ts`                        |
+| `.constants.ts`  | Fixed values                      | `statuses.constants.ts`                  |
+| `.enum.ts`       | A stand-alone enum                | `priority.enum.ts`                       |
+| `.util.ts`       | A helper function with logic      | `calculateNextRunAt.util.ts`             |
+| `.validator.ts`  | A format validator                | `gst.validator.ts`                       |
+| `.helper.ts`     | A tiny generic helper             | `padNumber.helper.ts`                    |
+| `.class.ts`      | A class                           | `asnWrapper.class.ts`                    |
+| `.spec.ts`       | Tests, next to the file they test | `calculateNextRunAt.util.spec.ts`        |
+
+Company-specific files get a lowercase company prefix: `abc_haltingVehicles.typings.ts`.
+
+### 8.2 Names inside files
+
+| Kind                      | Pattern                          | Example                                   |
+| ------------------------- | -------------------------------- | ----------------------------------------- |
+| Full row type             | `I<Name>`                        | `IReportsPluginConfigCompany`             |
+| Row without relations     | `INested<Name>`                  | `INestedReportsPluginConfigCompany`       |
+| Include enum              | `<NAME>_INCLUDE`                 | `REPORT_SCHEDULE_RECIPIENT_INCLUDE`       |
+| Other interfaces          | `I<Name>`                        | `IScheduleShape`, `ITaxRelatedItemInputs` |
+| Enums and constant objects| `UPPER_SNAKE_CASE`               | `REPORTS_PLUGIN`, `STATUSES`              |
+| Enum values               | `UPPER_SNAKE_CASE` = same string | `DAILY = "DAILY"`                         |
+| Include enum values       | the relation name                | `schedule = "schedule"`                   |
+| Company-specific type     | `I<COMPANY>_<Name>`              | `IABC_HaltingVehiclesReport`              |
+| Company-specific enum     | `<COMPANY>_<NAME>`               | `ABC_HALTING_VEHICLE_APPROVAL`            |
+| Functions                 | camelCase, starts with a verb    | `calculateNextRunAt`, `getContactPerson`  |
+| Fields                    | snake_case, same as the DB column| `next_run_at`, `to_emails`                |
+
+---
+
+## 9. Coding rules and style
+
+- It must run in the browser. The frontends import this package. Don't import Node-only modules (`fs`, `path`, `crypto`, `node:*`), NestJS, Prisma or React. Use only TypeScript, `date-fns`, `zod` and `uuid`.
+- No side effects. A file must not do anything when imported (no `console.log`, no timers, no reading `process.env`).
+- Use relative imports (`../typings/...`). There are no path aliases here.
+- Strict TypeScript is on. Avoid `any`; if you must use it, keep it small and local.
+- Don't add a new dependency unless every project can live with it. Each one ends up in the frontends' bundles.
+- Prefer enums over plain strings for statuses and kinds, and use string enums (`A = "A"`) so values survive JSON.
+- When you change an existing type, remember it is used in five projects. Adding an optional field is safe. Renaming or removing a field, or making one required, breaks other projects; search them first and fix them in the same branch.
+- Don't leave test or sample types in `index.ts` (see `ITesting` in section 16).
+
+---
+
+## 10. Recipes: step-by-step guides
+
+### 10.1 Add types for a new table
+
+Example: a new table `report_delivery_log`.
+
+1. Backend first: add the model and migration in the Kraya backend.
+2. Create `typings/system/reportDeliveryLog.typings.ts` with the three parts from section 7.1 (`REPORT_DELIVERY_LOG_INCLUDE`, `IReportDeliveryLog`, `INestedReportDeliveryLog`).
+3. If another table has a relation to it, add the field to that table's `I<Name>` and to its `INested<Name>` `Omit` list.
+4. Export the file from `index.ts`.
+5. `npx tsc`, then link or publish (sections 12 and 13).
+
+### 10.2 Add a field to an existing type
+
+1. Add the field with its exact column name and nullability: `max_halt_days_for_halting_vehicles_report: number | null;`.
+2. If it is a relation, also add it to the `INested<Name>` `Omit` list.
+3. `npx tsc`, and build the projects that use the type to make sure nothing broke.
+
+### 10.3 Add a report data type for a company
+
+1. Create `typings/reports/<company>/<company>_<reportName>.typings.ts`.
+2. Write the pieces (`IABC_<Name>Kpis`, `IABC_<Name>Row`, …) and one top-level `IABC_<Name>Report`.
+3. If it's a new report kind, add the value to `REPORTS_PLUGIN` in `typings/plugins/reports.plugins.ts`, with the same value as the backend's Prisma enum.
+4. Export it under `// For Reports` in `index.ts`.
+5. Then follow "Add a new report" in the ERP server's README (data) and the engine's README (PDF).
+
+### 10.4 Add a helper function
+
+1. Create `utils/<name>.util.ts` with one exported pure function. Write the return type.
+2. Create `utils/<name>.util.spec.ts` next to it. Cover normal cases, `null`/`undefined`/`NaN` inputs, and edge cases (for dates: month ends, IST midnight).
+3. `npm test`.
+4. Export it under `// Utils` in `index.ts`.
+
+### 10.5 Add a constant or enum value
+
+1. Add it to the right `constants/*.constants.ts` (or `enums/*.enum.ts`).
+2. If the value also exists in Prisma, it must match the backend exactly.
+3. Check the projects that `switch` on that enum. A new value may need a new `case` there.
+
+---
+
+## 11. Testing
+
+- Tests use Jest with `ts-jest`. Test files end with `.spec.ts` and sit next to the code (`utils/taxes.util.spec.ts`).
+- Run them with `npm test`.
+- Every function in `utils/` and `helpers/` should have a spec. Types and constants don't need tests.
+- Keep tests free of network and dates that change: pass a fixed `Date` instead of using `new Date()` inside the test.
+
+```ts
+import { padNumber } from "./padNumber.helper";
+
+describe("padNumber", () => {
+  it("pads single digits", () => {
+    expect(padNumber(7)).toBe("07");
+  });
+  it("returns non-numeric strings as they are", () => {
+    expect(padNumber("abc")).toBe("abc");
+  });
+});
+```
+
+---
+
+## 12. Using your local copy in another project
+
+While you work on a feature, you want the backend or the ERP server to use your local kcommons, not the published one. We do this with a symlink:
+
+```bash
+# from the other project, e.g. erp-integration-server/
+rm -rf node_modules/kcommons
+ln -s ../../kraya_common node_modules/kcommons
+```
+
+Then, every time you change kcommons, run `npx tsc` in `kraya_common`. The other project reads `build/` straight away (restart its dev server if it doesn't notice).
+
+Things to know:
+
+- `npm install` in the other project can replace or delete the link. Check `ls -la node_modules/kcommons` after installing and link again if needed.
+- The link only exists on your machine. Before you merge, the other project's `package.json` must point to a published version that has your change (section 13).
+- Today the backend, the vendor panel, the ERP server and the engine are all linked like this on the main dev machine. The company panel uses the published package.
+
+---
+
+## 13. Publishing a new version
+
+Only publish from `master` (or with the team's agreement), after your changes are merged.
+
+```bash
+cd kraya_common
+git checkout master && git pull
+npx tsc                      # build/ must match the source
+git add . && git commit -m "CHORE: did npm run prepare"   # build/ is committed (see section 16)
+git push
+npm version patch            # bumps package.json, makes a commit and a tag, e.g. 18.25.7
+git push --follow-tags
+npm publish                  # runs "prepare" (tsc) again, then uploads build/
+```
+
+Which number to bump:
+
+| Change                                                    | Command             |
+| --------------------------------------------------------- | ------------------- |
+| New types, fields, utils, enum values (nothing breaks)    | `npm version patch` |
+| A type or function changed in a way that breaks a project | `npm version minor` and tell the team |
+| Big rework                                                | `npm version major` (agree with the team first) |
+
+Then, in each project that needs the change:
+
+```bash
+npm install kcommons@<new version>
+```
+
+and commit it as `CHORE: updated kcommons to <version>`.
+
+---
+
+## 14. Git and teamwork
+
+Same as the other projects:
+
+- Branches: `master` ← `dev` ← `feat/...`, `hotfix/...`, `refactor/...`. Branch from `dev`.
+- Commits: `FEAT:`, `FIX:`, `CHORE:`, `REFACTOR:` followed by what changed in plain words. Version bumps made by `npm version` are just the number (for example `18.25.6`).
+- Use the same branch name as the matching branches in the backend / ERP server / engine, and merge kcommons first.
+
+Before you open a PR:
+
+- [ ] `npx tsc` passes
+- [ ] `npm test` passes, and new utils have specs
+- [ ] New files are exported from `index.ts`
+- [ ] Types match the backend's Prisma schema
+- [ ] No Node-only, NestJS, Prisma or React imports
+- [ ] You searched the other projects for any type you renamed or removed
+
+---
+
+## 15. Troubleshooting and FAQ
+
+| Problem                                                          | What it means / what to do                                                                                                      |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `Module 'kcommons' has no exported member 'X'`                   | X isn't in `index.ts`, you didn't run `npx tsc`, or the project uses an older published version. Check `node_modules/kcommons`. |
+| `Cannot find module 'kcommons'`                                  | The project's link was removed (often by `npm install`), or `kcommons` isn't in its `package.json`. Link again (section 12).   |
+| My change works locally but CI / the server breaks               | Your local link hides the problem. Publish a version and install it in the project.                                            |
+| `Module "./x" has already exported a member named 'Y'`           | Two files export the same name. Rename one.                                                                                    |
+| A frontend fails to build after a kcommons change                | You probably imported something Node-only. See section 9.                                                                      |
+| `npm publish` says the version already exists                    | Someone published that number already. Pull, then `npm version patch` again.                                                  |
+| The report schedule runs at the wrong hour                       | `send_time` is IST and `calculateNextRunAt` returns UTC. Check you're not converting twice.                                    |
+
+---
+
+## 16. Things that don't follow the rules yet
+
+You will see some older code that doesn't match this document. Follow this document for new code, and fix old code only in a separate `REFACTOR:` commit.
+
+| What                                   | Where                                                                                                    | How it should look                                                    |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `prepare` cleans the wrong folder      | `"prepare": "rm -rf ./dist && npx tsc"`, but the output folder is `build/`                               | `rm -rf ./build && npx tsc`, so deleted files don't linger in `build/` |
+| `build/` is committed                  | `.gitignore` only ignores `node_modules`                                                                 | Ignore `build/` and let `prepare` build it on publish                 |
+| Tests end up in the package            | `tsconfig.json` has no `exclude`, so `*.spec.ts` compile into `build/`                                   | Exclude `**/*.spec.ts`                                               |
+| Old publish notes                      | This file used to be four lines of publish steps                                                         | This document                                                         |
+| Sample type in the barrel              | `ITesting` at the end of `index.ts`                                                                      | Delete it                                                             |
+| Same file exported twice               | `reports/hsfpl/hsfpl_haltingVehicles.typings` under `// Plugins` and `// For Reports`                    | Only under `// For Reports`                                           |
+| Missing company prefix                 | `IHaltingVehiclesNeedsAction` in the HSFPL report typings                                                | `IHSFPL_HaltingVehiclesNeedsAction`                                   |
+| File name typos                        | `companySepcificVendorItems`, `companyDocumentUplodPath`, `getDefaultVAlues`, `comparativeItemQUantitySplit`, `convertDurationToreadableFormat`, `removeQueryParamsFormReqStr.util.spec.ts` | Correct spelling (rename and update `index.ts` in one commit)        |
+| Mixed folder layout                    | Many entities at the top of `typings/`, newer ones under `typings/company/...`                           | New company entities go under `typings/company/`                      |
+| Whole of date-fns re-exported          | `export * from "date-fns"` in `index.ts`                                                                 | Import date-fns directly in each project                              |
+| `.DS_Store` files                      | `typings/`, `utils/`, repo root                                                                          | Delete them and add `.DS_Store` to `.gitignore`                       |
+| Projects on different versions         | Backend `^18.25.4`, company panel `^18.25.6`, vendor panel `^18.22.4`; the ERP server and engine have no `kcommons` entry in `package.json` at all | Every project lists `kcommons` and is updated together               |
+| Registry ahead of `master`             | npm has `18.26.0`, `package.json` here says `18.25.6`                                                    | Publish only from `master`, so the repo and npm agree                 |
+| Utils without tests                    | `calculateNextRunAt`, `generateId`, `calculateToleranceRange`, `getFileExtension`, `stripQueryParams`, the validators and the extra-form utils have no `.spec.ts` | A spec next to each one, starting with `calculateNextRunAt` (it decides when reports are sent) |
+| No lint / format config                | No ESLint or Prettier here                                                                               | Add the same Prettier config as the other projects                    |
+
+---
+
+## 17. Cheat sheet
+
+Build it: `npx tsc` ➜ `build/`. Test it: `npm test`.
+
+The change path: edit ➜ export from `index.ts` ➜ `npx tsc` ➜ (local: linked projects see it) ➜ merge ➜ `npm version patch` ➜ `npm publish` ➜ `npm install kcommons@<version>` in each project.
+
+Naming at a glance (table `report_schedule_recipient`):
+
+| Thing             | Name                                          |
+| ----------------- | --------------------------------------------- |
+| File              | `typings/system/reportScheduleRecipient.typings.ts` |
+| Full row          | `IReportScheduleRecipient`                    |
+| Without relations | `INestedReportScheduleRecipient`              |
+| Include enum      | `REPORT_SCHEDULE_RECIPIENT_INCLUDE`           |
+| Report data type  | `IABC_HaltingVehiclesReport` in `typings/reports/abc/abc_haltingVehicles.typings.ts` |
+| Util              | `utils/taxes.util.ts` + `utils/taxes.util.spec.ts` |
+| Commit            | `FEAT: Added report schedule recipient typings` |
+
+Golden rules:
+
+1. Five projects depend on this. Add freely, but search before you rename or remove.
+2. Types follow the backend's Prisma schema, with the same field names and enum values.
+3. Every table gets `I<Name>`, `INested<Name>` and `<NAME>_INCLUDE`.
+4. Everything is exported from `index.ts`, and nothing is imported by deep path.
+5. Utils are pure, browser-safe and tested.
+6. Build after every change; publish only from `master`.
+7. When in doubt, copy what the files next to yours do.