hvp-shared 3.4.0 → 3.5.0

package/dist/contracts/catalog-item/responses.d.ts

@@ -0,0 +1,132 @@
+/**
+ * CatalogItem Response Types
+ *
+ * Response DTOs for catalog item endpoints.
+ */
+import { SyncField } from '../../types/sync-field.types';
+import { UsageType, SyncStatus } from '../../constants/catalog-item.constants';
+import { Warehouse } from '../../types/qvet.types';
+/**
+ * Warehouse stock response
+ */
+export interface WarehouseStockResponse {
+    warehouse: Warehouse;
+    currentStock: number;
+    minStock: SyncField<number>;
+    optimalStock: SyncField<number>;
+}
+/**
+ * CatalogItem List Response
+ *
+ * Simplified item for list views with effective values.
+ *
+ * @example GET /api/catalog-items
+ */
+export interface CatalogItemListResponse {
+    id: string;
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    salePrice: number;
+    isActive: boolean;
+    usageType: UsageType;
+    hasPendingChanges: boolean;
+    /** Which fields have pending changes */
+    pendingFields?: string[];
+    syncStatus: SyncStatus;
+    lastSyncAt: string;
+}
+/**
+ * CatalogItem Detail Response
+ *
+ * Full item detail with all sync fields.
+ *
+ * @example GET /api/catalog-items/:id
+ */
+export interface CatalogItemDetailResponse {
+    id: string;
+    qvetCode: number;
+    qvetSync: {
+        description: SyncField<string>;
+        barcode: SyncField<string>;
+        reference: SyncField<string>;
+        section: SyncField<string>;
+        family: SyncField<string>;
+        subfamily: SyncField<string>;
+        brand: SyncField<string>;
+        purchasePrice: SyncField<number>;
+        salePrice: SyncField<number>;
+        purchaseMargin: SyncField<number>;
+        saleMargin: SyncField<number>;
+        vatSale: SyncField<number>;
+        vatPurchase: SyncField<number>;
+        purchaseUnit: SyncField<string>;
+        saleUnit: SyncField<string>;
+        conversionFactor: SyncField<number>;
+        isActive: SyncField<boolean>;
+        stockControlType: SyncField<string>;
+        stockByWarehouse: WarehouseStockResponse[];
+        qvetCreatedAt?: string;
+        lastSaleDate?: string;
+    };
+    hvpData: {
+        usageType: UsageType;
+        notes?: string;
+        internalCategory?: string;
+    };
+    hasPendingChanges: boolean;
+    lastSyncAt: string;
+    syncStatus: SyncStatus;
+    createdAt: string;
+    updatedAt: string;
+    updatedBy?: string;
+}
+/**
+ * Paginated list response
+ */
+export interface CatalogItemPaginatedResponse {
+    items: CatalogItemListResponse[];
+    meta: {
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+        hasNextPage: boolean;
+        hasPrevPage: boolean;
+    };
+}
+/**
+ * Sync status response
+ *
+ * @example GET /api/catalog-items/sync/status
+ */
+export interface CatalogSyncStatusResponse {
+    /** Is a sync currently in progress? */
+    isRunning: boolean;
+    /** Last sync timestamp */
+    lastSyncAt?: string;
+    /** Last sync result */
+    lastSyncResult?: {
+        success: boolean;
+        itemsProcessed: number;
+        itemsCreated: number;
+        itemsUpdated: number;
+        itemsSkipped: number;
+        errors: string[];
+        duration: number;
+    };
+}
+/**
+ * Sync trigger response
+ *
+ * @example POST /api/catalog-items/sync
+ */
+export interface CatalogSyncTriggerResponse {
+    /** Sync started successfully */
+    started: boolean;
+    /** Message */
+    message: string;
+    /** Estimated items to process */
+    estimatedItems?: number;
+}

package/dist/contracts/catalog-item/responses.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * CatalogItem Response Types
+ *
+ * Response DTOs for catalog item endpoints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -3,3 +3,4 @@
  * Request and Response types for all API endpoints
  */
 export * from './collaborator';
+export * from './catalog-item';

package/dist/contracts/index.js

@@ -19,3 +19,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./collaborator"), exports);
+__exportStar(require("./catalog-item"), exports);

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from './types';
 export * from './constants';
 export * from './contracts';
 export * from './validation';
-export * from './inventory';
 export { debugLog } from './utils/debug-logger';
+export * from './utils/sync-field.helpers';
+export * from './utils/qvet-catalog.helpers';

package/dist/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./types"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./contracts"), exports);
 __exportStar(require("./validation"), exports);
-__exportStar(require("./inventory"), exports);
 var debug_logger_1 = require("./utils/debug-logger");
 Object.defineProperty(exports, "debugLog", { enumerable: true, get: function () { return debug_logger_1.debugLog; } });
+__exportStar(require("./utils/sync-field.helpers"), exports);
+__exportStar(require("./utils/qvet-catalog.helpers"), exports);

package/dist/types/catalog-item.types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * CatalogItem Types
+ *
+ * Type definitions for catalog items (products/services) that sync with QVET.
+ */
+import { SyncField } from './sync-field.types';
+import { UsageType, SyncStatus } from '../constants/catalog-item.constants';
+import { Warehouse } from './qvet.types';
+/**
+ * Stock information for a specific warehouse
+ */
+export interface WarehouseStock {
+    /** Warehouse identifier */
+    warehouse: Warehouse;
+    /** Current stock quantity (read-only from QVET) */
+    currentStock: number;
+    /** Minimum stock level (sync with QVET) */
+    minStock: SyncField<number>;
+    /** Optimal stock level (sync with QVET) */
+    optimalStock: SyncField<number>;
+}
+/**
+ * QVET Sync Data
+ *
+ * All fields that sync bidirectionally with QVET.
+ * Uses SyncField pattern for tracking pending changes.
+ */
+export interface CatalogItemQvetSync {
+    description: SyncField<string>;
+    barcode: SyncField<string>;
+    reference: SyncField<string>;
+    section: SyncField<string>;
+    family: SyncField<string>;
+    subfamily: SyncField<string>;
+    brand: SyncField<string>;
+    purchasePrice: SyncField<number>;
+    salePrice: SyncField<number>;
+    purchaseMargin: SyncField<number>;
+    saleMargin: SyncField<number>;
+    vatSale: SyncField<number>;
+    vatPurchase: SyncField<number>;
+    purchaseUnit: SyncField<string>;
+    saleUnit: SyncField<string>;
+    conversionFactor: SyncField<number>;
+    isActive: SyncField<boolean>;
+    stockControlType: SyncField<string>;
+    stockByWarehouse: WarehouseStock[];
+    qvetCreatedAt?: string;
+    lastSaleDate?: string;
+}
+/**
+ * HVP-only Data
+ *
+ * Fields that only exist in HVP, not synced to QVET.
+ */
+export interface CatalogItemHvpData {
+    /** How the item is used (sales, internal, etc.) */
+    usageType: UsageType;
+    /** Internal notes */
+    notes?: string;
+    /** Internal category for HVP organization */
+    internalCategory?: string;
+}
+/**
+ * Complete CatalogItem
+ *
+ * Full catalog item structure as stored in MongoDB.
+ */
+export interface CatalogItem {
+    /** MongoDB ObjectId as string */
+    id: string;
+    /** QVET internal code (primary key from QVET) */
+    qvetCode: number;
+    /** Fields that sync with QVET */
+    qvetSync: CatalogItemQvetSync;
+    /** HVP-only fields (no sync) */
+    hvpData: CatalogItemHvpData;
+    /** Has any pending changes (computed) */
+    hasPendingChanges: boolean;
+    /** Last sync from QVET */
+    lastSyncAt: string;
+    /** Current sync status */
+    syncStatus: SyncStatus;
+    createdAt: string;
+    updatedAt: string;
+    updatedBy?: string;
+}
+/**
+ * Simplified CatalogItem for list views
+ *
+ * Flattened structure using effective values (pending ?? value).
+ */
+export interface CatalogItemListItem {
+    id: string;
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    salePrice: number;
+    isActive: boolean;
+    usageType: UsageType;
+    hasPendingChanges: boolean;
+    syncStatus: SyncStatus;
+}

package/dist/types/catalog-item.types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * CatalogItem Types
+ *
+ * Type definitions for catalog items (products/services) that sync with QVET.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -6,3 +6,6 @@ export * from './api-response.types';
 export * from './company-settings.types';
 export * from './collaborator-fiscal.types';
 export * from './error-codes.types';
+export * from './sync-field.types';
+export * from './catalog-item.types';
+export * from './qvet.types';

package/dist/types/index.js

@@ -22,3 +22,6 @@ __exportStar(require("./api-response.types"), exports);
 __exportStar(require("./company-settings.types"), exports);
 __exportStar(require("./collaborator-fiscal.types"), exports);
 __exportStar(require("./error-codes.types"), exports);
+__exportStar(require("./sync-field.types"), exports);
+__exportStar(require("./catalog-item.types"), exports);
+__exportStar(require("./qvet.types"), exports);

package/dist/types/qvet.types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * QVET Types
+ *
+ * Type definitions for QVET system integration.
+ * Constants are in constants/qvet-*.ts
+ * Helpers are in utils/qvet-catalog.helpers.ts
+ */
+import { QVET_SECTIONS, QVET_CATALOG } from '../constants/qvet-catalog';
+import { WAREHOUSES } from '../constants/qvet-warehouses';
+/**
+ * QVET Section type (derived from QVET_SECTIONS constant)
+ */
+export type QvetSection = (typeof QVET_SECTIONS)[keyof typeof QVET_SECTIONS];
+/**
+ * QVET Catalog type (the complete catalog structure)
+ */
+export type QvetCatalog = typeof QVET_CATALOG;
+/**
+ * Warehouse type (derived from WAREHOUSES constant)
+ */
+export type Warehouse = (typeof WAREHOUSES)[number];

package/dist/types/qvet.types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * QVET Types
+ *
+ * Type definitions for QVET system integration.
+ * Constants are in constants/qvet-*.ts
+ * Helpers are in utils/qvet-catalog.helpers.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/sync-field.types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SyncField<T> - Bidirectional sync pattern
+ *
+ * Used for fields that sync between an external system (QVET) and HVP.
+ * Supports tracking proposed changes that are pending confirmation from the external system.
+ *
+ * @example
+ * // Clean state (no pending change)
+ * { value: "Original description", pending: undefined }
+ *
+ * // With pending change
+ * { value: "Original description", pending: "New description" }
+ */
+export interface SyncField<T> {
+    /** Current value from external system (QVET) */
+    value: T;
+    /** Proposed change waiting for external confirmation. undefined = no pending change */
+    pending: T | undefined;
+}
+/**
+ * Creates a new SyncField with an initial value
+ */
+export declare function createSyncField<T>(value: T): SyncField<T>;

package/dist/types/sync-field.types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyncField = createSyncField;
+/**
+ * Creates a new SyncField with an initial value
+ */
+function createSyncField(value) {
+    return { value, pending: undefined };
+}

package/dist/utils/qvet-catalog.helpers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * QVET Catalog Helpers
+ *
+ * Utility functions for working with QVET catalog data.
+ */
+/**
+ * Get all families for a section
+ */
+export declare function getFamiliesForSection(section: string): string[];
+/**
+ * Get all subfamilies for a section + family combination
+ */
+export declare function getSubfamiliesForFamily(section: string, family: string): readonly string[];
+/**
+ * Check if a section exists in the catalog
+ */
+export declare function isValidSection(section: string): boolean;
+/**
+ * Check if a section is countable (physical inventory)
+ */
+export declare function isCountableSection(section: string): boolean;
+/**
+ * Check if a family exists within a section
+ */
+export declare function isValidFamily(section: string, family: string): boolean;
+/**
+ * Check if a subfamily exists within a section + family
+ */
+export declare function isValidSubfamily(section: string, family: string, subfamily: string): boolean;
+/**
+ * Get sort order for a section (lower = higher priority)
+ */
+export declare function getSectionSortOrder(section: string): number;
+/**
+ * Check if an item requires expiration date tracking based on section and family
+ */
+export declare function requiresExpirationDate(section: string, family: string): boolean;

package/dist/utils/qvet-catalog.helpers.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * QVET Catalog Helpers
+ *
+ * Utility functions for working with QVET catalog data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFamiliesForSection = getFamiliesForSection;
+exports.getSubfamiliesForFamily = getSubfamiliesForFamily;
+exports.isValidSection = isValidSection;
+exports.isCountableSection = isCountableSection;
+exports.isValidFamily = isValidFamily;
+exports.isValidSubfamily = isValidSubfamily;
+exports.getSectionSortOrder = getSectionSortOrder;
+exports.requiresExpirationDate = requiresExpirationDate;
+const qvet_catalog_1 = require("../constants/qvet-catalog");
+const qvet_inventory_1 = require("../constants/qvet-inventory");
+// =============================================================================
+// CATALOG NAVIGATION
+// =============================================================================
+/**
+ * Get all families for a section
+ */
+function getFamiliesForSection(section) {
+    const sectionData = qvet_catalog_1.QVET_CATALOG[section];
+    if (!sectionData)
+        return [];
+    return Object.keys(sectionData);
+}
+/**
+ * Get all subfamilies for a section + family combination
+ */
+function getSubfamiliesForFamily(section, family) {
+    const sectionData = qvet_catalog_1.QVET_CATALOG[section];
+    if (!sectionData)
+        return [];
+    const familyData = sectionData[family];
+    if (!familyData)
+        return [];
+    return familyData;
+}
+// =============================================================================
+// VALIDATION
+// =============================================================================
+/**
+ * Check if a section exists in the catalog
+ */
+function isValidSection(section) {
+    return section in qvet_catalog_1.QVET_CATALOG;
+}
+/**
+ * Check if a section is countable (physical inventory)
+ */
+function isCountableSection(section) {
+    return qvet_inventory_1.INVENTORY_COUNTABLE_SECTIONS_SET.has(section);
+}
+/**
+ * Check if a family exists within a section
+ */
+function isValidFamily(section, family) {
+    const sectionData = qvet_catalog_1.QVET_CATALOG[section];
+    if (!sectionData)
+        return false;
+    return family in sectionData;
+}
+/**
+ * Check if a subfamily exists within a section + family
+ */
+function isValidSubfamily(section, family, subfamily) {
+    const subfamilies = getSubfamiliesForFamily(section, family);
+    return subfamilies.includes(subfamily);
+}
+// =============================================================================
+// SORTING
+// =============================================================================
+/**
+ * Get sort order for a section (lower = higher priority)
+ */
+function getSectionSortOrder(section) {
+    const index = qvet_inventory_1.SECTION_SORT_PRIORITY.indexOf(section);
+    if (index >= 0) {
+        return index;
+    }
+    // Non-priority sections come after, sorted alphabetically
+    return qvet_inventory_1.SECTION_SORT_PRIORITY.length + section.charCodeAt(0);
+}
+// =============================================================================
+// EXPIRATION DATE
+// =============================================================================
+/**
+ * Check if an item requires expiration date tracking based on section and family
+ */
+function requiresExpirationDate(section, family) {
+    // Full section requires expiration
+    if (qvet_inventory_1.SECTIONS_REQUIRE_EXPIRATION.includes(section)) {
+        return true;
+    }
+    // Check specific families within sections
+    const familiesForSection = qvet_inventory_1.FAMILIES_REQUIRE_EXPIRATION[section];
+    if (familiesForSection) {
+        return familiesForSection.includes(family);
+    }
+    return false;
+}

package/dist/utils/sync-field.helpers.d.ts

@@ -0,0 +1,84 @@
+import { SyncField } from '../types/sync-field.types';
+/**
+ * Get the effective value (pending if exists, otherwise current)
+ *
+ * @example
+ * getValue({ value: "old", pending: "new" }) // "new"
+ * getValue({ value: "old", pending: undefined }) // "old"
+ */
+export declare function getValue<T>(field: SyncField<T>): T;
+/**
+ * Get the external system value (always the synced one, ignores pending)
+ *
+ * @example
+ * getQvetValue({ value: "old", pending: "new" }) // "old"
+ */
+export declare function getQvetValue<T>(field: SyncField<T>): T;
+/**
+ * Check if field has a pending change
+ *
+ * @example
+ * hasPending({ value: "old", pending: "new" }) // true
+ * hasPending({ value: "old", pending: undefined }) // false
+ */
+export declare function hasPending<T>(field: SyncField<T>): boolean;
+/**
+ * Check if pending value differs from current value
+ *
+ * @example
+ * isDirty({ value: "old", pending: "new" }) // true
+ * isDirty({ value: "old", pending: "old" }) // false (same value)
+ * isDirty({ value: "old", pending: undefined }) // false
+ */
+export declare function isDirty<T>(field: SyncField<T>): boolean;
+/**
+ * Set a pending value. If newValue equals current value, clears pending instead.
+ *
+ * @example
+ * setPending({ value: "old", pending: undefined }, "new")
+ * // { value: "old", pending: "new" }
+ *
+ * setPending({ value: "old", pending: undefined }, "old")
+ * // { value: "old", pending: undefined } - no change needed
+ */
+export declare function setPending<T>(field: SyncField<T>, newValue: T): SyncField<T>;
+/**
+ * Clear pending (revert to external system value)
+ *
+ * @example
+ * clearPending({ value: "old", pending: "new" })
+ * // { value: "old", pending: undefined }
+ */
+export declare function clearPending<T>(field: SyncField<T>): SyncField<T>;
+/**
+ * Confirm sync from external system.
+ * Updates the value to the new external value and clears pending.
+ *
+ * @example
+ * // External system confirmed our change
+ * confirmSync({ value: "old", pending: "new" }, "new")
+ * // { value: "new", pending: undefined }
+ *
+ * // External system has different value
+ * confirmSync({ value: "old", pending: undefined }, "updated")
+ * // { value: "updated", pending: undefined }
+ */
+export declare function confirmSync<T>(field: SyncField<T>, externalValue: T): SyncField<T>;
+/**
+ * Apply sync from external system, preserving pending if it differs from new value.
+ * Use this when you want to keep local changes during a sync.
+ *
+ * @example
+ * // We have pending, external hasn't changed yet
+ * applySyncPreservePending({ value: "old", pending: "new" }, "old")
+ * // { value: "old", pending: "new" } - pending preserved
+ *
+ * // External confirmed our change
+ * applySyncPreservePending({ value: "old", pending: "new" }, "new")
+ * // { value: "new", pending: undefined } - pending cleared
+ *
+ * // External changed to something else (conflict scenario)
+ * applySyncPreservePending({ value: "old", pending: "new" }, "other")
+ * // { value: "other", pending: "new" } - pending preserved, value updated
+ */
+export declare function applySyncPreservePending<T>(field: SyncField<T>, externalValue: T): SyncField<T>;