hvp-shared 6.7.1 → 6.9.0

package/dist/constants/background-job.constants.d.ts

@@ -15,8 +15,51 @@ export declare enum JobType {
     SYNC_MOVEMENTS = "SYNC_MOVEMENTS",
     SYNC_STOCK_CONFIG = "SYNC_STOCK_CONFIG",
     SYNC_CATALOG = "SYNC_CATALOG",
+    SYNC_CLIENTS = "SYNC_CLIENTS",
+    SYNC_INVENTORY_SNAPSHOT = "SYNC_INVENTORY_SNAPSHOT",
+    SYNC_BATCH = "SYNC_BATCH",
     SYNC_ALL = "SYNC_ALL"
 }
+/**
+ * Report types for batch sync operations.
+ * Each report type has specific parameter requirements.
+ */
+export declare enum ReportType {
+    /** Sales report - uses date range params */
+    SALES = "SALES",
+    /** Purchases report - uses date range params */
+    PURCHASES = "PURCHASES",
+    /** Inventory movements report - uses date range params */
+    MOVEMENTS = "MOVEMENTS",
+    /** Transfers report - uses date range params */
+    TRANSFERS = "TRANSFERS",
+    /** Inventory snapshot - uses snapshot date param */
+    INVENTORY_SNAPSHOT = "INVENTORY_SNAPSHOT",
+    /** Clients list - no date params required */
+    CLIENTS = "CLIENTS",
+    /** Product catalog - no date params required */
+    CATALOG = "CATALOG",
+    /** Stock configuration - no date params required */
+    STOCK_CONFIG = "STOCK_CONFIG"
+}
+/**
+ * Sub-task status within a batch job
+ */
+export declare enum SubTaskStatus {
+    PENDING = "pending",
+    IN_PROGRESS = "in_progress",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    SKIPPED = "skipped"
+}
+/**
+ * Parameter type for each report type
+ */
+export type ReportParamType = 'date_range' | 'snapshot' | 'no_params';
+/**
+ * Mapping of report types to their parameter type
+ */
+export declare const REPORT_PARAM_TYPES: Record<ReportType, ReportParamType>;
 /**
  * Job execution status
  */
@@ -40,6 +83,14 @@ export declare enum JobStep {
  * Human-readable labels for job types (Spanish for UI)
  */
 export declare const JOB_TYPE_LABELS: Record<JobType, string>;
+/**
+ * Human-readable labels for report types (Spanish for UI)
+ */
+export declare const REPORT_TYPE_LABELS: Record<ReportType, string>;
+/**
+ * Human-readable labels for sub-task status (Spanish for UI)
+ */
+export declare const SUB_TASK_STATUS_LABELS: Record<SubTaskStatus, string>;
 /**
  * Human-readable labels for job steps (Spanish for UI)
  */

package/dist/constants/background-job.constants.js

@@ -6,7 +6,7 @@
  * Used by frontend (polling) and backend (job execution).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JOB_STATUS_LABELS = exports.JOB_STEP_LABELS = exports.JOB_TYPE_LABELS = exports.JobStep = exports.JobStatus = exports.JobType = void 0;
+exports.JOB_STATUS_LABELS = exports.JOB_STEP_LABELS = exports.SUB_TASK_STATUS_LABELS = exports.REPORT_TYPE_LABELS = exports.JOB_TYPE_LABELS = exports.JobStep = exports.JobStatus = exports.REPORT_PARAM_TYPES = exports.SubTaskStatus = exports.ReportType = exports.JobType = void 0;
 /**
  * Job types for QVET sync operations
  */
@@ -19,8 +19,58 @@ var JobType;
     JobType["SYNC_MOVEMENTS"] = "SYNC_MOVEMENTS";
     JobType["SYNC_STOCK_CONFIG"] = "SYNC_STOCK_CONFIG";
     JobType["SYNC_CATALOG"] = "SYNC_CATALOG";
+    JobType["SYNC_CLIENTS"] = "SYNC_CLIENTS";
+    JobType["SYNC_INVENTORY_SNAPSHOT"] = "SYNC_INVENTORY_SNAPSHOT";
+    JobType["SYNC_BATCH"] = "SYNC_BATCH";
     JobType["SYNC_ALL"] = "SYNC_ALL";
 })(JobType || (exports.JobType = JobType = {}));
+/**
+ * Report types for batch sync operations.
+ * Each report type has specific parameter requirements.
+ */
+var ReportType;
+(function (ReportType) {
+    /** Sales report - uses date range params */
+    ReportType["SALES"] = "SALES";
+    /** Purchases report - uses date range params */
+    ReportType["PURCHASES"] = "PURCHASES";
+    /** Inventory movements report - uses date range params */
+    ReportType["MOVEMENTS"] = "MOVEMENTS";
+    /** Transfers report - uses date range params */
+    ReportType["TRANSFERS"] = "TRANSFERS";
+    /** Inventory snapshot - uses snapshot date param */
+    ReportType["INVENTORY_SNAPSHOT"] = "INVENTORY_SNAPSHOT";
+    /** Clients list - no date params required */
+    ReportType["CLIENTS"] = "CLIENTS";
+    /** Product catalog - no date params required */
+    ReportType["CATALOG"] = "CATALOG";
+    /** Stock configuration - no date params required */
+    ReportType["STOCK_CONFIG"] = "STOCK_CONFIG";
+})(ReportType || (exports.ReportType = ReportType = {}));
+/**
+ * Sub-task status within a batch job
+ */
+var SubTaskStatus;
+(function (SubTaskStatus) {
+    SubTaskStatus["PENDING"] = "pending";
+    SubTaskStatus["IN_PROGRESS"] = "in_progress";
+    SubTaskStatus["COMPLETED"] = "completed";
+    SubTaskStatus["FAILED"] = "failed";
+    SubTaskStatus["SKIPPED"] = "skipped";
+})(SubTaskStatus || (exports.SubTaskStatus = SubTaskStatus = {}));
+/**
+ * Mapping of report types to their parameter type
+ */
+exports.REPORT_PARAM_TYPES = {
+    [ReportType.SALES]: 'date_range',
+    [ReportType.PURCHASES]: 'date_range',
+    [ReportType.MOVEMENTS]: 'date_range',
+    [ReportType.TRANSFERS]: 'date_range',
+    [ReportType.INVENTORY_SNAPSHOT]: 'snapshot',
+    [ReportType.CLIENTS]: 'no_params',
+    [ReportType.CATALOG]: 'no_params',
+    [ReportType.STOCK_CONFIG]: 'no_params',
+};
 /**
  * Job execution status
  */
@@ -53,8 +103,34 @@ exports.JOB_TYPE_LABELS = {
     [JobType.SYNC_MOVEMENTS]: 'Sincronizar Movimientos',
     [JobType.SYNC_STOCK_CONFIG]: 'Sincronizar Config. Stock',
     [JobType.SYNC_CATALOG]: 'Sincronizar Catálogo',
+    [JobType.SYNC_CLIENTS]: 'Sincronizar Clientes',
+    [JobType.SYNC_INVENTORY_SNAPSHOT]: 'Sincronizar Snapshot Inventario',
+    [JobType.SYNC_BATCH]: 'Sincronización por Lotes',
     [JobType.SYNC_ALL]: 'Sincronizar Todo',
 };
+/**
+ * Human-readable labels for report types (Spanish for UI)
+ */
+exports.REPORT_TYPE_LABELS = {
+    [ReportType.SALES]: 'Ventas',
+    [ReportType.PURCHASES]: 'Compras',
+    [ReportType.MOVEMENTS]: 'Movimientos',
+    [ReportType.TRANSFERS]: 'Traspasos',
+    [ReportType.INVENTORY_SNAPSHOT]: 'Snapshot Inventario',
+    [ReportType.CLIENTS]: 'Clientes',
+    [ReportType.CATALOG]: 'Catálogo',
+    [ReportType.STOCK_CONFIG]: 'Config. Stock',
+};
+/**
+ * Human-readable labels for sub-task status (Spanish for UI)
+ */
+exports.SUB_TASK_STATUS_LABELS = {
+    [SubTaskStatus.PENDING]: 'Pendiente',
+    [SubTaskStatus.IN_PROGRESS]: 'En proceso',
+    [SubTaskStatus.COMPLETED]: 'Completado',
+    [SubTaskStatus.FAILED]: 'Fallido',
+    [SubTaskStatus.SKIPPED]: 'Omitido',
+};
 /**
  * Human-readable labels for job steps (Spanish for UI)
  */

package/dist/contracts/qvet/responses.d.ts

@@ -9,7 +9,7 @@
  * Represents one line item in a sale transaction
  */
 export interface QvetSaleResponse {
-    _id: string;
+    id: string;
     date: string;
     warehouse: string;
     subtotal: number;
@@ -90,7 +90,7 @@ export interface QvetSalesQueryParams {
     year?: number;
     month?: number;
     halfMonth?: 1 | 2;
-    warehouse?: string;
+    branch?: string;
     section?: string;
     family?: string;
     qvetCode?: number;
@@ -104,7 +104,7 @@ export interface QvetSalesQueryParams {
  * Represents one line item in a purchase transaction
  */
 export interface QvetPurchaseResponse {
-    _id: string;
+    id: string;
     qvetCode: number;
     productName: string;
     barcode: string;
@@ -184,7 +184,7 @@ export interface QvetPurchasesQueryParams {
     year?: number;
     month?: number;
     halfMonth?: 1 | 2;
-    warehouse?: string;
+    branch?: string;
     section?: string;
     family?: string;
     supplier?: string;
@@ -193,3 +193,78 @@ export interface QvetPurchasesQueryParams {
     skip?: number;
     sort?: string;
 }
+/**
+ * Single movement record from QVET
+ * Represents an inventory movement (sale, purchase, transfer, adjustment, etc.)
+ */
+export interface QvetMovementResponse {
+    id: string;
+    date: string;
+    warehouse: string;
+    movementType: string;
+    quantity: number;
+    runningStock: number;
+    staffName: string;
+    counterparty: string;
+    qvetCode: number;
+    productName: string;
+    section: string;
+    family: string;
+    subfamily: string;
+    conversionFactor: number;
+    lastPurchaseCost: number;
+    avgPurchaseCost: number;
+    batchReference: string | null;
+    expirationDate: string | null;
+    branch: string;
+    syncedAt: string;
+}
+/**
+ * Paginated list of movements
+ */
+export interface QvetMovementsListResponse {
+    ok: boolean;
+    data: QvetMovementResponse[];
+    pagination: {
+        total: number;
+        limit: number;
+        skip: number;
+        hasMore: boolean;
+    };
+}
+/**
+ * Movements summary statistics for a period
+ */
+export interface QvetMovementsSummaryResponse {
+    ok: boolean;
+    data: {
+        totalRecords: number;
+        totalQuantityIn: number;
+        totalQuantityOut: number;
+        uniqueProducts: number;
+        byMovementType: Array<{
+            type: string;
+            count: number;
+            totalQuantity: number;
+        }>;
+    };
+}
+/**
+ * Query parameters for movements endpoint
+ */
+export interface QvetMovementsQueryParams {
+    startDate?: string;
+    endDate?: string;
+    year?: number;
+    month?: number;
+    quarter?: 1 | 2 | 3 | 4;
+    branch?: string;
+    warehouse?: string;
+    movementType?: string;
+    section?: string;
+    family?: string;
+    qvetCode?: number;
+    limit?: number;
+    skip?: number;
+    sort?: string;
+}

package/dist/types/background-job.types.d.ts

@@ -4,7 +4,7 @@
  * Interfaces for background job system.
  * Used by frontend (polling) and backend (job execution).
  */
-import { JobStatus, JobStep, JobType } from '../constants/background-job.constants';
+import { JobStatus, JobStep, JobType, ReportType, SubTaskStatus } from '../constants/background-job.constants';
 /**
  * Job progress information
  */
@@ -40,6 +40,85 @@ export interface JobError {
     /** Stack trace (only in development) */
     stack?: string;
 }
+/**
+ * Parameters for date-range based reports (Sales, Purchases, Movements, Transfers)
+ */
+export interface DateRangeParams {
+    /** Year to sync */
+    year: number;
+    /** Month to sync (1-12). If omitted, syncs full year */
+    month?: number;
+    /** Half month (1 = days 1-15, 2 = days 16-end). Optional */
+    halfMonth?: 1 | 2;
+}
+/**
+ * Parameters for snapshot-based reports (Inventory Snapshot)
+ */
+export interface SnapshotParams {
+    /** The specific date to get inventory snapshot for (ISO string) */
+    snapshotDate: string;
+    /** Optional: filter by warehouse */
+    warehouse?: string;
+}
+/**
+ * Union type for all possible sync parameters
+ */
+export type SyncParams = DateRangeParams | SnapshotParams | Record<string, never>;
+/**
+ * Result for a single sub-task
+ */
+export interface SubTaskResult {
+    /** Total records processed */
+    recordsProcessed: number;
+    /** New records created */
+    recordsCreated: number;
+    /** Existing records updated */
+    recordsUpdated: number;
+    /** Non-fatal errors encountered */
+    errors: string[];
+}
+/**
+ * A sub-task within a batch job
+ */
+export interface BatchSubTask {
+    /** Unique identifier for this sub-task */
+    id: string;
+    /** Report type to sync */
+    reportType: ReportType;
+    /** Current status */
+    status: SubTaskStatus;
+    /** Parameters specific to this report type */
+    params: SyncParams;
+    /** Progress percentage (0-100) */
+    progress: number;
+    /** Human-readable progress message */
+    progressMessage: string;
+    /** When the sub-task started */
+    startedAt?: string;
+    /** When the sub-task completed */
+    completedAt?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Result when completed */
+    result?: SubTaskResult;
+    /** Error message when failed */
+    error?: string;
+}
+/**
+ * Summary of batch job sub-tasks
+ */
+export interface BatchSubTasksSummary {
+    /** Total number of sub-tasks */
+    total: number;
+    /** Number completed successfully */
+    completed: number;
+    /** Number failed */
+    failed: number;
+    /** Number skipped */
+    skipped: number;
+    /** Number still pending */
+    pending: number;
+}
 /**
  * Background job response (for API)
  */
@@ -68,6 +147,12 @@ export interface BackgroundJobResponse {
     result?: JobResult;
     /** Error (when failed) */
     error?: JobError;
+    /** Index of current sub-task being processed (for batch jobs) */
+    currentSubTaskIndex?: number;
+    /** Sub-tasks in this batch job */
+    subTasks?: BatchSubTask[];
+    /** Summary of sub-task statuses (for batch jobs) */
+    subTasksSummary?: BatchSubTasksSummary;
 }
 /**
  * Request to create a new sync job
@@ -78,6 +163,18 @@ export interface CreateSyncJobRequest {
     /** Optional parameters for the sync */
     params?: Record<string, unknown>;
 }
+/**
+ * Request to create a batch sync job
+ */
+export interface CreateBatchSyncJobRequest {
+    /** Sub-tasks to execute in this batch */
+    subTasks: Array<{
+        /** Report type to sync */
+        reportType: ReportType;
+        /** Parameters specific to this report type */
+        params: SyncParams;
+    }>;
+}
 /**
  * Sync status for a report type
  */
@@ -105,3 +202,25 @@ export interface SyncStatusResponse {
         startedAt: string;
     }>;
 }
+/**
+ * A sync suggestion for missing data
+ */
+export interface SyncSuggestion {
+    /** Report type */
+    reportType: ReportType;
+    /** Suggested parameters */
+    params: SyncParams;
+    /** Human-readable description */
+    description: string;
+    /** Priority (lower = more important) */
+    priority: number;
+}
+/**
+ * Sync suggestions response
+ */
+export interface SyncSuggestionsResponse {
+    /** List of suggested syncs */
+    suggestions: SyncSuggestion[];
+    /** When suggestions were generated */
+    generatedAt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "6.7.1",
+  "version": "6.9.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",