hvp-shared 3.4.0 → 3.5.1

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

@@ -0,0 +1,113 @@
+/**
+ * CatalogItem Request Types
+ *
+ * Request DTOs for catalog item endpoints.
+ */
+import { UsageType, SyncStatus } from '../../constants/catalog-item.constants';
+/**
+ * Query filters for listing catalog items
+ *
+ * @example GET /api/catalog-items?section=FARMACIA&isActive=true&page=1&limit=20
+ */
+export interface CatalogItemQueryFilters {
+    /** Filter by section */
+    section?: string;
+    /** Filter by family */
+    family?: string;
+    /** Filter by usage type */
+    usageType?: UsageType;
+    /** Filter by active status */
+    isActive?: boolean;
+    /** Filter by sync status */
+    syncStatus?: SyncStatus;
+    /** Show only items with pending changes */
+    hasPendingChanges?: boolean;
+    /** Search in description/barcode */
+    search?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    limit?: number;
+    /** Sort field */
+    sortBy?: 'description' | 'qvetCode' | 'section' | 'salePrice' | 'updatedAt';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Update QVET sync fields (sets pending values)
+ *
+ * @example PATCH /api/catalog-items/:id
+ */
+export interface UpdateCatalogItemRequest {
+    /** Update description (sets pending) */
+    description?: string;
+    /** Update sale price (sets pending) */
+    salePrice?: number;
+    /** Update purchase price (sets pending) */
+    purchasePrice?: number;
+    /** Update section (sets pending) */
+    section?: string;
+    /** Update family (sets pending) */
+    family?: string;
+    /** Update subfamily (sets pending) */
+    subfamily?: string;
+    /** Update barcode (sets pending) */
+    barcode?: string;
+    /** Update reference (sets pending) */
+    reference?: string;
+    /** Update brand (sets pending) */
+    brand?: string;
+    /** Update active status (sets pending) */
+    isActive?: boolean;
+    /** Update stock control type (sets pending) */
+    stockControlType?: string;
+}
+/**
+ * Update HVP-only fields (direct update, no pending)
+ *
+ * @example PATCH /api/catalog-items/:id/hvp-data
+ */
+export interface UpdateCatalogItemHvpDataRequest {
+    /** Usage type */
+    usageType?: UsageType;
+    /** Internal notes */
+    notes?: string;
+    /** Internal category */
+    internalCategory?: string;
+}
+/**
+ * Update stock levels for a warehouse (sets pending)
+ *
+ * @example PATCH /api/catalog-items/:id/stock/:warehouse
+ */
+export interface UpdateWarehouseStockRequest {
+    /** Minimum stock level */
+    minStock?: number;
+    /** Optimal stock level */
+    optimalStock?: number;
+}
+/**
+ * Bulk update request
+ *
+ * @example PATCH /api/catalog-items/bulk
+ */
+export interface BulkUpdateCatalogItemsRequest {
+    /** Item IDs to update */
+    ids: string[];
+    /** Updates to apply */
+    updates: {
+        /** Update usage type for all selected items */
+        usageType?: UsageType;
+        /** Update active status (sets pending) */
+        isActive?: boolean;
+    };
+}
+/**
+ * Revert a field to QVET value
+ *
+ * @example POST /api/catalog-items/:id/revert/:field
+ */
+export interface RevertFieldRequest {
+    /** Field name to revert */
+    field: string;
+}

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

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

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/types.d.ts

@@ -1,8 +1,8 @@
 /**
  * Shared types for HVP2021
- * Used by both backend and frontend for type consistency
+ * Re-exports from types/index.ts for backward compatibility.
+ *
+ * Note: This file exists for module resolution. TypeScript resolves
+ * `import from './types'` to this file instead of types/index.ts.
  */
-export * from './types/api-response.types';
-export * from './types/error-codes.types';
-export * from './types/company-settings.types';
-export * from './types/collaborator-fiscal.types';
+export * from './types/index';

package/dist/types.js

@@ -1,8 +1,4 @@
 "use strict";
-/**
- * Shared types for HVP2021
- * Used by both backend and frontend for type consistency
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -18,16 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// ============================================================================
-// API Response Types - Standardized format for all endpoints
-// ============================================================================
-__exportStar(require("./types/api-response.types"), exports);
-// ============================================================================
-// Error Codes - Domain-specific error codes
-// ============================================================================
-__exportStar(require("./types/error-codes.types"), exports);
-// ============================================================================
-// Domain Types - Business entities and DTOs
-// ============================================================================
-__exportStar(require("./types/company-settings.types"), exports);
-__exportStar(require("./types/collaborator-fiscal.types"), exports);
+/**
+ * Shared types for HVP2021
+ * Re-exports from types/index.ts for backward compatibility.
+ *
+ * Note: This file exists for module resolution. TypeScript resolves
+ * `import from './types'` to this file instead of types/index.ts.
+ */
+__exportStar(require("./types/index"), exports);

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;
+}