@hailer/mcp 1.1.16 → 1.1.17-beta.0

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

@@ -0,0 +1,238 @@
+---
+name: sdk-activity-patterns
+description: Activity CRUD patterns - field value formats, dates, users, links, dropdowns
+version: 1.5.0
+triggers: Create activity, update activity, field values, date format, activitylink value
+---
+
+# Activity CRUD Patterns
+
+## Create Activity
+
+```javascript
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  phaseId: "682ac815fba468d857d49904",
+  name: "New Task",  // Optional
+  fields: {
+    "fieldId1": "value1",
+    "fieldId2": "value2"
+  }
+})
+```
+
+## Update Activity
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  fields: { "fieldId1": "new value" },
+  phaseId: "682ac815fba468d857d49906"  // Optional: move to different phase
+})
+```
+
+---
+
+## Critical Field Value Rules
+
+**All single-value fields use STRING, not array.** No multi-select types exist in Hailer.
+
+```javascript
+// ✅ Correct
+fields: { priority: "High", assignee: "userId", customer: "actId" }
+
+// ❌ Wrong — arrays rejected
+fields: { priority: ["High"], assignee: ["userId"], customer: ["actId"] }
+```
+
+**Dates are Unix timestamps in milliseconds** (not ISO strings):
+```javascript
+fields: { due_date: new Date('2024-11-07').getTime() }  // 1730937600000
+```
+
+**Time fields** also use full millisecond timestamps including date:
+```javascript
+const today = new Date();
+today.setUTCHours(9, 30, 0, 0);
+fields: { start_time: today.getTime() }
+```
+
+**daterange / datetimerange** use object with `start` + `end`:
+```javascript
+fields: { period: { start: 1730937600000, end: 1731024000000 } }
+```
+
+**activitylink** is plain string ID — READ format (object with `_id`, `name`) differs from WRITE format:
+```javascript
+// ✅ Write: plain string ID
+fields: { customer: "692abc123def456" }
+
+// ❌ Wrong: object (this is what you get when reading)
+fields: { customer: { _id: "692abc123def456", name: "Acme" } }
+```
+
+**textpredefinedoptions** is the exact option string, not an array:
+```javascript
+fields: { status: "In Progress" }
+```
+
+**text fields must always be strings**, even for numeric-looking values:
+```javascript
+fields: { code: "300" }  // not 300
+```
+
+---
+
+## Modified Fields (Checkbox & File)
+
+These use base types with a `modifier` in the field config:
+
+| Config | Write Format |
+|--------|-------------|
+| `numeric` + `modifier.checkbox: true` | `1` (true) or `0` (false) |
+| `text` + `modifier.file: true` | File reference (UI handles upload) |
+
+---
+
+## Clearing Field Values
+
+```javascript
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  fields: {
+    "assignee_abc": "",     // Clear user
+    "due_date_def": null,   // Clear date
+    "notes_ghi": ""         // Clear text
+  }
+})
+```
+
+---
+
+## 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" }
+    }
+  ]
+})
+```
+
+### 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. Get IDs from `workspace/teams.ts`.
+
+### Common Error: "Missing team(s)" (Code 127)
+
+**Fix options:**
+1. Pass `teamId` explicitly in every create call (best)
+2. Set default team on the workflow in Hailer UI
+3. Ask orchestrator for available team IDs before creating
+
+---
+
+## Enum Key vs ObjectId Gotcha
+
+MCP tools require actual MongoDB ObjectIds (24-char hex strings), not enum key names.
+
+```javascript
+// ❌ WRONG - enum KEY NAME, not the ID
+mcp__hailer__create_activity({
+  workflowId: "Asiakkaat",            // enum key
+  fields: { "projekti_f84": "value" } // enum key
+})
+
+// ✅ CORRECT - real ObjectIds
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  fields: { "68cbfec59b3869137fe2af84": "value" }
+})
+```
+
+**TypeScript code vs MCP calls:**
+- **TypeScript:** Use enums for type safety → `WorkflowIds.Asiakkaat` resolves to the ObjectId
+- **MCP tools:** Pass the actual ObjectId string directly
+
+**Where to get real IDs:**
+- `workspace/enums.ts` → enum values ARE the real ObjectIds
+- `list_workflows` → workflow `_id` field
+- `get_workflow_schema` → field `_id` property
+
+---
+
+## Phase Transitions
+
+```javascript
+// Move only
+mcp__hailer__update_activity({ activityId: "...", phaseId: "..." })
+
+// Move + update fields
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  phaseId: "682ac815fba468d857d49906",
+  fields: { "completed_date_abc": Date.now() }
+})
+```
+
+---
+
+## 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
+
+---
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `{ priority: ["High"] }` | `{ priority: "High" }` (string) |
+| `{ assignee: ["userId"] }` | `{ assignee: "userId" }` (string) |
+| `{ customer: ["actId"] }` | `{ customer: "actId" }` (string) |
+| `{ date: "2024-11-07" }` | `{ date: 1730937600000 }` (timestamp ms) |
+| `{ time: "09:00" }` | `{ time: 1765863000000 }` (ms timestamp) |
+| `{ daterange: 1730937600000 }` | `{ daterange: { start: ..., end: ... } }` |
+| `{ textField: 300 }` | `{ textField: "300" }` (must be string) |
+| Passing enum key names as IDs | Use real 24-char hex ObjectIds |
+| Bulk create with top-level teamId | Put teamId INSIDE each activity object |

package/.claude/skills/{SDK-document-templates → sdk-document-templates}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: SDK-document-templates
+name: sdk-document-templates
 description: PDF/CSV document template patterns - field mappings, pdfmake structure, generation code
 version: 1.2.0
 triggers: Document template, PDF generation, CSV export, pdfmake, field mapping
@@ -21,6 +21,17 @@ workspace/[Workflow]_[id]/
 
 ## Template Lifecycle
 
+### Sync vs Push
+
+| Command | Creates new | Updates existing | Deletes removed |
+|---------|-------------|------------------|-----------------|
+| `templates sync` | Yes | No | Yes |
+| `templates push` | No | Yes | No |
+
+**New template flow:** Add entry to `templates.ts` → `npm run templates-sync` (creates template on server) → `npm run pull` (downloads generated folder + `template.config.ts` + `template.code.ts`) → edit config/code → `npm run templates-push`.
+
+**Updating existing:** Just edit `template.config.ts` or `template.code.ts` and run `npm run templates-push`.
+
 ### Creating New Template
 
 ```
@@ -317,91 +328,7 @@ export class invoice_abc {
 
 ---
 
-## pdfmake Patterns
-
-### Basic Text
-```javascript
-{ text: 'Hello World' }
-{ text: 'Bold text', bold: true }
-{ text: 'Large text', fontSize: 14 }
-```
-
-### Using Field Values
-```javascript
-const fields = this.fieldMap.fields;
-
-{ text: fields.invoiceNumber?.value || 'N/A' }
-{ text: fields.customerName?.label + ': ' + fields.customerName?.value }
-```
-
-### Columns
-```javascript
-{
-  columns: [
-    { width: '*', text: 'Left side' },
-    { width: 'auto', text: 'Right side' }
-  ]
-}
-```
-
-### Tables
-```javascript
-{
-  table: {
-    headerRows: 1,
-    widths: ['*', 100, 100],
-    body: [
-      // Header row
-      [
-        { text: 'Item', bold: true },
-        { text: 'Qty', bold: true },
-        { text: 'Price', bold: true }
-      ],
-      // Data rows
-      ['Product A', '10', '€100.00'],
-      ['Product B', '5', '€50.00']
-    ]
-  }
-}
-```
-
-### Table Spacing for Label:Value Grids
-
-For 4-column label:value layouts, use narrower label columns to keep values close:
-```javascript
-// ✅ Good: Values stay close to labels
-{
-  table: {
-    widths: [90, 'auto', 90, 'auto'],
-    body: [
-      [
-        { text: 'Tilaaja:', bold: true }, fields.customer?.value || '',
-        { text: 'Päivämäärä:', bold: true }, fields.date?.value || ''
-      ]
-    ]
-  },
-  layout: 'noBorders'
-}
-
-// ❌ Avoid: [120, '*', 120, '*'] spreads content too wide
-```
-```
-
-### Images
-```javascript
-// From fieldMap
-{
-  image: this.fieldMap.images?.logo?.value,
-  width: 150
-}
-
-// With fallback
-this.fieldMap.images?.logo?.value
-  ? { image: this.fieldMap.images.logo.value, width: 150 }
-  : { text: 'No logo', italics: true }
-```
-
-### Logo in Header (Two-Step Requirement)
+## Logo in Header (Two-Step Requirement)
 
 **CRITICAL:** Logo in PDF header requires BOTH config AND code reference:
 
@@ -437,111 +364,6 @@ getEmptyPdfDoc(fieldMap) {
 
 **Common mistake:** Adding logo to config but not referencing in header function → logo doesn't appear.
 
-### Margins & Spacing
-```javascript
-// [left, top, right, bottom]
-{ text: 'Padded', margin: [10, 20, 10, 20] }
-
-// Blank line
-{ text: ' ' }
-{ text: '', margin: [0, 10, 0, 0] }
-```
-
-### Styles
-```javascript
-// Define in getEmptyPdfDoc
-styles: {
-  header: { fontSize: 18, bold: true },
-  subheader: { fontSize: 14, bold: true },
-  tableHeader: { bold: true, fillColor: '#eeeeee' }
-}
-
-// Use
-{ text: 'Title', style: 'header' }
-```
-
----
-
-## Complete PDF Example
-
-```javascript
-async setPdfDefinition() {
-  const fields = this.fieldMap.fields;
-  const images = this.fieldMap.images;
-
-  const doc = this.getEmptyPdfDoc(this.fieldMap);
-
-  // Header with logo
-  doc.content.push({
-    columns: [
-      images?.logo?.value
-        ? { image: images.logo.value, width: 120 }
-        : { text: '' },
-      {
-        alignment: 'right',
-        stack: [
-          { text: 'INVOICE', style: 'header' },
-          { text: fields.invoiceNumber?.value || '' }
-        ]
-      }
-    ]
-  });
-
-  // Customer info
-  doc.content.push({ text: ' ' });
-  doc.content.push({
-    text: fields.customerName?.value || 'Unknown Customer',
-    style: 'subheader'
-  });
-
-  // Line items table
-  doc.content.push({ text: ' ' });
-  doc.content.push(this.buildLineItemsTable());
-
-  // Total
-  doc.content.push({
-    alignment: 'right',
-    text: `Total: €${fields.amount?.value || '0.00'}`,
-    bold: true,
-    margin: [0, 20, 0, 0]
-  });
-
-  const filename = `invoice_${fields.invoiceNumber?.value || 'draft'}`;
-  this.setDocument(doc, filename);
-}
-
-buildLineItemsTable() {
-  // Build from itemTable if available
-  const items = this.fieldMap.itemTable || [];
-
-  const body = [
-    // Header
-    [
-      { text: 'Description', bold: true },
-      { text: 'Qty', bold: true },
-      { text: 'Price', bold: true }
-    ]
-  ];
-
-  // Data rows
-  items.forEach(item => {
-    body.push([
-      item.description || '',
-      item.quantity || '',
-      item.price || ''
-    ]);
-  });
-
-  return {
-    table: {
-      headerRows: 1,
-      widths: ['*', 60, 80],
-      body
-    }
-  };
-}
-```
-
 ---
 
 ## CSV Templates
@@ -729,17 +551,6 @@ getEmptyPdfDoc(fieldMap) {
 
 ## Additional Patterns
 
-### Using Raw Field IDs vs Enums
-
-When orchestrator provides field IDs directly, use them as strings:
-```typescript
-// Raw field ID (common)
-value: "::67e697da6ada809b961c35b5"
-
-// With enums (when imported)
-value: `::${Workflow_FieldIds.date_abc}`
-```
-
 ### Clickable Links
 ```javascript
 if (fields.materialsLink?.value) {
@@ -881,144 +692,6 @@ if (isValidValue(fields.weight?.value)) {
 
 ---
 
-### Distinguishing Meaningful Zero from Empty/Null
-
-**Problem:** CO2 fields in Spolia required multiple iterations to filter correctly. Some zeros are meaningful (calculated values), others are empty/null placeholders.
-
-**Solution:** Use type-specific filtering logic:
-
-```typescript
-// Core pattern: Filter out truly empty values but keep meaningful zeros
-function shouldDisplayValue(value: unknown): boolean {
-  // Null and undefined are always empty
-  if (value === null || value === undefined) return false;
-
-  // Empty string is empty
-  if (value === '') return false;
-
-  // NaN is empty (for numeric fields)
-  if (typeof value === 'number' && isNaN(value)) return false;
-
-  // CRITICAL: Keep 0 - it's a meaningful numeric value
-  if (value === 0) return true;
-
-  return true;
-}
-
-// Pattern: Filter fields for display based on value type
-const displayFields = fields.filter(f => {
-  const value = activity.fields?.[f.id]?.value;
-
-  // Different rules per field type
-  switch (f.fieldType) {
-    case 'number':
-      // Keep 0, filter null/undefined/NaN
-      return shouldDisplayValue(value);
-
-    case 'text':
-      // Filter null, undefined, empty string
-      // Consider whitespace-only as empty
-      if (!value) return false;
-      if (typeof value === 'string' && value.trim() === '') return false;
-      return true;
-
-    case 'reference':
-      // Reference fields must have a valid ID string
-      // ID length varies by workflow - check for non-empty string
-      return typeof value === 'string' && value.trim().length > 0;
-
-    case 'date':
-      // Valid ISO date or timestamp
-      return value && !isNaN(new Date(value).getTime());
-
-    case 'boolean':
-      // Keep false and true - both are valid
-      return typeof value === 'boolean';
-
-    default:
-      return shouldDisplayValue(value);
-  }
-});
-```
-
-**Field-type specific examples:**
-
-```typescript
-// Numeric field: 0 is valid, undefined is empty
-const co2Value = fields.co2_emissions?.value;  // Could be 0, could be undefined
-if (shouldDisplayValue(co2Value)) {
-  // Display: "0 kgCO2e" ✓
-  // Don't display: undefined/null/NaN ✓
-}
-
-// Text field: Empty string is empty, whitespace-only is empty
-const description = fields.description?.value;
-if (description && typeof description === 'string' && description.trim() !== '') {
-  // Display: "Sample text" ✓
-  // Don't display: "" or "   " ✓
-}
-
-// Reference field: Check for non-empty string ID
-const linkedActivityId = fields.linked_activity?.value;
-if (typeof linkedActivityId === 'string' && linkedActivityId.trim().length > 0) {
-  // Display: "507f1f77bcf86cd799439011" ✓
-  // Don't display: "" or null ✓
-}
-
-// Boolean field: Both true and false are valid values
-const isActive = fields.active?.value;
-if (typeof isActive === 'boolean') {
-  // Display: false ✓ (don't filter out)
-  // Don't display: null/undefined ✓
-}
-
-// Function field returning formatted number: Keep meaningful zeros
-const calculatedCost = fields.total_cost?.value;  // Example: "0 €" or "150 €"
-if (shouldDisplayValue(calculatedCost)) {
-  // Display: "0 €" if it's a calculated zero ✓
-  // But if underlying value was null, filtered function may still output placeholder
-  // → Use isValidValue() helper (above) for extra safety
-}
-```
-
-**Real-world scenario from Spolia CO2 case:**
-
-```typescript
-// ❌ Bad: Filters out valid zeros
-const fields = activity.fields.filter(f => f.value);  // Loses 0 values!
-
-// ❌ Also bad: Checks truthiness
-if (activity.fields[fieldId]?.value) {  // false for 0!
-  // Won't render CO2: 0 kgCO2e/yksikkö
-}
-
-// ✅ Good: Type-aware filtering
-if (shouldDisplayValue(activity.fields[fieldId]?.value)) {
-  // Renders CO2: 0 kgCO2e/yksikkö ✓
-  // Skips CO2: undefined ✓
-}
-
-// ✅ Better: Field-specific logic
-const co2 = activity.fields[CO2_FIELD_ID]?.value;
-if (co2 !== null && co2 !== undefined && !isNaN(Number(co2))) {
-  doc.content.push({
-    text: `CO2: ${co2} kgCO2e/yksikkö`
-  });
-}
-```
-
-**Troubleshooting:**
-
-| Symptom | Likely Cause | Fix |
-|---------|--------------|-----|
-| "0 € " values missing from PDF | Using truthiness check (if value) | Use `shouldDisplayValue()` |
-| Function field shows "−" or placeholder | Underlying data is null but function formatted it | Use `isValidValue()` helper |
-| Some zeros showing, some not | Inconsistent filter logic per field type | Use switch statement by fieldType |
-| NaN appearing in output | Not checking `isNaN()` for numbers | Add NaN check |
-| Whitespace-only text showing | Not trimming string values | Use `value.trim() !== ''` for text |
-
----
-
 ## Checklist
 
 Before pushing template changes: