@cxtms/cx-schema 1.8.1 → 1.8.2

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

@@ -1,7 +1,50 @@
 # Entity CRUD Tasks Reference
 
+## Contents
+- Entity/Change task (generic entity modification in Before triggers)
+- Order tasks (Create, Update, Delete, Get, Copy, Split, Import, etc.)
+- Contact tasks (Create, Update, Delete)
+- ContactAddress tasks (Create, Update, Delete, Import)
+- ContactPaymentMethod tasks (Create, Update, SendChargedAmount, VerifyChargedAmount)
+- Commodity tasks (Create, Update, Split, Repack, Unpack)
+- CommodityTrackingNumber tasks (Create, Update, Delete)
+- Job tasks (Create, Update, Delete, Assign, Unassign)
+- Charge tasks (Create, Update, Delete, DynamicUpdate, Calculate)
+- Discount task (Update)
+- Order sub-entity tasks (OrderCommodity, OrderCharge, OrderDocument, OrderTrackingEvent, OrderEntity)
+- Inventory tasks (InventoryItem Create, Update, Delete)
+- Other entity tasks (Movement, Country, Cities, Rate, TrackingEvent/Import)
+- Note tasks (Create, Update, Delete, Import, Export, RenameThread)
+- AccountingTransaction/ApplyCredit task
+
 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

@@ -0,0 +1,128 @@
+# NCalc Expressions & Functions
+
+## Contents
+- NCalc expression syntax `[variable]` (in conditions and expression directives)
+- Operators (comparison, logical, arithmetic, ternary, membership)
+- Iterator variables (`[each.*]` and `[item.*]`)
+- Collection functions (any, all, count, sum, first, last, distinct, groupBy, join, etc.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, etc.)
+- Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
+- Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
+- Domain functions (convertWeight, convertDimension)
+
+For template expressions `{{ path }}` used in step inputs, see [ref-expressions-template.md](ref-expressions-template.md).
+
+## NCalc Expressions: `[variable]` (in conditions and expression directives)
+
+Used in `conditions[].expression`, `switch` case `when`, and `expression:` value directives. Variables use **square bracket** `[name]` syntax.
+
+```yaml
+conditions:
+  - expression: "[status] = 'Active' AND [amount] > 100"
+  - expression: "isNullOrEmpty([Data.GetOrder.order?]) = false"
+  - expression: "any([changes], [each.key] = 'Status') = true"
+```
+
+**Parameter resolution rules**:
+- Empty strings are converted to `null` (so `""` is treated as no value)
+- Numeric strings are auto-converted to `decimal` when needed (e.g., `[price] > 100` works even if price is the string `"150"`)
+- Dot paths resolve deep: `[Activity.Step.output.nested.field]`
+- Optional suffix `?` prevents errors: `[order.customer?.name?]`
+
+### Operators
+
+| Type | Operators |
+|------|-----------|
+| Comparison | `=`, `!=`, `<>`, `<`, `>`, `<=`, `>=` |
+| Logical | `AND`, `OR`, `NOT` (also `&&`, `\|\|`, `!`) |
+| Arithmetic | `+`, `-`, `*`, `/`, `%` |
+| Ternary | `if(condition, trueVal, falseVal)` |
+| Membership | `in(value, val1, val2, ...)` |
+
+### Iterator Variables
+
+Functions use two iterator variable names:
+- **`[each.*]`** -- used by: `any`, `all`, `sum`, `join` (3-arg)
+- **`[item.*]`** -- used by: `first`, `last`, `groupBy`
+
+### Collection Functions
+
+| Function | Description |
+|----------|-------------|
+| `any([items], [each.prop] = 'val')` | True if any item matches expression. Without expression: checks if collection contains the value |
+| `all([items], [each.prop] > 0)` | True if all items match. Returns `false` for null/empty collections |
+| `count([items])` | Count items in list or JToken. Returns `0` for non-collections |
+| `sum([items], [each.amount])` | Sum values as `decimal`. Optional `[each.*]` accessor. Skips nulls |
+| `first([items])` or `first([items], [item.name])` | First item or evaluate expression on first item. Returns `""` if empty |
+| `last([items])` or `last([items], [item.name])` | Last item or evaluate expression on last item. Returns `""` if empty |
+| `distinct([items])` | Remove duplicates. Uses deep comparison for dictionaries |
+| `reverse([items])` | Reverse collection or string |
+| `contains([source], 'needle')` | String contains, JArray contains, list contains, or dict key/value contains |
+| `removeEmpty([items])` | Remove null and whitespace-only items |
+| `concat([list1], [list2], ...)` | Concatenate multiple collections into flat list. Variadic args. Skips nulls |
+| `groupBy([items], [item.cat])` | Group by one or more key expressions. Returns `[{key, items}]`. Multi-key: keys joined with `\|` |
+| `join([items], [each.name], ',')` | Join collection with `[each.*]` accessor and separator (3-arg) |
+| `join([items], ',')` | Join collection directly with separator (2-arg) |
+| `split([str], ' ')` | Split string by first character of separator. Returns `List<string>` |
+| `elementAt([items], 0)` | Get element at index (zero-based) from list |
+
+### String Functions
+
+| Function | Description |
+|----------|-------------|
+| `isNullOrEmpty([var])` | True if null, empty string, or empty list |
+| `length([var])` | String length or collection count. `0` for null strings and non-collections |
+| `lower([name])` / `upper([code])` | Case conversion. Handles string, JToken, any `.ToString()` |
+| `left([code], 3)` / `right([code], 3)` | Left/right N characters. Returns full string if shorter than N |
+| `substring([str], 0, 5)` | Extract substring starting at position for given length |
+| `replace([str], 'old', 'new')` | String replacement. Returns null if any arg is null |
+| `trim([value])` | Trim whitespace. Returns `""` for null |
+| `format('{0}-{1}', [prefix], [id])` | String.Format style. Variadic args. Returns null if format is null |
+| `base64([value])` / `fromBase64([encoded])` | Base64 encode/decode. Handles string, byte[], JToken |
+| `bool([value])` | Convert to boolean: null->`false`, empty string->`false`, "true"/"false"->parsed, non-zero number->`true`, any object->`true` |
+| `transliterate([value])` | Unicode to ASCII (Unidecode). Returns `""` for null |
+| `transliterateUa([value])` | Ukrainian-specific transliteration. Returns `""` for null |
+| `parseAddress([address])` | Parse address -> `{StreetNumber, StreetName}`. Handles US and EU formats |
+
+### Date Functions
+
+| Function | Description |
+|----------|-------------|
+| `parseDate([str])` | Parse date string to DateTime. Supports common formats (ISO, US, etc.) |
+| `now()` | Current UTC `DateTime` |
+| `now('yyyy-MM-dd', 'en-US')` | Formatted current time as string |
+| `addDays([date], 30)` | Add days (decimal, can be negative). Accepts DateTime, DateTimeOffset, string |
+| `addHours([date], 2)` | Add hours (decimal, can be negative). Same type handling |
+| `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 |
+
+### Business Date Math (in Lucene filter expressions)
+
+The filter engine (`FilterBy`) supports business-aware date math units in Lucene date expressions:
+
+| Unit | Aliases | Description |
+|------|---------|-------------|
+| `BHOUR` | `BHOURS` | Add/subtract business hours (respects weekly schedule + holidays) |
+| `BDAY` | `BDAYS` | Add/subtract business days (skips non-working days) |
+
+**Usage**: These units are used in **Lucene filter strings** (not NCalc expressions). They require an `IBusinessDateMathResolver` and are resolved via the organization's business calendar.
+
+```
+dueDate: [NOW TO NOW+3BDAYS]
+pickupDate: [* TO NOW-8BHOURS]
+```
+
+### Math Functions (NCalc built-in)
+
+`Abs(x)`, `Ceiling(x)`, `Floor(x)`, `Round(x, decimals)`, `Min(x, y)`, `Max(x, y)`, `Pow(x, y)`, `Sqrt(x)`, `Truncate(x)`
+
+Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to double.
+
+### Domain Functions
+
+| Function | Description |
+|----------|-------------|
+| `convertWeight([weight], 'Kg', 'Lb')` | Weight unit conversion. Returns `decimal` rounded to 5 places |
+| `convertDimension([length], 'Cm', 'In')` | Dimension unit conversion. Returns `decimal` rounded to 3 places |

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

@@ -0,0 +1,159 @@
+# Template Expressions & Value Directives
+
+## Contents
+- Template expression syntax `{{ path }}` (in step inputs)
+- Type converters (int, decimal, bool, fromJson, toJson, etc.)
+- Value directives (expression, coalesce, foreach, switch, extends, $raw, $eval, encrypt/decrypt)
+- Property path syntax (dot paths, array indexing, wildcards, filters, projections)
+
+There are **two distinct syntaxes** for referencing variables, used in different contexts. This file covers **template expressions** used in step inputs. For NCalc conditions and functions, see [ref-expressions-ncalc.md](ref-expressions-ncalc.md).
+
+## Template Expressions: `{{ path }}` (in step inputs)
+
+Used in step `inputs` values. Resolves variable paths from scoped variables.
+
+```yaml
+inputs:
+  orderId: "{{ inputs.orderId }}"                    # Simple reference
+  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
+  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
+  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
+```
+
+**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
+
+### Type Converters (prefix in {{ }})
+
+```yaml
+organizationId: "{{ int organizationId }}"
+amount: "{{ decimal totalAmount }}"
+isActive: "{{ bool isActive }}"
+flag: "{{ boolOrFalse someFlag }}"        # null -> false
+flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
+notes: "{{ emptyIfNull notes }}"          # null -> ""
+notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
+config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
+payload: "{{ toJson someObject }}"        # object -> JSON string
+name: "{{ trim value }}"
+search: "{{ luceneString query }}"        # escape & quote for Lucene
+```
+
+| Converter | Returns | Null handling |
+|-----------|---------|---------------|
+| `string` | `string` | null. Reads `Stream` to string if value is Stream |
+| `int` | `int` | Throws on null |
+| `decimal` | `decimal` | Throws on null |
+| `bool` | `bool` | Throws on null |
+| `boolOrFalse` | `bool` | `false` if null |
+| `boolOrTrue` | `bool` | `true` if null |
+| `datetime` | `DateTime` | Throws on null |
+| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
+| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
+| `luceneString` | `string` | null |
+| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
+| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
+| `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)
+
+**`expression`** -- Evaluate NCalc expression as a value:
+```yaml
+amount:
+  expression: "[price] * [quantity]"
+```
+
+**`coalesce`** -- First non-null value from a list:
+```yaml
+displayName:
+  coalesce:
+    - "{{ customer.name? }}"
+    - "{{ customer.email? }}"
+    - "Unknown"
+```
+
+**`foreach`** (value context) -- Transform collections inline:
+```yaml
+commodities:
+  foreach: "sourceCommodities"
+  item: "item"                             # default: "item"
+  conditions: "[item.isActive] = true"     # optional NCalc filter per item
+  continueOnError: false                   # optional, skip errors
+  mapping:                                 # dict -> List<dict>, string -> List<object>
+    name: "{{ item.name }}"
+    quantity: "{{ item.qty }}"
+```
+
+**`switch`** (value context) -- Value-based switch (case-insensitive match):
+```yaml
+perLb:
+  switch: "{{ contact.commissionTier }}"
+  cases:
+    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
+    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
+  default: "0"
+```
+
+**`extends`** -- Extend/merge an existing object or array:
+```yaml
+orderData:
+  extends: "{{ existingOrder }}"           # base object or array
+  defaultIfNull: {}                        # fallback if extends is null
+  mapping:                                 # dict: merge overrides. array: append items
+    status: "Updated"
+    notes: "{{ newNotes }}"
+```
+
+**`resolve`** -- Entity ID lookup by querying a GraphQL collection:
+```yaml
+customerId:
+  resolve:
+    entity: "Contact"                        # Entity type (auto-pluralized for query)
+    filter: "name:{{ customerName }}"         # Lucene filter (template-parsed)
+    field: "contactId"                       # Field to return (default: <entity>Id)
+```
+Results are batched and cached per unique `entity|filter|field` combination by `ResolvePreProcessor` before step execution. Cache misses return `null`. Useful inside `foreach` mappings where many items reference the same entity — only one query per unique filter value.
+
+**`$raw`** -- Prevent template parsing (pass as-is):
+```yaml
+template:
+  $raw: "This {{ won't }} be parsed"
+```
+
+**`$eval`** -- Parse JSON string then evaluate as template:
+```yaml
+dynamicConfig:
+  $eval: "{{ configJsonString }}"
+```
+
+**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
+```yaml
+apiKey:
+  decrypt:
+    encryptedValue: "{{ encryptedApiKey }}"
+    key: "{{ encryptionKey }}"             # optional Base64 AES key
+    initializationVector: "{{ iv }}"       # optional Base64 IV
+```
+
+---
+
+## Property Path Syntax (in collection, mapping, variable paths)
+
+Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `a.b.c` | Dot-separated nested path | `order.customer.name` |
+| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
+| `list[0]` | Array index | `items[0]` |
+| `list[^1]` | Index from end (last item) | `items[^1]` |
+| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
+| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
+| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
+| `list[condition]` | Filter by condition | `items[status=Active]` |
+| `dict['key']` | Dictionary key access | `customValues['myField']` |
+| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
+| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
+| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |

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

@@ -1,5 +1,12 @@
 # Flow Workflow YAML Reference
 
+## Contents
+- Flow top-level structure (workflowType, entity, states, transitions, aggregations)
+- Flow entity section (entity name, type, includes, query)
+- Flow states section (initial, final, parent hierarchy, onEnter/onExit steps)
+- Flow transitions section (manual, auto, event triggers; from/to states; conditions)
+- Flow aggregations section (reusable collection expressions: all, any, sum, count)
+
 Flow workflows are declarative state machines for entity lifecycle management. Use `workflowType: Flow` in the workflow section.
 
 ## Top-Level Structure
@@ -86,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-other.md

@@ -1,5 +1,14 @@
 # Other Tasks Reference
 
+## Contents
+- User & Auth tasks (User CRUD, verification codes, OAuth2 authentication)
+- Caching tasks (SetCache and GetCache for in-memory key-value storage)
+- EDI & Structured File Parsing tasks (EDI/Parse for X12/EDIFACT, StructuredFile/Parse)
+- Flow/Transition task (trigger state machine transitions programmatically)
+- Note tasks (Create, Update, Delete, NoteThread/Rename, bulk Import/Export)
+- AppModule tasks (Create, Update, Delete app modules)
+- ActionEvent/Create task (trigger UI notifications or webhooks)
+
 ## User & Auth
 
 | Task | Description |

package/README.md

@@ -29,19 +29,19 @@ npm install @cxtms/cx-schema
 
 ```bash
 # Initialize a new project
-npx cx-cli init
+npx cxtms init
 
 # Create a new module
-npx cx-cli create module orders
+npx cxtms create module orders
 
 # Create a new workflow
-npx cx-cli create workflow invoice-processor
+npx cxtms create workflow invoice-processor
 
 # Validate files
-npx cx-cli modules/*.yaml workflows/*.yaml
+npx cxtms modules/*.yaml workflows/*.yaml
 
 # Generate validation report
-npx cx-cli report modules/*.yaml --report report.html
+npx cxtms report modules/*.yaml --report report.html
 ```
 
 ## CLI Commands
@@ -51,14 +51,14 @@ npx cx-cli report modules/*.yaml --report report.html
 Validate YAML file(s) against JSON Schema definitions.
 
 ```bash
-cx-cli [files...]
-cx-cli validate [files...]
+cxtms [files...]
+cxtms validate [files...]
 
 # Examples
-cx-cli modules/orders-module.yaml
-cx-cli modules/*.yaml workflows/*.yaml
-cx-cli --verbose modules/orders-module.yaml
-cx-cli --format json modules/orders-module.yaml
+cxtms modules/orders-module.yaml
+cxtms modules/*.yaml workflows/*.yaml
+cxtms --verbose modules/orders-module.yaml
+cxtms --format json modules/orders-module.yaml
 ```
 
 ### init
@@ -66,7 +66,7 @@ cx-cli --format json modules/orders-module.yaml
 Initialize a new CX project with configuration files.
 
 ```bash
-cx-cli init
+cxtms init
 ```
 
 Creates:
@@ -81,11 +81,11 @@ Creates:
 Create a new module or workflow from template.
 
 ```bash
-cx-cli create <type> <name>
+cxtms create <type> <name>
 
 # Examples
-cx-cli create module orders
-cx-cli create workflow invoice-generator
+cxtms create module orders
+cxtms create workflow invoice-generator
 ```
 
 Generated files include:
@@ -98,12 +98,12 @@ Generated files include:
 Generate validation report for multiple files.
 
 ```bash
-cx-cli report [files...] --report <output-file>
+cxtms report [files...] --report <output-file>
 
 # Examples
-cx-cli report modules/*.yaml --report report.html
-cx-cli report workflows/*.yaml --report report.md
-cx-cli report modules/*.yaml workflows/*.yaml --report results.json
+cxtms report modules/*.yaml --report report.html
+cxtms report workflows/*.yaml --report report.md
+cxtms report modules/*.yaml workflows/*.yaml --report results.json
 ```
 
 Report formats (auto-detected from extension):
@@ -116,13 +116,13 @@ Report formats (auto-detected from extension):
 Display the JSON Schema definition for a component or task.
 
 ```bash
-cx-cli schema <name>
+cxtms schema <name>
 
 # Examples
-cx-cli schema form
-cx-cli schema dataGrid
-cx-cli schema workflow
-cx-cli schema foreach
+cxtms schema form
+cxtms schema dataGrid
+cxtms schema workflow
+cxtms schema foreach
 ```
 
 ### example
@@ -130,11 +130,11 @@ cx-cli schema foreach
 Show example YAML for a component or task.
 
 ```bash
-cx-cli example <name>
+cxtms example <name>
 
 # Examples
-cx-cli example form
-cx-cli example workflow
+cxtms example form
+cxtms example workflow
 ```
 
 ### list
@@ -142,9 +142,9 @@ cx-cli example workflow
 List all available schemas for validation.
 
 ```bash
-cx-cli list
-cx-cli list --type module
-cx-cli list --type workflow
+cxtms list
+cxtms list --type module
+cxtms list --type workflow
 ```
 
 ## CLI Options
@@ -298,11 +298,11 @@ Generated workflows include:
 ```yaml
 - name: Validate YAML files
   run: |
-    npx cx-cli --format compact modules/*.yaml workflows/*.yaml
+    npx cxtms --format compact modules/*.yaml workflows/*.yaml
 
 - name: Generate validation report
   run: |
-    npx cx-cli report modules/*.yaml workflows/*.yaml --report validation-report.html
+    npx cxtms report modules/*.yaml workflows/*.yaml --report validation-report.html
 
 - name: Upload report
   uses: actions/upload-artifact@v3
@@ -316,7 +316,7 @@ Generated workflows include:
 ```yaml
 validate:
   script:
-    - npx cx-cli --format json modules/*.yaml > validation-results.json
+    - npx cxtms --format json modules/*.yaml > validation-results.json
   artifacts:
     paths:
       - validation-results.json
@@ -331,7 +331,7 @@ validate:
 staged_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml)$')
 
 if [ -n "$staged_files" ]; then
-  npx cx-cli --format compact $staged_files
+  npx cxtms --format compact $staged_files
   if [ $? -ne 0 ]; then
     echo "Validation failed. Please fix errors before committing."
     exit 1