@cxtms/cx-schema 1.7.17 → 1.8.1

package/.claude/skills/cx-core/ref-graphql-query.md

@@ -1,320 +0,0 @@
-# GraphQL Query Reference
-
-## CLI Query Command
-
-```bash
-npx cxtms query '<graphql-query>'              # Inline query
-npx cxtms query my-query.graphql               # From file
-npx cxtms query '<query>' --vars '{"key":"v"}' # With variables
-```
-
-Requires active login (`npx cxtms login`). Uses the active organization.
-
-## Query Arguments
-
-All root entity queries follow this pattern:
-
-```graphql
-orders(
-  organizationId: Int!    # Required — active org ID
-  filter: String          # Lucene query syntax (see below)
-  search: String          # Full-text search across key fields
-  orderBy: String         # Comma-separated sort fields
-  take: Int               # Page size (alias: limit)
-  skip: Int               # Offset (alias: offset)
-)
-```
-
-Entity-specific extras:
-- `orders` — `includeDraft: Boolean` (default false)
-
-Available root queries: `orders`, `contacts`, `commodities`, `accountingTransactions`, `jobs`, and others.
-
-## Filter Syntax (Lucene Query)
-
-Filters use **Lucene Query syntax** (not OData, not NCalc).
-
-### Basic field matching
-```
-filter: "orderId:196596"
-filter: "orderType:ParcelShipment"
-filter: "status:Active"
-```
-
-### Wildcards
-```
-filter: "name:*pending*"        # Contains
-filter: "code:ABC*"             # Starts with
-filter: "status:*Active"        # Ends with
-```
-
-### Logical operators
-```
-filter: "countryCode:US AND name:Test"
-filter: "status:Active OR status:Pending"
-filter: "NOT customValues.po:123"
-filter: "orderType:ParcelShipment AND (status:Active OR status:Pending)"
-```
-
-### Nested paths (dot notation)
-```
-filter: "orderEntities.entityType:Consignee"
-filter: "orderEntities.contactId:7128"
-filter: "jobs.orders.orderNumber:16*"
-```
-
-### Range queries
-```
-filter: "lastModified:[\"2026-01-01\" TO \"2026-03-15\"]"
-filter: "lastModified:[\"2026-01-01\" TO *]"    # >= date
-filter: "amount:[100 TO 500]"
-```
-
-### NULL checks
-```
-filter: "customValues.po:NULL"
-```
-
-### CustomValues (JSONB fields)
-```
-filter: "customValues.fieldName:value"
-filter: "customValues.fieldName:\"exact match\""
-filter: "customValues.fieldName:NULL"
-```
-
-### Filtered collections (bracket notation)
-```
-filter: "children[category:CatA].name:test"
-```
-
-## OrderBy Syntax
-
-```
-orderBy: "orderNumber"                # Ascending
-orderBy: "-orderNumber"               # Descending
-orderBy: "-created,orderNumber"       # Multi-field
-orderBy: "customValues.fieldName"     # Custom field sort
-orderBy: "orderNumber~ToInt32"        # Type conversion during sort
-```
-
-## Pagination
-
-```graphql
-{
-  orders(organizationId: 1, take: 50, skip: 0) {
-    items { orderId orderNumber }
-    totalCount
-    pageInfo { hasNextPage hasPreviousPage }
-  }
-}
-```
-
-## Audit Change History
-
-### Entity-level: `changeHistory` computed field
-
-Available on: **Order**, **Contact**, **Commodity**, **AccountingTransaction**
-
-```graphql
-{
-  orders(organizationId: 1, filter: "orderId:196596", take: 1) {
-    items {
-      orderId
-      changeHistory(maxResults: 20) {
-        entityName
-        hasMoreRecords
-        continuationToken
-        changes {
-          state         # "Added" | "Modified" | "Deleted"
-          userId
-          timestamp
-          user {
-            fullName
-            email
-          }
-          changedFields {
-            fieldName
-            originalValue
-            currentValue
-            fieldType
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-Arguments: `startDate: DateTime`, `endDate: DateTime`, `maxResults: Int` (default 10)
-
-### Root-level: `auditChanges` query
-
-Query audit changes directly without fetching the entity first:
-
-```graphql
-{
-  auditChanges(
-    organizationId: 1
-    filter: "entityName:Order AND primaryKey:196596"
-    take: 20
-  ) {
-    items {
-      state
-      userId
-      timestamp
-      user { fullName email }
-      changedFields {
-        fieldName
-        originalValue
-        currentValue
-        fieldType
-      }
-    }
-  }
-}
-```
-
-Arguments: `organizationId: Int!`, `filter: String`, `search: String`, `take: Int`, `skip: Int`, `orderBy: String`
-
-Filter fields: `entityName`, `primaryKey`, `userId`, `state`
-
-### Root-level: `auditChangeSummaries` query
-
-High-level summary of changes (grouped by change event):
-
-```graphql
-{
-  auditChangeSummaries(
-    organizationId: 1
-    startDate: "2026-03-01T00:00:00Z"
-    endDate: "2026-03-15T23:59:59Z"
-    maxResults: 50
-  ) {
-    items {
-      changeId
-      userId
-      timestamp
-      changePaths
-      organizationId
-    }
-    continuationToken
-    hasMoreRecords
-  }
-}
-```
-
-### Root-level: `auditChange` — single change detail
-
-```graphql
-{
-  auditChange(filePath: "<s3-file-path>") {
-    entityName
-    state
-    primaryKey
-    userId
-    timestamp
-    originalValues
-    currentValues
-    fields {
-      fieldName
-      originalValue
-      currentValue
-      fieldType
-    }
-  }
-}
-```
-
-## GraphQL Type Reference
-
-### EntityAuditHistoryLightResult
-| Field | Type |
-|-------|------|
-| `entityName` | `String` |
-| `primaryKey` | `String` |
-| `organizationId` | `Int` |
-| `changes` | `[AuditChangeEntry!]!` |
-| `continuationToken` | `String` |
-| `hasMoreRecords` | `Boolean!` |
-
-### AuditChangeEntry
-| Field | Type | Notes |
-|-------|------|-------|
-| `state` | `String` | "Added", "Modified", "Deleted" |
-| `userId` | `String` | |
-| `timestamp` | `DateTime!` | |
-| `user` | `AuditUser` | Lazy-loaded resolver |
-| `changedFields` | `[AuditChangeField!]!` | Lazy-loaded resolver |
-
-### AuditChangeField
-| Field | Type |
-|-------|------|
-| `fieldName` | `String!` |
-| `originalValue` | `Any` |
-| `currentValue` | `Any` |
-| `fieldType` | `String!` |
-
-### AuditUser
-| Field | Type |
-|-------|------|
-| `id` | `String` |
-| `firstName` | `String` |
-| `lastName` | `String` |
-| `fullName` | `String` |
-| `userName` | `String` |
-| `email` | `String` |
-
-## Discovering Fields
-
-**Always discover field names before building a query.** Do not guess field names — use the tools below.
-
-### CLI: `cxtms gql` — schema exploration commands
-
-```bash
-# List all query root fields (what you can query)
-npx cxtms gql queries
-npx cxtms gql queries --filter order
-
-# List all mutation root fields
-npx cxtms gql mutations
-npx cxtms gql mutations --filter order
-
-# List all types (filter by name)
-npx cxtms gql types --filter audit
-npx cxtms gql types --filter order
-
-# Inspect a specific type — shows fields, arguments, input fields, enum values
-npx cxtms gql type OrderGqlDto
-npx cxtms gql type AuditChangeEntry
-npx cxtms gql type EntityAuditHistoryLightResult
-npx cxtms gql type CreateOrderInput
-```
-
-### TMS MCP: `graphql_schema` / `graphql_type` — equivalent MCP tools
-
-When TMS MCP is available, the same discovery is available via MCP tools:
-
-```
-graphql_schema(section: "queries", filter: "order")
-graphql_schema(section: "types", filter: "audit")
-graphql_type(typeName: "OrderGqlDto")
-graphql_execute(query: "{ orders(organizationId: 1, take: 1) { items { orderId } } }")
-```
-
-### Workflow: discover → query
-
-1. **Find the type** — `cxtms gql types --filter order` to find type names
-2. **Inspect the type** — `cxtms gql type OrderGqlDto` to see all fields and their types
-3. **Check query args** — `cxtms gql queries --filter order` to see arguments
-4. **Build and run** — `cxtms query '<graphql-query>'`
-
-### Fallback: error-driven discovery
-
-GraphQL error messages reveal valid field/type names:
-- "The field `foo` does not exist on the type `BarType`" — tells you the type name
-- "The argument `bar` does not exist" — tells you valid argument patterns
-
-### Other sources
-
-- `npx cxtms schema <name>` — shows workflow/module JSON schema fields (not GraphQL)
-- Entity reference files (`ref-entity-*.md`) — document common fields, computed properties, and enums

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

@@ -1,111 +0,0 @@
-# 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 |
-
-### 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

@@ -1,148 +0,0 @@
-# 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 |
-
-### 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 }}"
-```
-
-**`$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}` |