@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/query/listSalesCreditNotesByInvoice.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesInvoiceIdRequiredError } from "../lib/errors.generated";
+import { baseCreditNote, issuedCreditNote, issuedSalesInvoice } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesCreditNotesByInvoice";
+
+describe("listSalesCreditNotesByInvoice", () => {
+  it("lists credit notes under an invoice", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseCreditNote, issuedCreditNote]);
+
+    const result = await run(db, { salesInvoiceId: issuedSalesInvoice.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("filters credit notes by status when provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([issuedCreditNote]);
+
+    const result = await run(db, { salesInvoiceId: issuedSalesInvoice.id, status: "ISSUED" });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("throws when invoice id is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { salesInvoiceId: "" });
+    expectErr(result as never, SalesInvoiceIdRequiredError);
+  });
+});

package/src/modules/sales/query/listSalesCreditNotesByInvoice.ts

@@ -0,0 +1,42 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesInvoiceIdRequiredError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "creditDate" | "status";
+
+export interface ListSalesCreditNotesByInvoiceInput extends PaginationInput<OrderByField> {
+  salesInvoiceId: string;
+  status?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesCreditNotesByInvoiceInput) {
+  if (!input.salesInvoiceId) {
+    return err(new SalesInvoiceIdRequiredError("credit-notes"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "creditDate";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db
+    .selectFrom("SalesCreditNote")
+    .selectAll()
+    .where("salesInvoiceId", "=", input.salesInvoiceId);
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+
+  const creditNotes = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(creditNotes, limit));
+}

package/src/modules/sales/query/listSalesInvoicesBySalesOrder.generated.ts

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

package/src/modules/sales/query/listSalesInvoicesBySalesOrder.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesOrderIdRequiredError } from "../lib/errors.generated";
+import { baseSalesInvoice, issuedSalesInvoice, confirmedSalesOrder } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesInvoicesBySalesOrder";
+
+describe("listSalesInvoicesBySalesOrder", () => {
+  it("lists invoices under a sales order", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseSalesInvoice, issuedSalesInvoice]);
+
+    const result = await run(db, { salesOrderId: confirmedSalesOrder.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("filters invoices by status when provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([issuedSalesInvoice]);
+
+    const result = await run(db, { salesOrderId: confirmedSalesOrder.id, status: "ISSUED" });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("throws when sales-order id is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { salesOrderId: "" });
+    expectErr(result as never, SalesOrderIdRequiredError);
+  });
+});

package/src/modules/sales/query/listSalesInvoicesBySalesOrder.ts

@@ -0,0 +1,42 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesOrderIdRequiredError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "invoiceDate" | "status";
+
+export interface ListSalesInvoicesBySalesOrderInput extends PaginationInput<OrderByField> {
+  salesOrderId: string;
+  status?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesInvoicesBySalesOrderInput) {
+  if (!input.salesOrderId) {
+    return err(new SalesOrderIdRequiredError("sales-invoices"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "invoiceDate";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db
+    .selectFrom("SalesInvoice")
+    .selectAll()
+    .where("salesOrderId", "=", input.salesOrderId);
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+
+  const invoices = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(invoices, limit));
+}

package/src/modules/sales/query/listSalesOrders.generated.ts

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

package/src/modules/sales/query/listSalesOrders.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import {
+  baseSalesOrder,
+  submittedSalesOrder,
+  baseSalesOrderLine,
+  baseCompany,
+  baseCustomer,
+} from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesOrders";
+
+describe("listSalesOrders", () => {
+  it("lists sales orders by company scope", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseSalesOrder]);
+    spies.select.mockReturnValueOnce(baseSalesOrder);
+    spies.select.mockReturnValueOnce([baseSalesOrderLine]);
+
+    const result = await run(db, { companyId: baseCompany.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("filters sales orders by status and customer when provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([submittedSalesOrder]);
+    spies.select.mockReturnValueOnce(submittedSalesOrder);
+    spies.select.mockReturnValueOnce([baseSalesOrderLine]);
+
+    const result = await run(db, {
+      companyId: baseCompany.id,
+      status: "SUBMITTED",
+      customerId: baseCustomer.id,
+    });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("returns summary open-balance metrics", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseSalesOrder]);
+    spies.select.mockReturnValueOnce(baseSalesOrder);
+    spies.select.mockReturnValueOnce([baseSalesOrderLine]);
+
+    const result = await run(db, { companyId: baseCompany.id });
+    const { items } = expectOk<{
+      items: {
+        fulfillmentTotals: {
+          totalOrdered: number;
+          totalShipped: number;
+          totalInvoiced: number;
+          openToShip: number;
+          openToInvoice: number;
+        };
+      }[];
+      hasNextPage: boolean;
+    }>(result as never);
+
+    expect(items[0].fulfillmentTotals).toEqual({
+      totalOrdered: 10,
+      totalShipped: 0,
+      totalInvoiced: 0,
+      openToShip: 10,
+      openToInvoice: 10,
+    });
+  });
+
+  it("throws when company scope is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { companyId: "" });
+    expectErr(result as never, CompanyScopeRequiredError);
+  });
+});

package/src/modules/sales/query/listSalesOrders.ts

@@ -0,0 +1,67 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import { loadSalesOrderAggregate } from "../lib/repository";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "orderDate" | "status";
+
+export interface ListSalesOrdersInput extends PaginationInput<OrderByField> {
+  companyId: string;
+  customerId?: string;
+  status?: string;
+  channelId?: string;
+  dateFrom?: Date;
+  dateTo?: Date;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesOrdersInput) {
+  if (!input.companyId) {
+    return err(new CompanyScopeRequiredError("sales-orders"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "orderDate";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db.selectFrom("SalesOrder").selectAll().where("companyId", "=", input.companyId);
+  if (input.customerId) {
+    query = query.where("customerId", "=", input.customerId);
+  }
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+  if (input.channelId) {
+    query = query.where("channelId", "=", input.channelId);
+  }
+
+  const salesOrders = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  const filteredByDate = salesOrders.filter((row) => {
+    if (input.dateFrom && row.orderDate < input.dateFrom) return false;
+    if (input.dateTo && row.orderDate > input.dateTo) return false;
+    return true;
+  });
+
+  const items = [];
+  for (const row of filteredByDate.slice(0, limit + 1)) {
+    const aggregate = await loadSalesOrderAggregate(db, row.id);
+    if (!aggregate) continue;
+    items.push({
+      ...aggregate.salesOrder,
+      fulfillmentTotals: aggregate.fulfillmentTotals,
+    });
+  }
+
+  return ok(buildPaginatedResult(items, limit));
+}

package/src/modules/sales/query/listSalesPaymentTerms.generated.ts

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

package/src/modules/sales/query/listSalesPaymentTerms.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import { baseCompany, basePaymentTerm, draftPaymentTerm } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesPaymentTerms";
+
+describe("listSalesPaymentTerms", () => {
+  it("lists payment terms by company", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([basePaymentTerm, draftPaymentTerm]);
+
+    const result = await run(db, { companyId: baseCompany.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("filters payment terms by status when provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([basePaymentTerm]);
+
+    const result = await run(db, { companyId: baseCompany.id, status: "ACTIVE" });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("throws when company scope is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { companyId: "" });
+    expectErr(result as never, CompanyScopeRequiredError);
+  });
+});

package/src/modules/sales/query/listSalesPaymentTerms.ts

@@ -0,0 +1,42 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "name" | "status";
+
+export interface ListSalesPaymentTermsInput extends PaginationInput<OrderByField> {
+  companyId: string;
+  status?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesPaymentTermsInput) {
+  if (!input.companyId) {
+    return err(new CompanyScopeRequiredError("sales-payment-terms"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "name";
+  const orderDirection = input.orderDirection ?? "asc";
+
+  let query = db
+    .selectFrom("SalesPaymentTerm")
+    .selectAll()
+    .where("companyId", "=", input.companyId);
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+
+  const paymentTerms = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(paymentTerms, limit));
+}

package/src/modules/sales/query/listSalesPriceLists.generated.ts

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

package/src/modules/sales/query/listSalesPriceLists.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import { baseCompany, basePriceList, draftPriceList } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesPriceLists";
+
+describe("listSalesPriceLists", () => {
+  it("lists sales price lists by company", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([basePriceList, draftPriceList]);
+
+    const result = await run(db, { companyId: baseCompany.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("filters price lists by lifecycle status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([basePriceList]);
+
+    const result = await run(db, { companyId: baseCompany.id, status: "ACTIVE" });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("throws when company scope is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { companyId: "" });
+    expectErr(result as never, CompanyScopeRequiredError);
+  });
+});

package/src/modules/sales/query/listSalesPriceLists.ts

@@ -0,0 +1,39 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { CompanyScopeRequiredError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "name" | "priority" | "status";
+
+export interface ListSalesPriceListsInput extends PaginationInput<OrderByField> {
+  companyId: string;
+  status?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesPriceListsInput) {
+  if (!input.companyId) {
+    return err(new CompanyScopeRequiredError("sales-price-lists"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "priority";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db.selectFrom("SalesPriceList").selectAll().where("companyId", "=", input.companyId);
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+
+  const priceLists = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(priceLists, limit));
+}

package/src/modules/sales/query/listSalesPriceRulesByPriceList.generated.ts

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

package/src/modules/sales/query/listSalesPriceRulesByPriceList.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { PriceListNotFoundError } from "../lib/errors.generated";
+import { basePriceList, basePriceRule, draftPriceRule } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listSalesPriceRulesByPriceList";
+
+describe("listSalesPriceRulesByPriceList", () => {
+  it("lists rules under a sales price list", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(basePriceList);
+    spies.select.mockReturnValueOnce([basePriceRule, draftPriceRule]);
+
+    const result = await run(db, { salesPriceListId: basePriceList.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("filters rules by lifecycle status when provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(basePriceList);
+    spies.select.mockReturnValueOnce([basePriceRule]);
+
+    const result = await run(db, { salesPriceListId: basePriceList.id, status: "ACTIVE" });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("throws when price list is not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { salesPriceListId: "nonexistent-id" });
+    expectErr(result as never, PriceListNotFoundError);
+  });
+});

package/src/modules/sales/query/listSalesPriceRulesByPriceList.ts

@@ -0,0 +1,47 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { PriceListNotFoundError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "minimumQuantity" | "priority" | "status";
+
+export interface ListSalesPriceRulesByPriceListInput extends PaginationInput<OrderByField> {
+  salesPriceListId: string;
+  status?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListSalesPriceRulesByPriceListInput) {
+  const priceList = await db
+    .selectFrom("SalesPriceList")
+    .selectAll()
+    .where("id", "=", input.salesPriceListId)
+    .executeTakeFirst();
+  if (!priceList) {
+    return err(new PriceListNotFoundError(input.salesPriceListId));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "priority";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db
+    .selectFrom("SalesPriceRule")
+    .selectAll()
+    .where("salesPriceListId", "=", input.salesPriceListId);
+  if (input.status) {
+    query = query.where("status", "=", input.status as never);
+  }
+
+  const rules = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(rules, limit));
+}

package/src/modules/sales/query/listShipmentsBySalesOrder.generated.ts

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

package/src/modules/sales/query/listShipmentsBySalesOrder.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesOrderIdRequiredError } from "../lib/errors.generated";
+import { baseShipment, postedShipment, confirmedSalesOrder } from "../testing/fixtures";
+import { expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./listShipmentsBySalesOrder";
+
+describe("listShipmentsBySalesOrder", () => {
+  it("lists shipments under a sales order", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseShipment]);
+
+    const result = await run(db, { salesOrderId: confirmedSalesOrder.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(1);
+  });
+
+  it("returns both draft and posted shipments when present", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseShipment, postedShipment]);
+
+    const result = await run(db, { salesOrderId: confirmedSalesOrder.id });
+    const { items } = expectOk<{ items: unknown[]; hasNextPage: boolean }>(result as never);
+
+    expect(items).toHaveLength(2);
+  });
+
+  it("throws when sales-order id is missing", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { salesOrderId: "" });
+    expectErr(result as never, SalesOrderIdRequiredError);
+  });
+});

package/src/modules/sales/query/listShipmentsBySalesOrder.ts

@@ -0,0 +1,36 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { SalesOrderIdRequiredError } from "../lib/errors.generated";
+import {
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+  err,
+  ok,
+  type PaginationInput,
+  type ReadonlyDB,
+} from "@tailor-platform/erp-kit/module";
+
+type OrderByField = "createdAt" | "shipmentDate" | "status";
+
+export interface ListShipmentsBySalesOrderInput extends PaginationInput<OrderByField> {
+  salesOrderId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListShipmentsBySalesOrderInput) {
+  if (!input.salesOrderId) {
+    return err(new SalesOrderIdRequiredError("shipments"));
+  }
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "shipmentDate";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  const shipments = await db
+    .selectFrom("Shipment")
+    .selectAll()
+    .where("salesOrderId", "=", input.salesOrderId)
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+  return ok(buildPaginatedResult(shipments, limit));
+}