@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,105 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  IdentificationNotFoundError,
+  InvalidValueError,
+  DuplicateIdentificationError,
+  InvalidValidityPeriodError,
+} from "../lib/errors.generated";
+
+export interface UpdatePartnerIdentificationInput {
+  id: string;
+  value?: string;
+  issuingCountry?: string;
+  validFrom?: Date;
+  validTo?: Date;
+}
+
+/**
+ * Function: updatePartnerIdentification
+ *
+ * Updates an existing partner identification record.
+ * Type is immutable. Re-validates (type, value) uniqueness if value changes.
+ * Validates validity period using merged result with existing data.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdatePartnerIdentificationInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, value, issuingCountry, validFrom, validTo, ...customFields } = input;
+
+  // 1. Check identification exists
+  const existing = await db
+    .selectFrom("PartnerIdentification")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new IdentificationNotFoundError(id));
+  }
+
+  // 2. Validate value is non-empty if provided
+  if (value !== undefined && (!value || value.trim() === "")) {
+    return err(new InvalidValueError(value ?? ""));
+  }
+
+  // 3. If value changed, re-validate (type, value) uniqueness within company scope
+  if (value !== undefined && value !== existing.value) {
+    // Get the partner to find companyId
+    const partner = await db
+      .selectFrom("BusinessPartner")
+      .selectAll()
+      .where("id", "=", existing.partnerId)
+      .executeTakeFirst();
+
+    const duplicate = await db
+      .selectFrom("PartnerIdentification")
+      .innerJoin("BusinessPartner", "BusinessPartner.id", "PartnerIdentification.partnerId")
+      .selectAll("PartnerIdentification")
+      .where("BusinessPartner.companyId", "=", partner!.companyId)
+      .where("PartnerIdentification.type", "=", existing.type)
+      .where("PartnerIdentification.value", "=", value)
+      .executeTakeFirst();
+
+    if (duplicate) {
+      return err(new DuplicateIdentificationError(`${existing.type}:${value}`));
+    }
+  }
+
+  // 4. Validate validity period (merge with existing)
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- null means "clear the field", distinct from undefined (not provided)
+  const effectiveFrom = validFrom !== undefined ? validFrom : existing.validFrom;
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+  const effectiveTo = validTo !== undefined ? validTo : existing.validTo;
+
+  if (effectiveFrom && effectiveTo && effectiveTo < effectiveFrom) {
+    return err(
+      new InvalidValidityPeriodError(
+        `${effectiveFrom instanceof Date ? effectiveFrom.toISOString() : effectiveFrom} - ${effectiveTo instanceof Date ? effectiveTo.toISOString() : effectiveTo}`,
+      ),
+    );
+  }
+
+  // 5. Build update set
+  const updateSet: Record<string, unknown> = {
+    ...customFields,
+    updatedAt: new Date(),
+  };
+  if (value !== undefined) updateSet.value = value;
+  if (issuingCountry !== undefined) updateSet.issuingCountry = issuingCountry;
+  if (validFrom !== undefined) updateSet.validFrom = validFrom;
+  if (validTo !== undefined) updateSet.validTo = validTo;
+
+  // 6. Update record
+  const identification = await db
+    .updateTable("PartnerIdentification")
+    .set(updateSet)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ identification });
+}

package/src/modules/business-partner/db/businessPartner.ts

@@ -0,0 +1,59 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub, currency as currencyStub } from "../lib/_db_deps";
+
+export const BASE_PARTNER_STATUSES = ["DRAFT", "ACTIVE", "INACTIVE"] as const;
+
+export const PARTNER_TYPES = ["ORGANIZATION", "INDIVIDUAL"] as const;
+
+export interface CreateBusinessPartnerTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+  companyType?: TailorAnyDBType;
+  currencyType?: TailorAnyDBType;
+}
+
+export function createBusinessPartnerType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateBusinessPartnerTypeParams<F>,
+) {
+  const statuses = [...BASE_PARTNER_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type("BusinessPartner", {
+      name: db.string().description("Business partner display name"),
+      type: db
+        .enum(["ORGANIZATION", "INDIVIDUAL"])
+        .description("Partner type: ORGANIZATION or INDIVIDUAL"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "businessPartners",
+        })
+        .description("Foreign key to Company from organization module"),
+      preferredCurrencyId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "businessPartners",
+        })
+        .description("Optional preferred transaction currency"),
+      status: db.enum(statuses).description("Lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const businessPartner = createBusinessPartnerType({});

package/src/modules/business-partner/db/contactPerson.ts

@@ -0,0 +1,49 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner } from "./businessPartner";
+
+export const BASE_CONTACT_STATUSES = ["ACTIVE", "INACTIVE"] as const;
+
+export interface CreateContactPersonTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+}
+
+export function createContactPersonType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateContactPersonTypeParams<F>,
+) {
+  const statuses = [...BASE_CONTACT_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type("ContactPerson", {
+      partnerId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: businessPartner },
+          backward: "contactPersons",
+        })
+        .description("Foreign key to ORGANIZATION-type BusinessPartner"),
+      firstName: db.string().description("Contact person first name"),
+      lastName: db.string().description("Contact person last name"),
+      email: db.string({ optional: true }).description("Contact person email address"),
+      phone: db.string({ optional: true }).description("Contact person phone number"),
+      jobTitle: db.string({ optional: true }).description("Contact person job title"),
+      department: db.string({ optional: true }).description("Contact person department"),
+      isPrimary: db.bool().description("Whether this is the primary contact for the organization"),
+      status: db.enum(statuses).description("Contact person status: ACTIVE or INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const contactPerson = createContactPersonType({});

package/src/modules/business-partner/db/partnerAddress.ts

@@ -0,0 +1,45 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner } from "./businessPartner";
+
+export const ADDRESS_TYPES = ["BILLING", "SHIPPING", "REGISTERED", "OTHER"] as const;
+
+export interface CreatePartnerAddressTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createPartnerAddressType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePartnerAddressTypeParams<F>,
+) {
+  return db
+    .type("PartnerAddress", {
+      partnerId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: businessPartner },
+          backward: "partnerAddresses",
+        })
+        .description("Foreign key to BusinessPartner"),
+      addressType: db
+        .enum(["BILLING", "SHIPPING", "REGISTERED", "OTHER"])
+        .description("Address purpose: BILLING, SHIPPING, REGISTERED, OTHER"),
+      line1: db.string().description("Address line 1"),
+      line2: db.string({ optional: true }).description("Address line 2"),
+      city: db.string().description("City"),
+      state: db.string({ optional: true }).description("State or province"),
+      postalCode: db.string().description("Postal code"),
+      country: db.string().description("ISO 3166-1 alpha-2 country code"),
+      isDefault: db.bool().description("Whether this is the default address for its type"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const partnerAddress = createPartnerAddressType({});

package/src/modules/business-partner/db/partnerBankAccount.ts

@@ -0,0 +1,53 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { currency as currencyStub } from "../lib/_db_deps";
+import { businessPartner } from "./businessPartner";
+
+export interface CreatePartnerBankAccountTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  currencyType?: TailorAnyDBType;
+}
+
+export function createPartnerBankAccountType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePartnerBankAccountTypeParams<F>,
+) {
+  return db
+    .type("PartnerBankAccount", {
+      partnerId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: businessPartner },
+          backward: "partnerBankAccounts",
+        })
+        .description("Foreign key to BusinessPartner"),
+      bankName: db.string().description("Name of the bank"),
+      accountHolderName: db.string().description("Name of the account holder"),
+      accountNumber: db.string({ optional: true }).description("Bank account number"),
+      routingNumber: db.string({ optional: true }).description("Domestic routing number"),
+      iban: db.string({ optional: true }).description("International Bank Account Number"),
+      swiftBic: db
+        .string({ optional: true })
+        .description("SWIFT/BIC code for international transfers"),
+      currencyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "partnerBankAccounts",
+        })
+        .description("Foreign key to Currency from primitives module"),
+      isDefault: db.bool().description("Whether this is the default bank account for the partner"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const partnerBankAccount = createPartnerBankAccountType({});

package/src/modules/business-partner/db/partnerIdentification.ts

@@ -0,0 +1,53 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner } from "./businessPartner";
+
+export const IDENTIFICATION_TYPES = [
+  "TAX_ID",
+  "VAT",
+  "DUNS",
+  "COMPANY_REGISTRY",
+  "NATIONAL_ID",
+  "OTHER",
+] as const;
+
+export interface CreatePartnerIdentificationTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createPartnerIdentificationType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePartnerIdentificationTypeParams<F>,
+) {
+  return db
+    .type("PartnerIdentification", {
+      partnerId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: businessPartner },
+          backward: "partnerIdentifications",
+        })
+        .description("Foreign key to BusinessPartner"),
+      type: db
+        .enum(["TAX_ID", "VAT", "DUNS", "COMPANY_REGISTRY", "NATIONAL_ID", "OTHER"])
+        .description(
+          "Identification type: TAX_ID, VAT, DUNS, COMPANY_REGISTRY, NATIONAL_ID, OTHER",
+        ),
+      value: db.string().description("Identification value (e.g., tax number, VAT number)"),
+      issuingCountry: db
+        .string({ optional: true })
+        .description("ISO 3166-1 alpha-2 country code of the issuing authority"),
+      validFrom: db.date({ optional: true }).description("Start date of validity period"),
+      validTo: db.date({ optional: true }).description("End date of validity period"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const partnerIdentification = createPartnerIdentificationType({});

package/src/modules/business-partner/db/partnerRole.ts

@@ -0,0 +1,43 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner } from "./businessPartner";
+
+export const PARTNER_ROLES = ["CUSTOMER", "SUPPLIER"] as const;
+
+export interface CreatePartnerRoleTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createPartnerRoleType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePartnerRoleTypeParams<F>,
+) {
+  return db
+    .type("PartnerRole", {
+      partnerId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: businessPartner },
+          backward: "partnerRoles",
+        })
+        .description("Foreign key to BusinessPartner"),
+      role: db
+        .enum(["CUSTOMER", "SUPPLIER"])
+        .description("Role classification: CUSTOMER or SUPPLIER"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["partnerId", "role"],
+      unique: true,
+      name: "partner_role_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const partnerRole = createPartnerRoleType({});

package/src/modules/business-partner/docs/commands/ActivatePartner.md

@@ -0,0 +1,39 @@
+# ActivatePartner
+
+## Overview
+
+activatePartner transitions a business partner from DRAFT to ACTIVE status, making the partner eligible for role assignments, transactions, and other downstream operations. Only partners in DRAFT status can be activated.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in DRAFT status
+- After activation, the partner can be assigned roles and participate in transactions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Partner exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return activated partner]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **INVALID_STATE_TRANSITION**: The required state transition is not valid for the current status
+
+## Test Cases
+
+- activates a DRAFT partner
+- returns error when partner not found
+- returns error when partner is ACTIVE
+- returns error when partner is INACTIVE

package/src/modules/business-partner/docs/commands/AssignRoleToPartner.md

@@ -0,0 +1,49 @@
+# AssignRoleToPartner
+
+## Overview
+
+assignRoleToPartner assigns a business role (CUSTOMER or SUPPLIER) to an active partner. Roles determine which business processes a partner can participate in. A partner can hold multiple roles simultaneously (e.g., both CUSTOMER and SUPPLIER). The operation is idempotent — assigning a role that is already present does not produce an error.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in ACTIVE status
+- Role must be a valid value (CUSTOMER or SUPPLIER)
+- A partner can hold multiple roles simultaneously
+- Assignment is idempotent — re-assigning an existing role succeeds without error
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign role request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Partner is ACTIVE?}
+    D -->|No| E[Return error: partner not active]
+    D -->|Yes| F{Role valid?}
+    F -->|No| G[Return error: invalid role]
+    F -->|Yes| H{Role already assigned?}
+    H -->|Yes| I[Return success - idempotent]
+    H -->|No| J[Assign role to partner]
+    J --> K[Return updated partner]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **PARTNER_NOT_ACTIVE**: Partner is not in ACTIVE status
+- **INVALID_ROLE**: Role is not CUSTOMER or SUPPLIER
+
+## Test Cases
+
+- assigns CUSTOMER to partner with no roles
+- assigns SUPPLIER to partner that already holds CUSTOMER
+- idempotent when role already assigned
+- returns error when partner not found
+- returns error when partner is INACTIVE
+- returns error when partner is DRAFT
+- returns error when role is invalid

package/src/modules/business-partner/docs/commands/CreateContactPerson.md

@@ -0,0 +1,59 @@
+# CreateContactPerson
+
+## Overview
+
+createContactPerson adds a contact person to an organization-type business partner. Contact persons represent individuals within an organization who serve as points of contact for business communications. At least one communication channel (email or phone) is required. Contact persons are created in ACTIVE status.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be of type ORGANIZATION — contact persons cannot be added to INDIVIDUAL partners
+- First name and last name are required and must be non-empty
+- At least one of email or phone must be provided
+- Email, if provided, must be in a valid format
+- Contact person is created in ACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Partner is ORGANIZATION?}
+    D -->|No| E[Return error: partner not organization]
+    D -->|Yes| F1{firstName and lastName non-empty?}
+    F1 -->|No| F2[Return error: invalid name]
+    F1 -->|Yes| F{Email or phone provided?}
+    F -->|No| G[Return error: missing communication channel]
+    F -->|Yes| H{Email provided?}
+    H -->|Yes| I{Email format valid?}
+    I -->|No| J[Return error: invalid email format]
+    I -->|Yes| K[Create contact person in ACTIVE status]
+    H -->|No| K
+    K --> L[Return created contact person]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **PARTNER_NOT_ORGANIZATION**: Partner is of type INDIVIDUAL, not ORGANIZATION
+- **INVALID_FIRST_NAME**: First name is empty or not provided
+- **INVALID_LAST_NAME**: Last name is empty or not provided
+- **MISSING_COMMUNICATION_CHANNEL**: Neither email nor phone was provided
+- **INVALID_EMAIL_FORMAT**: Provided email is not in a valid format
+
+## Test Cases
+
+- creates contact person
+- returns error when partner not found
+- returns error when partner is INDIVIDUAL
+- returns error when firstName is empty
+- returns error when lastName is empty
+- returns error when neither email nor phone provided
+- returns error for invalid email format
+- returns error when whitespace-only channels provided as only communication
+- creates with ACTIVE status

package/src/modules/business-partner/docs/commands/CreatePartner.md

@@ -0,0 +1,54 @@
+# CreatePartner
+
+## Overview
+
+createPartner establishes a new business partner in the system. Partners represent external entities (organizations or individuals) with which the company conducts business. Every partner is created in DRAFT status, allowing review and enrichment before activation. The partner type (ORGANIZATION or INDIVIDUAL) is set at creation and cannot be changed afterward.
+
+## Business Rules
+
+- Name is required and must be non-empty
+- Type is required and must be one of ORGANIZATION or INDIVIDUAL
+- Type is immutable after creation — it cannot be changed once assigned
+- Partner is always created in DRAFT status regardless of input
+- Preferred currency, if provided, must reference an existing Currency in the primitives module
+- Company ID must reference an existing Company in the organization module
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Company exists?}
+    B -->|No| C[Return error: company not found]
+    B -->|Yes| D{Name non-empty?}
+    D -->|No| E[Return error: invalid name]
+    D -->|Yes| F{Type valid?}
+    F -->|No| G[Return error: invalid partner type]
+    F -->|Yes| H{Currency provided?}
+    H -->|Yes| I{Currency exists?}
+    I -->|No| J[Return error: currency not found]
+    I -->|Yes| K[Create partner in DRAFT status]
+    H -->|No| K
+    K --> L[Return created partner]
+```
+
+## External Dependencies
+
+- [organization::Company](../../../organization/docs/models/Company.md) - Validates that the referenced company exists
+- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced preferred currency exists (when provided)
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_NAME**: Name is empty or not provided
+- **INVALID_PARTNER_TYPE**: Type is not ORGANIZATION or INDIVIDUAL
+- **CURRENCY_NOT_FOUND**: Referenced preferred currency does not exist
+
+## Test Cases
+
+- creates partner in DRAFT status
+- returns error when company not found
+- returns error when type is invalid
+- returns error when name is empty
+- creates partner without preferred currency
+- creates partner with preferred currency
+- returns error when currency not found

package/src/modules/business-partner/docs/commands/CreatePartnerAddress.md

@@ -0,0 +1,60 @@
+# CreatePartnerAddress
+
+## Overview
+
+createPartnerAddress adds a physical or mailing address to a business partner. Addresses are categorized by type and can be designated as default for their type. Partners in DRAFT or ACTIVE status can have addresses added, but INACTIVE partners cannot receive new addresses. When an address is set as default, any previous default of the same type for that partner is automatically unset.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in DRAFT or ACTIVE status (not INACTIVE)
+- Address type must be a valid enum value
+- Line1, city, postal code, and country are required
+- Country must be a valid ISO 3166-1 alpha-2 code
+- If isDefault is true, the previous default address of the same type for the partner is unset
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Partner is INACTIVE?}
+    D -->|Yes| E[Return error: partner inactive]
+    D -->|No| F{Address type valid?}
+    F -->|No| G[Return error: invalid address type]
+    F -->|Yes| H1{line1, city, postalCode non-empty?}
+    H1 -->|No| H2[Return error: missing required address field]
+    H1 -->|Yes| H{Country code valid?}
+    H -->|No| I[Return error: invalid country code]
+    H -->|Yes| J{isDefault true?}
+    J -->|Yes| K[Unset previous default of same type]
+    K --> L[Create address as default]
+    J -->|No| L[Create address record]
+    L --> M[Return created address]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **PARTNER_INACTIVE**: Partner is in INACTIVE status
+- **INVALID_ADDRESS_TYPE**: Address type is not a valid enum value
+- **MISSING_REQUIRED_ADDRESS_FIELD**: One or more required fields (line1, city, postalCode) are empty or not provided
+- **INVALID_COUNTRY_CODE**: Country is not a valid ISO 3166-1 alpha-2 code
+
+## Test Cases
+
+- creates address for active partner
+- creates address for draft partner
+- returns error when partner not found
+- returns error when partner is inactive
+- returns error when address type is invalid
+- returns error when required fields missing
+- returns error when country code is invalid
+- returns error when country code is lowercase
+- creates non-default address
+- unsets previous default when creating with isDefault true