@hailer/mcp 1.1.13 → 1.1.15

package/.claude/skills/SDK-function-fields/SKILL.md

@@ -0,0 +1,542 @@
+---
+name: SDK-function-fields
+description: Complete guide to creating calculated function fields in Hailer - workflow, variable types, patterns
+version: 1.2.0
+triggers:
+  - function field
+  - calculated field
+  - formula field
+  - backlinks
+  - phase filtering
+  - Data metadata
+---
+
+# Function Fields
+
+Complete guide for creating calculated fields that auto-update when dependencies change.
+
+---
+
+## Overview
+
+Function fields compute values from other fields. Examples:
+- Total = Quantity × Unit Price
+- Days Until Due = Due Date - Today
+- Invoice Total = Sum of line item prices (filtered by phase)
+
+---
+
+## Step-by-Step Workflow
+
+### 1. Pull Latest
+```bash
+npm run pull
+```
+
+### 2. Add Field Definition (fields.ts)
+
+```typescript
+// workspace/[Workflow]_[id]/fields.ts
+{
+  label: "Total Cost",
+  type: "number",
+  key: "total_cost",
+  function: "@function:totalCost",
+  functionEnabled: true,
+  editable: false,
+  functionVariables: {
+    quantity: {
+      type: "=",
+      data: [FieldIds.quantity]
+    },
+    unitPrice: {
+      type: "=",
+      data: [FieldIds.unit_price]
+    }
+  }
+}
+```
+
+### 3. Create Function File
+
+Create `workspace/[Workflow]_[id]/functions/totalCost.ts`:
+
+```typescript
+export function totalCost(dep: {
+  quantity: number | null;
+  unitPrice: number | null;
+}): number {
+  const qty = Number(dep.quantity) || 0;
+  const price = Number(dep.unitPrice) || 0;
+  return qty * price;
+}
+```
+
+### 4. Export Function
+
+Edit `workspace/[Workflow]_[id]/functions/index.ts`:
+
+```typescript
+export { totalCost } from './totalCost';
+```
+
+### 5. Test
+
+```typescript
+// workspace/[Workflow]_[id]/main.test.ts
+import { totalCost } from './functions';
+
+describe('totalCost', () => {
+  it('multiplies quantity by unit price', () => {
+    expect(totalCost({ quantity: 5, unitPrice: 10 })).toBe(50);
+  });
+
+  it('handles null values', () => {
+    expect(totalCost({ quantity: null, unitPrice: 10 })).toBe(0);
+  });
+});
+```
+
+Run: `npm test`
+
+### 6. Push
+
+```bash
+npm run fields-push:force
+```
+
+---
+
+## Variable Types Reference
+
+| Type | Name | data Array | Returns |
+|------|------|------------|---------|
+| `=` | Current field | `[FieldId]` | Single value |
+| `>` | Forward link | `[LinkFieldId, TargetFieldId]` | Single value |
+| `<` | Backlink | `[WorkflowId, TargetFieldId]` | **Array** |
+| `?` | Static | `[WorkflowId, PhaseId]` | Phase ID string |
+
+---
+
+## Field Data Formats in Functions
+
+What format does each field type return when used as a dependency variable?
+
+| Field Type | Returns | Example |
+|------------|---------|---------|
+| `text`, `textarea` | `string` | `"Hello world"` |
+| `numeric`, `numericunit` | `number` | `42.5` |
+| `date`, `datetime` | `number` (ms timestamp) | `1730937600000` |
+| `daterange`, `datetimerange` | `{ start: number, end: number }` | `{ start: 1730937600000, end: 1731024000000 }` |
+| `time` | `number` (ms timestamp, includes date!) | `1765863000000` |
+| `timerange` | `{ start: number, end: number }` | `{ start: 1765863000000, end: 1765915200000 }` (ms timestamps, includes date!) |
+| `textpredefinedoptions` | `string` | `"High"` |
+| `users`, `teams` | `string` (ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
+| `activitylink` | `string` (activity ID) | `"692abc123def456"` |
+| `country` | `string` (ISO code) | `"FI"` |
+| `numeric` + `modifier.checkbox` | `number` | `1` (true) or `0` (false) |
+
+**Examples:**
+
+```javascript
+// Date field (milliseconds timestamp)
+const dueDate = dep.dueDate;  // 1730937600000
+const isOverdue = dueDate < Date.now();
+
+// Daterange field (object with start/end)
+const period = dep.eventPeriod;  // { start: 1730937600000, end: 1731024000000 }
+const startDate = period ? period.start : null;
+const endDate = period ? period.end : null;
+const durationMs = (endDate && startDate) ? (endDate - startDate) : 0;
+const durationDays = Math.ceil(durationMs / 86400000);
+
+// Time field (ms timestamp - includes date!)
+const startTime = dep.startTime;  // 1765863000000
+// To extract just the time, use Date methods:
+const date = new Date(startTime);
+const hours = date.getUTCHours();
+const minutes = date.getUTCMinutes();
+
+// Timerange field (object with start/end as ms timestamps - includes date!)
+const workHours = dep.workingHours;  // { start: 1765863000000, end: 1765915200000 }
+const durationMs = workHours ? (workHours.end - workHours.start) : 0;
+const durationMinutes = durationMs / 60000;
+
+// IMPORTANT: When to convert vs keep raw:
+// - Display only (text output) → use Date methods to extract time
+// - Write to another date/time field → keep as Unix milliseconds (no conversion!)
+
+// Checkbox field (1 or 0)
+const isActive = dep.isActive;  // 1 or 0
+if (isActive === 1) { /* checked */ }
+```
+
+---
+
+## Backlink Arrays (`<`)
+
+Backlinks return **arrays** because multiple activities can link to this one.
+
+```javascript
+// functionVariables config
+{
+  prices: {
+    type: "<",
+    data: [WorkflowIds.invoice_rows, InvoiceRows_FieldIds.total_price]
+  }
+}
+
+// In function - ALWAYS default to empty array
+const prices = dep.prices || [];
+let total = 0;
+for (let i = 0; i < prices.length; i++) {
+  total += Number(prices[i]) || 0;
+}
+return total;
+```
+
+---
+
+## Activity Metadata (`"meta"`)
+
+The special `"meta"` value returns activity metadata. It works with **all variable types**:
+
+### Current Activity Metadata (`=`)
+
+```javascript
+// Get metadata of THIS activity
+{
+  myMeta: {
+    type: "=",
+    data: ["meta"]
+  }
+}
+
+// In function
+const myPhase = dep.myMeta ? dep.myMeta.phase : null;
+const myCreated = dep.myMeta ? dep.myMeta.created : 0;
+```
+
+### Forward Link Metadata (`>`)
+
+```javascript
+// Get metadata of LINKED activity (this → other)
+{
+  customerMeta: {
+    type: ">",
+    data: [FieldIds.customer_link, "meta"]
+  }
+}
+
+// In function
+const customerPhase = dep.customerMeta ? dep.customerMeta.phaseName : 'Unknown';
+```
+
+### Backlink Metadata (`<`)
+
+```javascript
+// Get metadata of activities linking TO this (others → this)
+{
+  rowsMeta: {
+    type: "<",
+    data: [WorkflowIds.invoice_rows, "meta"]
+  }
+}
+
+// In function - returns ARRAY
+const rows = dep.rowsMeta || [];
+for (let i = 0; i < rows.length; i++) {
+  const phaseName = rows[i] ? rows[i].phaseName : 'Unknown';
+}
+```
+
+### Metadata Structure
+
+```javascript
+{
+  "_id": "694c9536acfa30f6df13201b",      // Activity ID
+  "name": "Invoice row name",              // Activity name
+  "process": "67dc1b7d3d2c9f6cf9a5468d",  // Workflow ID
+  "phase": "67dc1b7d3d2c9f6cf9a546c4",    // Phase ID
+  "processName": "Invoice Rows",           // Workflow name
+  "phaseName": "Active",                   // Phase name
+  "created": 1766626614031,               // Created timestamp (ms)
+  "updated": 1766626614031,               // Updated timestamp (ms)
+  "completed": null,                       // Completed timestamp or null
+  "sequence": 1649,                        // Activity sequence number
+  "active": true                           // Is activity active
+}
+```
+
+---
+
+## Parallel Array Guarantee
+
+**CRITICAL INSIGHT:** When you have multiple `<` (backlink) variables from the **SAME source workflow**, they are guaranteed to be:
+- Same length
+- Same order (index 0 in all arrays = same activity)
+
+**This is a core Hailer feature that enables safe parallel iteration.**
+
+```javascript
+const prices = dep['Total price'] || [];   // [41.76, 26.1, 153.47]
+const data = dep['Data'] || [];            // [{...}, {...}, {...}]
+
+// Index 0 in both = same Invoice Row activity
+for (let i = 0; i < prices.length; i++) {
+  const price = Number(prices[i]) || 0;
+  const phaseName = data[i] ? data[i].phaseName : 'Unknown';
+  // price and phaseName are from the SAME activity
+}
+```
+
+**Arrays from DIFFERENT workflows** are independent.
+
+---
+
+## Static Variables (`?`)
+
+Static variables provide phase IDs for comparison in your function logic.
+
+```javascript
+// Get specific phase IDs to compare against
+{
+  donePhase: {
+    type: "?",
+    data: [WorkflowIds.sales_activities, PhaseIds.done]
+  },
+  archivePhase: {
+    type: "?",
+    data: [WorkflowIds.sales_activities, PhaseIds.archive]
+  }
+}
+
+// In function - compare against metadata phase
+const donePhase = dep.donePhase;       // "627d14339381d6077ab90ce9"
+const archivePhase = dep.archivePhase; // "639b49617a4413c20f15ac12"
+
+if (item.phase === donePhase || item.phase === archivePhase) {
+  // Activity is in done or archive phase
+}
+```
+
+**Note:** To get `process` and `phase` IDs from activities, use `"meta"` (not `?`). Static `?` is only for providing known phase IDs for comparison.
+
+---
+
+## Common Patterns
+
+### Sum from Backlinks
+
+```javascript
+function total(dep) {
+  const prices = dep.prices || [];
+  let sum = 0;
+  for (let i = 0; i < prices.length; i++) {
+    sum += Number(prices[i]) || 0;
+  }
+  return sum;
+}
+```
+
+### Filter by Phase (Complete Example)
+
+**functionVariables config:**
+```javascript
+{
+  Data: {
+    type: "<",
+    data: [WorkflowIds.sales_activities, "meta"]
+  },
+  dl: {
+    type: "<",
+    data: [WorkflowIds.sales_activities, FieldIds.deadline]
+  },
+  done: {
+    type: "?",
+    data: [WorkflowIds.sales_activities, PhaseIds.done]
+  },
+  archive: {
+    type: "?",
+    data: [WorkflowIds.sales_activities, PhaseIds.archive]
+  }
+}
+```
+
+**Function (find latest deadline from done/archived activities):**
+```javascript
+function latestCompletedDeadline(dep) {
+  const data = dep.Data || [];
+  const deadlines = dep.dl || [];
+  const donePhase = dep.done;
+  const archivePhase = dep.archive;
+
+  const arr = [];
+  for (let i = 0; i < data.length; i++) {
+    const item = data[i];
+    if ((item.phase === donePhase || item.phase === archivePhase) && deadlines[i]) {
+      arr.push(deadlines[i]);
+    }
+  }
+
+  if (arr.length === 0) return null;
+  return Math.max(...arr);
+}
+```
+
+### Sum Active Only
+
+```javascript
+function sumActiveOnly(dep) {
+  const prices = dep['Total price'] || [];
+  const data = dep['Data'] || [];
+  const activePhase = dep['Active'];
+
+  let total = 0;
+  for (let i = 0; i < prices.length; i++) {
+    if (data[i] && data[i].phase === activePhase) {
+      total += Number(prices[i]) || 0;
+    }
+  }
+  return total;
+}
+```
+
+### Group by Phase
+
+```javascript
+function groupByPhase(dep) {
+  const prices = dep['Total price'] || [];
+  const data = dep['Data'] || [];
+
+  const result = {};
+  for (let i = 0; i < prices.length; i++) {
+    const phaseName = data[i] ? data[i].phaseName : 'Unknown';
+    const price = Number(prices[i]) || 0;
+    result[phaseName] = (result[phaseName] || 0) + price;
+  }
+  return JSON.stringify(result);
+}
+```
+
+### Exclude Multiple Phases
+
+```javascript
+function sumExcludingCancelled(dep) {
+  const prices = dep['Total price'] || [];
+  const data = dep['Data'] || [];
+  const cancelledPhase = dep['Cancelled'];
+  const deletedPhase = dep['Deleted'];
+
+  let total = 0;
+  for (let i = 0; i < prices.length; i++) {
+    const phase = data[i] ? data[i].phase : null;
+    if (phase === cancelledPhase || phase === deletedPhase) continue;
+    total += Number(prices[i]) || 0;
+  }
+  return total;
+}
+```
+
+### Conditional Text
+
+```javascript
+function status(dep) {
+  if (!dep.dueDate) return "No due date";
+  if (dep.dueDate < Date.now()) return "Overdue";
+  return "On track";
+}
+```
+
+### Forward Link Value
+
+```javascript
+// Get value from linked activity
+functionVariables: {
+  customerName: {
+    type: ">",
+    data: [FieldIds.customer_link, Customers_FieldIds.name]
+  }
+}
+```
+
+### Emoji Based on Own Phase
+
+```javascript
+// In name function: use activity's own phase, not parent workflow phase
+functionVariables: {
+  myMeta: {
+    type: "=",
+    data: ["meta"]  // Returns this activity's metadata
+  },
+  donePhase: {
+    type: "?",
+    data: [WorkflowIds.this_workflow, PhaseIds.done]
+  }
+}
+
+// In name function
+function nameWithEmoji(dep) {
+  const myPhase = dep.myMeta ? dep.myMeta.phase : null;
+  const donePhase = dep.donePhase;
+
+  const prefix = (myPhase === donePhase) ? "✅ " : "🔄 ";
+  return prefix + dep.activityName;
+}
+```
+
+**Key:** Compare against the activity's OWN phase (from `"data"` metadata), not the parent workflow's phase.
+
+---
+
+## Code Style
+
+**Use `const` and `let`** - NOT `var`:
+```javascript
+// Correct
+const prices = dep.prices || [];
+let total = 0;
+
+// Wrong
+var prices = dep.prices || [];
+```
+
+---
+
+## Critical Rules
+
+1. **ES6 JavaScript only** - No TypeScript syntax in function body
+2. **Never return null/undefined** - Always return valid typed value
+3. **Handle null inputs** - Use `|| 0` or `|| ""` defaults
+4. **Same inputs = same outputs** - No randomness, deterministic
+5. **Helpers inside function** - Define helper functions in function body
+6. **Use enums** - Never hardcode field/workflow IDs
+7. **updateMany single-workflow rule** - `v3.activity.updateMany` targets one workflow per call. For cascading updates across multiple workflows, create separate function fields per target workflow. Don't mix activities from different workflows in one payload
+8. **Double-wrapped array for generic CRUD** - When outputting a payload for the monolith `POST /api/update-activities` handler, use `[[{_id, phaseId}, ...]]` (double-wrapped). The handler spreads parsed JSON as `updateMany(...args)`, so the first arg must be the array. Single-wrapped `[{_id, phaseId}]` causes "must be an array" validation error
+9. **Empty string validation** - Hailer rejects empty string `''` with "value is not allowed to be empty". Always return `'[]'` or a valid non-empty string as default from function fields
+10. **Data metadata shorthand** - `type: "="` with `data: ["data"]` returns this activity's metadata object (same as `data: ["meta"]`). Similarly, `type: "<"` with `data: [workflowId, "data"]` returns array of metadata objects for linked activities
+
+---
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `var arr = dep.arr` | `const arr = dep.arr \|\| []` |
+| `arr[i] * 2` | `(Number(arr[i]) \|\| 0) * 2` |
+| `data[i].phase` | `data[i] ? data[i].phase : null` |
+| Assuming arrays match across workflows | Only same-workflow arrays are parallel |
+| Hardcoding phase IDs | Use `?` static variables with enums |
+
+---
+
+## Checklist
+
+Before creating a function with backlinks:
+
+- [ ] All `<` arrays have `|| []` default
+- [ ] Individual array values use `Number(x) || 0`
+- [ ] Data metadata access has null check
+- [ ] Phase comparisons use `?` static variables
+- [ ] Using enums from workspace for all IDs
+- [ ] Tested with Vitest before push

package/.claude/skills/SDK-generate-skill/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: SDK-generate-skill
+description: TypeScript type generation from Hailer workspace
+version: 1.0.0
+triggers: Generate types, TypeScript generation, update types, enums
+---
+
+# SDK Type Generation
+
+Generate TypeScript types from your Hailer workspace configuration.
+
+## Overview
+
+The SDK generates TypeScript types and enums from your workspace configuration, providing type-safe access to:
+- Workflow IDs
+- Field IDs
+- Phase IDs
+- Team IDs
+- Group IDs
+- Member IDs
+
+---
+
+## Generated Files
+
+After `npm run pull`, these files are auto-generated:
+
+```
+workspace/
+├── enums.ts        # Type-safe ID constants (DO NOT EDIT)
+├── hailer.d.ts     # TypeScript definitions (DO NOT EDIT)
+```
+
+---
+
+## Using Enums
+
+```typescript
+import {
+  WorkflowIds,
+  Tasks_FieldIds,
+  Tasks_PhaseIds,
+  TeamIds,
+  WorkspaceMembers
+} from './workspace/enums';
+
+// Reference workflow
+const workflowId = WorkflowIds.tasks;
+
+// Reference field
+const fieldId = Tasks_FieldIds.due_date;
+
+// Reference phase
+const phaseId = Tasks_PhaseIds.in_progress;
+```
+
+---
+
+## Regenerating Types
+
+Types are regenerated automatically when you run:
+
+```bash
+npm run pull
+```
+
+**When to regenerate:**
+- After pushing new fields/phases/workflows
+- After team/group changes
+- When enums seem out of date
+
+---
+
+## Important Notes
+
+1. **Never edit enums.ts manually** - It's auto-generated
+2. **Pull after push** - Get new IDs into enums after adding items
+3. **Use enums everywhere** - Never hardcode IDs as strings
+4. **Type safety** - TypeScript will catch invalid ID references
+
+---
+
+## Troubleshooting
+
+**Enum not found after adding field:**
+1. Ensure you ran `npm run fields-push:force`
+2. Run `npm run pull` to regenerate enums
+3. Check that the field was actually created in Hailer
+
+**Type errors after changes:**
+1. Run `npm run pull` to sync
+2. Restart TypeScript server in your IDE