@cxtms/cx-schema 1.7.11 → 1.7.13

package/.claude/skills/cx-core/SKILL.md

@@ -12,6 +12,10 @@ Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx
 
 For CLI authentication, PAT tokens, org management, and publishing: see [ref-cli-auth.md](ref-cli-auth.md)
 
+## GraphQL Querying & Audit History
+
+For running GraphQL queries via CLI, filter syntax (Lucene), pagination, audit change history, and field discovery: see [ref-graphql-query.md](ref-graphql-query.md)
+
 ## Feature File Layout
 
 All modules and workflows are organized under feature directories:

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

@@ -0,0 +1,320 @@
+# 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-module/SKILL.md

@@ -238,6 +238,15 @@ permissions:
     displayName: { en-US: "..." }
     roles: ["Admin", "Manager"]
 
+configurations:                              # Optional: org-level config definitions
+  - configName: "apps.myFeature"             # Unique config key
+    displayName: { en-US: "My Feature Settings" }
+    description: { en-US: "Configure my feature" }
+    component: "ModuleName/ConfigComponent"  # Component that renders the config UI
+    defaultValue:                            # Optional default values
+      enabled: true
+      limit: 100
+
 routes:
   - name: "routeName"
     path: "/module-path"                   # Supports :params

package/.claude/skills/cx-workflow/SKILL.md

@@ -18,7 +18,7 @@ You are a CargoXplorer workflow YAML builder. You generate schema-valid YAML for
 - **Feature folder**: `npx cxtms create workflow <name> --template <template> --feature <feature-name>`
 - **Deploy to server**: `npx cxtms workflow deploy <file.yaml> --org <id>` — creates or updates workflow on the CX server
 - **Undeploy from server**: `npx cxtms workflow undeploy <workflowId> --org <id>` — removes a workflow by UUID
-- **Execute**: `npx cxtms workflow execute <workflowId|file.yaml> --org <id> [--vars '<json>']` — trigger a workflow execution
+- **Execute**: `npx cxtms workflow execute <workflowId|file.yaml> --org <id> [--vars '<json>'] [--file varName=path]` — trigger a workflow execution (--file uploads a local file and passes the URL as a variable)
 - **List logs**: `npx cxtms workflow logs <workflowId|file.yaml> --org <id> [--from YYYY-MM-DD] [--to YYYY-MM-DD]` — list executions with log availability
 - **Download log**: `npx cxtms workflow log <executionId> --org <id> [--json] [--console] [--output <file>]` — download execution log
 - **Publish all**: `npx cxtms publish [--feature <name>] --org <id>` — push all modules and workflows to the server
@@ -380,8 +380,16 @@ npx cxtms workflow execute workflows/my-workflow.yaml
 
 # Pass input variables as JSON
 npx cxtms workflow execute <workflowId> --vars '{"city": "London", "count": 5}'
+
+# Upload a local file and pass its URL as a workflow variable
+npx cxtms workflow execute workflow.yaml --file importFile=/path/to/data.csv
+
+# Combine variables and file uploads
+npx cxtms workflow execute workflow.yaml --vars '{"mode": "preview"}' --file importFile=data.csv --file templateFile=template.xlsx
 ```
 
+`--file varName=path` uploads the local file to the server via presigned URL and sets the resulting URL as the named variable. Can be specified multiple times.
+
 Returns execution result including `executionId`, `isAsync`, `outputs` (for Sync workflows).
 
 ### Execution Logs
@@ -417,6 +425,7 @@ npx cxtms workflow log <executionId> --json --console
 - Text logs show step-by-step execution trace with timestamps
 - Sync workflow executions may not appear in `workflow logs` — they return results inline
 - Use `workflow execute --vars` to test workflows with specific inputs
+- Use `workflow execute --file varName=path` to upload local files for workflows that expect file URL inputs
 
 ---