@hailer/mcp 1.0.28 → 1.1.2

package/.claude/skills/SDK-activity-patterns/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: SDK-activity-patterns
+description: Activity CRUD patterns - field value formats, dates, users, links, dropdowns
+version: 1.4.0
+triggers: Create activity, update activity, field values, date format, activitylink value
+---
+
+# Activity CRUD Patterns
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__hailer__create_activity` | Create new activity |
+| `mcp__hailer__update_activity` | Update existing activity |
+
+---
+
+## Create Activity
+
+```javascript
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  phaseId: "682ac815fba468d857d49904",
+  name: "New Task",  // Optional - activity name
+  fields: {
+    "fieldId1": "value1",
+    "fieldId2": "value2"
+  }
+})
+```
+
+## Update Activity
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  fields: {
+    "fieldId1": "new value"
+  },
+  // Optional: move to different phase
+  phaseId: "682ac815fba468d857d49906"
+})
+```
+
+---
+
+## Field Value Formats
+
+All valid field types from `hailer.d.ts`. **No multi-select types exist.**
+
+### Text Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `text` | String | `"Hello world"` |
+| `textarea` | String | `"Multi\nline\ntext"` |
+| `textunit` | String | `"100"` (unit in display) |
+
+### Number Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `numeric` | Number | `42` or `42.5` |
+| `numericunit` | Number | `99.99` (unit defined in field config) |
+
+### Date/Time Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `date` | Unix timestamp (ms) | `1730937600000` |
+| `datetime` | Unix timestamp (ms) | `1730937600000` |
+| `daterange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
+| `datetimerange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
+| `time` | Unix timestamp (ms, includes date!) | `1765863000000` |
+| `timerange` | Object | `{ start: 1765863000000, end: 1765915200000 }` (ms timestamps, includes date!) |
+
+**Date Conversion:**
+```javascript
+// JavaScript Date to Hailer timestamp
+const timestamp = new Date('2024-11-07').getTime();  // 1730937600000
+
+// Hailer timestamp to Date
+const date = new Date(1730937600000);
+
+// Time field: also Unix timestamp (includes date)
+const today = new Date();
+today.setUTCHours(9, 30, 0, 0);
+const timeValue = today.getTime();  // e.g., 1765863000000
+```
+
+### Selection Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `textpredefinedoptions` | **STRING** | `"High"` |
+
+**CRITICAL:** Value is STRING, not array! No multi-select type exists.
+```javascript
+// ✅ Correct
+fields: { priority: "High" }
+
+// ❌ Wrong
+fields: { priority: ["High"] }
+```
+
+### User & Team Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `users` | **STRING** (user ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
+| `teams` | **STRING** (team ID) | `"teamId123"` |
+
+**CRITICAL:** Value is STRING, not array! No multi-select types exist.
+```javascript
+// ✅ Correct
+fields: { assignee: "5f8a1b2c3d4e5f6a7b8c9d0e" }
+
+// ❌ Wrong
+fields: { assignee: ["5f8a1b2c3d4e5f6a7b8c9d0e"] }
+```
+
+### Link Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `activitylink` | **STRING** (activity ID) | `"692abc123def456"` |
+
+**CRITICAL:** Activity link is plain STRING ID, not array or object!
+```javascript
+// ✅ Correct - plain string ID
+fields: { customer: "692abc123def456" }
+
+// ❌ Wrong - array
+fields: { customer: ["692abc123def456"] }
+
+// ❌ Wrong - object (this is READ format, not WRITE format!)
+fields: { customer: { _id: "692abc123def456", name: "Acme" } }
+```
+
+**READ vs WRITE formats differ:**
+- **READ** (from API): `{ _id: string, name: string }` object
+- **WRITE** (to API): plain string ID only
+
+### Modified Fields (Checkbox & File)
+
+These use base types with a `modifier` in the field config:
+
+| Config | Value Format | Example |
+|--------|--------------|---------|
+| `numeric` + `modifier.checkbox: true` | Number | `1` (true) or `0` (false) |
+| `text` + `modifier.file: true` | Object | File reference (UI handles) |
+
+### Other Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `country` | ISO code | `"FI"`, `"SE"`, `"US"` |
+
+---
+
+## Complete Create Example
+
+```javascript
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  phaseId: "682ac815fba468d857d49904",
+  name: "Fix login bug",
+  fields: {
+    // Text
+    "description_abc": "Users cannot log in after password reset",
+
+    // Dropdown select (STRING!)
+    "priority_def": "High",
+
+    // User (STRING!)
+    "assignee_jkl": "5f8a1b2c3d4e5f6a7b8c9d0e",
+
+    // Activity link (STRING!)
+    "project_mno": "692abc123def456",
+
+    // Date (timestamp ms)
+    "due_date_pqr": 1730937600000,
+
+    // Number
+    "estimated_hours_stu": 4
+  }
+})
+```
+
+---
+
+## Bulk Creation
+
+Use the `activities[]` array for bulk creation. **Each activity must include its own teamId and phaseId.**
+
+```javascript
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  activities: [
+    {
+      name: "Task 1",
+      phaseId: "682ac815fba468d857d49904",
+      teamId: "690d2b2e2b3a4c5d6e7f8a9b",  // REQUIRED per activity!
+      fields: { "priority_abc": "High" }
+    },
+    {
+      name: "Task 2",
+      phaseId: "682ac815fba468d857d49904",
+      teamId: "690d2b2e2b3a4c5d6e7f8a9b",
+      fields: { "priority_abc": "Medium" }
+    }
+  ]
+})
+```
+
+**API:** Calls `v3.activity.createMany` via socket.
+
+### Single vs Bulk: Parameter Placement
+
+| Parameter | Single mode | Bulk mode |
+|-----------|-------------|-----------|
+| `name` | Top-level | Inside each `activities[]` item |
+| `phaseId` | Top-level | Inside each `activities[]` item |
+| `teamId` | Top-level | **Inside each `activities[]` item** |
+| `fields` | Top-level | Inside each `activities[]` item |
+| `workflowId` | Top-level | Top-level (shared) |
+
+**CRITICAL:** In bulk mode, `teamId` at the top level is **IGNORED**. Each activity in the array must have its own `teamId`. Omitting it causes "Missing team(s)" (code 127) unless the workflow has a default team.
+
+### Team ID Fallback Chain
+
+The MCP tool auto-fills `teamId` if omitted:
+1. Per-activity `teamId` (if provided) — **always provide this**
+2. Workflow's default team (`workflow.team`)
+3. First workspace team (last resort, may be wrong team)
+
+**Best practice:** Always pass `teamId` explicitly. Don't rely on fallbacks.
+
+---
+
+## Phase Transitions
+
+Move activity to different phase:
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  phaseId: "682ac815fba468d857d49906"  // Target phase
+})
+```
+
+Update fields AND move phase:
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  phaseId: "682ac815fba468d857d49906",
+  fields: {
+    "completed_date_abc": Date.now()
+  }
+})
+```
+
+---
+
+## Getting IDs
+
+Before creating/updating, you need:
+- **Workflow ID** - from `list_workflows` (real MongoDB ObjectId)
+- **Phase ID** - from `list_workflow_phases` (real MongoDB ObjectId)
+- **Field IDs** - from `get_workflow_schema` (real MongoDB ObjectId)
+- **User IDs** - from `search_workspace_users`
+- **Activity IDs** - from `list_activities` or previous create results
+
+**CRITICAL: MCP Tools Need Real ObjectIds**
+
+MCP tools require actual MongoDB ObjectIds (24-char hex strings), not enum key names.
+
+```javascript
+// ❌ WRONG - Passing enum KEY NAMES as strings
+mcp__hailer__create_activity({
+  workflowId: "Asiakkaat",           // ❌ This is the enum key, not the ID
+  fields: { "projekti_f84": "value" } // ❌ This is the enum key, not the ID
+})
+
+// ✅ CORRECT - Use real MongoDB ObjectIds
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",        // ✅ Real ObjectId
+  fields: { "68cbfec59b3869137fe2af84": "value" } // ✅ Real ObjectId
+})
+```
+
+**TypeScript code vs MCP calls:**
+- **TypeScript:** Use enums for type safety → `WorkflowIds.Asiakkaat` (resolves to the ObjectId)
+- **MCP tools:** Pass the actual ObjectId string → `"682ac815fba468d857d498f7"`
+
+**Where to get real IDs:**
+- `enums.ts` → enum values ARE the real ObjectIds
+- `list_workflows` → workflow `_id` field
+- `get_workflow_schema` → field `_id` property
+- Kenji agent → extracts IDs from workspace files
+
+**Agent pattern:** Orchestrator gets real IDs from Kenji (or enums.ts), passes to Dmitri.
+
+---
+
+## Date Helpers
+
+### Current Date
+```javascript
+const now = Date.now();  // Current timestamp ms
+```
+
+### Specific Date
+```javascript
+// From string
+const date = new Date('2024-11-07T09:00:00').getTime();
+
+// From components
+const date = new Date(2024, 10, 7, 9, 0, 0).getTime();  // Month is 0-indexed!
+```
+
+### Add Days
+```javascript
+const inOneWeek = Date.now() + (7 * 24 * 60 * 60 * 1000);
+```
+
+### Start of Day
+```javascript
+const today = new Date();
+today.setHours(0, 0, 0, 0);
+const startOfDay = today.getTime();
+```
+
+---
+
+## Time Field Values
+
+Time fields (`time` and `timerange`) store **Unix timestamps in milliseconds** that include the date.
+
+```javascript
+// Time field stores a full timestamp
+const timeField = 1765863000000;  // e.g., 2025-12-16 09:30:00 UTC
+
+// To extract just the time portion:
+const date = new Date(timeField);
+const hours = date.getUTCHours();    // 9
+const minutes = date.getUTCMinutes(); // 30
+
+// To create a time value for a specific time today:
+const today = new Date();
+today.setUTCHours(9, 30, 0, 0);
+const timeValue = today.getTime();
+```
+
+**Note:** When copying values between time/timerange fields, no conversion needed.
+
+---
+
+## Clearing Field Values
+
+To clear a field, set to empty string or null:
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  fields: {
+    "assignee_abc": "",     // Clear user
+    "due_date_def": null,   // Clear date
+    "notes_ghi": ""         // Clear text
+  }
+})
+```
+
+---
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `{ priority: ["High"] }` | `{ priority: "High" }` (string for single select) |
+| `{ assignee: ["userId"] }` | `{ assignee: "userId" }` (string for single user) |
+| `{ customer: ["actId"] }` | `{ customer: "actId" }` (string for activitylink) |
+| `{ date: "2024-11-07" }` | `{ date: 1730937600000 }` (timestamp ms) |
+| `{ time: "09:00" }` | `{ time: 1765863000000 }` (ms timestamp) |
+| `{ datetimerange: 1730937600000 }` | `{ datetimerange: { start: 1730937600000, end: 1731024000000 } }` (OBJECT!) |
+| `{ daterange: 1730937600000 }` | `{ daterange: { start: 1730937600000, end: 1731024000000 } }` (OBJECT!) |
+| `{ textField: 300 }` | `{ textField: "300" }` (text fields must be STRINGS, even for numbers) |
+| Guessing field IDs | Get from enums or `get_workflow_schema` |
+| Bulk create with top-level teamId | Put teamId INSIDE each activity object |
+| Creating without loading this skill | Always load SDK-activity-patterns before CRUD calls |
+
+---
+
+## Team Handling
+
+### Option 1: Pass teamId explicitly (recommended)
+Always include `teamId` in your create calls. For bulk mode, include it in **each activity object**.
+
+### Option 2: Workflow default team
+If the workflow has a default team set, the MCP tool auto-fills `teamId` when omitted.
+
+**Set default team:** Hailer UI → Workflow Settings → Default Team → Select team.
+
+### Common Error: "Missing team(s)" (Code 127)
+
+**Cause:** No teamId provided AND workflow has no default team AND no workspace teams found.
+
+**Fix options:**
+1. Pass `teamId` explicitly in every create call (best)
+2. Set default team on the workflow in Hailer UI
+3. Ask orchestrator/Kenji for available team IDs before creating
+
+---
+
+## Checklist
+
+Before creating/updating activities:
+
+- [ ] Have workflow ID (from enum or API)
+- [ ] Have phase ID (from enum or API)
+- [ ] Have field IDs (from enum or API)
+- [ ] Have **team ID** (from teams.ts or API) — don't rely on fallbacks
+- [ ] All values are **STRINGS** for select/user/link fields (no multi-select types exist)
+- [ ] Dates are **Unix timestamps in milliseconds**
+- [ ] Times are **Unix timestamps in milliseconds** (like dates)
+- [ ] **Bulk mode:** teamId, phaseId, fields are **inside each activity object**, not top-level