@hailer/mcp 1.0.28 → 1.1.2

package/.claude/skills/zapier-hailer-patterns/SKILL.md

@@ -0,0 +1,581 @@
+---
+name: zapier-hailer-patterns
+description: Patterns for building Zapier integrations with Hailer REST API
+version: 1.0.1
+triggers: When building Zapier automations, webhook triggers, or API integrations
+---
+
+# Zapier-Hailer Integration Patterns
+
+Use this skill when building Zapier automations that integrate with Hailer.
+
+## Key Insight: Zapier + Any REST API
+
+Zapier doesn't have a native Hailer integration, but **Webhooks by Zapier** can connect to ANY REST API. This means:
+- Hailer's full REST API is available via Zapier
+- Same pattern works for any external system with REST API
+
+---
+
+## CRITICAL: Custom Request Configuration
+
+**#1 Zapier mistake: Not setting `return_raw_response`**
+
+Every Custom Request step MUST set `return_raw_response: true` (or `"yes"` in JSON).
+
+Without this parameter:
+- Zapier returns only HTTP status (200 OK), not the response body
+- You can't get created activity IDs
+- You can't parse API responses in Code steps
+- You can't chain API calls using returned data
+
+**Always include this:**
+```json
+{
+  "method": "POST",
+  "url": "https://api.hailer.com/api/v3/activity/create",
+  "return_raw_response": "yes"  // ← ESSENTIAL - Enables access to response body
+}
+```
+
+This single parameter fixes 90% of "Zap runs but I can't access the data" issues.
+
+---
+
+## Knowledge Sources
+
+**Always query NotebookLM first** for detailed patterns and examples:
+
+```
+Notebook: "Zapier-opas Haileriin: Automaatio, AI-orkestointi ja yritysratkaisut"
+ID: 2d93afb6-6378-45e7-b380-3ee3c235244f
+```
+
+This notebook contains:
+- Hailer REST API documentation
+- Authentication patterns
+- Field type formats
+- Example zaps with annotations
+- Webhook configuration guides
+
+**Also check:** "Hailer REST-api" notebook (ID: `68e4e3fd-6ed6-4e0b-b624-672773ba4142`) for API endpoint details.
+
+## Quick Reference
+
+### Authentication
+```
+POST https://api.hailer.com/api/login
+Body: {"0": "email", "1": "password"}
+Returns: Session key → use as "hlrkey" header
+```
+
+### Webhook Triggers
+- Configured per-phase in Hailer (not per-workflow)
+- Set `webhooksEnabled: true` and `webhookUrl` on phase
+
+**CRITICAL: Webhook Payload Structure**
+```typescript
+{
+  _id: string;            // Activity ID (MongoDB ObjectId)
+  name: string;           // Activity name
+  currentPhase: string;   // Phase ID (MongoDB ObjectId)
+  process: string;        // Workflow ID (MongoDB ObjectId)
+  fields: Array<{
+    id: string;           // Field ID (MongoDB ObjectId)
+    type: string;         // Field type
+    value: any;           // Field value
+    key?: string;         // Optional field key (human-readable)
+  }>;
+}
+```
+
+**Finding field values - two methods:**
+```javascript
+// Method 1: By key (if field has key property - preferred when available)
+const tagValue = fields.find(f => f.key === 'tag')?.value;
+
+// Method 2: By fieldId (always works - use real MongoDB IDs)
+const tagValue = fields.find(f => f.id === '507f1f77bcf86cd799439011')?.value;
+```
+
+**⚠️ NEVER use SDK enums in automations.** Webhooks receive raw MongoDB ObjectIds, not SDK enum names. Use real IDs from the workspace or extract from payload.
+
+### Activity Creation
+```
+POST https://api.hailer.com/api/v3/activity/create
+Headers: Content-Type: application/json, hlrkey: <session_key>
+Body: {
+  "0": "workflowId",
+  "1": {
+    "name": "Activity name",
+    "phaseId": "phaseId",
+    "teamId": "teamId",
+    "fields": { "fieldId": "value" }
+  }
+}
+```
+
+### Field Types
+| Type | Format |
+|------|--------|
+| text/textarea | String |
+| date | Timestamp in milliseconds |
+| users | 24-char userId |
+| activitylink | 24-char activityId |
+| textpredefinedoptions | Exact option string |
+
+### Zapier Tips
+- **Always set `return_raw_response: true`** in Custom Request steps - this gives you the full JSON response for parsing in subsequent code steps
+- Webhook payloads use `id` (not `_id`) for field identifiers
+- Use Code steps to parse and transform data between API calls
+- Search fields by `key` property when available (e.g., `f.key === 'user'`) for more readable code
+- **For Dataset workflows:** `phaseId` must be in the OPTIONS object (third parameter "2"), not in the activity object
+
+### Zapier Import/Export JSON Format
+
+Zaps can be exported and imported as JSON files. This is useful for:
+- Version controlling automations in git
+- Sharing zap templates between projects
+- Backing up zap configurations
+
+**Top-level structure:**
+```json
+{
+  "metadata": { "version": 2 },
+  "zaps": [{
+    "id": 1,
+    "title": "Zap name",
+    "nodes": {
+      "1": { /* trigger */ },
+      "2": { /* action 1 */ },
+      "3": { /* action 2 */ }
+    }
+  }]
+}
+```
+
+**Node structure:**
+```json
+{
+  "id": 1,
+  "paused": false,
+  "type_of": "read",           // "read" = trigger, "write" = action
+  "params": {},                // Step-specific parameters
+  "meta": { "$editor": { "has_automatic_issues": false }, "timezone": "Europe/Helsinki" },
+  "triple_stores": { "copied_from": null, "created_by": null, "polling_interval_override": 0, "block_and_release_limit_override": 0, "spread_tasks": 1 },
+  "parent_id": null,           // null for trigger, previous node id for actions
+  "root_id": null,             // null for trigger, 1 for all actions
+  "action": "hook_raw",        // Action type (see below)
+  "selected_api": "WebHookCLIAPI@1.0.29",
+  "title": "Step title",
+  "authentication_id": null
+}
+```
+
+**Action types:**
+| action | selected_api | Purpose |
+|--------|--------------|---------|
+| `hook_raw` | WebHookCLIAPI@1.0.29 | Catch Webhook trigger |
+| `post` | WebHookCLIAPI@1.0.29 | POST request |
+| `custom` | WebHookCLIAPI@1.0.29 | Custom Request (GET/POST/PUT) |
+| `01929fad-d3dd-...` | CodeCLIAPI@1.0.1 | Run JavaScript code |
+
+**Data references between steps:**
+Use `{{node_id__field}}` syntax:
+- `{{1__raw_body}}` - Raw body from trigger
+- `{{2__results}}` - Results from node 2 (e.g., session key from login)
+- `{{3__payload}}` - Output field from code step
+
+**Example: Webhook → Login → Code → Create Activity**
+```json
+{
+  "metadata": { "version": 2 },
+  "zaps": [{
+    "id": 1,
+    "title": "Phase webhook → Create task",
+    "nodes": {
+      "1": {
+        "id": 1, "type_of": "read", "action": "hook_raw",
+        "selected_api": "WebHookCLIAPI@1.0.29",
+        "title": "Catch webhook", "parent_id": null, "root_id": null,
+        "params": {}, "paused": false, "authentication_id": null,
+        "meta": { "$editor": { "has_automatic_issues": false }, "timezone": "Europe/Helsinki" },
+        "triple_stores": { "copied_from": null, "created_by": null, "polling_interval_override": 0, "block_and_release_limit_override": 0, "spread_tasks": 1 }
+      },
+      "2": {
+        "id": 2, "type_of": "write", "action": "post",
+        "selected_api": "WebHookCLIAPI@1.0.29",
+        "title": "Login to Hailer", "parent_id": 1, "root_id": 1,
+        "params": {
+          "payload_type": "json", "wrap_in_array": "no", "unflatten": "yes",
+          "url": "https://api.hailer.com/api/login",
+          "data": { "0": "user@example.com", "1": "PASSWORD" },
+          "headers": { "Content-Type": "application/json" }
+        },
+        "paused": false, "authentication_id": null,
+        "meta": { "$editor": { "has_automatic_issues": false }, "parammap": {} },
+        "triple_stores": { "copied_from": null, "created_by": null, "polling_interval_override": 0, "block_and_release_limit_override": 0, "spread_tasks": 1 }
+      },
+      "3": {
+        "id": 3, "type_of": "write", "action": "01929fad-d3dd-62c2-52ed-7868d5fcc691",
+        "selected_api": "CodeCLIAPI@1.0.1",
+        "title": "Build payload", "parent_id": 2, "root_id": 1,
+        "params": {
+          "code": "const body = JSON.parse(inputData.rawBody);\\nconst payload = { \"0\": \"workflowId\", \"1\": { ... } };\\nreturn { payload: JSON.stringify(payload) };",
+          "input": { "rawBody": "{{1__raw_body}}" }
+        },
+        "paused": false, "authentication_id": null,
+        "meta": { "$editor": { "has_automatic_issues": false }, "parammap": {} },
+        "triple_stores": { "copied_from": null, "created_by": null, "polling_interval_override": 0, "block_and_release_limit_override": 0, "spread_tasks": 1 }
+      },
+      "4": {
+        "id": 4, "type_of": "write", "action": "custom",
+        "selected_api": "WebHookCLIAPI@1.0.29",
+        "title": "Create activity", "parent_id": 3, "root_id": 1,
+        "params": {
+          "method": "POST", "unflatten": "yes", "return_raw_response": "no",
+          "url": "https://api.hailer.com/api/v3/activity/create",
+          "headers": { "Content-Type": "application/json", "hlrkey": "{{2__results}}" },
+          "data": "{{3__payload}}"
+        },
+        "paused": false, "authentication_id": null,
+        "meta": { "$editor": { "has_automatic_issues": false }, "parammap": {} },
+        "triple_stores": { "copied_from": null, "created_by": null, "polling_interval_override": 0, "block_and_release_limit_override": 0, "spread_tasks": 1 }
+      }
+    }
+  }]
+}
+```
+
+**See also:** `sdk-projects/pohjaset/automations/` for real-world examples with annotations
+
+---
+
+## Zapier Built-in Tools Reference
+
+These are Zapier's native apps - no external service needed. Essential for Hailer integrations.
+
+### Webhooks by Zapier
+**API:** `WebHookCLIAPI@1.0.29`
+
+| Trigger/Action | Purpose | Key Params |
+|----------------|---------|------------|
+| **Catch Hook** (trigger) | Receive webhook from Hailer phase | `action: "hook_raw"` |
+| **Catch Raw Hook** (trigger) | Same, preserves raw body | `action: "hook_raw"` |
+| **Custom Request** (action) | Any HTTP request | `action: "custom"`, `method`, `url`, `headers`, `data` |
+| **POST** (action) | Simple POST | `action: "post"`, `url`, `data` |
+| **GET** (action) | Simple GET | `action: "get"`, `url` |
+| **PUT** (action) | Simple PUT | `action: "put"`, `url`, `data` |
+
+**Custom Request params:**
+```json
+{
+  "method": "POST",
+  "url": "https://api.hailer.com/api/v3/activity/create",
+  "headers": { "Content-Type": "application/json", "hlrkey": "{{2__results}}" },
+  "data": "{{3__payload}}",
+  "unflatten": "yes",
+  "return_raw_response": "yes"
+}
+```
+
+### Code by Zapier
+**API:** `CodeCLIAPI@1.0.1`
+
+| Action | Purpose | Key Params |
+|--------|---------|------------|
+| **Run JavaScript** | Transform data, build payloads | `action: "01929fad-d3dd-62c2-52ed-7868d5fcc691"` |
+| **Run Python** | Same, Python syntax | Different action UUID |
+
+**JavaScript params:**
+```json
+{
+  "code": "const data = JSON.parse(inputData.rawBody);\\nreturn { result: data.field };",
+  "input": { "rawBody": "{{1__raw_body}}", "sessionKey": "{{2__results}}" }
+}
+```
+
+**Code tips:**
+- Access inputs via `inputData.variableName`
+- Return object with named outputs: `return { payload, email, id };`
+- Can use `fetch` for additional API calls (async supported)
+- Output fields available as `{{node__fieldname}}`
+
+### Filter by Zapier
+**API:** `FilterAPI` (legacy, still works)
+
+Conditionally continue or stop the Zap. Note: `type_of` is `"filter"` (not "write").
+
+| Action | Purpose |
+|--------|---------|
+| `filter` | Only continue if conditions match |
+
+**Params:**
+```json
+{
+  "selected_api": "FilterAPI",
+  "action": "filter",
+  "type_of": "filter",
+  "params": {
+    "filter_criteria": [
+      {
+        "id": 4699009700892223,
+        "group": 4153161264351725,
+        "key": "{{1__status}}",
+        "value": "approved",
+        "match": "icontains",
+        "action": "continue"
+      }
+    ]
+  }
+}
+```
+
+**Match types:** `icontains`, `inot_contains`, `iexact`, `inot_exact`, `is_set`, `not_set`, `greater_than`, `less_than`
+
+### Paths by Zapier
+**API:** `BranchingAPI` (419 uses found)
+
+Conditional branching - different actions based on conditions. Note: Uses `BranchingAPI` not `PathsCLIAPI`.
+
+```json
+{
+  "selected_api": "BranchingAPI",
+  "action": "branch",
+  "type_of": "branching",
+  "params": {
+    "branches": [
+      {
+        "name": "Path A - Approved",
+        "filter_criteria": [
+          { "key": "{{1__status}}", "value": "approved", "match": "iexact" }
+        ]
+      },
+      {
+        "name": "Path B - Rejected",
+        "filter_criteria": [
+          { "key": "{{1__status}}", "value": "rejected", "match": "iexact" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Formatter by Zapier
+**API:** `ZapierFormatterCLIAPI@1.0.7`
+
+Transform text, dates, numbers without code.
+
+| Action | Purpose |
+|--------|---------|
+| `datetime_line_item` | Format dates |
+| `text_line_item` | Manipulate strings |
+| `util_line_item` | Utilities (lookup, pick) |
+
+**Date format (useful for Hailer timestamps):**
+```json
+{
+  "selected_api": "ZapierFormatterCLIAPI@1.0.7",
+  "action": "datetime_line_item",
+  "type_of": "write",
+  "params": {
+    "transform": "date.formatting",
+    "to_timezone": "UTC",
+    "from_timezone": "UTC",
+    "inputs": "{{1__timestamp}}",
+    "to_format": "YYYY-MM-DD"
+  }
+}
+```
+
+**Text transform:**
+```json
+{
+  "selected_api": "ZapierFormatterCLIAPI@1.0.7",
+  "action": "text_line_item",
+  "type_of": "write",
+  "params": {
+    "transform": "text.replace",
+    "inputs": "{{1__email}}",
+    "find": "@old-domain.com",
+    "replace": "@new-domain.com"
+  }
+}
+```
+Note: Hailer uses milliseconds, Zapier's `X` is seconds - divide by 1000 in Code step or use date formatting.
+
+### Delay by Zapier
+**API:** `DelayCLIAPI@1.1.1`
+
+Pause execution.
+
+| Action | Purpose |
+|--------|---------|
+| `delay_for` | Wait specific duration |
+
+```json
+{
+  "selected_api": "DelayCLIAPI@1.1.1",
+  "action": "delay_for",
+  "type_of": "write",
+  "params": {
+    "delay_for_value": "5",
+    "delay_for_unit": "minutes"
+  }
+}
+```
+
+### Looping by Zapier
+**API:** `ZapierLoopingCLIAPI@1.2.6`
+
+Iterate over arrays (e.g., process multiple activities).
+
+| Action | Purpose |
+|--------|---------|
+| `loop_values_line_items` | Loop over line items (objects) |
+| `loop_values_numbers` | Loop over number range |
+| `loop_values_text` | Loop over text items |
+
+```json
+{
+  "selected_api": "ZapierLoopingCLIAPI@1.2.6",
+  "action": "loop_values_line_items",
+  "type_of": "write",
+  "params": {
+    "trim_whitespace": "True",
+    "iteration_start": "1",
+    "iteration_limit": "500",
+    "loop_values": {
+      "activityId": "{{1__activities[]_id}}",
+      "name": "{{1__activities[]name}}",
+      "status": "{{1__activities[]currentPhase}}"
+    }
+  }
+}
+```
+
+Access loop outputs: `{{node__activityId}}`, `{{node__name}}`, etc.
+
+### Sub-Zap by Zapier
+**API:** `SubZapCLIAPI@0.11.2`
+
+Call another Zap as a subroutine.
+
+| Action | Purpose |
+|--------|---------|
+| `start_subzap` | Trigger (receives call from parent) |
+| `call_subzap` | Call another Zap, wait for response |
+| `return_subzap` | Return data to caller |
+
+**Trigger (in sub-zap):**
+```json
+{
+  "selected_api": "SubZapCLIAPI@0.11.2",
+  "action": "start_subzap",
+  "type_of": "read",
+  "params": {
+    "input_list": ["activityId", "sessionKey", "workflowId"]
+  }
+}
+```
+
+**Call (from parent zap):**
+```json
+{
+  "selected_api": "SubZapCLIAPI@0.11.2",
+  "action": "call_subzap",
+  "type_of": "write",
+  "params": {
+    "account_id": "5024683",
+    "zap_id": "202514585",
+    "activityId": "{{1__activityId}}",
+    "sessionKey": "{{2__results}}",
+    "workflowId": "{{3__workflowId}}"
+  }
+}
+```
+
+Useful for reusable logic (e.g., "Login to Hailer" sub-zap).
+
+### Storage by Zapier
+**API:** `StorageCLIAPI@1.2.1`
+
+Store and retrieve values across Zap runs.
+
+| Action | Purpose |
+|--------|---------|
+| `get_multiple_values` | Retrieve stored values |
+| `list_push` | Add to list |
+| `set_value` | Store key-value pair |
+
+**Get values:**
+```json
+{
+  "selected_api": "StorageCLIAPI@1.2.1",
+  "action": "get_multiple_values",
+  "type_of": "search",
+  "params": {
+    "_zap_search_success_on_miss": true,
+    "keys": ["{{1__activityId}}", "lastSyncTimestamp"]
+  }
+}
+```
+
+**Push to list:**
+```json
+{
+  "selected_api": "StorageCLIAPI@1.2.1",
+  "action": "list_push",
+  "type_of": "write",
+  "params": {
+    "key": "processedIds",
+    "value": "{{1__activityId}}",
+    "location": "tail"
+  }
+}
+```
+
+Useful for: tracking last sync timestamp, deduplication, counters.
+
+---
+
+## Common Tool Combinations for Hailer
+
+| Pattern | Tools Used |
+|---------|------------|
+| **Webhook → Create Activity** | Catch Hook → Code → Custom Request |
+| **Conditional Processing** | Catch Hook → Filter → Code → Custom Request |
+| **Branching Logic** | Catch Hook → Paths → (different actions per path) |
+| **Batch Processing** | Catch Hook → Looping → Custom Request |
+| **Scheduled Sync** | Schedule trigger → Custom Request (list) → Looping → Custom Request (update) |
+| **Date Formatting** | Catch Hook → Formatter (date) → Code → Custom Request |
+| **Reusable Auth** | Sub-Zap for login → Return session key |
+
+---
+
+## Workflow for Building Zaps
+
+1. **Query NotebookLM** for API patterns and field formats
+2. **Get workspace IDs** using Kenji agent (workflow, phase, field, team IDs)
+3. **Design the zap flow**: Trigger → (optional code step) → API action
+4. **Create annotated documentation** for future reference
+5. **Store zap JSON** in project's `automations/` folder
+
+## Common Zap Patterns
+
+### Hailer Webhook → Hailer Action
+1. Catch Hook (webhook from Hailer phase)
+2. Login to get session key
+3. Code step to build payload
+4. Custom Request to Hailer API
+
+### External Trigger → Hailer
+1. Trigger from external app (Gmail, Slack, etc.)
+2. Login to Hailer
+3. Create/Update activity via API
+
+### Hailer → External Action
+1. Catch Hook from Hailer
+2. Transform data if needed
+3. Send to external API (Slack, Email, etc.)

package/.env.example

@@ -62,13 +62,32 @@
 # Default: false (nuclear tools completely hidden)
 # ENABLE_NUCLEAR_TOOLS=true
 
+
 # ==============================================
-# METRICS ADMIN API
+# OPTIONAL: MCP CLIENT CONFIGURATION (automated agent)
 # ==============================================
 
-# Metrics Admin API (for workspace/user search - requires whitelisted Hailer user)
-# These credentials are used for privileged metrics operations like searching all workspaces
-# Only whitelisted users can make these API calls
-# METRICS_ADMIN_EMAIL=admin@example.com
-# METRICS_ADMIN_PASSWORD=your-password
-# METRICS_ADMIN_API_URL=https://api.hailer.com
+# Enable the MCP Client (enabled by default)
+MCP_CLIENT_ENABLED=false
+
+# LLM Provider API Keys (add at least one)
+# ANTHROPIC_API_KEY=sk-ant-your-key-here
+# OPENAI_API_KEY=sk-your-openai-key-here
+
+# MCP Server URL (for client to call our own tools)
+MCP_SERVER_URL=http://localhost:3030/api/mcp
+#MCP_CLIENT_API_KEY=your-api-key
+
+# MCP Agent User IDs (required for agent tagging - get these from Hailer)
+MCP_CLIENT_AGENT_IDS='[]'
+
+# Bot Features (optional, defaults to true)
+TOKEN_USAGE_BOT_ENABLED=false
+AGENT_ACTIVITY_BOT_ENABLED=false
+
+# Adaptive Documentation Bot (automatically improves tool descriptions based on errors)
+ADAPTIVE_DOCUMENTATION_BOT_ENABLED=false
+ADAPTIVE_AUTO_UPDATE=false
+ADAPTIVE_UPDATE_INTERVAL=60000
+ADAPTIVE_MIN_ERROR_COUNT=3
+ADAPTIVE_SKILL_GENERATION=false