@unifiedcommerce/core 0.2.0 → 0.2.2

package/src/modules/inventory/repository/index.ts

@@ -0,0 +1,509 @@
+import { eq, and, inArray, isNull, sql } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { warehouses, inventoryLevels, inventoryMovements } from "../schema.js";
+
+// Infer types from Drizzle schema
+export type Warehouse = typeof warehouses.$inferSelect;
+export type WarehouseInsert = typeof warehouses.$inferInsert;
+export type InventoryLevel = typeof inventoryLevels.$inferSelect;
+export type InventoryLevelInsert = typeof inventoryLevels.$inferInsert;
+export type InventoryMovement = typeof inventoryMovements.$inferSelect;
+export type InventoryMovementInsert = typeof inventoryMovements.$inferInsert;
+
+/**
+ * InventoryRepository provides type-safe database operations for inventory entities.
+ *
+ * This repository manages warehouses, inventory levels, and inventory movements.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class InventoryRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Warehouses
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findWarehouseById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<Warehouse | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(warehouses)
+      .where(eq(warehouses.id, id));
+    return rows[0];
+  }
+
+  async findWarehouseByCode(
+    orgId: string,
+    code: string,
+    ctx?: TxContext,
+  ): Promise<Warehouse | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(warehouses)
+      .where(
+        and(
+          eq(warehouses.organizationId, orgId),
+          eq(warehouses.code, code),
+        ),
+      );
+    return rows[0];
+  }
+
+  async findAllWarehouses(
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<Warehouse[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(warehouses)
+      .where(eq(warehouses.organizationId, orgId));
+  }
+
+  async findActiveWarehouses(
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<Warehouse[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(warehouses)
+      .where(
+        and(
+          eq(warehouses.organizationId, orgId),
+          eq(warehouses.isActive, true),
+        ),
+      );
+  }
+
+  async createWarehouse(
+    data: WarehouseInsert,
+    ctx?: TxContext,
+  ): Promise<Warehouse> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(warehouses).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateWarehouse(
+    id: string,
+    data: Partial<Omit<WarehouseInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<Warehouse | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(warehouses)
+      .set(data)
+      .where(eq(warehouses.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteWarehouse(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(warehouses)
+      .where(eq(warehouses.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Inventory Levels
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findAllLevels(ctx?: TxContext): Promise<InventoryLevel[]> {
+    const db = this.getDb(ctx);
+    return db.select().from(inventoryLevels);
+  }
+
+  async findLevelById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(inventoryLevels)
+      .where(eq(inventoryLevels.id, id));
+    return rows[0];
+  }
+
+  async findLevelByKey(
+    entityId: string,
+    warehouseId: string,
+    variantId?: string | null,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel | undefined> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(inventoryLevels.entityId, entityId),
+      eq(inventoryLevels.warehouseId, warehouseId),
+    ];
+
+    // Only add variantId condition when it's a real string value — never pass null to eq()
+    if (variantId != null) {
+      conditions.push(eq(inventoryLevels.variantId, variantId));
+    }
+
+    const rows = await db
+      .select()
+      .from(inventoryLevels)
+      .where(and(...conditions));
+
+    // Post-filter for exact variantId match (handles SQL NULL correctly)
+    return rows.find((r) => r.variantId === (variantId ?? null));
+  }
+
+  async findLevelsByEntityId(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(inventoryLevels)
+      .where(eq(inventoryLevels.entityId, entityId));
+  }
+
+  async findLevelsByEntityAndVariant(
+    entityId: string,
+    variantId?: string | null,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel[]> {
+    const db = this.getDb(ctx);
+    const conditions = [eq(inventoryLevels.entityId, entityId)];
+
+    // Only add variantId condition when it's a real string value — never pass null to eq()
+    if (variantId != null) {
+      conditions.push(eq(inventoryLevels.variantId, variantId));
+    }
+
+    const rows = await db
+      .select()
+      .from(inventoryLevels)
+      .where(and(...conditions));
+
+    // Post-filter for exact variantId match (handles SQL NULL correctly in JS)
+    return rows.filter((r) =>
+      variantId == null ? r.variantId === null : r.variantId === variantId,
+    );
+  }
+
+  async findLevelsByWarehouseId(
+    warehouseId: string,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(inventoryLevels)
+      .where(eq(inventoryLevels.warehouseId, warehouseId));
+  }
+
+  async createLevel(
+    data: InventoryLevelInsert,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(inventoryLevels).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateLevel(
+    id: string,
+    data: Partial<Omit<InventoryLevelInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(inventoryLevels)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(inventoryLevels.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async upsertLevel(
+    entityId: string,
+    warehouseId: string,
+    variantId: string | undefined,
+    data: Omit<
+      InventoryLevelInsert,
+      "id" | "entityId" | "warehouseId" | "variantId"
+    >,
+    ctx?: TxContext,
+  ): Promise<InventoryLevel> {
+    const existing = await this.findLevelByKey(
+      entityId,
+      warehouseId,
+      variantId,
+      ctx,
+    );
+    if (existing) {
+      const updated = await this.updateLevel(existing.id, data, ctx);
+      return updated!;
+    }
+    return this.createLevel(
+      {
+        ...data,
+        entityId,
+        warehouseId,
+        ...(variantId !== undefined ? { variantId } : {}),
+      },
+      ctx,
+    );
+  }
+
+  async deleteLevel(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(inventoryLevels)
+      .where(eq(inventoryLevels.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Inventory Movements
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findMovementById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<InventoryMovement | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(inventoryMovements)
+      .where(eq(inventoryMovements.id, id));
+    return rows[0];
+  }
+
+  async findMovementsByEntityId(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<InventoryMovement[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(inventoryMovements)
+      .where(eq(inventoryMovements.entityId, entityId));
+  }
+
+  async findMovementsByReference(
+    referenceType: string,
+    referenceId: string,
+    ctx?: TxContext,
+  ): Promise<InventoryMovement[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(inventoryMovements)
+      .where(
+        and(
+          eq(inventoryMovements.referenceType, referenceType),
+          eq(inventoryMovements.referenceId, referenceId),
+        ),
+      );
+  }
+
+  async createMovement(
+    data: InventoryMovementInsert,
+    ctx?: TxContext,
+  ): Promise<InventoryMovement> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(inventoryMovements).values(data).returning();
+    return rows[0]!;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Concurrency-Safe Operations (SELECT FOR UPDATE)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Issues SELECT ... FOR UPDATE on the inventory_levels row matching
+   * the given entity, variant, and warehouse within the provided transaction.
+   *
+   * MUST be called inside an active transaction (ctx.tx must be set).
+   * Calling outside a transaction provides no locking guarantee.
+   *
+   * Uses isNull() for null variantId instead of eq() to generate correct
+   * SQL (IS NULL instead of = NULL).
+   */
+  async findLevelForUpdate(
+    entityId: string,
+    variantId: string | null,
+    warehouseId: string,
+    ctx: TxContext,
+  ): Promise<InventoryLevel | undefined> {
+    const db = this.getDb(ctx);
+
+    const conditions = [
+      eq(inventoryLevels.entityId, entityId),
+      eq(inventoryLevels.warehouseId, warehouseId),
+      variantId != null
+        ? eq(inventoryLevels.variantId, variantId)
+        : isNull(inventoryLevels.variantId),
+    ];
+
+    // Use raw SQL for FOR UPDATE since Drizzle's .for() may not be available
+    // on all query builder paths. This is the most portable approach.
+    const rows = await db
+      .select()
+      .from(inventoryLevels)
+      .where(and(...conditions))
+      .for("update");
+
+    return rows[0];
+  }
+
+  /**
+   * Performs a read-modify-write under a row-level lock.
+   * This is the ONLY correct method for modifying quantityReserved
+   * in a concurrent environment. Must be called inside a transaction.
+   *
+   * The lock is held for the duration of the enclosing transaction,
+   * which is typically just the checkout reservation — microsecond-level.
+   */
+  async reserveWithLock(
+    entityId: string,
+    variantId: string | null,
+    warehouseId: string,
+    quantity: number,
+    ctx: TxContext,
+  ): Promise<
+    { ok: true; level: InventoryLevel } | { ok: false; reason: string }
+  > {
+    const level = await this.findLevelForUpdate(
+      entityId,
+      variantId,
+      warehouseId,
+      ctx,
+    );
+
+    if (!level) {
+      return {
+        ok: false,
+        reason: "No inventory record found for this entity.",
+      };
+    }
+
+    const available = level.quantityOnHand - level.quantityReserved;
+    if (available < quantity) {
+      return {
+        ok: false,
+        reason: `Insufficient stock. Available: ${available}, requested: ${quantity}.`,
+      };
+    }
+
+    const updated = await this.getDb(ctx)
+      .update(inventoryLevels)
+      .set({
+        quantityReserved: level.quantityReserved + quantity,
+        updatedAt: new Date(),
+        version: level.version + 1,
+      })
+      .where(eq(inventoryLevels.id, level.id))
+      .returning();
+
+    return { ok: true, level: updated[0]! };
+  }
+
+  /**
+   * Performs a release under a row-level lock, mirroring reserveWithLock.
+   * Used by compensation chains to undo a reservation.
+   */
+  async releaseWithLock(
+    entityId: string,
+    variantId: string | null,
+    warehouseId: string,
+    quantity: number,
+    ctx: TxContext,
+  ): Promise<
+    { ok: true; level: InventoryLevel } | { ok: false; reason: string }
+  > {
+    const level = await this.findLevelForUpdate(
+      entityId,
+      variantId,
+      warehouseId,
+      ctx,
+    );
+
+    if (!level) {
+      return {
+        ok: false,
+        reason: "No inventory record found for this entity.",
+      };
+    }
+
+    const updated = await this.getDb(ctx)
+      .update(inventoryLevels)
+      .set({
+        quantityReserved: Math.max(0, level.quantityReserved - quantity),
+        updatedAt: new Date(),
+        version: level.version + 1,
+      })
+      .where(eq(inventoryLevels.id, level.id))
+      .returning();
+
+    return { ok: true, level: updated[0]! };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Aggregate Queries
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async getAvailableQuantity(
+    entityId: string,
+    variantId?: string | null,
+    ctx?: TxContext,
+  ): Promise<number> {
+    const levels = await this.findLevelsByEntityAndVariant(
+      entityId,
+      variantId,
+      ctx,
+    );
+    return levels.reduce(
+      (sum, level) => sum + (level.quantityOnHand - level.quantityReserved),
+      0,
+    );
+  }
+
+  async getAvailableQuantities(
+    entityIds: string[],
+    ctx?: TxContext,
+  ): Promise<Record<string, number>> {
+    if (entityIds.length === 0) return {};
+
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(inventoryLevels)
+      .where(inArray(inventoryLevels.entityId, entityIds));
+
+    const result: Record<string, number> = {};
+    for (const id of entityIds) {
+      result[id] = 0;
+    }
+
+    for (const row of rows) {
+      const available = row.quantityOnHand - row.quantityReserved;
+      result[row.entityId] = (result[row.entityId] ?? 0) + available;
+    }
+
+    return result;
+  }
+}

package/src/modules/inventory/schema.ts

@@ -0,0 +1,94 @@
+import {
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+import { sellableEntities, variants } from "../catalog/schema.js";
+
+export const warehouses = pgTable(
+  "warehouses",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    name: text("name").notNull(),
+    code: text("code").notNull(),
+    address: jsonb("address").$type<Record<string, unknown>>(),
+    isActive: boolean("is_active").notNull().default(true),
+    priority: integer("priority").notNull().default(0),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  },
+  (table) => ({
+    orgIdx: index("idx_warehouses_org").on(table.organizationId),
+    orgCodeUnique: uniqueIndex("warehouses_org_code_unique").on(table.organizationId, table.code),
+  }),
+);
+
+export const inventoryLevels = pgTable(
+  "inventory_levels",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    entityId: uuid("entity_id")
+      .references(() => sellableEntities.id, { onDelete: "cascade" })
+      .notNull(),
+    variantId: uuid("variant_id").references(() => variants.id, {
+      onDelete: "cascade",
+    }),
+    warehouseId: uuid("warehouse_id")
+      .references(() => warehouses.id)
+      .notNull(),
+    quantityOnHand: integer("quantity_on_hand").notNull().default(0),
+    quantityReserved: integer("quantity_reserved").notNull().default(0),
+    quantityIncoming: integer("quantity_incoming").notNull().default(0),
+    unitCost: integer("unit_cost"),
+    reorderThreshold: integer("reorder_threshold"),
+    reorderQuantity: integer("reorder_quantity"),
+    version: integer("version").notNull().default(0),
+    lastRestockedAt: timestamp("last_restocked_at", { withTimezone: true }),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    entityVariantWarehouseIdx: index("idx_inventory_entity_variant_warehouse").on(
+      table.entityId,
+      table.variantId,
+      table.warehouseId,
+    ),
+  }),
+);
+
+export const inventoryMovements = pgTable("inventory_movements", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  entityId: uuid("entity_id")
+    .references(() => sellableEntities.id)
+    .notNull(),
+  variantId: uuid("variant_id").references(() => variants.id),
+  warehouseId: uuid("warehouse_id")
+    .references(() => warehouses.id)
+    .notNull(),
+  type: text("type", {
+    enum: [
+      "receipt",
+      "sale",
+      "return",
+      "adjustment",
+      "transfer",
+      "reservation",
+      "release",
+      "fulfillment",
+    ],
+  }).notNull(),
+  quantity: integer("quantity").notNull(),
+  referenceType: text("reference_type"),
+  referenceId: text("reference_id"),
+  reason: text("reason"),
+  performedBy: text("performed_by").notNull(),
+  performedAt: timestamp("performed_at", { withTimezone: true }).defaultNow().notNull(),
+});

package/src/modules/inventory/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "@hono/zod-openapi";
+
+// ─── Zod Body Schemas (single source of truth) ─────────────────────────────
+
+export const InventoryAdjustBodySchema = z.object({
+  entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  variantId: z.string().optional().openapi({ example: "variant-uuid" }),
+  warehouseId: z.string().optional().openapi({ example: "warehouse-uuid" }),
+  adjustment: z.number().int().refine((v) => v !== 0, { message: "Adjustment cannot be zero" }).openapi({ example: 10 }),
+  reason: z.string().openapi({ example: "Restock from supplier" }),
+  performedBy: z.string().optional(),
+  referenceType: z.string().optional(),
+  referenceId: z.string().optional(),
+}).openapi("InventoryAdjustRequest");
+
+export const InventoryReserveBodySchema = z.object({
+  entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  variantId: z.string().optional(),
+  warehouseId: z.string().optional(),
+  quantity: z.number().int().min(1).openapi({ example: 2 }),
+  orderId: z.string().openapi({ example: "order-uuid" }),
+  performedBy: z.string().optional(),
+}).openapi("InventoryReserveRequest");
+
+export const InventoryReleaseBodySchema = z.object({
+  entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  variantId: z.string().optional(),
+  warehouseId: z.string().optional(),
+  quantity: z.number().int().min(1).openapi({ example: 2 }),
+  orderId: z.string().openapi({ example: "order-uuid" }),
+  performedBy: z.string().optional(),
+}).openapi("InventoryReleaseRequest");
+
+// ─── Derived Input Types ────────────────────────────────────────────────────
+
+export type InventoryAdjustInput = z.infer<typeof InventoryAdjustBodySchema>;
+export type InventoryReserveInput = z.infer<typeof InventoryReserveBodySchema>;
+export type InventoryReleaseInput = z.infer<typeof InventoryReleaseBodySchema>;