cxtms 1.9.13

package/skills/cxtms-developer/ref-entity-rate.md

@@ -0,0 +1,182 @@
+# Rate, Pricing & Accounting Lookup Reference
+
+## Contents
+- Rate
+- Lane
+- Discount
+- AccountingItem
+- AccountingAccount
+- PaymentTerm
+
+## Rate
+
+Carrier/vendor rates with tariff rules.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `rateId` | `int` | PK |
+| `organizationId` | `int` | |
+| `rateNumber` | `string?` | |
+| `rateType` | `RateType` enum | StandardClientRate=0, ClientRate=1, CarrierRate=2, CommissionRate=3 |
+| `carrierId` | `int?` | FK to Contact |
+| `clientId` | `int?` | FK to Contact |
+| `currencyId` | `int?` | FK to Currency |
+| `accountingItemId` | `int?` | FK to AccountingItem |
+| `modeOfTransportationId` | `int?` | FK |
+| `commodityTypeId` | `int?` | FK |
+| `effectiveDate` | `DateTime?` | |
+| `expirationDate` | `DateTime?` | |
+| `contractNumber` | `string?` | |
+| `amendmentNumber` | `string?` | |
+| `transitDaysMin` | `int?` | |
+| `transitDaysMax` | `int?` | |
+| `serviceType` | `ServiceType?` enum | PortToDoor=1, DoorToDoor=2, DoorToPort=3, PortToPort=4 |
+| `frequency` | `Frequency?` enum | Daily=1, Weekly=2, Biweekly=3, Monthly=4, Other=5 |
+| `automaticallyCreateCharge` | `bool` | |
+| `isHazardous` | `bool?` | |
+| `notes` | `string?` | |
+| `tariff` | `TariffOptions` | JSON object (see below) |
+| `routeId` | `int?` | FK to Route |
+| `routeLegId` | `int?` | FK to RouteLeg |
+| `customValues` | `Dictionary` | jsonb |
+
+### Port References (on Rate)
+
+| Field | Type |
+|-------|------|
+| `portOfReceiptId` | `string?` → Port |
+| `portOfLoadingId` | `string?` → Port |
+| `portOfUnloadingId` | `string?` → Port |
+| `portOfDeliveryId` | `string?` → Port |
+| `countryOfOriginCode` | `string?` → Country |
+| `countryOfDestinationCode` | `string?` → Country |
+
+### TariffOptions (JSON object)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `baseCharge` | `decimal?` | |
+| `minimum` | `decimal?` | |
+| `maximum` | `decimal?` | |
+| `rateMultiplier` | `decimal?` | |
+| `ratePer` | `decimal?` | |
+| `applyBy` | `ApplyBy?` enum | Pieces, Weight, ChargeableWeight, Volume, Container, Calculated, FlatRate |
+| `unitType` | `Units?` enum | Ft, Vlb, Vkg, M, Lb, Kg |
+| `ratePerType` | `RatePerType?` enum | Unit, Range |
+| `calculatedOf` | `CalculatedOfTypes?` enum | Income, Expense, Profit, IncomeFreight |
+| `percentageOfType` | `PercentageOfType?` enum | Cost, Income, Profit |
+| `minimumChargeableWeight` | `decimal?` | |
+| `minimumWeight` | `decimal?` | |
+| `maximumWeight` | `decimal?` | |
+| `rateData` | `[{rateIndex, rateValue, packageTypeId}]` | |
+
+---
+
+## Lane
+
+Shipping lanes linking origin/destination.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `organizationId` | `int` | |
+| `contactId` | `int` | FK to Contact |
+| `description` | `string?` | |
+| `originPortId` | `string?` | FK to Port |
+| `destinationPortId` | `string?` | FK to Port |
+| `originCityId` | `int?` | FK to City |
+| `destinationCityId` | `int?` | FK to City |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+`contact`, `originPort`, `destinationPort`, `originCity`, `destinationCity`, `modeOfTransportations` (M2M)
+
+---
+
+## Discount
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `discountId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string?` | |
+| `promoCode` | `string?` | |
+| `description` | `string?` | |
+| `type` | `DiscountType` enum | Percentage=1, FixedAmount=2 |
+| `value` | `decimal` | Percentage or fixed amount |
+| `startDate` | `DateTime` | |
+| `endDate` | `DateTime` | |
+| `isActive` | `bool` | |
+| `usageLimit` | `int?` | Max times discount can be used |
+| `usedCount` | `int` | |
+| `activationLimit` | `int?` | |
+| `activationCount` | `int` | |
+| `minimumChargeAmount` | `decimal?` | |
+| `minimumWeight` | `decimal?` | |
+| `minimumWeightUnit` | `WeightUnit?` | Lb, Kg |
+| `accountingItemId` | `int` | FK |
+| `targetContactTags` | `[string]` | Tag-based targeting |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+`carriers` (M2M via ContactDiscount), `transportationModes` (M2M), `destinationCountries` (M2M), `validationWorkflows` (M2M)
+
+---
+
+## AccountingItem
+
+Chart of accounts line items.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `accountingItemId` | `int` | PK |
+| `organizationId` | `int` | |
+| `itemCode` | `string?` | |
+| `description` | `string` | |
+| `itemType` | `ItemType` enum | Other=0, Freight=1, Valuation=2, Tax=3, OtherFreight=4, Inventory=5 |
+| `price` | `decimal?` | |
+| `accountId` | `int` | FK to AccountingAccount |
+| `salesTaxId` | `int?` | FK to SalesTax |
+| `tariff` | `TariffOptions?` | Same JSON as Rate |
+| `isInactive` | `bool` | |
+| `customValues` | `Dictionary` | jsonb |
+
+---
+
+## AccountingAccount
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `accountId` | `int` | PK |
+| `organizationId` | `int` | |
+| `accountName` | `string` | |
+| `accountNumber` | `string?` | |
+| `accountType` | `AccountType` enum | AccountReceivable=1, AccountPayable=2 |
+| `parentAccountId` | `int?` | Self-referencing FK |
+| `isInactive` | `bool` | |
+
+No customValues.
+
+---
+
+## PaymentTerm
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `paymentTermId` | `int` | PK |
+| `organizationId` | `int` | |
+| `description` | `string` | |
+| `netDueDays` | `int` | Days until due |
+| `discountPaidWithinDays` | `int?` | Early payment discount window |
+| `discountPercentage` | `int?` | Early payment discount % |
+| `isInactive` | `bool` | |
+
+No customValues.

package/skills/cxtms-developer/ref-entity-shared.md

@@ -0,0 +1,176 @@
+# Shared Entity Reference
+
+## Contents
+- Tag
+- Attachment
+- Division
+- EquipmentType
+- PackageType
+- NoteThread
+- Note
+
+Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread.
+
+## Tag
+
+Tagging system for orders, commodities, inventory items.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `tagId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `description` | `string?` | |
+| `entityName` | `string` | Discriminator: which entity type this tag belongs to |
+| `isDeleted` | `bool` | Soft delete |
+| `customValues` | `Dictionary` | jsonb |
+
+**Join entities** (all have own `customValues`):
+- `OrderTag` — `orderId` + `tagId` + `customValues`
+- `CommodityTag` — `commodityId` + `tagId` + `customValues`
+- `InventoryItemTag` — `inventoryItemId` + `tagId` + `customValues`
+
+---
+
+## Attachment
+
+File attachments linked to orders, contacts, jobs, etc.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `attachmentId` | `int` | PK |
+| `attachmentGuid` | `Guid?` | |
+| `fileName` | `string` | |
+| `fileUri` | `string` | Storage path |
+| `fileExtension` | `string` | Computed from fileName |
+| `previewUri` | `string?` | |
+| `thumbnailUri` | `string?` | |
+| `description` | `string?` | |
+| `attachmentType` | `AttachmentType` enum | Picture=1, OtherDocument, Avatar, CustomerDocument |
+| `parentId` | `string?` | Polymorphic FK (entity ID as string) |
+| `parentType` | `AttachmentParentType` enum | None=0, Order=1, Contact=2, AccountingTransaction=3, EquipmentType=4, Job=5, Commodity=6 |
+| `status` | `AttachmentStatus` enum | Active=0, PendingUpload=1, UploadFailed=2 |
+| `category` | `AttachmentCategory` enum | General=0, FieldValue=1 |
+| `organizationId` | `int` | |
+| `customValues` | `Dictionary` | jsonb |
+
+### GraphQL Computed
+
+- `isImage`, `isPdf` — computed from extension
+- `presignedFileUri`, `presignedPreviewUri`, `presignedThumbnailUri` — signed URLs
+- `getPresignedUri(expiresInDays, uriType)` — custom resolver
+- `getParentOrder` — resolve parent Order
+
+---
+
+## Division
+
+Organization divisions/branches.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `divisionId` | `int` | PK |
+| `organizationId` | `int` | |
+| `divisionName` | `string` | |
+| `email` | `string?` | |
+| `phoneNumber` | `string?` | |
+| `faxNumber` | `string?` | |
+| `streetAndNumber` | `string?` | |
+| `city` | `string?` | |
+| `stateCode` | `string?` | FK to State |
+| `countryCode` | `string?` | FK to Country |
+| `zipCode` | `string?` | |
+| `portId` | `string?` | FK to Port |
+| `comments` | `string?` | |
+| `parentDivisionId` | `int?` | Self-referencing FK |
+| `assignDivisionToEntities` | `bool` | |
+| `useDivisionInDocumentHeaders` | `bool` | |
+| `airAmsOriginatorCode` | `string?` | |
+
+**Navigation:** `country`, `state`, `port`, `parentDivision`, `nestedDivisions` (children). No customValues.
+
+---
+
+## EquipmentType
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `equipmentTypeId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+
+No customValues. Linked to carriers via `CarrierEquipment` join.
+
+---
+
+## PackageType
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `packageTypeId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `height` | `decimal` | |
+| `length` | `decimal` | |
+| `width` | `decimal` | |
+| `weight` | `decimal` | |
+| `maximumWeight` | `decimal` | |
+| `volume` | `decimal` | |
+| `air` | `bool` | Mode applicability |
+| `ground` | `bool` | |
+| `ocean` | `bool` | |
+| `containerDescriptionCode` | `string?` | FK |
+| `containerTypeCode` | `string?` | FK |
+| `packageCategoryCode` | `string` | FK |
+
+**Navigation:** `packageCategory`, `containerDescription`, `containerType`. No customValues.
+
+---
+
+## NoteThread
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `Guid` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `slug` | `string` | Lowercase identifier |
+| `isDeleted` | `bool` | Soft delete |
+| `metadata` | `Dictionary` | jsonb (non-nullable, defaults to {}) |
+
+**Collections:** `notes` (one-to-many)
+
+## Note
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `Guid` | PK |
+| `threadId` | `Guid` | FK to NoteThread |
+| `threadName` | `string` | Snapshot of thread name |
+| `content` | `Dictionary` | TipTap document format (root type="doc"), max 256KB |
+| `mentions` | `[Dictionary]?` | Mentioned users/entities |
+| `tags` | `[string]` | Max 20 tags, each max 32 chars |
+| `isPinned` | `bool` | |
+| `isDeleted` | `bool` | Soft delete |
+
+**Navigation:** `thread` (NoteThread)
+
+---
+
+## Secret
+
+Encrypted key-value store for sensitive configuration (API keys, tokens, credentials). Encrypted at rest with AES-256; scoped to organizations via qualified naming.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `secretName` | `string` | Qualified name: `org/{organizationId}/{secretName}`. Unique index. Max 500 chars. |
+| `encryptedValue` | `string` | AES-256 encrypted, base64-encoded (random IV prepended) |
+| `createdAt` | `DateTime` | |
+| `updatedAt` | `DateTime` | |
+
+**Table:** `secrets` (snake_case columns)
+**Provider:** `PostgresSecretManager` (default) or `AzureKeyVault` via `SecretManager:Provider` config.
+
+**GraphQL mutations:** `setSecret(organizationId, secretName, secretValue)`, `deleteSecret(organizationId, secretName)`.
+**Org scoping:** Commands validate user org membership; qualified name `org/{orgId}/{name}` is built by the command handler.

package/skills/cxtms-developer/ref-entity-warehouse.md

@@ -0,0 +1,115 @@
+# Warehouse & Inventory Entity Reference
+
+## Contents
+- InventoryItem
+- WarehouseLocation
+- CargoMovement
+
+## InventoryItem
+
+SKU-level inventory tracking.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `inventoryItemId` | `int` | PK |
+| `organizationId` | `int` | |
+| `sku` | `string` | Stock keeping unit |
+| `productName` | `string?` | |
+| `modelNumber` | `string?` | |
+| `description` | `string?` | |
+| `availableQuantity` | `int` | |
+| `backOrderQuantity` | `int` | |
+| `height` | `decimal?` | |
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `weight` | `decimal?` | |
+| `volumePiece` | `decimal?` | |
+| `dimensionsUnit` | `DimensionsUnit` enum | In, Cm, M, Ft |
+| `weightUnit` | `WeightUnit` enum | Lb, Kg |
+| `volumeUnit` | `VolumeUnit` enum | Ft, Vlb, Vkg, M, In, Cm |
+| `useSerialNumbers` | `bool` | |
+| `isInactive` | `bool` | |
+| `customerContactId` | `int?` | FK to Contact |
+| `manufacturerContactId` | `int?` | FK to Contact |
+| `packageTypeId` | `int?` | FK to PackageType |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `customerContact` | `Contact?` |
+| `manufacturerContact` | `Contact?` |
+| `packageType` | `PackageType?` |
+| `commodities` | `[Commodity]` |
+| `inventoryItemTags` | `[InventoryItemTag]` |
+| `allTags` | `[InventoryItemAllTagsView]` |
+
+### GraphQL Computed
+
+- `getContact(idPropertyName)` — resolve contact from customValues
+
+---
+
+## WarehouseLocation
+
+Physical storage zones/locations in warehouse.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `warehouseLocationId` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | Location code |
+| `description` | `string?` | |
+| `locationType` | `LocationType` enum | See below |
+| `height` | `decimal?` | |
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `maximumWeight` | `decimal?` | |
+| `isInactive` | `bool` | |
+| `customerId` | `int?` | FK to Contact |
+| `parentZoneId` | `int?` | FK to WarehouseZone |
+
+### LocationType Enum
+
+Receiving, Storage, Replenishment, Picking, QualityControl, Shipping, Mobile, Other, Packing, Service, PutAway
+
+### Navigation
+
+`customer` (Contact), `parentWarehouseZone` (WarehouseZone), `commodities` ([Commodity]). No customValues.
+
+---
+
+## CargoMovement
+
+**Not a separate entity** — implemented as `Order` with `orderType = CargoMovement` (value 7).
+
+Movement-specific data stored in Order's `customValues`:
+
+| CustomValues Key | Type | Notes |
+|-----------------|------|-------|
+| `movementStatus` | `string` | e.g., "Created" |
+| `movementType` | `string` | |
+| `destinationLocationId` | `string/int` | Warehouse location ID |
+| `destinationLocationDescription` | `string` | |
+| `transportationMode` | `string` | |
+| `finalMileCarrier` | `string` | |
+
+The Order's `trackingNumber` field serves as the pallet number for cargo movements.
+
+```yaml
+# Example: Query cargo movement in workflow
+- task: "Query/GraphQL@1"
+  name: GetMovement
+  inputs:
+    query: >-
+      query($id: Int!, $orgId: Int!) {
+        order(organizationId: $orgId, orderId: $id) {
+          orderId orderNumber trackingNumber orderType
+          customValues
+        }
+      }
+    variables:
+      id: "{{ int inputs.orderId }}"
+      orgId: "{{ int organizationId }}"
+```