@hailer/mcp 1.1.11 → 1.1.13

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

@@ -1,542 +0,0 @@
----
-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

@@ -1,92 +0,0 @@
----
-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