@cxtms/cx-schema 1.0.0 → 1.1.1

package/.claude/skills/cx-core/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: cx-core
+description: Shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns
+argument-hint: <entity name or question about fields>
+---
+
+Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx-module` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
+
+## Entity Field Reference
+
+### Primary Entities
+
+!cat .claude/skills/cx-core/ref-entity-order.md
+!cat .claude/skills/cx-core/ref-entity-contact.md
+!cat .claude/skills/cx-core/ref-entity-commodity.md
+!cat .claude/skills/cx-core/ref-entity-accounting.md
+
+### Order Sub-Entities & Related
+
+!cat .claude/skills/cx-core/ref-entity-order-sub.md
+!cat .claude/skills/cx-core/ref-entity-job.md
+
+### Pricing & Accounting Lookups
+
+!cat .claude/skills/cx-core/ref-entity-rate.md
+
+### Shared & Lookup Entities
+
+!cat .claude/skills/cx-core/ref-entity-shared.md
+!cat .claude/skills/cx-core/ref-entity-geography.md
+
+### Warehouse & Inventory
+
+!cat .claude/skills/cx-core/ref-entity-warehouse.md
+
+| Category | Entities | Reference |
+|----------|----------|-----------|
+| **Primary** | Order, Contact, Commodity, AccountingTransaction | ref-entity-order/contact/commodity/accounting.md |
+| **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | ref-entity-order-sub.md |
+| **Job** | Job, JobOrder, JobStatus | ref-entity-job.md |
+| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | ref-entity-rate.md |
+| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | ref-entity-shared.md |
+| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | ref-entity-geography.md |
+| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | ref-entity-warehouse.md |
+
+## CustomValues Pattern
+
+Most entities have `customValues` — a `Dictionary<string, object?>` stored as PostgreSQL `jsonb`:
+
+- **Access (workflow)**: `{{ entity.customValues.fieldName }}` or `{{ entity.customValues['field-name'] }}`
+- **Access (module)**: `customValues.fieldName` in GraphQL sort/filter paths
+- **Update (workflow)**: `CustomValues.fieldName: "value"` (dot notation) or `customValues: { field: "value" }` (bulk merge)
+- **Merge semantics**: upserts keys — does **not** replace entire dictionary
+- **Full-text searchable**: included in PostgreSQL `tsvector` via `jsonb_to_tsvector`
+- **GraphQL sort/filter**: use `CustomValues.fieldName` path — translates to `jsonb_extract_path_text`
+
+### Entities with customValues
+
+**Primary entities**: Order, Contact, Commodity, AccountingTransaction, Charge, Payment
+
+**Sub-entities**: OrderEntity, OrderCommodity, ContactAddress, ContactPaymentMethod, CommodityType, CommodityTag, OrderTag, LinkedOrder, InventoryItemTag
+
+**Lookup entities**: Job, JobStatus, Tag, Attachment, EventDefinition, Rate, Lane, Discount, AccountingItem, Port, Country, State, City, ModeOfTransportation
+
+**Without customValues**: Division, EquipmentType, PackageType, Vessel, CustomCode, AccountingAccount, PaymentTerm, WarehouseLocation, JobOrder
+
+### Audit Fields (AuditableEntity)
+
+Most entities inherit these fields:
+
+| Field | Type |
+|-------|------|
+| `created` | `DateTime` |
+| `createdBy` | `string` (user ID) |
+| `lastModified` | `DateTime` |
+| `lastModifiedBy` | `string` (user ID) |
+| `createdUser` | `User` navigation |
+| `updatedUser` | `User` navigation |
+
+### Entity Kind Mapping
+
+Used in module `entityKind` and Flow workflow `entity.name`:
+
+| EntityKind | Entities |
+|------------|----------|
+| `Order` | Order (all types: Brokerage, ParcelShipment, Quote, WarehouseReceipt, etc.) |
+| `Contact` | Contact (all types: Customer, Carrier, Vendor, Driver, Employee, etc.) |
+| `OrderEntity` | OrderEntity (Shipper, Consignee, Carrier roles on an order) |
+| `AccountingTransaction` | Invoice, Bill, CreditMemo |
+| `Commodity` | Commodity |
+| `Calendar` | CalendarEntity |
+| `CalendarEvent` | CalendarEvent |
+| `Other` | Any custom entity |

package/.claude/skills/cx-core/ref-entity-accounting.md

@@ -0,0 +1,173 @@
+# Accounting Transaction Entity Field Reference
+
+Field names as used in workflow expressions: `{{ entity.transactionNumber }}`, `{{ entity.customValues.myField }}`.
+
+## AccountingTransaction Fields
+
+### Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `accountingTransactionId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `divisionId` | `int` | Division scope |
+| `transactionNumber` | `string` | Business-facing number |
+| `transactionDate` | `DateTime` | Date of transaction |
+| `dueDate` | `DateTime` | Payment due date |
+| `paidDate` | `DateTime?` | When fully paid |
+| `accountingTransactionType` | `AccountingTransactionType` enum | Invoice, Bill, CreditMemo |
+| `accountingTransactionStatus` | `AccountingTransactionStatus` enum | Open, Paid, Void |
+| `amountDue` | `decimal` | Charges total minus payments |
+| `amountPaid` | `decimal` | Sum of applied payments |
+| `paidAs` | `PaidAs` enum | Prepaid, Collect |
+| `isDraft` | `bool` | Not yet submitted |
+| `note` | `string?` | |
+| `accountId` | `int?` | FK to AccountingAccount |
+| `applyToContactID` | `int?` | FK to Contact (customer/vendor) |
+| `billToContactAddressId` | `int?` | FK to ContactAddress |
+| `paymentTermsId` | `int?` | FK to PaymentTerm |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+### Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `applyToContact` | `Contact` | Customer or vendor |
+| `billToContactAddress` | `ContactAddress` | Billing address |
+| `division` | `Division` | |
+| `organization` | `Organization` | |
+| `paymentTerm` | `PaymentTerm` | |
+| `account` | `AccountingAccount` | |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+### Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `charges` | `[Charge]` | Via AccountingTransactionCharges join |
+| `payments` | `[Payment]` | Via AccountingTransactionPayment join |
+| `jobs` | `[Job]` | Via JobAccountingTransaction join |
+
+### Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `getChargesTotalAmount` | `decimal` | Sum of non-void charges |
+| `getAmountDue` | `decimal` | Charges total minus amountPaid |
+| `getRelatedOrders(filter, orderBy)` | `[Order]` | Orders linked via charges |
+| `getRelatedOrdersByOrderType(orderType)` | `[Order]` | Filtered by order type |
+| `getRelatedOrderByOrderType(orderType)` | `Order` | First match |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+---
+
+## Charge Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `chargeId` | `int` | Primary key |
+| `organizationId` | `int?` | |
+| `description` | `string?` | |
+| `chargeType` | `ChargeType` enum | Income, Expense, Credit |
+| `chargeStatus` | `ChargeStatus` enum | Pending, Open, Posted, Paid, Void |
+| `amount` | `decimal` | Calculated: `quantity * price` |
+| `price` | `decimal` | Unit price |
+| `quantity` | `decimal` | |
+| `unit` | `string?` | e.g., "TV", "Pallet", "Kg" |
+| `applyBy` | `ApplyBy` enum | Pieces, Weight, ChargeableWeight, Volume, Container, Calculated, FlatRate |
+| `applyToContactId` | `int` | FK to Contact (who pays) |
+| `paidAs` | `PaidAs` enum | Prepaid, Collect |
+| `currencyId` | `int` | FK to Currency |
+| `accountingItemId` | `int` | FK to AccountingItem |
+| `salesTaxId` | `int?` | FK to SalesTax |
+| `salesTaxRate` | `decimal` | |
+| `salesTaxAmount` | `decimal` | Computed: `salesTaxRate * amount` |
+| `totalAmount` | `decimal` | Computed: `amount + salesTaxAmount` |
+| `showInDocuments` | `bool` | |
+| `isConsolidated` | `bool` | |
+| `allowAutomaticUpdate` | `bool` | |
+| `note` | `string?` | |
+| `rateId` | `int?` | FK to Rate |
+| `customValues` | `Dictionary` | Own customValues |
+
+**Navigation:** `applyToContact`, `currency`, `accountingItem`, `salesTax`, `rate`, `orders` (many-to-many)
+
+---
+
+## Payment Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `paymentId` | `int` | Primary key |
+| `organizationId` | `int` | |
+| `divisionId` | `int` | |
+| `applyToContactId` | `int` | FK to Contact |
+| `amountReceived` | `decimal` | Total payment amount |
+| `currencyId` | `int` | FK to Currency |
+| `paymentDate` | `DateTime` | |
+| `checkNumber` | `string` | |
+| `memo` | `string` | |
+| `accountingAccountId` | `int` | FK to AccountingAccount |
+| `paymentStatus` | `PaymentStatus` enum | Posted=1, Void=2 |
+| `customValues` | `Dictionary` | Own customValues |
+
+**Navigation:** `applyToContact`, `currency`, `accountingAccount`, `division`, `organization`, `accountingTransactions` (many-to-many)
+
+**Join entity `AccountingTransactionPayment`** has `amountApplied` field — the amount from this payment applied to a specific transaction.
+
+---
+
+## Enums
+
+### AccountingTransactionType
+| Value | Int | Description |
+|-------|-----|-------------|
+| `Invoice` | 0 | Revenue — billed to customer |
+| `Bill` | 1 | Expense — owed to vendor |
+| `CreditMemo` | 2 | Credit adjustment |
+
+### AccountingTransactionStatus
+`Open=0`, `Paid=1`, `Void=2`
+
+### ChargeType
+`Income`, `Expense`, `Credit`
+
+### ChargeStatus
+`Pending`, `Open`, `Posted`, `Paid`, `Void`
+
+### ApplyBy
+`Pieces`, `Weight`, `ChargeableWeight`, `Volume`, `Container`, `Calculated`, `FlatRate`
+
+### PaymentStatus
+`Posted=1`, `Void=2`
+
+### PaidAs
+`Prepaid=0`, `Collect=1`
+
+---
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Present on:
+- `AccountingTransaction.customValues`
+- `Charge.customValues`
+- `Payment.customValues`
+
+```yaml
+# Access in workflow expressions
+invoiceNumber: "{{ entity.transactionNumber }}"
+customerName: "{{ entity.applyToContact.name }}"
+customField: "{{ entity.customValues.myField }}"
+
+# Charge access via collection
+chargeAmount: "{{ entity.charges[0].amount }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.accountingTransactionStatus] = 'Open'"
+  - expression: "[entity.amountDue] > 0"
+```

package/.claude/skills/cx-core/ref-entity-commodity.md

@@ -0,0 +1,205 @@
+# Commodity Entity Field Reference
+
+Field names as used in workflow expressions: `{{ entity.description }}`, `{{ entity.customValues.myField }}`.
+
+## Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `description` | `string` | Required |
+| `pieces` | `int` | Number of pieces |
+| `quantity` | `int?` | Inner quantity per piece |
+| `unit` | `string?` | Unit of measure (e.g., "TV", "Pallet", "Kg") |
+| `note` | `string?` | |
+| `serialNumber` | `string?` | Domain only (not in GraphQL) |
+| `isDeleted` | `bool?` | Soft delete |
+
+### Weight Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `weight` | `decimal?` | Per piece (or total if `weightByTotal`) |
+| `weightTotal` | `decimal?` | Calculated: `weight * pieces` |
+| `weightUnit` | `WeightUnit` enum | Lb, Kg |
+| `weightByTotal` | `bool` | When true, weight = sum of children |
+
+### Dimension Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `height` | `decimal?` | |
+| `dimensionsUnit` | `DimensionsUnit` enum | In, Cm, M, Ft |
+
+### Volume Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `volumePiece` | `decimal?` | Calculated: `L * W * H` converted to volumeUnit |
+| `volumeTotal` | `decimal?` | Calculated: `pieces * volumePiece` |
+| `volumeUnit` | `VolumeUnit` enum | Ft, Vlb, Vkg, M, In, Cm |
+
+### Value Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `unitaryValue` | `decimal?` | Value per unit |
+| `unitaryValueTotal` | `decimal?` | Calculated: `unitaryValue * quantity * pieces` |
+| `valueByTotal` | `bool` | When true, value = sum of children |
+
+### Foreign Keys
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityStatusId` | `int?` | FK to CommodityStatus |
+| `commodityTypeId` | `int?` | FK to CommodityType |
+| `packageTypeId` | `int?` | FK to PackageType |
+| `warehouseLocationId` | `int?` | FK — cascades to children |
+| `containerCommodityId` | `int?` | FK self-ref (parent commodity) |
+| `jobId` | `Guid?` | FK to Job |
+| `inventoryItemId` | `int?` | FK to InventoryItem |
+| `billToContactId` | `int?` | FK to Contact |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+## Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityStatus` | `CommodityStatus` | `.statusName`, `.statusStage` |
+| `commodityType` | `CommodityType` | `.code`, `.description` |
+| `packageType` | `PackageType` | `.name` |
+| `warehouseLocation` | `WarehouseLocation` | |
+| `containerCommodity` | `Commodity` | Parent commodity |
+| `job` | `Job` | |
+| `inventoryItem` | `InventoryItem` | |
+| `billToContact` | `Contact` | |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+## Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `containerCommodities` | `[Commodity]` | Child commodities in this container |
+| `orderCommodities` | `[OrderCommodity]` | Join to orders (has own `customValues`) |
+| `commodityTrackingNumbers` | `[CommodityTrackingNumber]` | Tracking numbers |
+| `commodityTags` | `[CommodityTag]` | Tags (has own `customValues`) |
+| `allTags` | `[CommodityAllTagsView]` | View: includes inherited tags |
+| `trackingEvents` | `[TrackingEvent]` | |
+| `shipments` | `[Order]` | Related orders (GraphQL) |
+
+## Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `totalAmount` | `decimal` | Computed: `unitaryValue * quantity` |
+| `packageTypeName` | `string` | From packageType.name |
+| `trackingNumbers` | `[TrackingNumber]` | From commodityTrackingNumbers |
+| `getChildCommodities(filter)` | `[Commodity]` | Child commodities |
+| `getParentCommodity` | `Commodity` | Parent commodity |
+| `getRelatedOrders(filter)` | `[Order]` | Related orders |
+| `getRelatedOrder(filter)` | `Order` | First related order |
+| `getCommodityTrackingNumber(idPropertyName)` | `TrackingNumber` | Lookup |
+| `getCommodityAttachments(filter)` | `[Attachment]` | |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+## Container/Child Pattern (Self-Referencing)
+
+Commodities form a tree via `containerCommodityId`:
+
+```
+Container Commodity (parent)
+  ├── Child Commodity 1
+  ├── Child Commodity 2
+  └── Child Commodity 3
+```
+
+- Parent → children: `containerCommodities` collection
+- Child → parent: `containerCommodity` navigation
+- When `weightByTotal=true`, weight is computed as sum of children
+- Changing warehouse location on parent cascades to children
+- Changing commodity status on parent cascades to children
+- Deleting parent cascades to children
+
+## CommodityTrackingNumber Sub-Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityTrackingNumberId` | `int` | PK |
+| `trackingNumber` | `string` | |
+| `trackingNumberType` | `string?` | BOL, PRO, PO, etc. |
+| `isPrimary` | `bool` | |
+| `syncOrderId` | `int?` | |
+
+## OrderCommodity Join Entity
+
+Links commodities to orders with per-association metadata:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityId` | `int` | |
+| `orderId` | `int` | |
+| `customValues` | `Dictionary` | **Own** customValues, separate from Commodity |
+| `commodity` | `Commodity` | Navigation |
+| `order` | `Order` | Navigation |
+
+## Enums
+
+### WeightUnit
+`Lb`, `Kg`
+
+### DimensionsUnit
+`In`, `Cm`, `M`, `Ft`
+
+### VolumeUnit
+| Value | Description |
+|-------|-------------|
+| `Ft` | Cubic feet |
+| `Vlb` | Volumetric lbs |
+| `Vkg` | Volumetric kg |
+| `M` | Cubic meters |
+| `In` | Cubic inches |
+| `Cm` | Cubic cm |
+
+### CommodityStatusStage
+`Pending=1`, `InProgress`, `Completed`
+
+### CommodityStatus (enum, distinct from entity)
+`Pending`, `OnRoute`, `Delivered`, `Cancelled`, `InQuote`, `OnHand`, `OnPacking`, `InTransit`
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:
+
+```yaml
+# Template expressions
+value: "{{ entity.description }}"
+value: "{{ entity.customValues.myField }}"
+value: "{{ entity.containerCommodity.description }}"
+
+# Access weight with unit conversion
+weight: "{{ entity.weight }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.pieces] > 0 AND isNullOrEmpty([entity.customValues.lotNumber?]) = false"
+
+# Update via Commodity/Update task
+inputs:
+  commodityId: "{{ entity.commodityId }}"
+  commodity:
+    CustomValues.lotNumber: "LOT-001"
+    CustomValues.hazmat: true
+```
+
+**Entities with own customValues:**
+- `Commodity.customValues` — commodity-level fields
+- `OrderCommodity.customValues` — per-order-per-commodity fields
+- `CommodityType.customValues` — type-level fields
+- `CommodityTag.customValues` — tag-level fields

package/.claude/skills/cx-core/ref-entity-contact.md

@@ -0,0 +1,153 @@
+# Contact Entity Field Reference
+
+Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.customValues.myField }}`.
+
+## Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `name` | `string` | Required. Company/display name |
+| `contactFirstName` | `string?` | |
+| `contactLastName` | `string?` | |
+| `contactType` | `ContactType` enum | See enum below |
+| `accountNumber` | `string?` | |
+| `emailAddress` | `string?` | |
+| `phoneNumber` | `string?` | |
+| `mobilePhoneNumber` | `string?` | |
+| `faxNumber` | `string?` | |
+| `website` | `string?` | |
+| `idNumber` | `string?` | EIN, DUNS, etc. |
+| `idNumberType` | `IDNumberType?` enum | EIN, DUNS, ForeignEntityId, Other |
+| `divisionId` | `int` | Primary division FK |
+| `paymentTermId` | `int?` | FK to PaymentTerm |
+| `creditLimit` | `decimal?` | |
+| `paidAs` | `PaidAs?` enum | Prepaid, Collect |
+| `isACorporation` | `bool?` | |
+| `isDeleted` | `bool` | Soft delete flag |
+| `contactStatusId` | `int?` | FK to ContactStatus |
+| `entityTypeId` | `int?` | FK to EntityType |
+| `parentContactId` | `int?` | Self-referencing FK |
+| `tags` | `[string]` | String array |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+## Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `division` | `Division` | Primary division |
+| `paymentTerm` | `PaymentTerm` | |
+| `contactStatus` | `ContactStatus` | `.statusName`, `.statusStage` (Active/Inactive) |
+| `entityType` | `EntityType` | |
+| `parentContact` | `Contact` | Self-referencing parent |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+## Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactAddresses` | `[ContactAddress]` | Addresses with types (Billing, Shipping, Other) |
+| `contacts` | `[Contact]` | Linked contacts (TO this contact) |
+| `linksToContacts` | `[Contact]` | Contacts this one links TO |
+| `contactLinks` | `[ContactLink]` | Link details (type: ParentContact, FactoringCompany, SalesPerson) |
+| `equipmentTypes` | `[EquipmentType]` | Carrier only |
+| `discounts` | `[Discount]` | Via ContactDiscount join |
+| `rates` | `[Rate]` | Carrier rates |
+| `additionalDivisions` | `[Division]` | Beyond primary division |
+| `orders` | `[Order]` | Via OrderCarrier |
+
+## Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `getContactAddressByType(addressType)` | `[ContactAddress]` | Filter by "Billing", "Shipping", "Other" |
+| `getFirstContactAddressByType(addressType)` | `ContactAddress` | First match |
+| `getContactAttachments(filter, orderBy)` | `[Attachment]` | |
+| `getCustomValuesAttachment(filter)` | `Attachment` | From customValues `attachmentId` key |
+| `availableCredit` | `[AvailableCreditByCurrency]` | Carrier/Customer only |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+## ContactType Enum
+
+| Value | Int | Notes |
+|-------|-----|-------|
+| `Customer` | 1 | Can have accounting |
+| `Carrier` | 2 | Can have accounting, equipment types |
+| `Vendor` | 3 | |
+| `Contact` | 4 | Generic, must have linked contact |
+| `Driver` | 5 | |
+| `Employee` | 6 | Can have user account |
+| `SalesPerson` | 7 | |
+| `ForwardingAgent` | 8 | |
+| `FactoringCompany` | 9 | |
+| `Lead` | 10 | |
+| `PoolPoint` | 11 | |
+| `DistributionCenter` | 12 | |
+| `Store` | 13 | |
+| `ContactUser` | 14 | User associated with contact |
+| `USPPI` | 15 | US Principal Party in Interest |
+
+## ContactAddress Sub-Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactAddressId` | `int` | PK |
+| `addressLine` | `string?` | |
+| `addressLine2` | `string?` | |
+| `addressType` | `AddressType` enum | Billing=1, Shipping=2, Other=3 |
+| `cityName` | `string?` | |
+| `countryCode` | `string?` | FK to Country |
+| `stateCode` | `string?` | FK to State |
+| `postalCode` | `string?` | |
+| `isInactive` | `bool?` | |
+| `latitude` | `double?` | From Location.Y (GraphQL resolved) |
+| `longitude` | `double?` | From Location.X (GraphQL resolved) |
+| `customValues` | `Dictionary` | Own customValues (separate from Contact) |
+| `country` | `Country` | Navigation |
+| `state` | `State` | Navigation |
+
+GraphQL resolver: `formattedAddress(outputFormat, addressFormat, lang, multiline)` — formatted string.
+
+## Other Related Enums
+
+| Enum | Values |
+|------|--------|
+| `IDNumberType` | EIN, DUNS, ForeignEntityId, Other |
+| `PaidAs` | Prepaid, Collect |
+| `AddressType` | Billing=1, Shipping=2, Other=3 |
+| `ContactLinkType` | ParentContact=1, FactoringCompany, SalesPerson, ContactAddressLink |
+| `ContactStatusStage` | Active=0, Inactive=1 |
+| `PaymentType` | Card=1, AccountCredit=2, Cash=3, Check=4, BankTransfer=5, Other=7 |
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:
+
+```yaml
+# Template expressions
+value: "{{ entity.name }}"
+value: "{{ entity.customValues.myField }}"
+
+# Access contact address
+address: "{{ entity.contactAddresses[0].addressLine }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.contactType] = 'Customer'"
+
+# Update via Contact/Update task
+inputs:
+  contactId: "{{ entity.contactId }}"
+  contact:
+    CustomValues.myField: "newValue"
+```
+
+**Entities with own customValues:**
+- `Contact.customValues` — contact-level custom fields
+- `ContactAddress.customValues` — address-level custom fields
+- `ContactPaymentMethod.customValues` — payment method custom fields