hvp-shared 7.1.0 → 7.2.1

package/dist/contracts/index.d.ts

@@ -14,3 +14,4 @@ export * from './job';
 export * from './inventory-session';
 export * from './client-billing';
 export * from './global-invoice';
+export * from './inventory-report';

package/dist/contracts/index.js

@@ -30,3 +30,4 @@ __exportStar(require("./job"), exports);
 __exportStar(require("./inventory-session"), exports);
 __exportStar(require("./client-billing"), exports);
 __exportStar(require("./global-invoice"), exports);
+__exportStar(require("./inventory-report"), exports);

package/dist/contracts/inventory-report/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Inventory Report API Contracts
+ *
+ * Types, request and response definitions for inventory report endpoints.
+ */
+export * from './types';
+export * from './requests';
+export * from './responses';

package/dist/contracts/inventory-report/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Inventory Report API Contracts
+ *
+ * Types, request and response definitions for inventory report endpoints.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./types"), exports);
+__exportStar(require("./requests"), exports);
+__exportStar(require("./responses"), exports);

package/dist/contracts/inventory-report/requests.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Inventory Report Requests
+ *
+ * Request types for inventory report generation.
+ *
+ * @example POST /api/inventory/reports/generate
+ * @example GET /api/inventory/reports/periods
+ */
+import { ReportPeriodType } from './types';
+/**
+ * Generate Inventory Report Request
+ *
+ * Generates a complete inventory report for the specified period.
+ *
+ * @example POST /api/inventory/reports/generate
+ * { "periodType": "monthly", "year": 2026, "month": 3 }
+ */
+export interface GenerateInventoryReportRequest {
+    /** Period type */
+    periodType: ReportPeriodType;
+    /** Year */
+    year: number;
+    /** Month (1-12) — required for monthly, start month for quarterly */
+    month: number;
+    /** Branch filter (omit for global report) */
+    branch?: string;
+}

package/dist/contracts/inventory-report/requests.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Inventory Report Requests
+ *
+ * Request types for inventory report generation.
+ *
+ * @example POST /api/inventory/reports/generate
+ * @example GET /api/inventory/reports/periods
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/inventory-report/responses.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Inventory Report Responses
+ *
+ * Response types for inventory report endpoints.
+ *
+ * @example POST /api/inventory/reports/generate
+ * @example GET /api/inventory/reports/periods
+ */
+import { ReportSummary, FlowByCategory, TopShrinkageItem, PurchaseVsSaleItem, ConsumptionItem, CfAnomalyItem, PeriodComparisonRow } from './types';
+/**
+ * Full Inventory Report Response
+ *
+ * Contains all 7 report sections.
+ *
+ * @example POST /api/inventory/reports/generate
+ */
+export interface InventoryReportResponse {
+    /** Section 1: Executive summary with key metrics */
+    summary: ReportSummary;
+    /** Section 2: Stock flow aggregated by usageType */
+    flowByCategory: FlowByCategory[];
+    /** Section 3: Products with highest real shrinkage (excludes consumption and CF artifacts) */
+    topShrinkage: TopShrinkageItem[];
+    /** Section 4: Purchase vs sale analysis for directSale items */
+    purchaseVsSale: PurchaseVsSaleItem[];
+    /** Section 5: Internal consumption analysis for internalUse items */
+    consumption: ConsumptionItem[];
+    /** Section 6: Items flagged as possible conversion factor anomalies */
+    cfAnomalies: CfAnomalyItem[];
+    /** Section 7: Period-over-period comparison metrics */
+    periodComparison: PeriodComparisonRow[];
+    /** Report generation metadata */
+    metadata: ReportMetadata;
+}
+/**
+ * Report generation metadata
+ */
+export interface ReportMetadata {
+    /** When the report was generated */
+    generatedAt: string;
+    /** Period date range */
+    period: {
+        from: string;
+        to: string;
+    };
+    /** Previous period date range (for comparison) */
+    previousPeriod?: {
+        from: string;
+        to: string;
+    };
+    /** Branch filter applied */
+    branch?: string;
+    /** Number of months in the period */
+    periodMonths: number;
+}
+/**
+ * Available Report Period
+ *
+ * Represents a period that can be generated (has snapshot data).
+ */
+export interface AvailableReportPeriod {
+    /** Year */
+    year: number;
+    /** Month (1-12) */
+    month: number;
+    /** Label for display (e.g., "Marzo 2026") */
+    label: string;
+    /** Snapshot date used for end of period */
+    snapshotDate: string;
+    /** Total items in snapshot */
+    totalItems: number;
+}
+/**
+ * Available Periods Response
+ *
+ * @example GET /api/inventory/reports/periods
+ */
+export interface AvailablePeriodsResponse {
+    /** Available monthly periods (sorted newest first) */
+    months: AvailableReportPeriod[];
+}

package/dist/contracts/inventory-report/responses.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Inventory Report Responses
+ *
+ * Response types for inventory report endpoints.
+ *
+ * @example POST /api/inventory/reports/generate
+ * @example GET /api/inventory/reports/periods
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/inventory-report/types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Inventory Report Types
+ *
+ * Domain types for periodic inventory reports (monthly, quarterly, annual).
+ * These reports aggregate stock flow data, detect anomalies, and compare periods.
+ */
+import { StockFlow } from '../stock-calculation/types';
+/**
+ * Report period type
+ */
+export declare enum ReportPeriodType {
+    monthly = "monthly",
+    quarterly = "quarterly",
+    annual = "annual"
+}
+export declare const REPORT_PERIOD_TYPE_LABELS: Record<ReportPeriodType, string>;
+/**
+ * Shrinkage flag — classifies the nature of each product's shrinkage
+ */
+export declare enum ShrinkageFlag {
+    /** Real unexplained loss */
+    realLoss = "real_loss",
+    /** Likely caused by conversion factor mismatch */
+    conversionArtifact = "conversion_artifact",
+    /** Expected consumption (internalUse items) */
+    expectedConsumption = "expected_consumption",
+    /** Surplus — more stock than expected */
+    surplus = "surplus",
+    /** Negligible (within tolerance) */
+    negligible = "negligible"
+}
+export declare const SHRINKAGE_FLAG_LABELS: Record<ShrinkageFlag, string>;
+/**
+ * Section 1: Executive Summary
+ */
+export interface ReportSummary {
+    /** Period date range */
+    period: {
+        from: string;
+        to: string;
+    };
+    /** Branch filter applied (undefined = all) */
+    branch?: string;
+    /** Stock value at period end (PVP) */
+    endStockValuePvp: number;
+    /** Stock value at period end (unit cost / PMPC) */
+    endStockValueCost: number;
+    /** Total products with movement in period */
+    productsWithMovement: number;
+    /** Total products in catalog */
+    totalCatalogProducts: number;
+    /** Aggregate purchase quantity */
+    totalPurchasesQty: number;
+    /** Aggregate purchase value (cost) */
+    totalPurchasesValue: number;
+    /** Aggregate sales quantity */
+    totalSalesQty: number;
+    /** Aggregate sales value (cost) */
+    totalSalesValue: number;
+    /** Total shrinkage units (directSale + autoDeduct only) */
+    totalShrinkageQty: number;
+    /** Total shrinkage value */
+    totalShrinkageValue: number;
+    /** Total internal consumption value */
+    totalConsumptionValue: number;
+    /** Number of items flagged as conversion artifacts */
+    conversionArtifactCount: number;
+    /** Comparison with previous period (same length) */
+    previousPeriod?: PeriodDelta;
+}
+/**
+ * Delta between current and previous period
+ */
+export interface PeriodDelta {
+    /** Previous period date range */
+    period: {
+        from: string;
+        to: string;
+    };
+    /** End stock value delta (%) */
+    stockValueDeltaPct: number;
+    /** Sales qty delta (%) */
+    salesDeltaPct: number;
+    /** Purchases qty delta (%) */
+    purchasesDeltaPct: number;
+    /** Shrinkage value delta (%) */
+    shrinkageDeltaPct: number;
+}
+/**
+ * Section 2: Flow by Category
+ *
+ * Aggregated stock flow grouped by usageType or section.
+ */
+export interface FlowByCategory {
+    /** Grouping key (usageType value or section name) */
+    category: string;
+    /** Display label */
+    label: string;
+    /** Number of products in this category */
+    productCount: number;
+    /** Aggregated flow */
+    flow: StockFlow;
+    /** Aggregated end stock value (cost) */
+    endStockValue: number;
+    /** Delta vs previous period (%) — undefined if no previous data */
+    endStockDeltaPct?: number;
+}
+/**
+ * Section 3: Top Shrinkage Items (real losses)
+ */
+export interface TopShrinkageItem {
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    usageType: string;
+    conversionFactor: number;
+    unitCost: number;
+    flow: StockFlow;
+    /** Classification of the shrinkage */
+    flag: ShrinkageFlag;
+    /** Shrinkage as % of available stock */
+    shrinkagePct: number;
+}
+/**
+ * Section 4: Purchase vs Sale Analysis
+ */
+export interface PurchaseVsSaleItem {
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    /** Total purchases (units, converted to sale units) */
+    purchasesQty: number;
+    /** Total purchase value (cost) */
+    purchasesValue: number;
+    /** Total sales (units) */
+    salesQty: number;
+    /** Total sales value (cost) */
+    salesValue: number;
+    /** Coverage ratio: purchases / sales. >1 = building stock, <1 = depleting */
+    coverageRatio: number | null;
+    /** Current end stock */
+    endStock: number;
+}
+/**
+ * Section 5: Internal Consumption Analysis
+ */
+export interface ConsumptionItem {
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    /** Consumed units = available - actualStock */
+    consumed: number;
+    /** Consumed value (cost) */
+    consumedValue: number;
+    /** Monthly consumption rate */
+    monthlyRate: number;
+    /** End stock */
+    endStock: number;
+    /** Days of stock remaining at current rate */
+    stockDaysRemaining: number | null;
+    /** Low stock flag (< 15 days remaining) */
+    isLowStock: boolean;
+}
+/**
+ * Section 6: Conversion Factor Anomaly
+ */
+export interface CfAnomalyItem {
+    qvetCode: number;
+    description: string;
+    section: string;
+    conversionFactor: number;
+    /** Raw shrinkage (units) — may be unrealistic due to CF */
+    shrinkage: number;
+    /** Shrinkage value */
+    shrinkageValue: number;
+    /** Shrinkage as % of available */
+    shrinkagePct: number;
+    /** Initial stock */
+    initialStock: number;
+    /** End stock */
+    actualStock: number;
+    /** Purchases (converted) */
+    purchasesTotal: number;
+    /** Likely explanation */
+    likelyCause: string;
+}
+/**
+ * Section 7: Period Comparison (multi-metric)
+ */
+export interface PeriodComparisonRow {
+    /** Metric name */
+    metric: string;
+    /** Display label (Spanish) */
+    label: string;
+    /** Current period value */
+    current: number;
+    /** Previous period value */
+    previous: number;
+    /** Absolute delta */
+    delta: number;
+    /** Percentage delta */
+    deltaPct: number | null;
+    /** Unit for display (e.g., "units", "$", "%") */
+    unit: string;
+}
+/** Classification for a report line */
+export type ReportLineClassification = 'consumption' | 'expired' | 'confirmed_loss' | 'unconfirmed_loss' | 'surplus' | 'negligible';
+export declare const REPORT_LINE_CLASSIFICATION_LABELS: Record<ReportLineClassification, string>;
+/** One product in one branch — the atomic unit of the V2 report */
+export interface ReportLine {
+    qvetCode: number;
+    description: string;
+    section: string;
+    family: string;
+    usageType: string;
+    branch: string;
+    unitCost: number;
+    conversionFactor: number;
+    initialStock: number;
+    purchases: number;
+    transfersIn: number;
+    transfersOut: number;
+    sold: number;
+    actualStock: number;
+    available: number;
+    theoreticalStock: number;
+    shrinkage: number;
+    shrinkageValue: number;
+    expiredQty: number;
+    expiredValue: number;
+    classification: ReportLineClassification;
+}
+/** Per-product-per-branch override */
+export interface ReportOverrideV2 {
+    qvetCode: number;
+    /** null = all branches */
+    branch: string | null;
+    action: 'ignore';
+    reason?: string;
+    reviewedBy?: string;
+    reviewedByName?: string;
+    reviewedAt?: string;
+}
+/**
+ * Waterfall V2 — same structure at every level (global, branch, section).
+ *
+ * Shows base (sin overrides, FIXED) and adjusted (con overrides).
+ * Equation: balance = consumption + expired + realLoss (ALWAYS holds)
+ */
+export interface WaterfallV2 {
+    baseFaltantes: number;
+    baseSobrantes: number;
+    baseBalance: number;
+    faltantes: number;
+    sobrantes: number;
+    balance: number;
+    consumption: number;
+    expired: number;
+    realLoss: number;
+    itemCount: number;
+}
+/** Waterfalls at all levels */
+export interface ReportWaterfalls {
+    global: WaterfallV2;
+    branches: {
+        branch: string;
+        waterfall: WaterfallV2;
+    }[];
+    sections: {
+        section: string;
+        waterfall: WaterfallV2;
+    }[];
+}
+/** V2 persisted report document */
+export interface InventoryReportDocumentV2 {
+    id: string;
+    periodType: ReportPeriodType;
+    year: number;
+    month: number;
+    status: 'draft' | 'closed';
+    schemaVersion: number;
+    lines: ReportLine[];
+    overrides: ReportOverrideV2[];
+    waterfall: ReportWaterfalls;
+    metadata: import('./responses').ReportMetadata;
+    createdByName?: string;
+    closedByName?: string;
+    closedAt?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}

package/dist/contracts/inventory-report/types.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Inventory Report Types
+ *
+ * Domain types for periodic inventory reports (monthly, quarterly, annual).
+ * These reports aggregate stock flow data, detect anomalies, and compare periods.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPORT_LINE_CLASSIFICATION_LABELS = exports.SHRINKAGE_FLAG_LABELS = exports.ShrinkageFlag = exports.REPORT_PERIOD_TYPE_LABELS = exports.ReportPeriodType = void 0;
+// ============================================================================
+// Enums
+// ============================================================================
+/**
+ * Report period type
+ */
+var ReportPeriodType;
+(function (ReportPeriodType) {
+    ReportPeriodType["monthly"] = "monthly";
+    ReportPeriodType["quarterly"] = "quarterly";
+    ReportPeriodType["annual"] = "annual";
+})(ReportPeriodType || (exports.ReportPeriodType = ReportPeriodType = {}));
+exports.REPORT_PERIOD_TYPE_LABELS = {
+    [ReportPeriodType.monthly]: 'Mensual',
+    [ReportPeriodType.quarterly]: 'Trimestral',
+    [ReportPeriodType.annual]: 'Anual',
+};
+/**
+ * Shrinkage flag — classifies the nature of each product's shrinkage
+ */
+var ShrinkageFlag;
+(function (ShrinkageFlag) {
+    /** Real unexplained loss */
+    ShrinkageFlag["realLoss"] = "real_loss";
+    /** Likely caused by conversion factor mismatch */
+    ShrinkageFlag["conversionArtifact"] = "conversion_artifact";
+    /** Expected consumption (internalUse items) */
+    ShrinkageFlag["expectedConsumption"] = "expected_consumption";
+    /** Surplus — more stock than expected */
+    ShrinkageFlag["surplus"] = "surplus";
+    /** Negligible (within tolerance) */
+    ShrinkageFlag["negligible"] = "negligible";
+})(ShrinkageFlag || (exports.ShrinkageFlag = ShrinkageFlag = {}));
+exports.SHRINKAGE_FLAG_LABELS = {
+    [ShrinkageFlag.realLoss]: 'Pérdida real',
+    [ShrinkageFlag.conversionArtifact]: 'Posible error de conversión',
+    [ShrinkageFlag.expectedConsumption]: 'Consumo esperado',
+    [ShrinkageFlag.surplus]: 'Sobrante',
+    [ShrinkageFlag.negligible]: 'Despreciable',
+};
+exports.REPORT_LINE_CLASSIFICATION_LABELS = {
+    consumption: 'Consumo interno',
+    expired: 'Caducidad',
+    confirmed_loss: 'Pérdida confirmada',
+    unconfirmed_loss: 'Sin confirmar',
+    surplus: 'Sobrante',
+    negligible: 'Despreciable',
+};

package/package.json

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