@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/inventory/query/getInventoryAdjustment.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseDraftAdjustment } from "../testing/fixtures";
+import { expectOk } from "../testing/commandTestUtils";
+import { run } from "./getInventoryAdjustment";
+
+describe("getInventoryAdjustment", () => {
+  it("returns adjustment when found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftAdjustment);
+
+    const result = await run(db, { id: baseDraftAdjustment.id });
+    const { adjustment } = expectOk<{ adjustment: unknown }>(result as never);
+
+    expect(adjustment).not.toBeNull();
+    expect(adjustment).toMatchObject({ id: baseDraftAdjustment.id });
+  });
+
+  it("returns null when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent-id" });
+    const { adjustment } = expectOk<{ adjustment: unknown }>(result as never);
+
+    expect(adjustment).toBeNull();
+  });
+
+  it("includes status and reason code", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftAdjustment);
+
+    const result = await run(db, { id: baseDraftAdjustment.id });
+    const { adjustment } = expectOk<{
+      adjustment: { status: string; reasonCode: string };
+    }>(result as never);
+
+    expect(adjustment.status).toBe("DRAFT");
+    expect(adjustment.reasonCode).toBe("damage");
+  });
+
+  it("includes optional lot and serial number references", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftAdjustment);
+
+    const result = await run(db, { id: baseDraftAdjustment.id });
+    const { adjustment } = expectOk<{
+      adjustment: {
+        lotId: string | null;
+        serialNumberId: string | null;
+      };
+    }>(result as never);
+
+    expect(adjustment.lotId).toBeNull();
+    expect(adjustment.serialNumberId).toBeNull();
+  });
+});

package/src/modules/inventory/query/getInventoryAdjustment.ts

@@ -0,0 +1,16 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetInventoryAdjustmentInput {
+  id: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetInventoryAdjustmentInput) {
+  const adjustment = await db
+    .selectFrom("InventoryAdjustment")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  return ok({ adjustment: adjustment ?? null });
+}

package/src/modules/inventory/query/getInventoryCount.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getInventoryCount";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getInventoryCount = defineQuery(run);

package/src/modules/inventory/query/getInventoryCount.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  baseInProgressCount,
+  basePendingCountLine,
+  baseApprovedCountLine,
+} from "../testing/fixtures";
+import { expectOk, expectErr } from "../testing/commandTestUtils";
+import { CountNotFoundError } from "../lib/errors.generated";
+import { run } from "./getInventoryCount";
+
+describe("getInventoryCount", () => {
+  it("returns count with lines when found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInProgressCount);
+    spies.select.mockReturnValueOnce([basePendingCountLine, baseApprovedCountLine]);
+
+    const result = await run(db, { id: baseInProgressCount.id });
+    const { inventoryCount, countLines } = expectOk<{
+      inventoryCount: unknown;
+      countLines: unknown[];
+    }>(result as never);
+
+    expect(inventoryCount).toMatchObject({ id: baseInProgressCount.id });
+    expect(countLines).toHaveLength(2);
+  });
+
+  it("includes variance for each line", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInProgressCount);
+    spies.select.mockReturnValueOnce([basePendingCountLine]);
+
+    const result = await run(db, { id: baseInProgressCount.id });
+    const { countLines } = expectOk<{
+      inventoryCount: unknown;
+      countLines: { variance: number }[];
+    }>(result as never);
+
+    expect(countLines[0].variance).toBe(-2);
+  });
+
+  it("returns error when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent-id" });
+    expectErr(result as never, CountNotFoundError);
+  });
+
+  it("includes line status (pending/approved/rejected/recount)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInProgressCount);
+    spies.select.mockReturnValueOnce([basePendingCountLine, baseApprovedCountLine]);
+
+    const result = await run(db, { id: baseInProgressCount.id });
+    const { countLines } = expectOk<{
+      inventoryCount: unknown;
+      countLines: { status: string }[];
+    }>(result as never);
+
+    expect(countLines[0].status).toBe("PENDING");
+    expect(countLines[1].status).toBe("APPROVED");
+  });
+});

package/src/modules/inventory/query/getInventoryCount.ts

@@ -0,0 +1,27 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { CountNotFoundError } from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetInventoryCountInput {
+  id: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetInventoryCountInput) {
+  const inventoryCount = await db
+    .selectFrom("InventoryCount")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  if (!inventoryCount) {
+    return err(new CountNotFoundError(input.id));
+  }
+
+  const countLines = await db
+    .selectFrom("InventoryCountLine")
+    .selectAll()
+    .where("inventoryCountId", "=", inventoryCount.id)
+    .execute();
+
+  return ok({ inventoryCount, countLines });
+}

package/src/modules/inventory/query/getItemValuation.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getItemValuation";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getItemValuation = defineQuery(run);

package/src/modules/inventory/query/getItemValuation.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseItemValuation, baseFifoPolicy } from "../testing/fixtures";
+import { expectOk, expectErr } from "../testing/commandTestUtils";
+import { ItemValuationNotFoundError } from "../lib/errors.generated";
+import { run } from "./getItemValuation";
+
+describe("getItemValuation", () => {
+  it("returns valuation when found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseItemValuation);
+    spies.select.mockReturnValueOnce(baseFifoPolicy);
+
+    const result = await run(db, {
+      itemId: baseItemValuation.itemId,
+      valuationPolicyId: baseItemValuation.valuationPolicyId,
+    });
+    const { itemValuation } = expectOk<{
+      itemValuation: { id: string };
+      valuationPolicy: unknown;
+    }>(result as never);
+
+    expect(itemValuation).toMatchObject({ id: baseItemValuation.id });
+  });
+
+  it("includes costing method from policy", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseItemValuation);
+    spies.select.mockReturnValueOnce(baseFifoPolicy);
+
+    const result = await run(db, {
+      itemId: baseItemValuation.itemId,
+      valuationPolicyId: baseItemValuation.valuationPolicyId,
+    });
+    const { valuationPolicy } = expectOk<{
+      itemValuation: unknown;
+      valuationPolicy: { costingMethod: string };
+    }>(result as never);
+
+    expect(valuationPolicy.costingMethod).toBe("FIFO");
+  });
+
+  it("returns error when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, {
+      itemId: "nonexistent-item",
+      valuationPolicyId: "policy-1",
+    });
+    expectErr(result as never, ItemValuationNotFoundError);
+  });
+
+  it("costPerUnit equals totalValue divided by totalQuantity", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseItemValuation);
+    spies.select.mockReturnValueOnce(baseFifoPolicy);
+
+    const result = await run(db, {
+      itemId: baseItemValuation.itemId,
+      valuationPolicyId: baseItemValuation.valuationPolicyId,
+    });
+    const { itemValuation } = expectOk<{
+      itemValuation: { costPerUnit: number; totalValue: number; totalQuantity: number };
+      valuationPolicy: unknown;
+    }>(result as never);
+
+    expect(itemValuation.costPerUnit).toBe(10);
+    expect(itemValuation.costPerUnit).toBe(itemValuation.totalValue / itemValuation.totalQuantity);
+  });
+});

package/src/modules/inventory/query/getItemValuation.ts

@@ -0,0 +1,29 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { ItemValuationNotFoundError } from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetItemValuationInput {
+  itemId: string;
+  valuationPolicyId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetItemValuationInput) {
+  const itemValuation = await db
+    .selectFrom("ItemValuation")
+    .selectAll()
+    .where("itemId", "=", input.itemId)
+    .where("valuationPolicyId", "=", input.valuationPolicyId)
+    .executeTakeFirst();
+
+  if (!itemValuation) {
+    return err(new ItemValuationNotFoundError(input.itemId));
+  }
+
+  const valuationPolicy = await db
+    .selectFrom("ValuationPolicy")
+    .selectAll()
+    .where("id", "=", itemValuation.valuationPolicyId)
+    .executeTakeFirst();
+
+  return ok({ itemValuation, valuationPolicy: valuationPolicy ?? null });
+}

package/src/modules/inventory/query/getLot.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getLot";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getLot = defineQuery(run);

package/src/modules/inventory/query/getLot.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseActiveLot, baseLotStockLevel } from "../testing/fixtures";
+import { expectOk } from "../testing/commandTestUtils";
+import { run } from "./getLot";
+
+describe("getLot", () => {
+  it("returns lot when found by id", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveLot);
+    spies.select.mockReturnValueOnce([baseLotStockLevel]);
+
+    const result = await run(db, { id: "lot-1" });
+    const { lot } = expectOk<{ lot: unknown }>(result as never);
+
+    expect(lot).not.toBeNull();
+    expect(lot).toMatchObject({ id: "lot-1" });
+  });
+
+  it("returns lot when found by lotNumber and itemId", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveLot);
+    spies.select.mockReturnValueOnce([baseLotStockLevel]);
+
+    const result = await run(db, { lotNumber: "LOT-001", itemId: "item-1" });
+    const { lot } = expectOk<{ lot: unknown }>(result as never);
+
+    expect(lot).not.toBeNull();
+    expect(lot).toMatchObject({ id: "lot-1", lotNumber: "LOT-001" });
+  });
+
+  it("returns null when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" });
+    const { lot, lotStockLevels } = expectOk<{
+      lot: null;
+      lotStockLevels: unknown[];
+    }>(result as never);
+
+    expect(lot).toBeNull();
+    expect(lotStockLevels).toEqual([]);
+  });
+
+  it("includes lot stock levels across locations", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveLot);
+    spies.select.mockReturnValueOnce([baseLotStockLevel]);
+
+    const result = await run(db, { id: "lot-1" });
+    const { lotStockLevels } = expectOk<{ lotStockLevels: unknown[] }>(result as never);
+
+    expect(lotStockLevels).toHaveLength(1);
+    expect(lotStockLevels[0]).toMatchObject({
+      lotId: "lot-1",
+      storageLocationId: "location-1",
+      onHand: 50,
+    });
+  });
+});

package/src/modules/inventory/query/getLot.ts

@@ -0,0 +1,28 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export type GetLotInput = { id: string } | { lotNumber: string; itemId: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetLotInput) {
+  let query = db.selectFrom("Lot").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("lotNumber", "=", input.lotNumber).where("itemId", "=", input.itemId);
+  }
+
+  const lot = await query.executeTakeFirst();
+
+  if (!lot) {
+    return ok({ lot: null, lotStockLevels: [] });
+  }
+
+  const lotStockLevels = await db
+    .selectFrom("LotStockLevel")
+    .selectAll()
+    .where("lotId", "=", lot.id)
+    .execute();
+
+  return ok({ lot, lotStockLevels });
+}

package/src/modules/inventory/query/getSerialNumber.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getSerialNumber";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getSerialNumber = defineQuery(run);

package/src/modules/inventory/query/getSerialNumber.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseAvailableSerial } from "../testing/fixtures";
+import { expectOk } from "../testing/commandTestUtils";
+import { run } from "./getSerialNumber";
+
+describe("getSerialNumber", () => {
+  it("returns serial when found by id", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+
+    const result = await run(db, { id: "serial-1" });
+    const { serialNumber } = expectOk<{ serialNumber: unknown }>(result as never);
+
+    expect(serialNumber).not.toBeNull();
+    expect(serialNumber).toMatchObject({ id: "serial-1" });
+  });
+
+  it("returns serial when found by serialNumber and itemId", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+
+    const result = await run(db, {
+      serialNumber: "SN-001",
+      itemId: "item-1",
+    });
+    const { serialNumber } = expectOk<{ serialNumber: unknown }>(result as never);
+
+    expect(serialNumber).not.toBeNull();
+    expect(serialNumber).toMatchObject({
+      id: "serial-1",
+      serialNumber: "SN-001",
+    });
+  });
+
+  it("returns null when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" });
+    const { serialNumber } = expectOk<{ serialNumber: null }>(result as never);
+
+    expect(serialNumber).toBeNull();
+  });
+
+  it("includes current status and location", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+
+    const result = await run(db, { id: "serial-1" });
+    const { serialNumber } = expectOk<{
+      serialNumber: { status: string; storageLocationId: string };
+    }>(result as never);
+
+    expect(serialNumber.status).toBe("AVAILABLE");
+    expect(serialNumber.storageLocationId).toBe("location-1");
+  });
+});

package/src/modules/inventory/query/getSerialNumber.ts

@@ -0,0 +1,18 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export type GetSerialNumberInput = { id: string } | { serialNumber: string; itemId: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetSerialNumberInput) {
+  let query = db.selectFrom("SerialNumber").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("serialNumber", "=", input.serialNumber).where("itemId", "=", input.itemId);
+  }
+
+  const serialNumber = await query.executeTakeFirst();
+
+  return ok({ serialNumber: serialNumber ?? null });
+}

package/src/modules/inventory/query/getSerialNumberHistory.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getSerialNumberHistory";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getSerialNumberHistory = defineQuery(run);

package/src/modules/inventory/query/getSerialNumberHistory.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseAvailableSerial, baseMoveLine } from "../testing/fixtures";
+import { expectOk, expectErr } from "../testing/commandTestUtils";
+import { SerialNumberNotFoundError } from "../lib/errors.generated";
+import { run } from "./getSerialNumberHistory";
+
+const doneMoveLine = {
+  ...baseMoveLine,
+  movementType: "GOODS_RECEIPT",
+  executedAt: new Date("2024-01-02T00:00:00.000Z"),
+  status: "DONE",
+  sourceLocationId: null,
+  destinationLocationId: "location-1",
+};
+
+describe("getSerialNumberHistory", () => {
+  it("returns full history ordered by date", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+    spies.select.mockReturnValueOnce([doneMoveLine]);
+
+    const result = await run(db, { serialNumberId: "serial-1" });
+    const { moveLines } = expectOk<{ moveLines: unknown[] }>(result as never);
+
+    expect(moveLines).toHaveLength(1);
+  });
+
+  it("includes state transitions", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+    spies.select.mockReturnValueOnce([doneMoveLine]);
+
+    const result = await run(db, { serialNumberId: "serial-1" });
+    const { moveLines } = expectOk<{
+      moveLines: { movementType: string; status: string }[];
+    }>(result as never);
+
+    expect(moveLines[0].movementType).toBe("GOODS_RECEIPT");
+    expect(moveLines[0].status).toBe("DONE");
+  });
+
+  it("includes location changes", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+    spies.select.mockReturnValueOnce([doneMoveLine]);
+
+    const result = await run(db, { serialNumberId: "serial-1" });
+    const { moveLines } = expectOk<{
+      moveLines: {
+        sourceLocationId: string | null;
+        destinationLocationId: string | null;
+      }[];
+    }>(result as never);
+
+    expect(moveLines[0].sourceLocationId).toBeNull();
+    expect(moveLines[0].destinationLocationId).toBe("location-1");
+  });
+
+  it("returns error when serial not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { serialNumberId: "non-existent" });
+
+    expectErr(result as never, SerialNumberNotFoundError);
+  });
+
+  it("returns empty history for newly created serial", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAvailableSerial);
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { serialNumberId: "serial-1" });
+    const { moveLines } = expectOk<{ moveLines: unknown[] }>(result as never);
+
+    expect(moveLines).toEqual([]);
+  });
+});

package/src/modules/inventory/query/getSerialNumberHistory.ts

@@ -0,0 +1,30 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { SerialNumberNotFoundError } from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetSerialNumberHistoryInput {
+  serialNumberId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetSerialNumberHistoryInput) {
+  const serialNumber = await db
+    .selectFrom("SerialNumber")
+    .selectAll()
+    .where("id", "=", input.serialNumberId)
+    .executeTakeFirst();
+
+  if (!serialNumber) {
+    return err(new SerialNumberNotFoundError(input.serialNumberId));
+  }
+
+  const moveLines = await db
+    .selectFrom("StockMoveLine")
+    .innerJoin("StockMovement", "StockMovement.id", "StockMoveLine.stockMovementId")
+    .selectAll("StockMoveLine")
+    .select(["StockMovement.movementType", "StockMovement.executedAt", "StockMovement.status"])
+    .where("StockMoveLine.serialNumberId", "=", input.serialNumberId)
+    .orderBy("StockMoveLine.createdAt", "asc")
+    .execute();
+
+  return ok({ moveLines });
+}

package/src/modules/inventory/query/getStockLevel.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getStockLevel";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getStockLevel = defineQuery(run);

package/src/modules/inventory/query/getStockLevel.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseStockLevel, emptyStockLevel } from "../testing/fixtures";
+import { expectOk } from "../testing/commandTestUtils";
+import { run } from "./getStockLevel";
+
+describe("getStockLevel", () => {
+  it("returns stock level when found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseStockLevel);
+
+    const result = await run(db, {
+      itemId: "item-1",
+      storageLocationId: "location-1",
+    });
+    const { stockLevel } = expectOk<{ stockLevel: unknown }>(result as never);
+
+    expect(stockLevel).not.toBeNull();
+    expect(stockLevel).toMatchObject({
+      itemId: "item-1",
+      storageLocationId: "location-1",
+    });
+  });
+
+  it("returns null when not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, {
+      itemId: "non-existent",
+      storageLocationId: "location-1",
+    });
+    const { stockLevel } = expectOk<{ stockLevel: null }>(result as never);
+
+    expect(stockLevel).toBeNull();
+  });
+
+  it("correctly computes available quantity", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseStockLevel);
+
+    const result = await run(db, {
+      itemId: "item-1",
+      storageLocationId: "location-1",
+    });
+    const { stockLevel } = expectOk<{
+      stockLevel: { availableQuantity: number };
+    }>(result as never);
+
+    // onHand(100) - reserved(10) - blocked(5) = 85
+    expect(stockLevel.availableQuantity).toBe(85);
+  });
+
+  it("available equals onHand minus reserved minus blocked", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(emptyStockLevel);
+
+    const result = await run(db, {
+      itemId: "item-2",
+      storageLocationId: "location-1",
+    });
+    const { stockLevel } = expectOk<{
+      stockLevel: { availableQuantity: number };
+    }>(result as never);
+
+    // onHand(0) - reserved(0) - blocked(0) = 0
+    expect(stockLevel.availableQuantity).toBe(0);
+  });
+});