@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/business-partner/command/setPrimaryContactPerson.ts

@@ -0,0 +1,55 @@
+import { ok, err } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { ContactPersonNotFoundError, InvalidStateTransitionError } from "../lib/errors.generated";
+
+export interface SetPrimaryContactPersonInput {
+  id: string;
+}
+
+/**
+ * Function: setPrimaryContactPerson
+ *
+ * Sets a contact person as the primary contact for their partner. Unsets the
+ * previous primary contact for the same partner. Contact must be ACTIVE.
+ */
+export async function run(db: Transaction, input: SetPrimaryContactPersonInput) {
+  const { id } = input;
+
+  // 1. Check contact exists
+  const existing = await db
+    .selectFrom("ContactPerson")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new ContactPersonNotFoundError(id));
+  }
+
+  // 2. Contact must be ACTIVE
+  if (existing.status !== "ACTIVE") {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  // 3. Unset previous primary for same partner
+  await db
+    .updateTable("ContactPerson")
+    .set({ isPrimary: false, updatedAt: new Date() })
+    .where("partnerId", "=", existing.partnerId)
+    .where("isPrimary", "=", true)
+    .execute();
+
+  // 4. Set this contact as primary
+  const contact = await db
+    .updateTable("ContactPerson")
+    .set({
+      isPrimary: true,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ contact: contact! });
+}

package/src/modules/business-partner/command/updateContactPerson.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updateContactPerson";
+
+export const updateContactPerson = defineCommand(permissions.updateContactPerson, run);

package/src/modules/business-partner/command/updateContactPerson.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ContactPersonNotFoundError,
+  InvalidFirstNameError,
+  InvalidLastNameError,
+  InvalidEmailFormatError,
+  MissingCommunicationChannelError,
+} from "../lib/errors.generated";
+import { baseActiveContact, baseNonPrimaryContact } from "../testing/fixtures";
+import { run } from "./updateContactPerson";
+
+describe("updateContactPerson", () => {
+  it("updates contact person details", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+    spies.update.mockReturnValue({
+      ...baseActiveContact,
+      firstName: "Updated",
+    });
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      firstName: "Updated",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.contact.firstName).toBe("Updated");
+    }
+  });
+
+  it("returns error when contact not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, {
+      id: "nonexistent",
+      firstName: "Updated",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ContactPersonNotFoundError);
+    }
+  });
+
+  it("returns error when first name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      firstName: "",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidFirstNameError);
+    }
+  });
+
+  it("returns error when first name is whitespace-only", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      firstName: "   ",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidFirstNameError);
+    }
+  });
+
+  it("returns error when last name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      lastName: "",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidLastNameError);
+    }
+  });
+
+  it("returns error when last name is whitespace-only", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      lastName: "   ",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidLastNameError);
+    }
+  });
+
+  it("returns error when email format is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      email: "invalid-email",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidEmailFormatError);
+    }
+  });
+
+  it("returns error when update would leave no communication channel", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // baseNonPrimaryContact has phone but no email
+    spies.select.mockReturnValueOnce(baseNonPrimaryContact);
+
+    const result = await run(db, {
+      id: baseNonPrimaryContact.id,
+      phone: null,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingCommunicationChannelError);
+    }
+  });
+
+  it("returns error when whitespace-only phone would leave no communication channel", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // Contact with only phone (no email)
+    spies.select.mockReturnValueOnce(baseNonPrimaryContact);
+
+    const result = await run(db, {
+      id: baseNonPrimaryContact.id,
+      phone: "   ",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingCommunicationChannelError);
+    }
+  });
+
+  it("does not change organization association", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+    spies.update.mockReturnValue({
+      ...baseActiveContact,
+      firstName: "Updated",
+    });
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      firstName: "Updated",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.not.objectContaining({ partnerId: expect.anything() as unknown }),
+    );
+  });
+
+  it("preserves primary contact designation", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveContact);
+    spies.update.mockReturnValue({
+      ...baseActiveContact,
+      firstName: "Updated",
+    });
+
+    const result = await run(db, {
+      id: baseActiveContact.id,
+      firstName: "Updated",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.not.objectContaining({ isPrimary: expect.anything() as unknown }),
+    );
+  });
+});

package/src/modules/business-partner/command/updateContactPerson.ts

@@ -0,0 +1,92 @@
+import { ok, err } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ContactPersonNotFoundError,
+  InvalidFirstNameError,
+  InvalidLastNameError,
+  InvalidEmailFormatError,
+  MissingCommunicationChannelError,
+} from "../lib/errors.generated";
+
+export interface UpdateContactPersonInput {
+  id: string;
+  firstName?: string;
+  lastName?: string;
+  email?: string | null;
+  phone?: string | null;
+  jobTitle?: string | null;
+  department?: string | null;
+}
+
+/**
+ * Function: updateContactPerson
+ *
+ * Updates a contact person's details. Validates name fields if provided,
+ * email format if provided, and ensures at least one communication channel
+ * remains after the update. isPrimary is not modifiable through this command.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateContactPersonInput & CF,
+) {
+  const { id, firstName, lastName, email, phone, jobTitle, department, ...customFields } = input;
+
+  // 1. Check contact exists
+  const existing = await db
+    .selectFrom("ContactPerson")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new ContactPersonNotFoundError(id));
+  }
+
+  // 2. Validate firstName if provided
+  if (firstName !== undefined && !firstName?.trim()) {
+    return err(new InvalidFirstNameError(id));
+  }
+
+  // 3. Validate lastName if provided
+  if (lastName !== undefined && !lastName?.trim()) {
+    return err(new InvalidLastNameError(id));
+  }
+
+  // 4. Validate email format if provided and non-null
+  if (email !== undefined && email !== null) {
+    const trimmedEmail = email.trim();
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(trimmedEmail)) {
+      return err(new InvalidEmailFormatError(email));
+    }
+  }
+
+  // 5. After update, at least one of email or phone must remain (whitespace-only values don't count)
+  const mergedEmail = email !== undefined ? email : existing.email;
+  const mergedPhone = phone !== undefined ? phone : existing.phone;
+  if (!mergedEmail?.trim() && !mergedPhone?.trim()) {
+    return err(new MissingCommunicationChannelError(id));
+  }
+
+  // 6. Build update values
+  const updateValues: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (firstName !== undefined) updateValues.firstName = firstName;
+  if (lastName !== undefined) updateValues.lastName = lastName;
+  if (email !== undefined) updateValues.email = email ?? null;
+  if (phone !== undefined) updateValues.phone = phone ?? null;
+  if (jobTitle !== undefined) updateValues.jobTitle = jobTitle ?? null;
+  if (department !== undefined) updateValues.department = department ?? null;
+
+  const contact = await db
+    .updateTable("ContactPerson")
+    .set(updateValues)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ contact: contact! });
+}

package/src/modules/business-partner/command/updatePartner.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updatePartner";
+
+export const updatePartner = defineCommand(permissions.updatePartner, run);

package/src/modules/business-partner/command/updatePartner.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PartnerNotFoundError,
+  InvalidNameError,
+  CurrencyNotFoundError,
+} from "../lib/errors.generated";
+import { baseActivePartner } from "../testing/fixtures";
+import { getCurrency } from "../../primitives/query/getCurrency.generated";
+import { run } from "./updatePartner";
+
+describe("updatePartner", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["business-partner:updatePartner"],
+  };
+
+  it("updates partner name", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedPartner = { ...baseActivePartner, name: "Updated Name" };
+    spies.select.mockReturnValueOnce(baseActivePartner);
+    spies.update.mockReturnValue(updatedPartner);
+
+    const result = await run(db, { id: baseActivePartner.id, name: "Updated Name" }, ctx, {
+      getCurrency,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partner.name).toBe("Updated Name");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("updates preferred currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const currency = { id: "currency-eur", code: "EUR" };
+    const updatedPartner = { ...baseActivePartner, preferredCurrencyId: "currency-eur" };
+    spies.select
+      .mockReturnValueOnce(baseActivePartner) // Partner lookup
+      .mockReturnValueOnce(currency); // Currency lookup
+    spies.update.mockReturnValue(updatedPartner);
+
+    const result = await run(
+      db,
+      { id: baseActivePartner.id, preferredCurrencyId: "currency-eur" },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partner.preferredCurrencyId).toBe("currency-eur");
+    }
+  });
+
+  it("returns error when partner not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent", name: "New Name" }, ctx, { getCurrency });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PartnerNotFoundError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActivePartner);
+
+    const result = await run(db, { id: baseActivePartner.id, name: "" }, ctx, { getCurrency });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNameError);
+    }
+  });
+
+  it("returns error when currency not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActivePartner) // Partner lookup
+      .mockReturnValueOnce(undefined); // Currency not found
+
+    const result = await run(
+      db,
+      { id: baseActivePartner.id, preferredCurrencyId: "nonexistent" },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CurrencyNotFoundError);
+    }
+  });
+});

package/src/modules/business-partner/command/updatePartner.ts

@@ -0,0 +1,76 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PartnerNotFoundError,
+  InvalidNameError,
+  CurrencyNotFoundError,
+} from "../lib/errors.generated";
+
+import type { defineModule as definePrimitivesModule } from "../../primitives";
+type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
+type PrimitivesQueries = PrimitivesModule["queries"];
+
+export interface UpdatePartnerInput {
+  id: string;
+  name?: string;
+  preferredCurrencyId?: string;
+}
+
+/**
+ * Function: updatePartner
+ *
+ * Updates mutable fields of an existing business partner.
+ * Validates partner existence, name non-empty if provided, and currency if provided.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdatePartnerInput & Partial<CF>,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getCurrency">,
+) {
+  const { id, name, preferredCurrencyId, ...customFields } = input;
+
+  // 1. Check partner exists
+  const partner = await db
+    .selectFrom("BusinessPartner")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!partner) {
+    return err(new PartnerNotFoundError(id));
+  }
+
+  // 2. Validate name is non-empty if provided
+  if (name?.trim() === "") {
+    return err(new InvalidNameError(id));
+  }
+
+  // 3. Validate currency exists if provided
+  if (preferredCurrencyId !== undefined) {
+    const { currency } = (
+      await primitivesQueries!.getCurrency(db, { id: preferredCurrencyId }, ctx)
+    ).value;
+    if (!currency) {
+      return err(new CurrencyNotFoundError(preferredCurrencyId));
+    }
+  }
+
+  // 4. Apply updates
+  const updates: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (name !== undefined) updates.name = name;
+  if (preferredCurrencyId !== undefined) updates.preferredCurrencyId = preferredCurrencyId;
+
+  const updatedPartner = await db
+    .updateTable("BusinessPartner")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ partner: updatedPartner });
+}

package/src/modules/business-partner/command/updatePartnerAddress.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updatePartnerAddress";
+
+export const updatePartnerAddress = defineCommand(permissions.updatePartnerAddress, run);

package/src/modules/business-partner/command/updatePartnerAddress.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { AddressNotFoundError, InvalidCountryCodeError } from "../lib/errors.generated";
+import { baseBillingAddress } from "../testing/fixtures";
+import { run } from "./updatePartnerAddress";
+
+describe("updatePartnerAddress", () => {
+  it("updates address fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedAddress = {
+      ...baseBillingAddress,
+      line1: "789 Elm St",
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(baseBillingAddress); // Address lookup
+    spies.update.mockReturnValue(updatedAddress);
+
+    const result = await run(db, {
+      id: "address-1",
+      line1: "789 Elm St",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.address.line1).toBe("789 Elm St");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("updates address for DRAFT partner", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const draftAddress = { ...baseBillingAddress, partnerId: "partner-1" };
+    const updatedAddress = {
+      ...draftAddress,
+      city: "Boston",
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(draftAddress);
+    spies.update.mockReturnValue(updatedAddress);
+
+    const result = await run(db, {
+      id: "address-1",
+      city: "Boston",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.address.city).toBe("Boston");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("updates address for ACTIVE partner", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activeAddress = { ...baseBillingAddress, partnerId: "partner-2" };
+    const updatedAddress = {
+      ...activeAddress,
+      postalCode: "10002",
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(activeAddress);
+    spies.update.mockReturnValue(updatedAddress);
+
+    const result = await run(db, {
+      id: "address-1",
+      postalCode: "10002",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.address.postalCode).toBe("10002");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("updates address for INACTIVE partner", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const inactiveAddress = { ...baseBillingAddress, partnerId: "partner-3" };
+    const updatedAddress = {
+      ...inactiveAddress,
+      line1: "999 Pine Rd",
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(inactiveAddress);
+    spies.update.mockReturnValue(updatedAddress);
+
+    const result = await run(db, {
+      id: "address-1",
+      line1: "999 Pine Rd",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.address.line1).toBe("999 Pine Rd");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when country code is lowercase", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBillingAddress);
+
+    const result = await run(db, {
+      id: "address-1",
+      country: "us",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidCountryCodeError);
+    }
+  });
+
+  it("returns error when address not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // Address not found
+
+    const result = await run(db, {
+      id: "nonexistent",
+      line1: "789 Elm St",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AddressNotFoundError);
+    }
+  });
+
+  it("returns error when country code is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBillingAddress); // Address exists
+
+    const result = await run(db, {
+      id: "address-1",
+      country: "USA",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidCountryCodeError);
+    }
+  });
+});