@cxtms/cx-schema 1.9.28 → 1.9.30

package/package.json

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

package/schemas/schema.graphql

@@ -5515,6 +5515,10 @@ type commodity {
   allTagNames: [String!]! @cost(weight: "10")
   "Gets only the tags directly assigned to this commodity"
   directTagNames: [String!]! @cost(weight: "10")
+  lastTrackingEvent(
+    eventDefinitionName: String
+    orderBy: String
+  ): trackingEvent @cost(weight: "10")
 }
 
 type commodityStatus {

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

@@ -119,6 +119,7 @@ Field names as used in workflow expressions: `{{ entity.description }}`, `{{ ent
 | `getRelatedOrder(filter)` | `Order` | First related order |
 | `getCommodityTrackingNumber(idPropertyName)` | `TrackingNumber` | Lookup |
 | `getCommodityAttachments(filter)` | `[Attachment]` | |
+| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
 | `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
 
 ## Container/Child Pattern (Self-Referencing)

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

@@ -108,7 +108,7 @@ These are virtual fields that filter `orderEntities` by type:
 | `getCharge(chargeDescription)` | `Charge` | Single charge by description |
 | `getChargesByChargeType(chargeType)` | `[Charge]` | Charges filtered by type |
 | `getOrderSummary(weightUnit, volumeUnit, dimensionsUnit)` | `OrderSummary` | |
-| `lastTrackingEvent(eventDefinitionName)` | `TrackingEvent` | Most recent |
+| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
 | `businessDays(path: String!)` | `int?` | Business days from the date at `path` to today, using the org's business calendar. `path` is a dot-separated property path on the order (e.g. `"customValues.leg.pickup.scheduledAt"`). Returns `null` if path doesn't resolve or value isn't a parseable date. |
 | `attachmentsSummary` | `OrderAttachmentSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesSummary` | `OrderNoteSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |

package/skills/cxtms-developer/ref-graphql-query.md

@@ -97,6 +97,25 @@ orderBy: "customValues.fieldName"     # Custom field sort
 orderBy: "orderNumber~ToInt32"        # Type conversion during sort
 ```
 
+### `lastTrackingEvent` synthetic sort path (Order / Commodity)
+
+Sort the result list by the winning tracking event of each order or commodity. The "winner" is selected using `COALESCE(EventDate, Created) DESC/ASC, TrackingEventId DESC/ASC` — identical to the DataLoader logic — so SQL-level ordering and per-row resolution are always consistent.
+
+```
+orderBy: "-lastTrackingEvent.eventDate"   # Latest event first (DESC)
+orderBy: "lastTrackingEvent.eventDate"    # Earliest event first (ASC)
+```
+
+Filter to a specific event type using bracket notation before sorting:
+
+```
+orderBy: "-lastTrackingEvent[eventDefinition.eventName:Departed].eventDate"
+```
+
+- The bracket predicate (`[path:value]`) filters the `TrackingEvents` collection before the winner is picked.
+- Only `.eventDate` is supported as the sub-path. The expression resolves to `COALESCE(winner.EventDate, winner.Created)`, so null `EventDate` values fall back to `Created`.
+- Works on both `orders` and `commodities` top-level queries.
+
 ## Pagination
 
 ```graphql