@classytic/flow 0.1.4

package/dist/enums-C3_z6aHC.mjs

@@ -0,0 +1,82 @@
+//#region src/domain/enums/location-type.ts
+const LocationType = {
+	view: "view",
+	internal: "internal",
+	receiving: "receiving",
+	storage: "storage",
+	picking: "picking",
+	packing: "packing",
+	shipping: "shipping",
+	transit: "transit",
+	vendor: "vendor",
+	customer: "customer",
+	returns: "returns",
+	quality_hold: "quality_hold",
+	damaged: "damaged",
+	scrap: "scrap",
+	inventory_loss: "inventory_loss",
+	production: "production"
+};
+/** Location types that hold physical stock (non-virtual). */
+const STOCKABLE_LOCATION_TYPES = [
+	LocationType.internal,
+	LocationType.receiving,
+	LocationType.storage,
+	LocationType.picking,
+	LocationType.packing,
+	LocationType.shipping,
+	LocationType.transit,
+	LocationType.returns,
+	LocationType.quality_hold,
+	LocationType.damaged,
+	LocationType.production
+];
+/** Virtual location types — no physical stock, used for accounting/routing. */
+const VIRTUAL_LOCATION_TYPES = [
+	LocationType.view,
+	LocationType.vendor,
+	LocationType.customer,
+	LocationType.scrap,
+	LocationType.inventory_loss
+];
+//#endregion
+//#region src/domain/enums/operation-type.ts
+const OperationType = {
+	receipt: "receipt",
+	transfer: "transfer",
+	shipment: "shipment",
+	return: "return",
+	adjustment: "adjustment",
+	count: "count"
+};
+//#endregion
+//#region src/domain/enums/stock-status.ts
+const StockStatus = {
+	sellable: "sellable",
+	damaged: "damaged",
+	quarantine: "quarantine",
+	hold: "hold",
+	returns: "returns",
+	expired: "expired",
+	in_transit: "in_transit"
+};
+/** Only sellable stock is counted as available for sale. */
+const SELLABLE_STATUSES = [StockStatus.sellable];
+//#endregion
+//#region src/domain/enums/tracking-mode.ts
+const TrackingMode = {
+	none: "none",
+	lot: "lot",
+	serial: "serial"
+};
+//#endregion
+//#region src/domain/enums/valuation-method.ts
+const ValuationMethod = {
+	wac: "wac",
+	fifo: "fifo",
+	fefo: "fefo",
+	specific: "specific",
+	standard: "standard"
+};
+//#endregion
+export { OperationType as a, VIRTUAL_LOCATION_TYPES as c, StockStatus as i, TrackingMode as n, LocationType as o, SELLABLE_STATUSES as r, STOCKABLE_LOCATION_TYPES as s, ValuationMethod as t };

package/dist/event-bus-BNmyoJb4.mjs

@@ -0,0 +1,37 @@
+//#region src/events/event-bus.ts
+/**
+* In-process event bus.
+*
+* Serves as the default {@link EventEmitterPort} implementation.
+* Handlers are invoked fire-and-forget; failures are logged but never
+* propagate to the emitter.  Replace with a Redis/Kafka adapter for
+* distributed workloads.
+*/
+var InProcessEventBus = class {
+	handlers = /* @__PURE__ */ new Map();
+	async emit(event, data, _session) {
+		const subscribers = this.handlers.get(event);
+		if (!subscribers || subscribers.size === 0) return;
+		const tasks = [...subscribers].map((handler) => handler(data).catch((err) => {
+			console.error(`[FlowEventBus] Handler error on "${event}":`, err);
+		}));
+		await Promise.all(tasks);
+	}
+	on(event, handler) {
+		let set = this.handlers.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.handlers.set(event, set);
+		}
+		set.add(handler);
+	}
+	off(event, handler) {
+		const set = this.handlers.get(event);
+		if (set) {
+			set.delete(handler);
+			if (set.size === 0) this.handlers.delete(event);
+		}
+	}
+};
+//#endregion
+export { InProcessEventBus as t };

package/dist/event-bus-Um_xrcMY.d.mts

@@ -0,0 +1,21 @@
+import { t as TransactionSession } from "./unit-of-work.port-CWEkrDKu.mjs";
+import { t as EventEmitterPort } from "./event-emitter.port-BFh2pasY.mjs";
+
+//#region src/events/event-bus.d.ts
+type EventHandler = (data: Record<string, unknown>) => Promise<void>;
+/**
+ * In-process event bus.
+ *
+ * Serves as the default {@link EventEmitterPort} implementation.
+ * Handlers are invoked fire-and-forget; failures are logged but never
+ * propagate to the emitter.  Replace with a Redis/Kafka adapter for
+ * distributed workloads.
+ */
+declare class InProcessEventBus implements EventEmitterPort {
+  private handlers;
+  emit(event: string, data: Record<string, unknown>, _session?: TransactionSession): Promise<void>;
+  on(event: string, handler: EventHandler): void;
+  off(event: string, handler: EventHandler): void;
+}
+//#endregion
+export { InProcessEventBus as t };

package/dist/event-emitter.port-BFh2pasY.d.mts

@@ -0,0 +1,183 @@
+import { t as TransactionSession } from "./unit-of-work.port-CWEkrDKu.mjs";
+
+//#region src/events/event-types.d.ts
+/**
+ * Typed event catalog for the @classytic/flow inventory package.
+ *
+ * All domain event names are defined here as a single `as const` object so
+ * consumers get full autocompletion and compile-time safety.
+ */
+declare const FlowEvents: {
+  readonly MOVE_GROUP_CREATED: "inventory.move_group.created";
+  readonly MOVE_GROUP_CONFIRMED: "inventory.move_group.confirmed";
+  readonly MOVE_GROUP_CANCELLED: "inventory.move_group.cancelled";
+  readonly MOVE_PLANNED: "inventory.move.planned";
+  readonly MOVE_RESERVED: "inventory.move.reserved";
+  readonly MOVE_DONE: "inventory.move.done";
+  readonly RESERVATION_CREATED: "inventory.reservation.created";
+  readonly RESERVATION_RELEASED: "inventory.reservation.released";
+  readonly RESERVATION_CONSUMED: "inventory.reservation.consumed";
+  readonly TRANSFER_DISPATCHED: "inventory.transfer.dispatched";
+  readonly TRANSFER_RECEIVED: "inventory.transfer.received";
+  readonly PROCUREMENT_RECEIVED: "inventory.procurement.received";
+  readonly COUNT_STARTED: "inventory.count.started";
+  readonly COUNT_RECONCILED: "inventory.count.reconciled";
+  readonly REPLENISHMENT_TRIGGERED: "inventory.replenishment.triggered";
+  readonly STOCK_LOW: "inventory.stock.low";
+  readonly ADJUSTMENT_POSTED: "inventory.adjustment.posted";
+  readonly LANDED_COST_APPLIED: "inventory.landed_cost.applied";
+};
+/** Union of all flow event names. */
+type FlowEventName = (typeof FlowEvents)[keyof typeof FlowEvents];
+/** Base payload — every event carries organizationId for tenant routing. */
+interface BasePayload {
+  organizationId: string;
+}
+interface MoveGroupCreatedPayload extends BasePayload {
+  groupId: string;
+  groupType: string;
+  documentNumber: string;
+  procurementOrderId?: string;
+}
+interface MoveGroupConfirmedPayload extends BasePayload {
+  groupId: string;
+  documentNumber: string;
+}
+interface MoveGroupCancelledPayload extends BasePayload {
+  groupId: string;
+  documentNumber: string;
+}
+interface MovePlannedPayload extends BasePayload {
+  moveId: string;
+  moveGroupId: string;
+  skuRef: string;
+  operationType: string;
+}
+interface MoveDonePayload extends BasePayload {
+  moveId: string;
+  moveGroupId: string;
+  skuRef: string;
+  operationType: string;
+  quantityDone: number;
+  sourceLocationId: string;
+  destinationLocationId: string;
+}
+interface ReservationCreatedPayload extends BasePayload {
+  reservationId: string;
+  skuRef: string;
+  locationId: string;
+  quantity: number;
+  ownerType: string;
+  ownerId: string;
+}
+interface ReservationReleasedPayload extends BasePayload {
+  reservationId: string;
+  skuRef: string;
+  locationId: string;
+  quantity: number;
+}
+interface ReservationConsumedPayload extends BasePayload {
+  reservationId: string;
+  skuRef: string;
+  locationId: string;
+  quantityConsumed: number;
+  totalConsumed: number;
+  isFullyConsumed: boolean;
+}
+interface TransferDispatchedPayload extends BasePayload {
+  groupId: string;
+  documentNumber: string;
+}
+interface TransferReceivedPayload extends BasePayload {
+  groupId: string;
+  documentNumber: string;
+  partial?: boolean;
+  failedMoves?: Array<{
+    moveId: string;
+    error: string;
+  }>;
+}
+interface ProcurementReceivedPayload extends BasePayload {
+  orderId: string;
+  orderNumber: string;
+  vendorRef: string;
+  destinationNodeId: string;
+  itemCount: number;
+}
+interface CountStartedPayload extends BasePayload {
+  countId: string;
+  countNumber: string;
+  countType: string;
+  lineCount: number;
+}
+interface CountReconciledPayload extends BasePayload {
+  countId: string;
+  totalLines: number;
+  varianceLines: number;
+  autoApproved: boolean;
+  needsManualReview: boolean;
+  moveGroupId: string;
+  documentNumber: string;
+}
+interface ReplenishmentTriggeredPayload extends BasePayload {
+  ruleId: string;
+  skuRef: string;
+  currentLevel: number;
+  reorderPoint: number;
+}
+interface StockLowPayload extends BasePayload {
+  skuRef: string;
+  locationId: string;
+  currentLevel: number;
+  threshold: number;
+}
+interface AdjustmentPostedPayload extends BasePayload {
+  countId: string;
+  countNumber: string;
+  movesPosted: number;
+}
+interface LandedCostAppliedPayload extends BasePayload {
+  skuRef: string;
+  additionalCost: number;
+}
+/**
+ * Maps event names to their typed payloads.
+ * Use with `emit<E extends keyof FlowEventMap>(event: E, data: FlowEventMap[E])`.
+ */
+interface FlowEventMap {
+  [FlowEvents.MOVE_GROUP_CREATED]: MoveGroupCreatedPayload;
+  [FlowEvents.MOVE_GROUP_CONFIRMED]: MoveGroupConfirmedPayload;
+  [FlowEvents.MOVE_GROUP_CANCELLED]: MoveGroupCancelledPayload;
+  [FlowEvents.MOVE_PLANNED]: MovePlannedPayload;
+  [FlowEvents.MOVE_DONE]: MoveDonePayload;
+  [FlowEvents.RESERVATION_CREATED]: ReservationCreatedPayload;
+  [FlowEvents.RESERVATION_RELEASED]: ReservationReleasedPayload;
+  [FlowEvents.RESERVATION_CONSUMED]: ReservationConsumedPayload;
+  [FlowEvents.TRANSFER_DISPATCHED]: TransferDispatchedPayload;
+  [FlowEvents.TRANSFER_RECEIVED]: TransferReceivedPayload;
+  [FlowEvents.PROCUREMENT_RECEIVED]: ProcurementReceivedPayload;
+  [FlowEvents.COUNT_STARTED]: CountStartedPayload;
+  [FlowEvents.COUNT_RECONCILED]: CountReconciledPayload;
+  [FlowEvents.REPLENISHMENT_TRIGGERED]: ReplenishmentTriggeredPayload;
+  [FlowEvents.STOCK_LOW]: StockLowPayload;
+  [FlowEvents.ADJUSTMENT_POSTED]: AdjustmentPostedPayload;
+  [FlowEvents.LANDED_COST_APPLIED]: LandedCostAppliedPayload;
+}
+//#endregion
+//#region src/domain/ports/event-emitter.port.d.ts
+/**
+ * Domain event emitter port.
+ * In-process default; consumer provides adapters for Redis, Kafka, webhooks, etc.
+ *
+ * Typed overload ensures compile-time safety for known Flow events.
+ * The string fallback keeps the port extensible for consumer-defined events.
+ */
+interface EventEmitterPort {
+  emit<E extends keyof FlowEventMap>(event: E, data: FlowEventMap[E], session?: TransactionSession): Promise<void>;
+  emit(event: string, data: Record<string, unknown>, session?: TransactionSession): Promise<void>;
+  on<E extends keyof FlowEventMap>(event: E, handler: (data: FlowEventMap[E]) => Promise<void>): void;
+  on(event: string, handler: (data: Record<string, unknown>) => Promise<void>): void;
+  off(event: string, handler: (data: Record<string, unknown>) => Promise<void>): void;
+}
+//#endregion
+export { FlowEvents as i, FlowEventMap as n, FlowEventName as r, EventEmitterPort as t };

package/dist/event-types-BSqQOvXv.mjs

@@ -0,0 +1,29 @@
+//#region src/events/event-types.ts
+/**
+* Typed event catalog for the @classytic/flow inventory package.
+*
+* All domain event names are defined here as a single `as const` object so
+* consumers get full autocompletion and compile-time safety.
+*/
+const FlowEvents = {
+	MOVE_GROUP_CREATED: "inventory.move_group.created",
+	MOVE_GROUP_CONFIRMED: "inventory.move_group.confirmed",
+	MOVE_GROUP_CANCELLED: "inventory.move_group.cancelled",
+	MOVE_PLANNED: "inventory.move.planned",
+	MOVE_RESERVED: "inventory.move.reserved",
+	MOVE_DONE: "inventory.move.done",
+	RESERVATION_CREATED: "inventory.reservation.created",
+	RESERVATION_RELEASED: "inventory.reservation.released",
+	RESERVATION_CONSUMED: "inventory.reservation.consumed",
+	TRANSFER_DISPATCHED: "inventory.transfer.dispatched",
+	TRANSFER_RECEIVED: "inventory.transfer.received",
+	PROCUREMENT_RECEIVED: "inventory.procurement.received",
+	COUNT_STARTED: "inventory.count.started",
+	COUNT_RECONCILED: "inventory.count.reconciled",
+	REPLENISHMENT_TRIGGERED: "inventory.replenishment.triggered",
+	STOCK_LOW: "inventory.stock.low",
+	ADJUSTMENT_POSTED: "inventory.adjustment.posted",
+	LANDED_COST_APPLIED: "inventory.landed_cost.applied"
+};
+//#endregion
+export { FlowEvents as t };

package/dist/events/index.d.mts

@@ -0,0 +1,3 @@
+import { i as FlowEvents, r as FlowEventName } from "../event-emitter.port-BFh2pasY.mjs";
+import { t as InProcessEventBus } from "../event-bus-Um_xrcMY.mjs";
+export { type FlowEventName, FlowEvents, InProcessEventBus };

package/dist/events/index.mjs

@@ -0,0 +1,3 @@
+import { t as InProcessEventBus } from "../event-bus-BNmyoJb4.mjs";
+import { t as FlowEvents } from "../event-types-BSqQOvXv.mjs";
+export { FlowEvents, InProcessEventBus };

package/dist/idempotency.port-CTC70JON.d.mts

@@ -0,0 +1,55 @@
+//#region src/domain/ports/idempotency.port.d.ts
+/**
+ * Idempotency port — safe-retry protocol for Flow operations.
+ *
+ * Two tiers:
+ *
+ * 1. **Legacy (required)**: `check()` + `save()` — simple check-then-save.
+ *    Every adapter MUST implement these.
+ *
+ * 2. **Atomic (optional)**: `claim()` + `complete()` + `release()` — prevents
+ *    the TOCTOU race under concurrent retries. Adapters SHOULD implement these
+ *    when the backing store supports atomic locks (Redis SET NX, Mongo upsert).
+ *
+ * Services prefer the atomic path when available, and fall back to legacy.
+ */
+interface IdempotencyPort {
+  /** Check if a result exists for the given key. */
+  check<T>(key: string): Promise<{
+    hit: true;
+    result: T;
+  } | {
+    hit: false;
+  }>;
+  /** Save a result for the given key. */
+  save<T>(key: string, result: T, ttlMs?: number): Promise<void>;
+  /**
+   * Atomically claim a key. If the key already has a completed result,
+   * return it. If it's unclaimed, acquire the lock.
+   *
+   * @returns
+   * - `{ status: 'hit', result }` — a previous execution completed with this result
+   * - `{ status: 'acquired' }` — lock acquired, caller should execute then call complete()
+   * - `{ status: 'busy' }` — another caller holds the lock; retry later
+   */
+  claim?<T>(key: string, ttlMs?: number): Promise<{
+    status: 'hit';
+    result: T;
+  } | {
+    status: 'acquired';
+  } | {
+    status: 'busy';
+  }>;
+  /**
+   * Store the result for a previously claimed key.
+   * Only the caller that received `{ status: 'acquired' }` should call this.
+   */
+  complete?<T>(key: string, result: T): Promise<void>;
+  /**
+   * Release a claim without storing a result (e.g., on error).
+   * Allows a future retry to re-acquire the key.
+   */
+  release?(key: string): Promise<void>;
+}
+//#endregion
+export { IdempotencyPort as t };

package/dist/index-Bia4m8d2.d.mts

@@ -0,0 +1,67 @@
+import { n as StockQuant } from "./stock-quant-CZhgvTu7.mjs";
+import { n as AllocationResult, t as AllocationPolicy } from "./allocation-policy-my_HfzdV.mjs";
+
+//#region src/reservations/exact-lot.strategy.d.ts
+/**
+ * Exact-lot allocation — only allocate from a specific lot.
+ * Used when a customer or regulation requires a specific batch.
+ */
+declare class ExactLotStrategy implements AllocationPolicy {
+  private targetLotId;
+  readonly name = "exact_lot";
+  constructor(targetLotId: string);
+  resolve(_skuRef: string, quantity: number, candidates: StockQuant[]): AllocationResult;
+}
+//#endregion
+//#region src/reservations/fefo.strategy.d.ts
+/**
+ * FEFO allocation — consume nearest-expiry stock first.
+ * Requires quants to carry lot expiry info. Quants without expiry sort last.
+ *
+ * Used for perishable goods: food, pharma, cosmetics.
+ */
+declare class FefoStrategy implements AllocationPolicy {
+  private minShelfLifeDays?;
+  readonly name = "fefo";
+  constructor(minShelfLifeDays?: number | undefined);
+  resolve(_skuRef: string, quantity: number, candidates: StockQuant[]): AllocationResult;
+}
+//#endregion
+//#region src/reservations/fifo.strategy.d.ts
+/**
+ * FIFO allocation — consume oldest stock first (by inDate).
+ * Default strategy for most operations.
+ */
+declare class FifoStrategy implements AllocationPolicy {
+  readonly name = "fifo";
+  resolve(_skuRef: string, quantity: number, candidates: StockQuant[]): AllocationResult;
+}
+/**
+ * Shared allocation logic — iterates sorted candidates and picks until quantity is met.
+ * Used by all strategies after sorting.
+ */
+declare function allocateFromSorted(sorted: StockQuant[], quantity: number): AllocationResult;
+//#endregion
+//#region src/reservations/lifo.strategy.d.ts
+/**
+ * LIFO allocation — consume newest stock first (by inDate DESC).
+ * Useful when freshness matters less and you want to keep oldest stock for auditing.
+ */
+declare class LifoStrategy implements AllocationPolicy {
+  readonly name = "lifo";
+  resolve(_skuRef: string, quantity: number, candidates: StockQuant[]): AllocationResult;
+}
+//#endregion
+//#region src/reservations/nearest.strategy.d.ts
+/**
+ * Nearest allocation — consume stock closest to pick face (by location sortOrder ASC).
+ * Minimizes warehouse travel distance.
+ *
+ * Requires quants to carry locationSortOrder (set by repository join or denormalized).
+ */
+declare class NearestStrategy implements AllocationPolicy {
+  readonly name = "nearest";
+  resolve(_skuRef: string, quantity: number, candidates: StockQuant[]): AllocationResult;
+}
+//#endregion
+export { FefoStrategy as a, allocateFromSorted as i, LifoStrategy as n, ExactLotStrategy as o, FifoStrategy as r, NearestStrategy as t };

package/dist/index-BmNm3oNU2.d.mts

@@ -0,0 +1,107 @@
+import { n as MovePort } from "./move.port-Qg1CYp7h.mjs";
+import { t as FlowContext } from "./index-DFF0GJ4J.mjs";
+import { t as LocationPort } from "./location.port-CValXIpb.mjs";
+import { r as QuantPort } from "./quant.port-BBa66PBT.mjs";
+
+//#region src/reporting/availability.d.ts
+interface AvailabilityMatrixQuery {
+  skuRefs: string[];
+  nodeIds?: string[];
+}
+interface AvailabilityMatrixResult {
+  matrix: Array<{
+    skuRef: string;
+    nodes: Array<{
+      nodeId: string;
+      onHand: number;
+      reserved: number;
+      available: number;
+      incoming: number;
+      outgoing: number;
+    }>;
+    totalOnHand: number;
+    totalAvailable: number;
+  }>;
+}
+declare class AvailabilityReport {
+  private quantPort;
+  private locationPort?;
+  constructor(quantPort: QuantPort, locationPort?: LocationPort | undefined);
+  getMatrix(query: AvailabilityMatrixQuery, ctx: FlowContext): Promise<AvailabilityMatrixResult>;
+}
+//#endregion
+//#region src/reporting/health-metrics.d.ts
+interface StockHealthMetrics {
+  turnoverRate: number;
+  daysOfInventory: number;
+  stockoutRate: number;
+  fillRate: number;
+  deadStockPercentage: number;
+  expiryRiskValue: number;
+  totalSkus: number;
+  totalOnHand: number;
+  totalValue: number;
+}
+declare class HealthMetricsReport {
+  private quantPort;
+  constructor(quantPort: QuantPort, _movePort: MovePort);
+  generate(ctx: FlowContext): Promise<StockHealthMetrics>;
+}
+//#endregion
+//#region src/reporting/stock-aging.d.ts
+interface AgingBucket {
+  label: string;
+  minDays: number;
+  maxDays: number;
+  quantity: number;
+  value: number;
+  skuCount: number;
+}
+interface StockAgingResult {
+  asOfDate: Date;
+  buckets: AgingBucket[];
+  slowMoving: Array<{
+    skuRef: string;
+    locationId: string;
+    quantity: number;
+    ageDays: number;
+  }>;
+  deadStock: Array<{
+    skuRef: string;
+    locationId: string;
+    quantity: number;
+    ageDays: number;
+  }>;
+}
+declare class StockAgingReport {
+  private quantPort;
+  constructor(quantPort: QuantPort);
+  generate(ctx: FlowContext, nodeId?: string): Promise<StockAgingResult>;
+}
+//#endregion
+//#region src/reporting/turnover.d.ts
+interface TurnoverResult {
+  period: {
+    start: Date;
+    end: Date;
+  };
+  totalCOGS: number;
+  averageInventoryValue: number;
+  turnoverRate: number;
+  daysOfInventory: number;
+  skuBreakdown: Array<{
+    skuRef: string;
+    unitsSold: number;
+    cogs: number;
+    avgInventory: number;
+    turnover: number;
+  }>;
+}
+declare class TurnoverReport {
+  private quantPort;
+  private movePort;
+  constructor(quantPort: QuantPort, movePort: MovePort);
+  generate(periodDays: number, ctx: FlowContext): Promise<TurnoverResult>;
+}
+//#endregion
+export { StockAgingResult as a, AvailabilityMatrixQuery as c, StockAgingReport as i, AvailabilityMatrixResult as l, TurnoverResult as n, HealthMetricsReport as o, AgingBucket as r, StockHealthMetrics as s, TurnoverReport as t, AvailabilityReport as u };