@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-transition-api/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: fluent-transition-api
+description: Query the Fluent Commerce Transition API to discover available user actions for entities at any workflow status. Enables dynamic test sequences and UI action validation. Triggers on "transition api", "user actions", "available actions", "workflow transitions", "what actions".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <entity-type> <subtype> <status> [--retailer-id <id>]
+---
+
+# Transition API — User Action Discovery
+
+Query the Fluent Commerce User Action / Transition API to discover what actions are available for an entity at a given workflow status.
+
+## Ownership Boundary
+
+This skill owns Transition API queries, user action discovery, and action attribute mapping.
+
+Workflow structure is owned by `/fluent-workflow-builder`.
+Event dispatch is owned by `/fluent-mcp-tools`.
+E2E test choreography is owned by `/fluent-e2e-test`.
+
+## When to Use
+
+- Discovering what user actions are available at a specific workflow status
+- Validating that expected UI buttons/actions appear after workflow deployment
+- Building dynamic test sequences that adapt to workflow changes
+- Mapping required event attributes for each user action
+- Auditing module-specific user action visibility
+
+## API Reference
+
+### Endpoint
+
+```
+POST <BASE_URL>/api/v4.1/transition
+Content-Type: application/json
+Authorization: Bearer <token>
+```
+
+### Request Body
+
+```json
+{
+  "triggers": [
+    {
+      "type": "<ENTITY_TYPE>",
+      "subtype": "<ENTITY_SUBTYPE>",
+      "status": "<CURRENT_STATUS>",
+      "retailerId": "<RETAILER_ID>",
+      "module": "<MODULE_FILTER>",
+      "flexType": "<ENTITY_TYPE>::<SUBTYPE>",
+      "flexVersion": <VERSION_NUMBER>
+    }
+  ]
+}
+```
+
+**Parameters:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | No | Entity type (ORDER, FULFILMENT, etc.) |
+| `subtype` | No | Entity subtype (HD, CC, DEFAULT, etc.) |
+| `status` | No | Current entity status. If omitted, returns actions for ALL statuses |
+| `retailerId` | Yes | Retailer ID |
+| `module` | Yes | Module filter (case-sensitive). Examples: `servicepoint`, `adminconsole`, `all` |
+| `flexType` | Yes | Workflow identifier: `<TYPE>::<SUBTYPE>` |
+| `flexVersion` | No | Specific workflow version. If omitted, uses latest |
+
+### Response
+
+```json
+{
+  "response": [
+    {
+      "trigger": {
+        "type": "ORDER",
+        "subtype": "HD",
+        "status": "BOOKED",
+        "module": "adminconsole",
+        "flexType": "ORDER::HD",
+        "retailerId": "2"
+      },
+      "userActions": [
+        {
+          "eventName": "CancelOrder",
+          "context": [
+            {
+              "label": "CANCEL ORDER",
+              "type": "SECONDARY",
+              "modules": ["adminconsole"],
+              "confirm": true
+            }
+          ],
+          "attributes": [
+            {
+              "name": "cancellationReason",
+              "label": "Reason for cancellation",
+              "type": "String",
+              "mandatory": true,
+              "source": "settings.cancellationReasons",
+              "options": ["Customer request", "Out of stock", "Other"]
+            }
+          ]
+        }
+      ],
+      "transitions": [
+        {
+          "eventName": "CancelOrder",
+          "context": [...],
+          "attributes": [...]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Usage Patterns
+
+Shell compatibility:
+- The examples below are Bash-first.
+- On Windows PowerShell, use `Invoke-RestMethod` equivalents (example below).
+- When MCP extension tools are available, prefer `workflow.transitions` for cross-platform execution without manual token scripting.
+
+```powershell
+# PowerShell equivalent for Pattern 1 (auth + transition query)
+$token = (Invoke-RestMethod -Method Post -Uri "$BASE_URL/oauth/token" -ContentType "application/x-www-form-urlencoded" -Body @{
+  username = $FLUENT_USERNAME
+  password = $FLUENT_PASSWORD
+  client_id = $ACCOUNT
+  client_secret = $SECRET
+  grant_type = "password"
+  scope = "api"
+}).access_token
+
+$headers = @{
+  Authorization = "Bearer $token"
+  "Content-Type" = "application/json"
+}
+
+$body = @{
+  triggers = @(
+    @{
+      type = "ORDER"
+      subtype = "HD"
+      status = "BOOKED"
+      retailerId = "2"
+      module = "adminconsole"
+      flexType = "ORDER::HD"
+    }
+  )
+} | ConvertTo-Json -Depth 10
+
+Invoke-RestMethod -Method Post -Uri "$BASE_URL/api/v4.1/transition" -Headers $headers -Body $body
+```
+
+### Pattern 1: Discover Available Actions at a Status
+
+> **Cross-platform note:** The REST API examples below use bash syntax. On Windows, use Git Bash, WSL, or the PowerShell equivalents shown earlier. The MCP `workflow.transitions` tool (shown in the PowerShell section above) is the recommended cross-platform approach.
+
+```bash
+# Authenticate
+# IMPORTANT: Use dedicated variables (FLUENT_USERNAME, FLUENT_PASSWORD) instead of $USER,
+# which collides with the Unix env var that contains the OS login name.
+TOKEN=$(curl -s -X POST "$BASE_URL/oauth/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=$FLUENT_USERNAME&password=$FLUENT_PASSWORD&client_id=$ACCOUNT&client_secret=$SECRET&grant_type=password&scope=api" \
+  | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
+
+# Query transitions for ORDER::HD at BOOKED status
+curl -s -X POST "$BASE_URL/api/v4.1/transition" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{
+    "triggers": [{
+      "type": "ORDER",
+      "subtype": "HD",
+      "status": "BOOKED",
+      "retailerId": "2",
+      "module": "adminconsole",
+      "flexType": "ORDER::HD"
+    }]
+  }' | python -m json.tool
+```
+
+### Pattern 2: Map All Actions Across All Statuses
+
+Query without a `status` to get actions for every status in the workflow:
+
+```bash
+curl -s -X POST "$BASE_URL/api/v4.1/transition" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{
+    "triggers": [{
+      "type": "ORDER",
+      "retailerId": "2",
+      "module": "adminconsole",
+      "flexType": "ORDER::HD"
+    }]
+  }'
+```
+
+### Pattern 3: Validate Specific Module Actions
+
+Filter by module to see only actions visible to a specific UI:
+
+```bash
+# ServicePoint UI actions
+curl -s -X POST "$BASE_URL/api/v4.1/transition" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{
+    "triggers": [{
+      "type": "FULFILMENT",
+      "subtype": "HD_WH",
+      "status": "CREATED",
+      "retailerId": "2",
+      "module": "servicepoint",
+      "flexType": "FULFILMENT::HD_WH"
+    }]
+  }'
+```
+
+### Pattern 4: Dynamic E2E Test Sequence
+
+Use the Transition API to build adaptive test flows:
+
+```
+1. Create entity via graphql.query mutation
+2. Query POST /api/v4.1/transition for current status
+3. For each userAction in response:
+   a. Extract eventName and required attributes
+   b. Send event via event.send with extracted attributes
+   c. Poll entity status until transition completes
+   d. Query transitions again for new status
+4. Repeat until no userActions
+5. If `userActions` is empty, confirm whether status is terminal or system-managed before stopping
+5. Report all transitions taken
+```
+
+This approach is more robust than hardcoded event sequences because:
+- Test adapts automatically when workflow changes
+- Discovers required attributes at runtime
+- Validates that expected UI buttons exist
+- Catches missing or unexpected user actions
+
+### Pattern 5: Empty `userActions` Diagnostic Check
+
+If transition response contains empty `userActions`, use this check:
+
+1. Verify trigger filters are correct (`retailerId`, `flexType`, `subtype`, `module`).
+2. Retry with `module: "all"` to rule out module visibility filtering.
+3. Verify entity is actually in the status used in the trigger.
+4. If still empty and status is non-terminal, treat as system-managed/gated phase and continue with workflow/event-based testing.
+
+## Response Field Reference
+
+### UserAction Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventName` | String | Event to send when this action is invoked — maps to `event.send` name parameter |
+| `context` | Context[] | UI display information (label, type, module visibility) |
+| `attributes` | Attribute[] | Data required from the user when invoking this action |
+
+### Context Fields
+
+| Field | Type | Values | Description |
+|-------|------|--------|-------------|
+| `label` | String | e.g., "CANCEL ORDER" | Button label in UI |
+| `type` | String | `PRIMARY`, `SECONDARY` | Button prominence |
+| `modules` | String[] | e.g., `["adminconsole"]` | Which UIs show this action |
+| `confirm` | Boolean | | Whether to show confirmation dialog |
+| `style` | String | | CSS class hint for button styling |
+
+### Attribute Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Attribute name to attach to the event |
+| `label` | String | UI form label |
+| `type` | String | `String`, `Address`, `OrderItem`, `Product` |
+| `mandatory` | Boolean | Whether this attribute is required |
+| `value` | Object | Locked-in value (if present, don't show form field) |
+| `defaultValue` | Object | Pre-filled default |
+| `source` | String | Settings key for valid values (e.g., `settings.cancellationReasons`) |
+| `options` | Object | Populated from `source` — the valid values list |
+
+## Mapping to MCP Event Dispatch
+
+The Transition API response maps directly to MCP `event.send` calls:
+
+```
+userAction.eventName     → event.send name parameter
+userAction.attributes    → event.send attributes parameter
+trigger.retailerId       → event.send retailerId parameter
+trigger.type + entityRef → event.send entityType + entityRef parameters
+```
+
+**Example:**
+
+Transition API returns:
+```json
+{
+  "eventName": "ConfirmShipment",
+  "attributes": [
+    { "name": "trackingNumber", "type": "String", "mandatory": true },
+    { "name": "carrierRef", "type": "String", "mandatory": true }
+  ]
+}
+```
+
+Maps to:
+```json
+event.send({
+  "name": "ConfirmShipment",
+  "entityRef": "<FULFILMENT_REF>",
+  "entityType": "FULFILMENT",
+  "retailerId": "2",
+  "attributes": {
+    "trackingNumber": "TRACK-001",
+    "carrierRef": "DHL"
+  }
+})
+```
+
+## Integration with Other Skills
+
+| Task | Skill |
+|------|-------|
+| Analyze workflow structure | `/fluent-workflow-analyzer` |
+| Build/edit workflow user actions | `/fluent-workflow-builder` |
+| Send events discovered by transitions | `/fluent-mcp-tools` |
+| Run full E2E test using transitions | `/fluent-e2e-test` |
+| Debug failed transitions | `/fluent-trace` |
+
+## Tips
+
+- **Module names are case-sensitive** — `servicepoint` works, `ServicePoint` does not
+- **Use `all` as module** to get actions across all UI modules
+- **Empty `userActions` array** can mean terminal, system-managed, or filter mismatch (module/flexType/status)
+- **`transitions` and `userActions`** often contain the same data — `userActions` is the canonical field
+- **Locked `value` attributes** mean the workflow pre-sets the value (e.g., cancellation reason locked to "BROKEN") — do not show a form field for these
+- **`flexVersion`** is optional — omit to get actions from the latest workflow version
+- **Multiple triggers** can be sent in one request to batch-query actions for multiple entities/statuses