@cxtms/cx-schema 1.7.17 → 1.8.0

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

@@ -4,12 +4,13 @@
 - Country
 - State
 - City
+- PostalCode
 - Port
 - Vessel
 - CustomCode
 - ModeOfTransportation
 
-Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation.
+Country, State, City, PostalCode, Port, Vessel, CustomCode, ModeOfTransportation.
 
 ## Country
 
@@ -59,6 +60,29 @@ Composite key: `organizationId` + `countryCode` + `stateCode`.
 
 ---
 
+## PostalCode
+
+PK: `id` (int, auto). Scoped per organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | Postal/zip code value |
+| `countryCode` | `string` | FK to Country |
+| `placeName` | `string` | Place/city name |
+| `stateCode` | `string?` | FK to State |
+| `accuracy` | `AccuracyTypes?` | 1=Region, 2=Municipality, 3=Neighborhood, 4=Place, 5=Street, 6=Centroid |
+| `timeZone` | `string?` | IANA timezone ID (e.g., `America/Chicago`) |
+| `customValues` | `Dictionary` | jsonb |
+| `location` | `Point?` | WGS 84 (SRID 4326). X=longitude, Y=latitude |
+
+**Navigation:** `country`, `state`
+
+**Mutations:** `ChangeCode`, `ChangePlaceName`, `ChangeCoordinates(lat, lng, accuracy)`, `ChangeCountry`/`ChangeCountryCode`, `ChangeState`/`ChangeStateCode`, `ChangeTimeZone`, `ChangeCustomValues`, `ChangeLatitude`, `ChangeLongitude`
+
+---
+
 ## Port
 
 String-based PK (e.g., UN/LOCODE).

package/.claude/skills/cx-core/ref-entity-order-sub.md

@@ -94,6 +94,12 @@ Template/type definition for tracking events.
 | `triggerConditionFields` | `string?` | |
 | `customValues` | `Dictionary` | jsonb |
 
+### GraphQL Resolvers
+
+| Resolver | Arguments | Returns | Description |
+|----------|-----------|---------|-------------|
+| `getContact` | `customValuesKey: String!` | `Contact` | Looks up a Contact by ID stored in `customValues[key]` |
+
 ---
 
 ## LinkedOrder

package/.claude/skills/cx-module/ref-components-display.md

@@ -44,7 +44,11 @@ Full-featured data table with views, filtering, sorting, pagination, and row act
 | `defaultView` | `string` | — | Default view name |
 | `defaultPageSize` | `number` | `20` | Rows per page |
 | `enableRefresh` | `boolean` | — | Auto-refresh |
+| `refreshInterval` | `number` | `30000` | Auto-refresh polling interval (ms) |
 | `enableChangeTracking` | `boolean` | `true` | Track data changes |
+| `highlightNew` | `boolean` | `true` | Highlight newly added rows |
+| `highlightUpdated` | `boolean` | `true` | Highlight rows with updated values |
+| `highlightForRefreshes` | `number` | `1` | Per-row TTL — refresh cycles a highlight persists |
 | `onRowClick` | `action[]` | — | Default row click action |
 | `onDataLoad` | `action[]` | — | Action after data loads |
 | `items` | `any` | — | Static data (instead of query) |

package/.claude/skills/cx-module/ref-components-forms.md

@@ -187,7 +187,7 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `onFocus` | Fires on focus |
 | `onKeyPress` | Fires on keypress (data: `key`, `keyCode`) |
 | `onSelectValue` | Fires on select-async value selection |
-| `onEditClick` | Fires when edit icon clicked (select-async, permission-gated) |
+| `onEditClick` | Fires when edit icon clicked. Supported on text and select-async fields. Passes current form values (with optional `valueFieldName`) to the action context |
 
 ```yaml
 # Text field

package/.claude/skills/cx-workflow/ref-entity.md

@@ -19,6 +19,32 @@
 
 All entity tasks follow the `Namespace/Operation@Version` pattern. Outputs are stored as `ActivityName.StepName.outputKey`.
 
+## PostalCodes
+
+| Task | Description |
+|------|-------------|
+| `PostalCodes/Import@1` | Import postal codes from file URL, stream, or inline data |
+
+### PostalCodes/Import@1
+
+Imports postal codes (CSV, JSON, Excel). Supports upsert via `matchByFields`.
+
+```yaml
+- task: "PostalCodes/Import@1"
+  name: ImportPostalCodes
+  inputs:
+    organizationId: "{{ int inputs.organizationId }}"
+    fileUrl: "{{ inputs.fileUrl }}"
+    matchByFields: ["code", "countryCode"]
+  outputs:
+    - name: importResult
+      mapping: "result?"
+```
+
+**Inputs:** `organizationId` (int, required), `fileUrl` (string?), `fileType` (FileType?), `stream` (Stream?), `postalCodes` (List?), `matchByFields` (string[]?)
+**Outputs:** `result.success`, `result.added`, `result.updated`, `result.errors`, `result.totalProcessed`, `result.hasErrors`
+Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions and returns them in `result.errors`.
+
 ## Generic Entity Change
 
 | Task | Description |

package/.claude/skills/cx-workflow/ref-expressions-ncalc.md

@@ -96,6 +96,7 @@ Functions use two iterator variable names:
 | `formatDate([date], 'dd/MM/yyyy', 'en-US')` | Format date with culture. Accepts DateTime or string |
 | `dateFromUnix([unixTime])` | Unix timestamp (seconds) -> `DateTimeOffset`. Accepts int, long, decimal, string |
 | `dateToUtc([date])` or `dateToUtc([date], 'en-US')` | Convert to UTC. Optional culture for string parsing |
+| `toLocalTime([date], 'America/Chicago')` | Convert UTC datetime to local time in IANA timezone. Returns `null` if date or timezone is invalid |
 
 ### Math Functions (NCalc built-in)
 

package/.claude/skills/cx-workflow/ref-expressions-template.md

@@ -55,6 +55,7 @@ search: "{{ luceneString query }}"        # escape & quote for Lucene
 | `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
 | `toJson` | `string` | `""` if null |
 | `trim` | `string` | null |
+| `toLocalTime` | `DateTime` or `string` | null. Syntax: `{{ toLocalTime path 'TimezoneId' 'format?' }}` |
 
 ### Value Directives (in YAML input mappings)
 

package/.claude/skills/cx-workflow/ref-flow.md

@@ -93,7 +93,7 @@ states:
 
 ### State Rules
 - **name**: Required, must be unique across all states
-- **isInitial**: At most one state can be initial
+- **isInitial**: At most one state can be initial. When an entity has null status, the engine resolves it to the initial state automatically.
 - **isFinal**: Final states cannot be transition sources
 - **parent**: References another state; parent cannot be initial or final; children inherit parent transitions
 

package/.claude/skills/cx-workflow/ref-utilities.md

@@ -28,6 +28,30 @@
 | `Utilities/MoveFile@1` | Move file |
 | `Utilities/ValidateReCaptcha` | Validate reCAPTCHA |
 | `Utilities/ValidateHMAC` | Validate HMAC signatures |
+| `Utilities/ResolveTimezone@1` | Resolve IANA timezone and UTC offset from lat/lng coordinates |
+
+## ResolveTimezone@1
+
+Resolves IANA timezone ID and current UTC offset from geographic coordinates using offline boundary lookup (GeoTimeZone).
+
+```yaml
+- task: "Utilities/ResolveTimezone@1"
+  name: ResolveTimezone
+  inputs:
+    latitude: "{{ postalCode.location.y }}"
+    longitude: "{{ postalCode.location.x }}"
+  outputs:
+    - name: tz
+      mapping: "timezoneId?"
+    - name: offset
+      mapping: "utcOffset?"
+```
+
+**Inputs:** `latitude` (double/string, required), `longitude` (double/string, required)
+**Outputs:** `timezoneId` (string, e.g. `America/Chicago`), `utcOffset` (double, e.g. `-5`)
+Throws `WorkflowRuntimeException` if lat/lng missing or unparseable.
+
+---
 
 ## SetVariable@1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.7.17",
+  "version": "1.8.0",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/schemas/workflows/tasks/transmission.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Transmission Tasks",
+  "description": "Create, update, and delete transmission records linked to orders",
+  "type": "object",
+  "properties": {
+    "task": {
+      "type": "string",
+      "enum": [
+        "Transmission/Create@1",
+        "Transmission/Update@1",
+        "Transmission/Delete@1"
+      ],
+      "description": "Task type identifier"
+    },
+    "name": {
+      "type": "string",
+      "description": "Step name identifier"
+    },
+    "description": {
+      "type": "string",
+      "description": "Step description"
+    },
+    "conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "expression": {
+            "type": "string"
+          }
+        },
+        "required": ["expression"]
+      }
+    },
+    "continueOnError": {
+      "type": "boolean"
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Task inputs — shape depends on task type",
+      "properties": {
+        "organizationId": {
+          "type": ["string", "integer"],
+          "description": "Organization ID (required for all task types)"
+        },
+        "transmissionId": {
+          "type": ["string", "integer"],
+          "description": "Transmission ID (required for Update and Delete)"
+        },
+        "transmission": {
+          "type": "object",
+          "description": "Transmission field values (Create: full object; Update: partial/dynamic)",
+          "properties": {
+            "orderIds": {
+              "type": ["array", "string"],
+              "items": { "type": ["integer", "string"] },
+              "description": "Order IDs to link (required for Create, at least one)"
+            },
+            "channel": {
+              "type": "string",
+              "maxLength": 20,
+              "description": "Communication channel (e.g. EDI, API, EMAIL, WEBHOOK)"
+            },
+            "direction": {
+              "type": ["string", "integer"],
+              "enum": ["Inbound", "Outbound", 0, 1],
+              "description": "Inbound (0) or Outbound (1)"
+            },
+            "messageType": {
+              "type": "string",
+              "maxLength": 50,
+              "description": "Message type identifier (e.g. 204, 990, 214)"
+            },
+            "sender": {
+              "type": "string",
+              "maxLength": 100,
+              "description": "Sender identifier"
+            },
+            "receiver": {
+              "type": "string",
+              "maxLength": 100,
+              "description": "Receiver identifier"
+            },
+            "correlationId": {
+              "type": "string",
+              "format": "uuid",
+              "description": "Correlation ID (auto-generated if omitted on Create)"
+            },
+            "parentId": {
+              "type": ["integer", "string", "null"],
+              "description": "Parent transmission ID for chaining"
+            },
+            "status": {
+              "type": ["string", "integer"],
+              "enum": ["Pending", "InProgress", "Sent", "Received", "Delivered", "Acknowledged", "Rejected", "Error", "RetryScheduled", "Cancelled", "Expired", 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+              "description": "Transmission status"
+            },
+            "endpoint": {
+              "type": "string",
+              "maxLength": 500,
+              "description": "Target endpoint URL"
+            },
+            "protocol": {
+              "type": "string",
+              "maxLength": 20,
+              "description": "Protocol (e.g. HTTPS, SFTP, AS2)"
+            },
+            "httpStatus": {
+              "type": ["integer", "string", "null"],
+              "description": "HTTP response status code"
+            },
+            "byteSize": {
+              "type": ["integer", "string", "null"],
+              "description": "Payload size in bytes"
+            },
+            "retryCount": {
+              "type": ["integer", "string"],
+              "description": "Current retry count (default: 0)"
+            },
+            "maxRetries": {
+              "type": ["integer", "string"],
+              "description": "Maximum retry attempts (default: 3)"
+            },
+            "nextRetryAt": {
+              "type": ["string", "null"],
+              "description": "Scheduled next retry time (ISO 8601)"
+            },
+            "errorCode": {
+              "type": ["string", "null"],
+              "maxLength": 50,
+              "description": "Error code"
+            },
+            "errorMessage": {
+              "type": ["string", "null"],
+              "description": "Error description"
+            },
+            "customValues": {
+              "type": ["object", "string", "null"],
+              "description": "Arbitrary key-value metadata (JSONB)"
+            },
+            "headers": {
+              "type": ["object", "string", "null"],
+              "description": "Message headers (JSONB)"
+            },
+            "payloadRef": {
+              "type": ["string", "null"],
+              "description": "Reference to stored payload (e.g. blob URI)"
+            },
+            "scheduledAt": {
+              "type": ["string", "null"],
+              "description": "Scheduled send time (ISO 8601)"
+            },
+            "startedAt": {
+              "type": ["string", "null"],
+              "description": "Processing start time (ISO 8601)"
+            },
+            "completedAt": {
+              "type": ["string", "null"],
+              "description": "Processing end time (ISO 8601)"
+            },
+            "durationMs": {
+              "type": ["integer", "string", "null"],
+              "description": "Processing duration in milliseconds"
+            }
+          }
+        }
+      },
+      "required": ["organizationId"]
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "mapping": { "type": "string" }
+        },
+        "required": ["name", "mapping"]
+      },
+      "description": "Create outputs: transmission (TransmissionDto). Delete outputs: success (boolean)."
+    }
+  },
+  "required": ["task", "name", "inputs"]
+}