@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/business-partner/docs/queries/GetPartnerBankAccount.md

@@ -0,0 +1,34 @@
+# GetPartnerBankAccount
+
+## Overview
+
+GetPartnerBankAccount retrieves a single bank account record by id. This serves as the lookup for update, delete, and setDefault bank account commands.
+
+## Business Rules
+
+- Accepts `{ id }` as input — retrieves by unique identifier
+- Returns the full PartnerBankAccount record or null if no matching bank account is found
+- Used by update, delete, and setDefault commands to verify the bank account exists before operating on it
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerBankAccount where id = input.id]
+    B --> C{Bank account found?}
+    C -->|Yes| D[Return bank account record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BANK_ACCOUNT_NOT_FOUND**: No bank account matches the given id — caller receives null
+
+## Test Cases
+
+- returns bank account when found
+- returns null when not found

package/src/modules/business-partner/docs/queries/GetPartnerIdentification.md

@@ -0,0 +1,34 @@
+# GetPartnerIdentification
+
+## Overview
+
+GetPartnerIdentification retrieves a single identification record by id. This serves as the lookup for update and delete identification commands.
+
+## Business Rules
+
+- Accepts `{ id }` as input — retrieves by unique identifier
+- Returns the full PartnerIdentification record or null if no matching identification is found
+- Used by update and delete commands to verify the identification exists before operating on it
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerIdentification where id = input.id]
+    B --> C{Identification found?}
+    C -->|Yes| D[Return identification record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **IDENTIFICATION_NOT_FOUND**: No identification matches the given id — caller receives null
+
+## Test Cases
+
+- returns identification when found
+- returns null when not found

package/src/modules/business-partner/docs/queries/GetPartnerRole.md

@@ -0,0 +1,34 @@
+# GetPartnerRole
+
+## Overview
+
+GetPartnerRole retrieves a role assignment by partnerId and role. This serves as the lookup for idempotency checks in assignRole and removeRole commands.
+
+## Business Rules
+
+- Accepts `{ partnerId, role }` as input — retrieves by the composite key of partner and role
+- Returns the full PartnerRole record or null if no matching assignment is found
+- Used to determine whether a role is already assigned before assigning, or still assigned before removing
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerRole where partnerId = input.partnerId AND role = input.role]
+    B --> C{Role found?}
+    C -->|Yes| D[Return role record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ROLE_NOT_FOUND**: No role assignment matches the given partnerId and role — caller receives null
+
+## Test Cases
+
+- returns role when found
+- returns null when role not found

package/src/modules/business-partner/docs/queries/GetPrimaryContactPerson.md

@@ -0,0 +1,36 @@
+# GetPrimaryContactPerson
+
+## Overview
+
+GetPrimaryContactPerson retrieves the primary contact person for a partner. This is used by downstream communication workflows to resolve the primary point of contact for a given business partner.
+
+## Business Rules
+
+- Accepts `{ partnerId }` as input — retrieves the contact person with isPrimary=true for the given partner
+- Returns the ContactPerson record where isPrimary is true, or null if no primary is set
+- At most one contact person per partner can be marked as primary
+- Returns null when the partner has no contact persons at all
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from ContactPerson where partnerId = input.partnerId AND isPrimary = true]
+    B --> C{Primary contact found?}
+    C -->|Yes| D[Return contact person record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns null when no primary contact person exists
+
+## Test Cases
+
+- returns primary contact when one exists
+- returns null when no primary is set
+- returns null when partner has no contact persons

package/src/modules/business-partner/docs/queries/ListContactPersonsByPartner.md

@@ -0,0 +1,39 @@
+# ListContactPersonsByPartner
+
+## Overview
+
+ListContactPersonsByPartner retrieves all contact persons linked to a given organization partner. This supports listing contact persons for an organization, including primary and non-primary contacts across all statuses.
+
+## Business Rules
+
+- Accepts `{ partnerId }` as input
+- Returns all contact persons linked to the specified partner, regardless of their status (ACTIVE or INACTIVE)
+- Returns an empty array when the partner has no contact persons — not an error
+- Results include both primary and non-primary contact persons
+- Only ORGANIZATION-type partners have contact persons; querying an INDIVIDUAL-type partner returns an empty array
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from ContactPerson where partnerId = input.partnerId]
+    B --> C{Any contacts found?}
+    C -->|Yes| D[Return contact person records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns an empty array when no contact persons exist for the partner
+
+## Test Cases
+
+- returns all contact persons for a partner with multiple contacts
+- returns empty array when partner has no contact persons
+- includes both ACTIVE and INACTIVE contact persons
+- includes both primary and non-primary contact persons
+- returns empty array for an INDIVIDUAL-type partner

package/src/modules/business-partner/docs/queries/ListPartnerAddressesByPartner.md

@@ -0,0 +1,41 @@
+# ListPartnerAddressesByPartner
+
+## Overview
+
+ListPartnerAddressesByPartner retrieves all addresses belonging to a given partner, with optional filtering by address type. This supports downstream modules that need to display or select from a partner's full set of addresses, as well as type-specific lookups (e.g., all SHIPPING addresses for a partner).
+
+## Business Rules
+
+- Accepts `{ partnerId, addressType? }` as input
+- When `addressType` is provided, returns only addresses of that type for the partner
+- When `addressType` is omitted, returns all addresses for the partner regardless of type
+- Returns an empty array when the partner has no addresses (or none of the requested type) — not an error
+- Results include both default and non-default addresses
+- Reading addresses is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{addressType provided?}
+    B -->|Yes| C[SELECT from PartnerAddress where partnerId = input.partnerId AND addressType = input.addressType]
+    B -->|No| D[SELECT from PartnerAddress where partnerId = input.partnerId]
+    C --> E[Return matching addresses]
+    D --> E
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns an empty array when no addresses match the criteria
+
+## Test Cases
+
+- returns all addresses for a partner with multiple addresses
+- returns only SHIPPING addresses when addressType filter is provided
+- returns empty array when partner has no addresses
+- returns empty array when partner has no addresses of the requested type
+- includes both default and non-default addresses in results

package/src/modules/business-partner/docs/queries/ListPartnerBankAccountsByPartner.md

@@ -0,0 +1,39 @@
+# ListPartnerBankAccountsByPartner
+
+## Overview
+
+ListPartnerBankAccountsByPartner retrieves all bank accounts belonging to a given partner. This supports downstream modules (accounts payable, accounts receivable) that need to display or select from a partner's full set of bank accounts, including both default and non-default accounts.
+
+## Business Rules
+
+- Accepts `{ partnerId }` as input
+- Returns all bank accounts for the specified partner, regardless of default designation
+- Returns an empty array when the partner has no bank accounts — not an error
+- Results include both the default bank account and non-default accounts
+- Reading bank accounts is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
+- Bank accounts are isolated per partner; only accounts belonging to the specified partner are returned
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerBankAccount where partnerId = input.partnerId]
+    B --> C{Any accounts found?}
+    C -->|Yes| D[Return bank account records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns an empty array when no bank accounts exist for the partner
+
+## Test Cases
+
+- returns all bank accounts for a partner with multiple accounts
+- returns empty array when partner has no bank accounts
+- includes both default and non-default accounts in results
+- returns accounts regardless of partner lifecycle status

package/src/modules/business-partner/docs/queries/ListPartnerIdentificationsByPartner.md

@@ -0,0 +1,41 @@
+# ListPartnerIdentificationsByPartner
+
+## Overview
+
+ListPartnerIdentificationsByPartner retrieves all identification records belonging to a given partner. This supports downstream modules and compliance workflows (tax reporting, KYC, duplicate detection) that need to view or verify all identification documents attached to a partner.
+
+## Business Rules
+
+- Accepts `{ partnerId, type? }` as input
+- When `type` is provided, returns only identification records of that type for the partner
+- When `type` is omitted, returns all identification records for the partner regardless of type
+- Returns an empty array when the partner has no identification records (or none of the requested type) — not an error
+- Results include identifications regardless of their validity period (expired, active, or not yet valid)
+- Reading identifications is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{type provided?}
+    B -->|Yes| C[SELECT from PartnerIdentification where partnerId = input.partnerId AND type = input.type]
+    B -->|No| D[SELECT from PartnerIdentification where partnerId = input.partnerId]
+    C --> E[Return matching identification records]
+    D --> E
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns an empty array when no identification records match the criteria
+
+## Test Cases
+
+- returns all identification records for a partner with multiple identifications
+- returns only TAX_ID records when type filter is provided
+- returns empty array when partner has no identification records
+- returns empty array when partner has no identifications of the requested type
+- includes identifications regardless of validity period

package/src/modules/business-partner/docs/queries/ListPartnersByRole.md

@@ -0,0 +1,47 @@
+# ListPartnersByRole
+
+## Overview
+
+ListPartnersByRole retrieves all business partners that hold a specified role (CUSTOMER or SUPPLIER). This supports downstream filtering where systems consuming partner data (purchasing, sales, accounts payable, accounts receivable) need to list partners by their role classification.
+
+## Business Rules
+
+- Accepts `{ role, status? }` as input where role is CUSTOMER or SUPPLIER
+- Role must be one of CUSTOMER or SUPPLIER; any other value is rejected
+- When `status` is provided, returns only partners with the specified lifecycle status (DRAFT, ACTIVE, or INACTIVE); downstream modules that need partners for new transactions should pass `status = ACTIVE`
+- When `status` is omitted, returns partners regardless of their lifecycle status (DRAFT, ACTIVE, INACTIVE)
+- A partner holding both CUSTOMER and SUPPLIER roles appears in results for either query
+- Returns an empty array when no partners match the criteria — not an error
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Role is CUSTOMER or SUPPLIER?}
+    B -->|No| C[Return error: invalid role]
+    B -->|Yes| D{status filter provided?}
+    D -->|Yes| E[SELECT partners via PartnerRole where role = input.role AND partner.status = input.status]
+    D -->|No| F[SELECT partners via PartnerRole where role = input.role]
+    E --> G{Any partners found?}
+    F --> G
+    G -->|Yes| H[Return partner records]
+    G -->|No| I[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_ROLE**: Provided role is not one of CUSTOMER or SUPPLIER
+
+## Test Cases
+
+- returns all partners with CUSTOMER role
+- returns all partners with SUPPLIER role
+- returns only ACTIVE partners when status filter is ACTIVE
+- returns partners of all statuses when status filter is omitted
+- returns partner in both queries when partner holds both roles
+- returns empty array when no partners match the criteria
+- returns error for invalid role value

package/src/modules/business-partner/generated/enums.ts

@@ -0,0 +1,60 @@
+/**
+ * Partner type: ORGANIZATION or INDIVIDUAL
+ */
+export const BusinessPartnerType = {
+  "ORGANIZATION": "ORGANIZATION",
+  "INDIVIDUAL": "INDIVIDUAL"
+} as const;
+export type BusinessPartnerType = (typeof BusinessPartnerType)[keyof typeof BusinessPartnerType];
+
+/**
+ * Lifecycle status: DRAFT, ACTIVE, INACTIVE
+ */
+export const BusinessPartnerStatus = {
+  "DRAFT": "DRAFT",
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type BusinessPartnerStatus = (typeof BusinessPartnerStatus)[keyof typeof BusinessPartnerStatus];
+
+/**
+ * Contact person status: ACTIVE or INACTIVE
+ */
+export const ContactPersonStatus = {
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type ContactPersonStatus = (typeof ContactPersonStatus)[keyof typeof ContactPersonStatus];
+
+/**
+ * Address purpose: BILLING, SHIPPING, REGISTERED, OTHER
+ */
+export const PartnerAddressAddressType = {
+  "BILLING": "BILLING",
+  "SHIPPING": "SHIPPING",
+  "REGISTERED": "REGISTERED",
+  "OTHER": "OTHER"
+} as const;
+export type PartnerAddressAddressType = (typeof PartnerAddressAddressType)[keyof typeof PartnerAddressAddressType];
+
+/**
+ * Identification type: TAX_ID, VAT, DUNS, COMPANY_REGISTRY, NATIONAL_ID, OTHER
+ */
+export const PartnerIdentificationType = {
+  "TAX_ID": "TAX_ID",
+  "VAT": "VAT",
+  "DUNS": "DUNS",
+  "COMPANY_REGISTRY": "COMPANY_REGISTRY",
+  "NATIONAL_ID": "NATIONAL_ID",
+  "OTHER": "OTHER"
+} as const;
+export type PartnerIdentificationType = (typeof PartnerIdentificationType)[keyof typeof PartnerIdentificationType];
+
+/**
+ * Role classification: CUSTOMER or SUPPLIER
+ */
+export const PartnerRoleRole = {
+  "CUSTOMER": "CUSTOMER",
+  "SUPPLIER": "SUPPLIER"
+} as const;
+export type PartnerRoleRole = (typeof PartnerRoleRole)[keyof typeof PartnerRoleRole];

package/src/modules/business-partner/generated/kysely-tailordb.ts

@@ -0,0 +1,114 @@
+import {
+  createGetDB,
+  type Generated,
+  type Timestamp,
+  type NamespaceDB,
+  type NamespaceInsertable,
+  type NamespaceSelectable,
+  type NamespaceTable,
+  type NamespaceTableName,
+  type NamespaceTransaction,
+  type NamespaceUpdateable,
+} from "@tailor-platform/sdk/kysely";
+
+export interface Namespace {
+  "main-db": {
+    BusinessPartner: {
+      id: Generated<string>;
+      name: string;
+      type: "ORGANIZATION" | "INDIVIDUAL";
+      companyId: string;
+      preferredCurrencyId: string | null;
+      status: "DRAFT" | "ACTIVE" | "INACTIVE";
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    ContactPerson: {
+      id: Generated<string>;
+      partnerId: string;
+      firstName: string;
+      lastName: string;
+      email: string | null;
+      phone: string | null;
+      jobTitle: string | null;
+      department: string | null;
+      isPrimary: boolean;
+      status: "ACTIVE" | "INACTIVE";
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PartnerAddress: {
+      id: Generated<string>;
+      partnerId: string;
+      addressType: "BILLING" | "SHIPPING" | "REGISTERED" | "OTHER";
+      line1: string;
+      line2: string | null;
+      city: string;
+      state: string | null;
+      postalCode: string;
+      country: string;
+      isDefault: boolean;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PartnerBankAccount: {
+      id: Generated<string>;
+      partnerId: string;
+      bankName: string;
+      accountHolderName: string;
+      accountNumber: string | null;
+      routingNumber: string | null;
+      iban: string | null;
+      swiftBic: string | null;
+      currencyId: string;
+      isDefault: boolean;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PartnerIdentification: {
+      id: Generated<string>;
+      partnerId: string;
+      type: "TAX_ID" | "VAT" | "DUNS" | "COMPANY_REGISTRY" | "NATIONAL_ID" | "OTHER";
+      value: string;
+      issuingCountry: string | null;
+      validFrom: Timestamp | null;
+      validTo: Timestamp | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PartnerRole: {
+      id: Generated<string>;
+      partnerId: string;
+      role: "CUSTOMER" | "SUPPLIER";
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Company: {
+      id: Generated<string>;
+    }
+
+    Currency: {
+      id: Generated<string>;
+    }
+  }
+}
+
+export const getDB = createGetDB<Namespace>();
+
+export type DB<N extends keyof Namespace = keyof Namespace> = NamespaceDB<Namespace, N>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  NamespaceTransaction<Namespace, K>;
+
+type TableName = NamespaceTableName<Namespace>;
+export type Table<T extends TableName> = NamespaceTable<Namespace, T>;
+
+export type Insertable<T extends TableName> = NamespaceInsertable<Namespace, T>;
+export type Selectable<T extends TableName> = NamespaceSelectable<Namespace, T>;
+export type Updateable<T extends TableName> = NamespaceUpdateable<Namespace, T>;

package/src/modules/business-partner/index.ts

@@ -0,0 +1,2 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./lib/permissions.generated";

package/src/modules/business-partner/lib/_db_deps.ts

@@ -0,0 +1,17 @@
+// Stub types for cross-module dependencies — used only for codegen.
+// At runtime, actual types are injected via defineModule() params.
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const company = db
+  .type("Company", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const currency = db
+  .type("Currency", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);