@unifiedcommerce/core 0.1.0 → 0.2.0

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

@@ -1,509 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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>;