datex-studio-cli 0.3.1__tar.gz → 0.3.3__tar.gz

{datex_studio_cli-0.3.1 → datex_studio_cli-0.3.3}/.gitignore

@@ -2,6 +2,9 @@ exclude/
 exploration/
 reviews/
 .tap/
+.superpowers/
+
+node_modules/
 
 # Environment
 .env
@@ -73,6 +76,12 @@ docs/_build/
 src/dxs/web/static/
 src/dxs/web/frontend/node_modules/
 src/dxs/web/frontend/.next/
+*.tsbuildinfo
+
+# Report fidelity testing artifacts
+tests/fixtures/reports/diffs/
+tests/fixtures/reports/composites/
+tests/fixtures/reports/scores.jsonl
 
 # Worktrees
 .worktrees/

{datex_studio_cli-0.3.1 → datex_studio_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datex-studio-cli
-Version: 0.3.1
+Version: 0.3.3
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli
@@ -36,11 +36,18 @@ Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
 Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'dev'
+Provides-Extra: fidelity
+Requires-Dist: cairosvg>=2.7.0; extra == 'fidelity'
+Requires-Dist: pillow>=10.0.0; extra == 'fidelity'
+Requires-Dist: scikit-image>=0.20.0; extra == 'fidelity'
 Provides-Extra: preview
 Requires-Dist: pillow>=10.0.0; extra == 'preview'
+Requires-Dist: reportlab>=4.0.0; extra == 'preview'
+Requires-Dist: svglib>=0.9.0; extra == 'preview'
 Provides-Extra: studio
 Requires-Dist: fastapi>=0.115.0; extra == 'studio'
 Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'studio'
+Requires-Dist: watchfiles>=0.20.0; extra == 'studio'
 Description-Content-Type: text/markdown
 
 # Datex Studio CLI (`dxs`)

datex_studio_cli-0.3.3/examples/bill-of-lading/01-schema-exploration.md

@@ -0,0 +1,303 @@
+# Bill of Lading - Schema Exploration Notes
+
+**Connection ID:** 9
+**Branch:** 73658
+**Date:** 2026-03-18
+
+## Search Results Summary
+
+### Keywords searched
+- `shipment` - Found **Shipments**, ShipmentLines, ShipmentOrderLookup, ShipmentStatuses, ShipmentLoadingInstructions, ShipmentRoutings, and others
+- `bill of lading` - No direct match (field lives on Shipment entity as `BillOfLading`)
+- `BOL` - No direct match
+- `outbound` - Found OutboundOrderPriorities, OutboundProcessingStrategies
+- `shipping` - Found ShippingContainers, ShippingManifests, ShippingHubShipments
+- `order` - Found **Orders**, **OrderLines**, **OrderAddresses**, OrderStatuses, OrderTypes, OrderClasses
+- `carrier` - Found **Carriers**, **CarrierServices**, **CarrierServiceTypes**
+- `freight` - Found **FreightClasses**, **FreightTerms**
+- `commodity` - No match (commodity info lives on Material as Description)
+
+## Key Entities
+
+### Shipments (root entity for BOL report)
+- **Entity type:** `Datex.FootPrint.Api.Shipment`
+- **Entity set:** `Shipments`
+- **Key:** `Id` (Int32)
+- **BOL-relevant properties:**
+  - `BillOfLading` (String, max 64) - the BOL number itself
+  - `LookupCode` (String, max 64) - shipment lookup code
+  - `ReferenceNumber` (String, max 128)
+  - `TrackingIdentifier` (String, max 256)
+  - `TrailerId` (String, max 64)
+  - `SealId` (String, max 64)
+  - `Notes` (String)
+  - `GrossWeight` (Decimal)
+  - `NetWeight` (Decimal)
+  - `WeightUomId` (Int32) -> MeasurementUnit
+  - `PalletCount` (Decimal)
+  - `ItemCount` (Decimal)
+  - `CarrierId` (Int32) -> Carrier
+  - `CarrierServiceTypeId` (Int32) -> CarrierServiceType
+  - `FreightTermId` (Int32) -> FreightTerm
+  - `AccountId` (Int32) -> Account (shipper/owner)
+  - `ShipToAccountId` (Int32) -> Account (consignee)
+  - `ContactId` (Int32) -> Contact
+  - `ShipToContactId` (Int32) -> Contact
+  - `ShippedDate` (DateTimeOffset)
+  - `ExpectedDate` (DateTimeOffset)
+  - `DeliveredDate` (DateTimeOffset)
+  - `PickupDate` (DateTimeOffset)
+  - `DateNeeded` (DateTimeOffset)
+  - `DatePromised` (DateTimeOffset)
+  - `StatusId` (Int32) -> ShipmentStatus
+  - `FobLocation` (String, max 256)
+  - `Incoterms` (String, max 50)
+  - `ContainerIdentifier` (String, max 64)
+  - `ContainerSize` (String, max 16)
+  - `BookingNumber` (String, max 50)
+  - `BrokerReference` (String, max 32)
+  - `PackingSlip` (String, max 128)
+  - `ExpectedWarehouseId` (Int32) -> Warehouse
+
+### ShipmentLines (collection - line items on a shipment)
+- **Entity type:** `Datex.FootPrint.Api.ShipmentLine`
+- **Entity set:** `ShipmentLines`
+- **Key:** `Id` (Int32)
+- **Properties:**
+  - `LineNumber` (Int32)
+  - `ShipmentId` (Int32) -> Shipment
+  - `OrderId` (Int32)
+  - `OrderLineNumber` (Int32)
+  - `ExpectedAmount` (Decimal)
+  - `ActualAmount` (Decimal)
+  - `ExpectedPackagedAmount` (Decimal)
+  - `ActualPackagedAmount` (Decimal)
+  - `ExpectedPackagedId` (Int32) -> InventoryMeasurementUnit
+  - `ActualPackagedId` (Int32) -> InventoryMeasurementUnit
+  - `GrossWeight` (Decimal)
+  - `NetWeight` (Decimal)
+  - `GrossVolume` (Decimal)
+  - `NetVolume` (Decimal)
+  - `WeightUomId` (Int32) -> MeasurementUnit
+  - `VolumeUomId` (Int32) -> MeasurementUnit
+  - `StatusId` (Int32) -> ShipmentLineStatus
+- **Navigation properties:**
+  - `OrderLine` -> OrderLine (via OrderId+OrderLineNumber)
+  - `Shipment` -> Shipment
+  - `ExpectedPackaged` -> InventoryMeasurementUnit
+  - `ActualPackaged` -> InventoryMeasurementUnit
+  - `WeightUOM` -> MeasurementUnit
+  - `VolumeUOM` -> MeasurementUnit
+  - `Status` -> ShipmentLineStatus
+
+### Orders
+- **Entity type:** `Datex.FootPrint.Api.Order`
+- **Key:** `Id` (Int32)
+- **BOL-relevant properties:**
+  - `LookupCode` (String, max 128) - order number
+  - `OwnerReference` (String, max 64)
+  - `VendorReference` (String, max 64)
+  - `Notes` (String, max 4000)
+  - `RequestedDeliveryDate` (DateTimeOffset)
+  - `PreferredCarrierId` (Int32) -> Carrier
+  - `PreferredCarrierServiceTypeId` (Int32) -> CarrierServiceType
+  - `ShippingAddressId` (Int32)
+- **Navigation properties:**
+  - `OrderLines` -> OrderLine (many)
+  - `Addresses` -> OrderAddress (many) - contains shipper/consignee addresses
+  - `Account` -> Account
+  - `PreferredCarrier` -> Carrier
+  - `Status` -> OrderStatus
+  - `ShipmentOrderLookups` -> ShipmentOrderLookup (many)
+
+### OrderLines
+- **Entity type:** `Datex.FootPrint.Api.OrderLine`
+- **Key:** `OrderId` (Int32) + `LineNumber` (Int32)
+- **BOL-relevant properties:**
+  - `Amount` (Decimal) - ordered quantity
+  - `PackagedAmount` (Decimal)
+  - `PackagedId` (Int32) -> InventoryMeasurementUnit
+  - `MaterialId` (Int32) -> Material
+  - `MaterialAlias` (String, max 256)
+  - `GrossWeight` (Decimal)
+  - `NetWeight` (Decimal)
+  - `WeightUomId` (Int32) -> MeasurementUnit
+  - `Cost` (Decimal)
+  - `Price` (Decimal)
+  - `Notes` (String)
+  - `PurchaseOrderIdentifier` (String, max 32)
+- **Navigation properties:**
+  - `Material` -> Material
+  - `InventoryMeasurementUnit` -> InventoryMeasurementUnit (packaging)
+  - `MaterialPackagingLookup` -> MaterialsPackagingsLookup
+  - `ShipmentLines` -> ShipmentLine (many)
+  - `Order` -> Order
+  - `WeightUom` -> MeasurementUnit
+
+### OrderAddresses (collection - multiple addresses per order)
+- **Entity type:** `Datex.FootPrint.Api.OrderAddress`
+- **Key:** `Id` (Int32)
+- **Properties:**
+  - `Orderid` (Int32) -> Order
+  - `TypeId` (Int32) -> OrderAddressesType (distinguishes shipper vs consignee)
+  - `Name` (String, max 256)
+  - `AttentionOf` (String, max 64)
+  - `Line1` (String, max 128)
+  - `Line2` (String, max 128)
+  - `Line3` (String, max 128)
+  - `Line4` (String, max 128)
+  - `City` (String, max 64)
+  - `State` (String, max 64)
+  - `PostalCode` (String, max 64)
+  - `Country` (String, max 32)
+  - `PrimaryTelephone` (String, max 50)
+  - `PrimaryEmail` (String, max 128)
+  - `PrimaryFax` (String, max 50)
+  - `FirstName` (String, max 32)
+  - `LastName` (String, max 32)
+  - `ReferenceCode` (String, max 32)
+- **Navigation:**
+  - `Type` -> OrderAddressesType (has Name like "Ship From", "Ship To", etc.)
+  - `Order` -> Order
+
+### OrderAddressesType (lookup for address types)
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 32), `SystemDefined` (Boolean)
+
+### Carriers
+- **Entity type:** `Datex.FootPrint.Api.Carrier`
+- **Key:** `Id` (Int32)
+- **Properties:**
+  - `Name` (String, max 64)
+  - `ShortName` (String, max 16)
+  - `ScacCode` (String, max 4) - SCAC code for BOL
+
+### CarrierServiceTypes
+- **Entity type:** `Datex.FootPrint.Api.CarrierServiceType`
+- **Key:** `Id` (Int32)
+- **Properties:**
+  - `Name` (String, max 64)
+  - `ShortName` (String, max 64)
+
+### FreightTerms
+- **Entity type:** `Datex.FootPrint.Api.FreightTerm`
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 128)
+
+### FreightClasses
+- **Entity type:** `Datex.FootPrint.Api.FreightClass`
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 128), `ShortName` (String, max 32)
+
+### Materials
+- **Entity type:** `Datex.FootPrint.Api.Material`
+- **Key:** `Id` (Int32)
+- **BOL-relevant properties:**
+  - `LookupCode` (String, max 256) - item/SKU code
+  - `Name` (String, max 128) - item name
+  - `Description` (String, max 1024) - commodity description for BOL
+  - `NmfcNumber` (String) - NMFC number
+  - `NmfcSubNumber` (String) - NMFC sub-number
+  - `CommodityCode` (String, UDF) - commodity code
+
+### MaterialsPackagingsLookup (dimensions & freight class per material+packaging)
+- **Entity type:** `Datex.FootPrint.Api.MaterialsPackagingsLookup`
+- **Key:** `MaterialId` + `PackagingId`
+- **BOL-relevant properties:**
+  - `FreightClassId` (Int32) -> FreightClass
+  - `Weight` (Decimal)
+  - `ShippingWeight` (Decimal)
+  - `Height` (Decimal)
+  - `Length` (Decimal)
+  - `Width` (Decimal)
+  - `Volume` (Decimal)
+  - `ShippingVolume` (Decimal)
+  - `TareWeight` (Decimal)
+  - `WeightUomId` (Int32) -> MeasurementUnit
+  - `DimensionUomId` (Int32) -> MeasurementUnit
+  - `VolumeUomId` (Int32) -> MeasurementUnit
+- **Navigation:**
+  - `FreightClass` -> FreightClass
+  - `WeightUom` -> MeasurementUnit
+  - `DimensionsUom` -> MeasurementUnit
+
+### Account (shipper / consignee company)
+- **Entity type:** `Datex.FootPrint.Api.Account`
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 256), `LookupCode` (String, max 128)
+
+### Contact (shipper / consignee contact person)
+- **Entity type:** `Datex.FootPrint.Api.Contact`
+- **Key:** `Id` (Int32)
+- **Properties:**
+  - `FirstName` (String, max 128)
+  - `LastName` (String, max 128)
+  - `PrimaryTelephone` (String, max 50)
+  - `PrimaryEmail` (String, max 128)
+  - `AddressId` (Int32) -> Address
+- **Navigation:** `Address` -> Address
+
+### Address (physical address for contacts)
+- **Entity type:** `Datex.FootPrint.Api.Address`
+- **Key:** `Id` (Int32)
+- **Properties:** `Line1`, `Line2`, `City`, `State`, `PostalCode`, `Country`, `AttentionOf`
+
+### Warehouse
+- **Entity type:** `Datex.FootPrint.Api.Warehouse`
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 128), `AddressId` (Int32)
+
+### MeasurementUnit
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 64), `Short_name` (String, max 16)
+
+### ShipmentStatus
+- **Key:** `Id` (Int32)
+- **Properties:** `Name` (String, max 128)
+
+## Data Model Relationships for BOL
+
+```
+Shipments (root)
+  ├── Carrier -> Carriers (name, SCAC code)
+  ├── CarrierServiceType -> CarrierServiceTypes (service level)
+  ├── FreightTerm -> FreightTerms (prepaid/collect/third-party)
+  ├── Account -> Accounts (shipper company)
+  ├── Contact -> Contacts -> Address (shipper contact + address)
+  ├── ShipToAccount -> Accounts (consignee company)
+  ├── ShipToContact -> Contacts -> Address (consignee contact + address)
+  ├── ExpectedWarehouse -> Warehouses (origin warehouse)
+  ├── Status -> ShipmentStatuses
+  ├── ShipmentLines (collection) ──┐
+  │     ├── OrderLine -> OrderLines │
+  │     │     ├── Material -> Materials (item desc, NMFC)
+  │     │     ├── MaterialPackagingLookup -> MaterialsPackagingsLookup
+  │     │     │     ├── FreightClass -> FreightClasses
+  │     │     │     ├── WeightUom -> MeasurementUnits
+  │     │     │     └── DimensionsUom -> MeasurementUnits
+  │     │     └── Order -> Orders
+  │     │           └── Addresses -> OrderAddresses (shipper/consignee addresses)
+  │     │                 └── Type -> OrderAddressesType
+  │     ├── WeightUOM -> MeasurementUnits
+  │     └── VolumeUOM -> MeasurementUnits
+  └── OrderLookups -> ShipmentOrderLookup (shipment-to-order mapping)
+```
+
+## Important Design Notes
+
+1. **Address sourcing:** BOL addresses come from two potential sources:
+   - **OrderAddresses** (per-order, typed by OrderAddressesType - e.g., "Ship From", "Ship To")
+   - **Contact.Address** (via Shipment.Contact/ShipToContact navigation)
+   - OrderAddresses is more specific to the order; Contact.Address is the master contact address.
+
+2. **Freight class** lives on `MaterialsPackagingsLookup` (not Material or OrderLine directly). Access via `OrderLine.MaterialPackagingLookup.FreightClass.Name`.
+
+3. **NMFC** is on the `Material` entity directly: `Material.NmfcNumber` and `Material.NmfcSubNumber`.
+
+4. **Weight** is available at multiple levels:
+   - Shipment level: `GrossWeight`, `NetWeight` (totals)
+   - ShipmentLine level: `GrossWeight`, `NetWeight`
+   - OrderLine level: `GrossWeight`, `NetWeight`
+   - MaterialsPackagingsLookup: `Weight`, `ShippingWeight`, `TareWeight`
+
+5. **ShipmentLines** is the collection that bridges shipments to order lines. Each ShipmentLine links to one OrderLine, which links to Material.

datex_studio_cli-0.3.3/examples/bill-of-lading/02-field-mapping.md

@@ -0,0 +1,192 @@
+# Bill of Lading - Field Mapping
+
+**Connection ID:** 9
+**Branch:** 73658
+**Root Entity:** `Shipments` (key: `Id`)
+
+## Root-Level Fields (DataSet: Shipments)
+
+These fields come from the Shipment entity and its single-value navigation properties. One row per shipment.
+
+| Report Field | OData Path | Source Entity | Notes |
+|---|---|---|---|
+| **Identifiers** | | | |
+| BOL Number | `BillOfLading` | Shipment | Primary BOL identifier, String(64) |
+| Shipment ID | `LookupCode` | Shipment | Shipment lookup code, String(64) |
+| Reference Number | `ReferenceNumber` | Shipment | String(128) |
+| Tracking Number | `TrackingIdentifier` | Shipment | String(256) |
+| Booking Number | `BookingNumber` | Shipment | String(50) |
+| Packing Slip | `PackingSlip` | Shipment | String(128) |
+| PRO Number | `BrokerReference` | Shipment | String(32), often used as PRO number |
+| **Carrier Info** | | | |
+| Carrier Name | `Carrier.Name` | Carrier | $expand=Carrier, String(64) |
+| Carrier Short Name | `Carrier.ShortName` | Carrier | String(16) |
+| SCAC Code | `Carrier.ScacCode` | Carrier | Standard Carrier Alpha Code, String(4) |
+| Service Type | `CarrierServiceType.Name` | CarrierServiceType | $expand=CarrierServiceType, String(64) |
+| Freight Terms | `FreightTerm.Name` | FreightTerm | $expand=FreightTerm (Prepaid/Collect/etc.), String(128) |
+| Trailer Number | `TrailerId` | Shipment | String(64) |
+| Seal Number | `SealId` | Shipment | String(64) |
+| **Shipper (From)** | | | |
+| Shipper Company | `Account.Name` | Account | $expand=Account, String(256) |
+| Shipper Account Code | `Account.LookupCode` | Account | String(128) |
+| Shipper Contact Name | `Contact.FirstName` / `Contact.LastName` | Contact | $expand=Contact, concatenate first+last |
+| Shipper Phone | `Contact.PrimaryTelephone` | Contact | String(50) |
+| Shipper Email | `Contact.PrimaryEmail` | Contact | String(128) |
+| Shipper Address Line 1 | `Contact.Address.Line1` | Address | $expand=Contact($expand=Address), String(128) |
+| Shipper Address Line 2 | `Contact.Address.Line2` | Address | String(128) |
+| Shipper City | `Contact.Address.City` | Address | String(64) |
+| Shipper State | `Contact.Address.State` | Address | String(64) |
+| Shipper Postal Code | `Contact.Address.PostalCode` | Address | String(64) |
+| Shipper Country | `Contact.Address.Country` | Address | String(32) |
+| **Consignee (To)** | | | |
+| Consignee Company | `ShipToAccount.Name` | Account | $expand=ShipToAccount, String(256) |
+| Consignee Account Code | `ShipToAccount.LookupCode` | Account | String(128) |
+| Consignee Contact Name | `ShipToContact.FirstName` / `ShipToContact.LastName` | Contact | $expand=ShipToContact, concatenate |
+| Consignee Phone | `ShipToContact.PrimaryTelephone` | Contact | String(50) |
+| Consignee Email | `ShipToContact.PrimaryEmail` | Contact | String(128) |
+| Consignee Address Line 1 | `ShipToContact.Address.Line1` | Address | $expand=ShipToContact($expand=Address) |
+| Consignee Address Line 2 | `ShipToContact.Address.Line2` | Address | String(128) |
+| Consignee City | `ShipToContact.Address.City` | Address | String(64) |
+| Consignee State | `ShipToContact.Address.State` | Address | String(64) |
+| Consignee Postal Code | `ShipToContact.Address.PostalCode` | Address | String(64) |
+| Consignee Country | `ShipToContact.Address.Country` | Address | String(32) |
+| **Dates** | | | |
+| Ship Date | `ShippedDate` | Shipment | DateTimeOffset, format as date |
+| Expected Date | `ExpectedDate` | Shipment | DateTimeOffset |
+| Delivery Date | `DeliveredDate` | Shipment | DateTimeOffset |
+| Pickup Date | `PickupDate` | Shipment | DateTimeOffset |
+| Date Needed | `DateNeeded` | Shipment | DateTimeOffset |
+| Date Promised | `DatePromised` | Shipment | DateTimeOffset |
+| **Totals & Misc** | | | |
+| Total Gross Weight | `GrossWeight` | Shipment | Decimal |
+| Total Net Weight | `NetWeight` | Shipment | Decimal |
+| Weight UOM | `WeightUOM.Short_name` | MeasurementUnit | Requires separate lookup via WeightUomId |
+| Pallet Count | `PalletCount` | Shipment | Decimal |
+| Item Count | `ItemCount` | Shipment | Decimal |
+| FOB Location | `FobLocation` | Shipment | String(256) |
+| Incoterms | `Incoterms` | Shipment | String(50) |
+| Container ID | `ContainerIdentifier` | Shipment | String(64) |
+| Container Size | `ContainerSize` | Shipment | String(16) |
+| Shipment Status | `Status.Name` | ShipmentStatus | $expand=Status, String(128) |
+| Special Instructions | `Notes` | Shipment | String (unlimited) |
+| Origin Warehouse | `ExpectedWarehouse.Name` | Warehouse | $expand=ExpectedWarehouse, String(128) |
+
+## Collection Fields - Shipment Lines (DataSet: ShipmentLines)
+
+These fields require a separate DataSet because ShipmentLines is a one-to-many collection. Filter by `ShipmentId`.
+
+| Report Field | OData Path | Source Entity | Notes |
+|---|---|---|---|
+| **Line Identification** | | | |
+| Line Number | `LineNumber` | ShipmentLine | Int32 |
+| Order ID | `OrderId` | ShipmentLine | Int32, FK to Orders |
+| Order Line Number | `OrderLineNumber` | ShipmentLine | Int32 |
+| **Quantities** | | | |
+| Expected Quantity | `ExpectedAmount` | ShipmentLine | Decimal |
+| Actual Quantity | `ActualAmount` | ShipmentLine | Decimal |
+| Expected Pkg Qty | `ExpectedPackagedAmount` | ShipmentLine | Decimal |
+| Actual Pkg Qty | `ActualPackagedAmount` | ShipmentLine | Decimal |
+| **Packaging** | | | |
+| Expected Package | `ExpectedPackaged.Name` | InventoryMeasurementUnit | $expand=ExpectedPackaged |
+| Actual Package | `ActualPackaged.Name` | InventoryMeasurementUnit | $expand=ActualPackaged |
+| **Weights & Volumes** | | | |
+| Line Gross Weight | `GrossWeight` | ShipmentLine | Decimal |
+| Line Net Weight | `NetWeight` | ShipmentLine | Decimal |
+| Line Gross Volume | `GrossVolume` | ShipmentLine | Decimal |
+| Line Net Volume | `NetVolume` | ShipmentLine | Decimal |
+| Weight UOM | `WeightUOM.Short_name` | MeasurementUnit | $expand=WeightUOM |
+| Volume UOM | `VolumeUOM.Short_name` | MeasurementUnit | $expand=VolumeUOM |
+| **Item Details (via OrderLine)** | | | |
+| Item Code | `OrderLine.Material.LookupCode` | Material | $expand=OrderLine($expand=Material) |
+| Item Name | `OrderLine.Material.Name` | Material | String(128) |
+| Commodity Description | `OrderLine.Material.Description` | Material | String(1024), main BOL line description |
+| NMFC Number | `OrderLine.Material.NmfcNumber` | Material | NMFC classification |
+| NMFC Sub-Number | `OrderLine.Material.NmfcSubNumber` | Material | NMFC sub-classification |
+| Material Alias | `OrderLine.MaterialAlias` | OrderLine | String(256) |
+| Ordered Quantity | `OrderLine.Amount` | OrderLine | Decimal |
+| PO Number | `OrderLine.PurchaseOrderIdentifier` | OrderLine | String(32) |
+| Line Notes | `OrderLine.Notes` | OrderLine | String |
+| Order Number | `OrderLine.Order.LookupCode` | Order | $expand=OrderLine($expand=Order) |
+| **Freight Class (via OrderLine -> MaterialPackagingLookup)** | | | |
+| Freight Class | `OrderLine.MaterialPackagingLookup.FreightClass.Name` | FreightClass | Deep expand required |
+| Freight Class Short | `OrderLine.MaterialPackagingLookup.FreightClass.ShortName` | FreightClass | String(32) |
+| Pkg Weight | `OrderLine.MaterialPackagingLookup.Weight` | MaterialsPackagingsLookup | Decimal |
+| Pkg Shipping Weight | `OrderLine.MaterialPackagingLookup.ShippingWeight` | MaterialsPackagingsLookup | Decimal |
+| Pkg Length | `OrderLine.MaterialPackagingLookup.Length` | MaterialsPackagingsLookup | Decimal |
+| Pkg Width | `OrderLine.MaterialPackagingLookup.Width` | MaterialsPackagingsLookup | Decimal |
+| Pkg Height | `OrderLine.MaterialPackagingLookup.Height` | MaterialsPackagingsLookup | Decimal |
+
+## Alternative/Supplemental: Order Addresses (DataSet: OrderAddresses)
+
+OrderAddresses provides per-order address overrides (shipper/consignee). Filter by `Orderid` and `Type.Name` (e.g., "Ship From", "Ship To"). Use this if order-level addresses differ from the Shipment-level Contact addresses.
+
+| Report Field | OData Path | Source Entity | Notes |
+|---|---|---|---|
+| Address Type | `Type.Name` | OrderAddressesType | $expand=Type; filter for "Ship From" or "Ship To" |
+| Company Name | `Name` | OrderAddress | String(256) |
+| Attention Of | `AttentionOf` | OrderAddress | String(64) |
+| Contact First Name | `FirstName` | OrderAddress | String(32) |
+| Contact Last Name | `LastName` | OrderAddress | String(32) |
+| Address Line 1 | `Line1` | OrderAddress | String(128) |
+| Address Line 2 | `Line2` | OrderAddress | String(128) |
+| Address Line 3 | `Line3` | OrderAddress | String(128) |
+| Address Line 4 | `Line4` | OrderAddress | String(128) |
+| City | `City` | OrderAddress | String(64) |
+| State | `State` | OrderAddress | String(64) |
+| Postal Code | `PostalCode` | OrderAddress | String(64) |
+| Country | `Country` | OrderAddress | String(32) |
+| Phone | `PrimaryTelephone` | OrderAddress | String(50) |
+| Email | `PrimaryEmail` | OrderAddress | String(128) |
+| Fax | `PrimaryFax` | OrderAddress | String(50) |
+| Reference Code | `ReferenceCode` | OrderAddress | String(32) |
+
+## OData Query Patterns
+
+### Root dataset (Shipment header)
+```
+Shipments?$filter=Id eq {shipmentId}
+  &$select=BillOfLading,LookupCode,ReferenceNumber,TrackingIdentifier,
+    BookingNumber,PackingSlip,BrokerReference,TrailerId,SealId,
+    ShippedDate,ExpectedDate,DeliveredDate,PickupDate,DateNeeded,DatePromised,
+    GrossWeight,NetWeight,PalletCount,ItemCount,
+    FobLocation,Incoterms,ContainerIdentifier,ContainerSize,Notes
+  &$expand=Carrier($select=Name,ShortName,ScacCode),
+    CarrierServiceType($select=Name),
+    FreightTerm($select=Name),
+    Account($select=Name,LookupCode),
+    ShipToAccount($select=Name,LookupCode),
+    Contact($select=FirstName,LastName,PrimaryTelephone,PrimaryEmail;$expand=Address($select=Line1,Line2,City,State,PostalCode,Country)),
+    ShipToContact($select=FirstName,LastName,PrimaryTelephone,PrimaryEmail;$expand=Address($select=Line1,Line2,City,State,PostalCode,Country)),
+    Status($select=Name),
+    ExpectedWarehouse($select=Name)
+```
+
+### Line items dataset (ShipmentLines)
+```
+ShipmentLines?$filter=ShipmentId eq {shipmentId}
+  &$select=LineNumber,OrderId,OrderLineNumber,
+    ExpectedAmount,ActualAmount,ExpectedPackagedAmount,ActualPackagedAmount,
+    GrossWeight,NetWeight,GrossVolume,NetVolume
+  &$expand=ExpectedPackaged($select=Name,ShortName),
+    ActualPackaged($select=Name,ShortName),
+    WeightUOM($select=Name,Short_name),
+    VolumeUOM($select=Name,Short_name),
+    OrderLine($select=Amount,MaterialAlias,PurchaseOrderIdentifier,Notes;
+      $expand=Material($select=LookupCode,Name,Description,NmfcNumber,NmfcSubNumber),
+        MaterialPackagingLookup($select=Weight,ShippingWeight,Length,Width,Height;
+          $expand=FreightClass($select=Name,ShortName)),
+        Order($select=LookupCode))
+```
+
+### Order addresses dataset (if needed)
+```
+OrderAddresses?$filter=Orderid eq {orderId}
+  &$expand=Type($select=Name)
+```
+
+## Notes
+
+- **Two address strategies:** The Shipment has Contact/ShipToContact (with nested Address) for shipper/consignee. Orders have OrderAddresses (typed by OrderAddressesType). Either can serve as the BOL address source. OrderAddresses has more fields (Line3, Line4) and is more likely to contain order-specific overrides.
+- **Freight class** requires a deep expand path: `ShipmentLine -> OrderLine -> MaterialPackagingLookup -> FreightClass`. This may need to be flattened or pre-joined depending on report engine capabilities.
+- **Weight UOM** on Shipment uses `WeightUomId` but there is no direct nav property named `WeightUOM` on Shipment (unlike ShipmentLine). May need separate lookup or include the UOM Id and resolve in-report.
+- **Multiple orders per shipment:** A shipment can contain lines from multiple orders. The `ShipmentOrderLookup` entity maps this. Line items will have different `OrderId` values.

datex_studio_cli-0.3.3/examples/bill-of-lading/bill-of-lading.data.json

@@ -0,0 +1,105 @@
+{
+    "dataSets": {
+        "ds_shipment": {
+            "data": [
+                {
+                    "BillOfLading": "BOL-2026-00451",
+                    "LookupCode": "SHP-78234",
+                    "ReferenceNumber": "REF-90123",
+                    "BrokerReference": "PRO-445567",
+                    "TrackingIdentifier": "1Z999AA10123456784",
+                    "TrailerId": "TRL-4821",
+                    "SealId": "SEAL-99012",
+                    "ShippedDate": "2026-03-18T08:00:00.0000000",
+                    "DeliveredDate": "2026-03-20T14:00:00.0000000",
+                    "GrossWeight": 12450.50,
+                    "NetWeight": 11200.00,
+                    "PalletCount": 8,
+                    "FobLocation": "Origin",
+                    "Notes": "Dock door 12. Call 30 min before arrival. No weekend deliveries.",
+                    "Carrier_Name": "XPO Logistics",
+                    "Carrier_ScacCode": "XPOL",
+                    "CarrierServiceType_Name": "LTL Standard",
+                    "FreightTerm_Name": "Prepaid",
+                    "Account_Name": "Acme Distribution Inc.",
+                    "Contact_Address_Line1": "1200 Industrial Blvd",
+                    "Contact_Address_Line2": "Suite 400",
+                    "Contact_Address_City": "Dallas",
+                    "Contact_Address_State": "TX",
+                    "Contact_Address_PostalCode": "75201",
+                    "ShipToAccount_Name": "National Retail Corp.",
+                    "ShipToContact_Address_Line1": "8900 Commerce Way",
+                    "ShipToContact_Address_Line2": "",
+                    "ShipToContact_Address_City": "Atlanta",
+                    "ShipToContact_Address_State": "GA",
+                    "ShipToContact_Address_PostalCode": "30301",
+                    "ExpectedWarehouse_Name": "Dallas DC"
+                }
+            ]
+        },
+        "ds_shipment_lines": {
+            "data": [
+                {
+                    "LineNumber": 1,
+                    "ExpectedAmount": 100,
+                    "ActualAmount": 100,
+                    "GrossWeight": 2500.00,
+                    "NetWeight": 2300.00,
+                    "WeightUOM_Short_name": "lbs",
+                    "ExpectedPackaged_Name": "Pallet",
+                    "OrderLine_Material_LookupCode": "SKU-10042",
+                    "OrderLine_Material_Description": "Premium Widget Assembly Kit - Standard",
+                    "OrderLine_Material_NmfcNumber": "86750-3",
+                    "OrderLine_MaterialPackagingLookup_FreightClass_Name": "70",
+                    "OrderLine_Order_LookupCode": "SO-44210",
+                    "OrderLine_PurchaseOrderIdentifier": "PO-78901"
+                },
+                {
+                    "LineNumber": 2,
+                    "ExpectedAmount": 250,
+                    "ActualAmount": 248,
+                    "GrossWeight": 4800.00,
+                    "NetWeight": 4500.00,
+                    "WeightUOM_Short_name": "lbs",
+                    "ExpectedPackaged_Name": "Case",
+                    "OrderLine_Material_LookupCode": "SKU-20085",
+                    "OrderLine_Material_Description": "Industrial Fastener Set - Heavy Duty",
+                    "OrderLine_Material_NmfcNumber": "51200-1",
+                    "OrderLine_MaterialPackagingLookup_FreightClass_Name": "85",
+                    "OrderLine_Order_LookupCode": "SO-44210",
+                    "OrderLine_PurchaseOrderIdentifier": "PO-78901"
+                },
+                {
+                    "LineNumber": 3,
+                    "ExpectedAmount": 50,
+                    "ActualAmount": 50,
+                    "GrossWeight": 3200.00,
+                    "NetWeight": 2900.00,
+                    "WeightUOM_Short_name": "lbs",
+                    "ExpectedPackaged_Name": "Pallet",
+                    "OrderLine_Material_LookupCode": "SKU-30120",
+                    "OrderLine_Material_Description": "Hydraulic Pump Motor - 3HP",
+                    "OrderLine_Material_NmfcNumber": "12340-2",
+                    "OrderLine_MaterialPackagingLookup_FreightClass_Name": "92.5",
+                    "OrderLine_Order_LookupCode": "SO-44215",
+                    "OrderLine_PurchaseOrderIdentifier": "PO-79055"
+                },
+                {
+                    "LineNumber": 4,
+                    "ExpectedAmount": 500,
+                    "ActualAmount": 500,
+                    "GrossWeight": 1950.50,
+                    "NetWeight": 1500.00,
+                    "WeightUOM_Short_name": "lbs",
+                    "ExpectedPackaged_Name": "Box",
+                    "OrderLine_Material_LookupCode": "SKU-40200",
+                    "OrderLine_Material_Description": "Copper Connector Plate - Type B",
+                    "OrderLine_Material_NmfcNumber": "44820-4",
+                    "OrderLine_MaterialPackagingLookup_FreightClass_Name": "65",
+                    "OrderLine_Order_LookupCode": "SO-44215",
+                    "OrderLine_PurchaseOrderIdentifier": ""
+                }
+            ]
+        }
+    }
+}