cli-jaw 0.1.0

package/skills_ref/whatsapp/assets/workflow-interactive-buttons-decide-function.json

@@ -0,0 +1,88 @@
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 120 },
+      "data": {
+        "node_type": "start",
+        "config": {}
+      }
+    },
+    {
+      "id": "send_interactive_1710000300000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 320 },
+      "data": {
+        "node_type": "send_interactive",
+        "config": {
+          "interactive_type": "button",
+          "body_text": "How can we help you today?",
+          "buttons": [
+            { "id": "sales", "title": "Sales" },
+            { "id": "support", "title": "Support" }
+          ]
+        }
+      }
+    },
+    {
+      "id": "wait_for_response_1710000304000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 520 },
+      "data": {
+        "node_type": "wait_for_response",
+        "config": {
+          "save_response_to": "button_choice"
+        }
+      }
+    },
+    {
+      "id": "decide_1710000308000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 720 },
+      "data": {
+        "node_type": "decide",
+        "config": {
+          "decision_type": "function",
+          "function_id": "FUNCTION_ID_HERE",
+          "conditions": [
+            { "label": "sales", "description": "User selected Sales" },
+            { "label": "support", "description": "User selected Support" }
+          ]
+        }
+      }
+    },
+    {
+      "id": "send_text_1710000312000",
+      "type": "flow-node",
+      "position": { "x": 0, "y": 920 },
+      "data": {
+        "node_type": "send_text",
+        "config": {
+          "message": "Got it - connecting you to Sales.",
+          "delay_seconds": 0
+        }
+      }
+    },
+    {
+      "id": "send_text_1710000316000",
+      "type": "flow-node",
+      "position": { "x": 240, "y": 920 },
+      "data": {
+        "node_type": "send_text",
+        "config": {
+          "message": "Got it - connecting you to Support.",
+          "delay_seconds": 0
+        }
+      }
+    }
+  ],
+  "edges": [
+    { "source": "start", "target": "send_interactive_1710000300000", "label": "next" },
+    { "source": "send_interactive_1710000300000", "target": "wait_for_response_1710000304000", "label": "next" },
+    { "source": "wait_for_response_1710000304000", "target": "decide_1710000308000", "label": "next" },
+    { "source": "decide_1710000308000", "target": "send_text_1710000312000", "label": "sales" },
+    { "source": "decide_1710000308000", "target": "send_text_1710000316000", "label": "support" }
+  ]
+}
+

package/skills_ref/whatsapp/assets/workflow-linear.json

@@ -0,0 +1,53 @@
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 120 },
+      "data": {
+        "node_type": "start",
+        "config": {}
+      }
+    },
+    {
+      "id": "send_text_1710000000000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 320 },
+      "data": {
+        "node_type": "send_text",
+        "config": {
+          "message": "Hello! What's your name?",
+          "delay_seconds": 0
+        }
+      }
+    },
+    {
+      "id": "wait_for_response_1710000005000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 520 },
+      "data": {
+        "node_type": "wait_for_response",
+        "config": {
+          "save_response_to": "user_name"
+        }
+      }
+    },
+    {
+      "id": "send_text_1710000009000",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 720 },
+      "data": {
+        "node_type": "send_text",
+        "config": {
+          "message": "Nice to meet you, {{vars.user_name}}!",
+          "delay_seconds": 0
+        }
+      }
+    }
+  ],
+  "edges": [
+    { "source": "start", "target": "send_text_1710000000000", "label": "next" },
+    { "source": "send_text_1710000000000", "target": "wait_for_response_1710000005000", "label": "next" },
+    { "source": "wait_for_response_1710000005000", "target": "send_text_1710000009000", "label": "next" }
+  ]
+}

package/skills_ref/whatsapp/package.json

@@ -0,0 +1,10 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "scripts": {
+    "openapi": "node scripts/openapi-explore.mjs"
+  }
+}

package/skills_ref/whatsapp/references/app-integrations.md

@@ -0,0 +1,89 @@
+# App Integrations (Workflow Nodes and Agent Tools)
+
+Use these when you need to call external apps (Slack, HubSpot, Sheets, etc).
+
+## Step 1: Accounts
+
+1. List connected accounts:
+   - `scripts/list-accounts.js --app-slug <slug>`
+   - Use `accounts[].pipedream_account_id` for any `--account-id` flag.
+2. If no account exists, generate a connect link:
+   - `scripts/create-connect-token.js --app-slug <slug>`
+3. Ask the user to open the connect URL and finish OAuth, then re-run list-accounts.
+
+## Action discovery notes
+
+- `action_id` is the same as the action `key` returned by `search-actions`.
+- Prefer one-word queries (ex: `calendar`, `slack`, `hubspot`) and then filter by `app_slug`.
+- If a multi-word query returns nothing, retry with a single token.
+
+## Inputs and variable_definitions (required for agent tools)
+
+App integration tools only accept inputs defined by `variable_definitions`. These inputs are mapped into
+`configured_props` using `{{placeholders}}`.
+
+Rules:
+- Every placeholder in `configured_props` becomes a required tool input.
+- If `variable_definitions` is omitted, Kapso infers variable names from `{{placeholders}}`
+  and treats them as `string`.
+- Agent tool calls must pass an `input` object with these variables.
+
+Example configured props:
+```json
+{
+  "calendarId": "{{calendar_id}}",
+  "timeMin": "{{time_min}}",
+  "timeMax": "{{time_max}}"
+}
+```
+
+Example variable definitions:
+```json
+{
+  "calendar_id": "string",
+  "time_min": "string",
+  "time_max": "string"
+}
+```
+
+Create integration with explicit variable definitions:
+```bash
+node scripts/create-integration.js \
+  --action-id "google_calendar-query-free-busy-calendars" \
+  --app-slug "google_calendar" \
+  --account-id "<pipedream_account_id>" \
+  --configured-props '{"calendarId":"{{calendar_id}}","timeMin":"{{time_min}}","timeMax":"{{time_max}}"}' \
+  --variable-definitions '{"calendar_id":"string","time_min":"string","time_max":"string"}'
+```
+
+Example asset: `assets/agent-app-integration-example.json`
+
+## Step 2: Choose integration path
+
+### Option A: Pipedream node (workflow graph)
+
+1. Search actions: `scripts/search-actions.js --query "slack" --app-slug slack`
+2. Get schema: `scripts/get-action-schema.js --action-id <id>`
+3. For remote options: `scripts/configure-prop.js --action-id <id> --prop-name <name> --account-id <pipedream_account_id>`
+4. For dynamic props: `scripts/reload-props.js --action-id <id> --account-id <pipedream_account_id>`
+5. Add a `pipedream` node to the graph with action_id, app_slug, account_id, configured_props.
+
+### Option B: Agent app integration tool (preferred for agent nodes)
+
+1. List existing integrations: `scripts/list-integrations.js`
+2. If none, create one:
+   - `scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <pipedream_account_id> --configured-props <json>`
+3. Use the integration id in `flow_agent_app_integration_tools` on the agent node.
+
+### Option C: Integration via webhook
+
+Use only when calling from a webhook node or agent webhook tool.
+
+1. Create integration (same as Option B).
+2. Call:
+   - `https://app.kapso.ai/api/v1/integrations/{integration_id}/invoke`
+
+Rules:
+- Prefer Option B for agent nodes.
+- Pipedream URLs do not work in webhook nodes or agent webhook tools.
+- Always get action_id from search-actions; do not guess.

package/skills_ref/whatsapp/references/databases-reference.md

@@ -0,0 +1,21 @@
+# Database Filters Reference
+
+Use PostgREST-style filters as query parameters.
+
+## Operators
+
+- `eq`: equals (`status=eq.active`)
+- `neq`: not equal (`status=neq.inactive`)
+- `gt`: greater than (`age=gt.18`)
+- `gte`: greater or equal (`age=gte.18`)
+- `lt`: less than (`price=lt.100`)
+- `lte`: less or equal (`price=lte.100`)
+- `like`: pattern match (`name=like.%john%`)
+- `in`: list match (`status=in.(active,pending)`)
+- `is.null`: is null (`deleted_at=is.null`)
+
+## Common patterns
+
+- Select columns: `?select=id,name,email`
+- Order: `?order=created_at.desc`
+- Pagination: `?limit=20&offset=40`

package/skills_ref/whatsapp/references/execution-context.md

@@ -0,0 +1,42 @@
+# Execution Context and Variables
+
+Execution context shape:
+
+```json
+{
+  "vars": { "user_name": "Alice" },
+  "system": { "flow_id": "uuid", "flow_name": "...", "trigger_type": "inbound_message" },
+  "context": { "channel": "whatsapp", "phone_number": "+1234567890", "contact": { "wa_id": "...", "profile_name": "..." } },
+  "metadata": { "request": { "ip": "...", "timestamp": "..." } }
+}
+```
+
+Always use this structure:
+- `vars`: user-defined variables
+- `system`: system variables (flow_id, trigger_type, etc)
+- `context`: channel info (phone number, contact)
+- `metadata`: request metadata
+
+## Variable syntax
+
+Environment variables (secrets):
+- `${ENV:VARIABLE_NAME}`
+
+Runtime variables:
+- `{{vars.my_variable}}`
+- `{{system.flow_name}}`
+- `{{context.phone_number}}`
+
+Substitution order:
+1. Environment variables
+2. Runtime variables
+
+Important WhatsApp keys:
+- `{{system.whatsapp_config.phone_number_id}}` (Meta phone_number_id)
+- `{{system.trigger_whatsapp_config_id}}` (Kapso WhatsApp config id)
+- `{{context.phone_number}}` (recipient phone)
+
+Never guess variable paths. Use:
+- `scripts/variables-list.js <workflow-id>`
+- `scripts/get-execution.js <execution-id>`
+- `scripts/get-context-value.js <execution-id> --variable-path <path>`

package/skills_ref/whatsapp/references/function-contracts.md

@@ -0,0 +1,55 @@
+# Workflow Function Contracts
+
+Use this when configuring function or decide nodes.
+
+## Code rules (must follow)
+
+- Code MUST start with: `async function handler(request, env) {`
+- Do NOT use `export`, `export default`, or arrow functions.
+- Output only JavaScript source code (no markdown fences).
+
+## Payload (function/decide nodes)
+
+```json
+{
+  "execution_context": { "vars": {}, "system": {}, "context": {}, "metadata": {} },
+  "available_edges": ["edge_a", "edge_b"],
+  "flow_events": [{ "event_type": "...", "payload": {} }]
+}
+```
+
+## Function node response
+
+Return variables to merge:
+
+```json
+{ "vars": { "processed": true } }
+```
+
+## Decide node response
+
+Return `next_edge` matching an outgoing edge label:
+
+```json
+{ "next_edge": "qualified", "vars": { "decision_reason": "qualified" } }
+```
+
+Always fall back to the first available edge if unsure.
+
+## Agent Function Tool
+
+Agent node function tools receive:
+
+```json
+{
+  "input": { "any": "shape" },
+  "execution_context": { "vars": {}, "system": {}, "context": {}, "metadata": {} },
+  "flow_events": [],
+  "flow_info": { "id": "uuid", "name": "...", "step_id": "uuid" },
+  "whatsapp_context": { "conversation": {}, "messages": [] }
+}
+```
+
+For full runtime contract details, load:
+- `functions-reference.md`
+- `functions-payloads.md`

package/skills_ref/whatsapp/references/functions-payloads.md

@@ -0,0 +1,87 @@
+# Payload Shapes (Quick Reference)
+
+## Workflow function node (request)
+
+Kapso sends:
+
+```json
+{
+  "execution_context": {
+    "vars": { "user_name": "John", "score": 42 },
+    "system": { "flow_id": "uuid", "flow_name": "...", "trigger_type": "inbound_message" },
+    "context": { "channel": "whatsapp", "phone_number": "+1234567890", "contact": { "wa_id": "...", "profile_name": "..." } },
+    "metadata": { "request": { "ip": "...", "timestamp": "..." } }
+  },
+  "available_edges": ["edge_a", "edge_b"],
+  "flow_events": [{ "event_type": "...", "payload": { "...": "..." } }]
+}
+```
+
+### Function node response
+
+Return vars to merge:
+
+```json
+{ "vars": { "processed": true, "result": "ok" } }
+```
+
+## Workflow decide node (request)
+
+Same request shape as function nodes.
+
+### Decide node response
+
+Return `next_edge` that matches an outgoing edge label:
+
+```json
+{ "next_edge": "qualified", "vars": { "decision_reason": "qualified" } }
+```
+
+Always fall back to the first available edge if unsure.
+
+## Agent function tool (request)
+
+```json
+{
+  "input": { "any": "shape" },
+  "execution_context": { "vars": {}, "system": {}, "context": {}, "metadata": {} },
+  "flow_events": [{ "event_type": "...", "payload": { "...": "..." } }],
+  "flow_info": { "id": "uuid", "name": "...", "step_id": "uuid" },
+  "whatsapp_context": { "conversation": { "...": "..." }, "messages": [] }
+}
+```
+
+## WhatsApp Flow data endpoint (request)
+
+Kapso forwards:
+
+```json
+{
+  "source": "whatsapp_flow",
+  "flow": { "id": "<uuid>", "meta_flow_id": "<meta_id>" },
+  "data_exchange": {
+    "action": "INIT" | "data_exchange" | "BACK",
+    "screen": "CURRENT_SCREEN_ID",
+    "data": { "...": "..." },
+    "flow_token": "opaque-token"
+  },
+  "signature_valid": true,
+  "received_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### WhatsApp Flow response
+
+```json
+{
+  "version": "3.0",
+  "screen": "NEXT_SCREEN_ID",
+  "data": {}
+}
+```
+
+## Code rules
+
+- Code MUST start with: `async function handler(request, env) {`
+- Do NOT use `export`, `export default`, or arrow functions.
+- Output only JavaScript source code (no markdown fences).

package/skills_ref/whatsapp/references/functions-reference.md

@@ -0,0 +1,133 @@
+# Function Runtime Contract
+
+## Handler signature
+
+Functions must start with:
+
+```
+async function handler(request, env) {
+```
+
+Do not use `export` or arrow functions. Return a `Response` object.
+
+## Runtime APIs
+
+- `request`: Fetch API Request; use `await request.json()` for JSON.
+- `env.DB`: D1 database access (if enabled for the project).
+- `env.KV`: KV storage with `.get(key)`, `.put(key, value)`, `.delete(key)`.
+- `env.SECRET_NAME`: Secrets configured in the function settings.
+
+## Typical workflow
+
+1. Create function with `code` that follows the contract.
+2. Deploy the function (required before use).
+3. Use the returned `function_url` for webhook destinations.
+
+## Platform API payload envelope
+
+When calling the Platform API directly (not via scripts), wrap attributes under `function`:
+
+```json
+{ "function": { "name": "...", "description": "...", "code": "..." } }
+```
+
+## Workflow node payload (Function / Decide)
+
+When a workflow function node runs, Kapso sends:
+
+```json
+{
+  "execution_context": {
+    "vars": { "user_name": "John", "score": 42 },
+    "system": { "flow_id": "uuid", "flow_name": "...", "trigger_type": "inbound_message" },
+    "context": { "channel": "whatsapp", "phone_number": "+1234567890", "contact": { "wa_id": "...", "profile_name": "..." } },
+    "metadata": { "request": { "ip": "...", "timestamp": "..." } }
+  },
+  "available_edges": ["edge_a", "edge_b"],
+  "flow_events": [{ "event_type": "...", "payload": { "..." : "..." } }]
+}
+```
+
+Execution context structure is always:
+- `vars`: user-defined variables
+- `system`: system variables (flow_id, trigger_type, etc)
+- `context`: channel data (phone number, contact)
+- `metadata`: request metadata
+
+### Function node response
+
+Return `vars` to update context:
+
+```json
+{
+  "vars": { "processed": true, "result": "ok" }
+}
+```
+
+### Decide node response
+
+Return `next_edge` that matches an outgoing edge label:
+
+```json
+{
+  "next_edge": "qualified",
+  "vars": { "decision_reason": "qualified" }
+}
+```
+
+Always fall back to the first available edge when unsure.
+
+## Agent function tool payload
+
+If an agent node uses a Function Tool, Kapso calls the function with:
+
+```json
+{
+  "input": { "any": "shape" },
+  "execution_context": { "vars": {}, "system": {}, "context": {}, "metadata": {} },
+  "flow_events": [{ "event_type": "...", "payload": { "...": "..." } }],
+  "flow_info": { "id": "uuid", "name": "...", "step_id": "uuid" },
+  "whatsapp_context": { "conversation": { "...": "..." }, "messages": [] }
+}
+```
+
+The tool expects a standard JSON response; you may return `vars` as above.
+
+## WhatsApp Flow data endpoint payload
+
+For WhatsApp Flow data endpoints, Kapso forwards:
+
+```json
+{
+  "source": "whatsapp_flow",
+  "flow": { "id": "<uuid>", "meta_flow_id": "<meta_id>" },
+  "data_exchange": {
+    "action": "INIT" | "data_exchange" | "BACK",
+    "screen": "CURRENT_SCREEN_ID",
+    "data": { "...": "..." },
+    "flow_token": "opaque-token"
+  },
+  "signature_valid": true,
+  "received_at": "2024-01-01T00:00:00Z"
+}
+```
+
+Respond with:
+
+```json
+{
+  "version": "3.0",
+  "screen": "NEXT_SCREEN_ID",
+  "data": {}
+}
+```
+
+For full Flow JSON details and gotchas, load:
+- `../integrate-whatsapp/references/whatsapp-flows-spec.md`
+
+## Best practices
+
+- Guard access: `const vars = body.execution_context?.vars || {};`
+- Do not mutate `execution_context` in place; return new `vars`.
+- Use try/catch for external API calls.
+- Keep responses under the Meta timeout (10-15s).