@cxtms/cx-schema 1.1.0 → 1.1.1

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

@@ -0,0 +1,120 @@
+# Other Tasks Reference
+
+## User & Auth
+
+| Task | Description |
+|------|-------------|
+| `User/Create` | Create user account |
+| `User/Update` | Update user |
+| `User/Delete` | Delete user |
+| `User/GetVerificationCode` | Get phone verification code |
+| `User/GetEmailVerificationCode` | Get email verification code |
+| `User/GetResetPasswordToken` | Get password reset token |
+| `Authentication/OAuth2` | Execute OAuth2 authentication flow |
+
+```yaml
+- task: "Authentication/OAuth2"
+  name: Authenticate
+  inputs:
+    provider: "{{ oauthConfig.provider }}"
+    clientId: "{{ oauthConfig.clientId }}"
+    clientSecret: "{{ oauthConfig.clientSecret }}"
+    tokenUrl: "{{ oauthConfig.tokenUrl }}"
+  outputs:
+    - name: token
+      mapping: "accessToken"
+```
+
+## Caching
+
+| Task | Description |
+|------|-------------|
+| `Caching/SetCache` | Store value in in-memory cache |
+| `Caching/GetCache` | Retrieve value from cache |
+
+```yaml
+- task: "Caching/SetCache@1"
+  name: CacheRate
+  inputs:
+    key: "rate-{{ inputs.carrierId }}"
+    value: "{{ Data.GetRate.rate }}"
+    ttl: 3600
+```
+
+```yaml
+- task: "Caching/GetCache@1"
+  name: GetCachedRate
+  inputs:
+    key: "rate-{{ inputs.carrierId }}"
+  outputs:
+    - name: rate
+      mapping: "value"
+```
+
+## EDI & Structured File Parsing
+
+| Task | Description |
+|------|-------------|
+| `EDI/Parse` | Parse EDI documents (X12, EDIFACT) |
+| `StructuredFile/Parse` | Parse structured files |
+
+```yaml
+- task: "EDI/Parse@1"
+  name: ParseEdi
+  inputs:
+    content: "{{ Transfer.Download.content }}"
+    format: "X12"
+  outputs:
+    - name: parsed
+      mapping: "document"
+```
+
+## Flow
+
+| Task | Description |
+|------|-------------|
+| `Flow/Transition` | Trigger a Flow state transition programmatically |
+
+```yaml
+- task: "Flow/Transition@1"
+  name: TransitionOrder
+  inputs:
+    entityName: "Order"
+    entityId: "{{ inputs.orderId }}"
+    transition: "approve"
+```
+
+## Notes
+
+| Task | Description |
+|------|-------------|
+| `Note/Create` | Create a note |
+| `Note/Update` | Update a note |
+| `Note/Delete` | Delete a note |
+| `NoteThread/Rename` | Rename note thread |
+| `Notes/Import` | Bulk import notes |
+| `Notes/Export` | Bulk export notes |
+
+## App Module
+
+| Task | Description |
+|------|-------------|
+| `AppModule/Create` | Create app module |
+| `AppModule/Update` | Update app module |
+| `AppModule/Delete` | Delete app module |
+
+## Action Events
+
+| Task | Description |
+|------|-------------|
+| `ActionEvent/Create` | Create action event (triggers UI notifications or webhook) |
+
+```yaml
+- task: "ActionEvent/Create"
+  name: NotifyUser
+  inputs:
+    eventName: "OrderStatusChanged"
+    data:
+      orderId: "{{ inputs.orderId }}"
+      newStatus: "{{ Data.GetOrder.order.status }}"
+```

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

@@ -0,0 +1,85 @@
+# Query, Validation & Workflow Tasks Reference
+
+## Query/GraphQL
+
+Executes internal GraphQL queries against the CX backend. The query runs via MediatR to the internal GraphQL engine.
+
+```yaml
+- task: "Query/GraphQL"
+  name: GetOrder
+  inputs:
+    query: |
+      query($organizationId: Int!, $orderId: Int!) {
+        order(organizationId: $organizationId, orderId: $orderId) {
+          orderId
+          orderNumber
+          status
+          customer {
+            contactId
+            name
+          }
+        }
+      }
+    variables:
+      organizationId: "{{ organizationId }}"
+      orderId: "{{ inputs.orderId }}"
+  outputs:
+    - name: order
+      mapping: "order"
+```
+
+The query result is a dictionary. The `mapping` path extracts from the result. Output stored at `ActivityName.GetOrder.order`.
+
+**Notes**:
+- `organizationId` is always available as a system variable
+- Variables support template expressions: `"{{ int organizationId }}"`
+- Multiple queries can be in one step (returns merged results)
+
+## Validation/Validate@1
+
+Validates data against rules. Commonly used in Before entity triggers to block invalid changes.
+
+```yaml
+- task: "Validation/Validate@1"
+  name: ValidateOrder
+  inputs:
+    rules:
+      - field: "status"
+        condition: "[Data.GetOrder.order.status] != 'Cancelled'"
+        message: "Cannot modify cancelled orders"
+      - field: "amount"
+        condition: "[Data.GetOrder.order.amount] > 0"
+        message: "Amount must be positive"
+```
+
+If validation fails, execution stops and error is returned to the caller.
+
+## Workflow/Execute
+
+Executes a child workflow. Can run sync (wait for result) or async (fire and forget).
+
+```yaml
+- task: "Workflow/Execute@1"
+  name: RunChild
+  inputs:
+    workflowId: "<uuid>"
+    workflowInputs:
+      orderId: "{{ inputs.orderId }}"
+      customerId: "{{ Data.GetOrder.order.customer.contactId }}"
+```
+
+The child workflow's outputs are available as step outputs: `ActivityName.RunChild.outputName`.
+
+**Circular call detection**: The executor maintains a call stack and throws if a workflow calls itself recursively.
+
+## Workflow/Create, Workflow/Update, Workflow/Delete
+
+CRUD operations on workflow definitions (not executions). Rarely used in standard workflows.
+
+```yaml
+- task: "Workflow/Create"
+  name: CreateWorkflow
+  inputs:
+    name: "Generated Workflow"
+    document: "{{ workflowYaml }}"
+```

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

@@ -0,0 +1,171 @@
+# Utilities Tasks Reference
+
+## Available Tasks
+
+| Task | Description |
+|------|-------------|
+| `Utilities/SetVariable@1` | Set variables in workflow scope (activity + global) |
+| `Utilities/Log@1` | Log all task variables to workflow logger |
+| `Utilities/Error@1` | Throw a workflow error with message |
+| `Utilities/HttpRequest@1` | HTTP request (GET/POST/PUT/PATCH/DELETE) |
+| `Utilities/Map@1` | Map/extract variables from inputs |
+| `Utilities/Template@1` | Handlebars template rendering |
+| `Utilities/Import@1` | Import data |
+| `Utilities/Export@1` | Export data |
+| `Utilities/CsvParse@1` | Parse CSV content |
+| `Utilities/MoveFile@1` | Move file |
+| `Utilities/ValidateReCaptcha` | Validate reCAPTCHA |
+| `Utilities/ValidateHMAC` | Validate HMAC signatures |
+
+## SetVariable@1
+
+Sets variables directly into both activity and global scope. No outputs — the side effect IS the variable setting.
+
+```yaml
+- task: "Utilities/SetVariable@1"
+  name: SetResult
+  inputs:
+    variables:
+      - name: processResult
+        value:
+          success: true
+          orderId: "{{ inputs.orderId }}"
+      - name: hasMore
+        value:
+          expression: "[offset] < [Data?.FetchPage?.result?.totalCount?]"
+```
+
+Each variable entry has `name` (string) and `value` (any type, supports expression directives).
+
+## Log@1
+
+Logs all task variables (everything in the step's scoped variables) to the workflow file logger.
+
+```yaml
+- task: "Utilities/Log@1"
+  name: LogInfo
+  inputs:
+    message: "Processing order: {{ Data?.GetOrder?.order?.orderNumber? }}"
+    level: Information
+```
+
+Levels: `Debug`, `Information`, `Warning`, `Error`.
+
+## Error@1
+
+Throws a workflow error that halts execution (unless `continueOnError: true` on a parent step).
+
+```yaml
+- task: "Utilities/Error@1"
+  name: ThrowValidationError
+  conditions:
+    - expression: "isNullOrEmpty([Data?.GetOrder?.order?]) = true"
+  inputs:
+    message: "Order not found: {{ inputs.orderId }}"
+```
+
+## HttpRequest@1
+
+Performs HTTP requests to external APIs.
+
+```yaml
+- task: "Utilities/HttpRequest@1"
+  name: CallApi
+  inputs:
+    url: "{{ apiBaseUrl }}/api/v1/orders"
+    method: POST
+    contentType: "application/json"
+    headers:
+      - name: "Authorization"
+        value: "Bearer {{ apiToken }}"
+    body:
+      orderId: "{{ inputs.orderId }}"
+  outputs:
+    - name: result
+      mapping: "response?.body?"
+```
+
+**Response structure**: The task returns a `Dictionary<string, object>` (case-insensitive) with key `response`. The response contains `StatusCode`, `Headers`, and `Body` (PascalCase in C#, but access is case-insensitive). Use `response?.body?` to get the parsed body. You can drill deeper: `response?.body?.output?`, `response?.body?.items?[0]?`.
+
+**Case sensitivity**: Variable paths go through `Dictionary<string, object>(StringComparer.OrdinalIgnoreCase)` — so `body` and `Body` both work. Convention: use lowercase `body`.
+
+Response available at `ActivityName?.CallApi?.result?`.
+
+## Map@1
+
+Extracts/reshapes data from variables into new variables.
+
+```yaml
+- task: "Utilities/Map@1"
+  name: MapData
+  inputs:
+    variables:
+      - name: orderNumber
+        value: "{{ Data?.GetOrder?.order?.orderNumber? }}"
+      - name: customerName
+        value: "{{ Data?.GetOrder?.order?.customer?.name? }}"
+```
+
+## Template@1
+
+Renders a Handlebars template string with data.
+
+```yaml
+- task: "Utilities/Template@1"
+  name: RenderMessage
+  inputs:
+    template: "Hello {{name}}, your order {{orderNumber}} is {{status}}."
+    data:
+      name: "{{ Data?.GetOrder?.order?.customer?.name? }}"
+      orderNumber: "{{ Data?.GetOrder?.order?.orderNumber? }}"
+      status: "{{ Data?.GetOrder?.order?.status? }}"
+  outputs:
+    - name: message
+      mapping: "result?"
+```
+
+## CsvParse@1
+
+Parses CSV content into structured data.
+
+```yaml
+- task: "Utilities/CsvParse@1"
+  name: ParseCsv
+  inputs:
+    content: "{{ Data?.DownloadFile?.fileContent? }}"
+    delimiter: ","
+    hasHeader: true
+  outputs:
+    - name: rows
+      mapping: "rows?"
+```
+
+## Export@1
+
+Exports data to file format.
+
+```yaml
+- task: "Utilities/Export@1"
+  name: ExportData
+  inputs:
+    data: "{{ Data?.GetOrders?.result?.items? }}"
+    format: "csv"
+  outputs:
+    - name: file
+      mapping: "file?"
+```
+
+## Import@1
+
+Imports data from file content.
+
+```yaml
+- task: "Utilities/Import@1"
+  name: ImportData
+  inputs:
+    content: "{{ fileContent }}"
+    format: "csv"
+  outputs:
+    - name: data
+      mapping: "data?"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -31,7 +31,8 @@
     "dist",
     "schemas",
     "scripts",
-    "templates"
+    "templates",
+    ".claude"
   ],
   "dependencies": {
     "ajv": "^8.12.0",