@hailer/mcp 0.0.1

package/.claude/skills/building-hailer-apps-skill/SKILL.md

@@ -0,0 +1,548 @@
+---
+name: Building Hailer Apps
+description: Complete guide for building Hailer apps with the @hailer/app-sdk - covers data loading, field access, API patterns, and common pitfalls
+---
+
+# Building Hailer Apps Skill
+
+Complete guide for building Hailer apps using the `@hailer/app-sdk` package. This skill covers critical patterns and gotchas that prevent data loading issues.
+
+## ⚠️ CRITICAL: Hailer App SDK vs MCP API
+
+**IMPORTANT:** The Hailer App SDK (used in React/frontend apps) is DIFFERENT from the MCP API (used by Claude Code tools).
+
+### Hailer App SDK (Frontend Apps)
+```typescript
+// Available on window.Hailer in browser apps
+const hailer = await window.Hailer.init({ appId: '...' });
+
+// NO hailer.api - access directly:
+hailer.activity.list(workflowId, phaseId, { limit: 100 })
+hailer.activity.get(activityId)
+hailer.activity.create(workflowId, data)
+```
+
+### MCP API (Claude Code Tools)
+```typescript
+// Used by Claude Code MCP tools
+await list_activities({ workflowId, phaseId, fields: [...] })
+await show_activity_by_id({ activityId })
+await create_activity({ workflowId, fields: {...} })
+```
+
+**Key Difference:** Frontend apps use `hailer.activity.list()` directly, NOT `hailer.api.activity.list()`!
+
+---
+
+## 1. Data Loading Pattern
+
+### ✅ CORRECT Pattern
+
+```typescript
+import { useEffect, useState } from 'react';
+
+function MyComponent({ hailer }) {
+  const [data, setData] = useState([]);
+
+  useEffect(() => {
+    loadData();
+  }, []);
+
+  async function loadData() {
+    // ✅ Call with 3 POSITIONAL PARAMETERS
+    const result = await hailer.activity.list(
+      '691ffdf84217e9e8434e5693',  // 1st: workflowId
+      '691ffdf84217e9e8434e569f',  // 2nd: phaseId
+      { limit: 100 }                // 3rd: options object
+    );
+
+    setData(result || []);
+  }
+}
+```
+
+### ❌ WRONG Patterns
+
+```typescript
+// ❌ WRONG: Using object with named params
+await hailer.activity.list({
+  process: workflowId,
+  phase: phaseId,
+  limit: 100
+});
+
+// ❌ WRONG: Using hailer.api (doesn't exist in frontend SDK)
+await hailer.api.activity.list(workflowId, phaseId, options);
+
+// ❌ WRONG: Missing options object (3rd param)
+await hailer.activity.list(workflowId, phaseId);
+```
+
+### SDK Method Signature
+
+```typescript
+hailer.activity.list(
+  workflowId: string,
+  phaseId: string,
+  options?: {
+    limit?: number,
+    skip?: number,
+    filters?: object
+  }
+): Promise<Activity[]>
+```
+
+---
+
+## 2. Field Access - The Critical Issue
+
+### Understanding Field Structure
+
+**Activities returned from API have fields keyed by FIELD IDs, NOT readable keys!**
+
+```typescript
+// ❌ WRONG: Fields are NOT keyed by readable names
+{
+  _id: "691ffe874217e9e8434e5800",
+  name: "Jude Bellingham Jr",
+  fields: {
+    playerName: { value: "Jude" },     // ❌ WRONG - This doesn't exist!
+    jerseyNumber: { value: 26 }        // ❌ WRONG - This doesn't exist!
+  }
+}
+
+// ✅ CORRECT: Fields are keyed by field IDs
+{
+  _id: "691ffe874217e9e8434e5800",
+  name: "Jude Bellingham Jr",
+  fields: {
+    "691ffdf84217e9e8434e5694": { type: "text", value: "Jude Bellingham Jr" },
+    "691ffdf84217e9e8434e5695": { type: "numeric", value: 26 },
+    "691ffdf84217e9e8434e5696": { type: "textpredefinedoptions", value: "Midfielder" }
+  }
+}
+```
+
+### Step 1: Get Field IDs Using MCP Tools
+
+**ALWAYS use MCP tools to get field schema BEFORE building components:**
+
+```typescript
+// In Claude Code, use MCP tool:
+await get_workflow_schema({
+  workflowId: "691ffdf84217e9e8434e5693",
+  phaseId: "691ffdf84217e9e8434e569f"
+});
+
+// Returns field mappings:
+// Player Name → 691ffdf84217e9e8434e5694
+// Jersey Number → 691ffdf84217e9e8434e5695
+// Position → 691ffdf84217e9e8434e5696
+```
+
+### Step 2: Create Field ID Constants
+
+```typescript
+// src/fieldIds.ts
+export const PLAYER_FIELDS = {
+  PLAYER_NAME: '691ffdf84217e9e8434e5694',
+  JERSEY_NUMBER: '691ffdf84217e9e8434e5695',
+  POSITION: '691ffdf84217e9e8434e5696',
+  DATE_OF_BIRTH: '691ffdf84217e9e8434e5697',
+  NATIONALITY: '691ffdf84217e9e8434e5698',
+  HEIGHT: '691ffdf84217e9e8434e5699',
+  WEIGHT: '691ffdf84217e9e8434e569a',
+} as const;
+
+// Helper function to safely get field value
+export function getFieldValue<T = any>(
+  fields: Record<string, { type: string; value: T }>,
+  fieldId: string
+): T | undefined {
+  return fields[fieldId]?.value;
+}
+```
+
+### Step 3: Use Field IDs in Components
+
+```typescript
+import { PLAYER_FIELDS, getFieldValue } from './fieldIds';
+
+function PlayerCard({ player }) {
+  return (
+    <div>
+      {/* ✅ CORRECT: Use getFieldValue with field ID */}
+      <h3>{getFieldValue(player.fields, PLAYER_FIELDS.PLAYER_NAME)}</h3>
+      <div>#{getFieldValue(player.fields, PLAYER_FIELDS.JERSEY_NUMBER)}</div>
+      <div>{getFieldValue(player.fields, PLAYER_FIELDS.POSITION)}</div>
+
+      {/* ❌ WRONG: This won't work! */}
+      <h3>{player.fields.playerName?.value}</h3>
+      <div>#{player.fields.jerseyNumber?.value}</div>
+    </div>
+  );
+}
+```
+
+---
+
+## 3. Complete Working Example
+
+### Full Component with Proper Data Loading
+
+```typescript
+import { useState, useEffect } from 'react';
+import { PLAYER_FIELDS, getFieldValue } from '../fieldIds';
+
+const WORKFLOW_IDS = {
+  PLAYERS: '691ffdf84217e9e8434e5693',
+  ACTIVE_PHASE: '691ffdf84217e9e8434e569f',
+};
+
+export default function PlayerList({ hailer }) {
+  const [players, setPlayers] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    loadPlayers();
+  }, []);
+
+  async function loadPlayers() {
+    try {
+      setLoading(true);
+
+      // ✅ Call with 3 positional parameters
+      const result = await hailer.activity.list(
+        WORKFLOW_IDS.PLAYERS,
+        WORKFLOW_IDS.ACTIVE_PHASE,
+        { limit: 100 }
+      );
+
+      console.log(`Loaded ${result?.length || 0} players`);
+      setPlayers(result || []);
+    } catch (error) {
+      console.error('Failed to load players:', error);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className="player-list">
+      {players.map(player => (
+        <div key={player._id} className="player-card">
+          {/* ✅ Use getFieldValue with field IDs */}
+          <h3>{getFieldValue(player.fields, PLAYER_FIELDS.PLAYER_NAME) || player.name}</h3>
+          <div className="jersey">
+            #{getFieldValue(player.fields, PLAYER_FIELDS.JERSEY_NUMBER) || '?'}
+          </div>
+          <div className="position">
+            {getFieldValue(player.fields, PLAYER_FIELDS.POSITION)}
+          </div>
+          <div className="stats">
+            <span>Height: {getFieldValue(player.fields, PLAYER_FIELDS.HEIGHT)} cm</span>
+            <span>Weight: {getFieldValue(player.fields, PLAYER_FIELDS.WEIGHT)} kg</span>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## 4. Common Field Types
+
+### Field Type Reference
+
+```typescript
+// text
+{ type: "text", value: "John Doe" }
+
+// numeric
+{ type: "numeric", value: 42 }
+
+// numericunit
+{ type: "numericunit", value: 180 }  // e.g., 180 cm
+
+// date
+{ type: "date", value: 1036454400000 }  // timestamp
+
+// textpredefinedoptions (dropdown)
+{ type: "textpredefinedoptions", value: "Active" }
+
+// country
+{ type: "country", value: { code: "US", name: "United States" } }
+
+// activitylink (reference to another activity)
+{ type: "activitylink", value: { _id: "...", name: "..." } }
+```
+
+### Type-Safe Field Access
+
+```typescript
+// For simple types
+const name = getFieldValue<string>(fields, PLAYER_FIELDS.PLAYER_NAME);
+const age = getFieldValue<number>(fields, PLAYER_FIELDS.AGE);
+
+// For complex types (country)
+const country = getFieldValue<{ code: string; name: string }>(
+  fields,
+  PLAYER_FIELDS.NATIONALITY
+);
+console.log(country?.name);
+
+// For activity links
+const team = getFieldValue<{ _id: string; name: string }>(
+  fields,
+  PLAYER_FIELDS.CURRENT_TEAM
+);
+console.log(team?.name);
+```
+
+---
+
+## 5. Development Workflow
+
+### Step-by-Step: Building a Hailer App Component
+
+1. **Use MCP tool to get schema**
+   ```typescript
+   await get_workflow_schema({
+     workflowId: "...",
+     phaseId: "..."
+   });
+   ```
+
+2. **Create field ID constants**
+   ```typescript
+   // src/fieldIds.ts
+   export const WORKFLOW_FIELDS = {
+     FIELD_NAME: 'field-id-from-schema',
+   };
+   ```
+
+3. **Create component with proper data loading**
+   ```typescript
+   // Use 3-param signature for hailer.activity.list()
+   const data = await hailer.activity.list(workflowId, phaseId, options);
+   ```
+
+4. **Access fields using field IDs**
+   ```typescript
+   // Use getFieldValue(fields, FIELD_ID)
+   const value = getFieldValue(item.fields, WORKFLOW_FIELDS.FIELD_NAME);
+   ```
+
+5. **Test and verify data loads**
+   ```typescript
+   console.log('Loaded data:', data);
+   console.log('First item fields:', data[0]?.fields);
+   ```
+
+---
+
+## 6. Debugging Data Loading Issues
+
+### Quick Diagnostics
+
+```typescript
+async function loadPlayers() {
+  try {
+    console.log('=== DEBUG DATA LOADING ===');
+
+    // 1. Check hailer object
+    console.log('hailer:', hailer);
+    console.log('hailer.activity:', hailer.activity);
+    console.log('hailer.activity.list:', typeof hailer.activity.list);
+
+    // 2. Call API
+    const result = await hailer.activity.list(workflowId, phaseId, { limit: 10 });
+
+    // 3. Check result structure
+    console.log('Result:', result);
+    console.log('Result length:', result?.length);
+    console.log('First item:', result?.[0]);
+    console.log('First item fields:', result?.[0]?.fields);
+    console.log('Field keys:', Object.keys(result?.[0]?.fields || {}));
+
+    return result;
+  } catch (error) {
+    console.error('Load failed:', error);
+  }
+}
+```
+
+### Common Issues and Solutions
+
+| Issue | Symptom | Solution |
+|-------|---------|----------|
+| `Cannot read properties of undefined (reading 'activity')` | `hailer.api` doesn't exist | Use `hailer.activity`, NOT `hailer.api.activity` |
+| `"processId" must be a string` | Passing object instead of positional params | Use 3 positional params: `list(workflowId, phaseId, options)` |
+| Fields showing as `undefined` | Using readable keys like `fields.playerName` | Use field IDs: `fields['691ffdf...']` or `getFieldValue()` |
+| Empty data displayed | Data loads but doesn't render | Check field access - use correct field IDs |
+
+---
+
+## 7. Loading Data from Multiple Phases
+
+```typescript
+async function loadAllPlayers() {
+  const allPlayers = [];
+
+  // Load from multiple phases
+  const phases = [
+    { id: '691ffdf84217e9e8434e569f', name: 'Active' },
+    { id: '691ffdf84217e9e8434e56a0', name: 'On Loan' },
+    { id: '691ffdf84217e9e8434e56a1', name: 'Injured' },
+  ];
+
+  for (const phase of phases) {
+    try {
+      const result = await hailer.activity.list(
+        WORKFLOW_IDS.PLAYERS,
+        phase.id,
+        { limit: 100 }
+      );
+
+      console.log(`Loaded ${result?.length || 0} players from ${phase.name}`);
+
+      if (result && Array.isArray(result)) {
+        allPlayers.push(...result);
+      }
+    } catch (error) {
+      console.error(`Failed to load ${phase.name}:`, error);
+    }
+  }
+
+  return allPlayers;
+}
+```
+
+---
+
+## 8. Best Practices
+
+### ✅ DO
+
+1. **Always get schema first** - Use MCP `get_workflow_schema` tool
+2. **Create field ID constants** - Store in `src/fieldIds.ts`
+3. **Use helper functions** - `getFieldValue()` for safe access
+4. **Log during development** - Verify data structure
+5. **Handle errors** - Wrap API calls in try-catch
+6. **Use TypeScript** - Type your field values
+
+### ❌ DON'T
+
+1. **Don't use readable keys** - `fields.playerName` won't work
+2. **Don't use hailer.api** - It doesn't exist in frontend SDK
+3. **Don't pass objects to list()** - Use positional params
+4. **Don't assume field structure** - Always check schema first
+5. **Don't forget error handling** - API calls can fail
+6. **Don't hardcode field IDs inline** - Use constants
+
+---
+
+## 9. TypeScript Definitions
+
+```typescript
+// src/types.ts
+export interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, FieldValue>;
+  currentPhase: string;
+  process: string;
+  created: number;
+  updated: number;
+  active: boolean;
+  discussion?: string;
+  files?: any[];
+  followers?: string[];
+}
+
+export interface FieldValue<T = any> {
+  type: string;
+  value: T;
+}
+
+// Hailer client type
+export interface HailerClient {
+  activity: {
+    list(workflowId: string, phaseId: string, options?: {
+      limit?: number;
+      skip?: number;
+      filters?: any;
+    }): Promise<Activity[]>;
+
+    get(activityId: string): Promise<Activity>;
+
+    create(workflowId: string, data: {
+      name: string;
+      fields?: Record<string, any>;
+      phaseId?: string;
+    }): Promise<Activity>;
+
+    update(activityId: string, data: Partial<Activity>): Promise<Activity>;
+
+    remove(activityId: string): Promise<void>;
+  };
+
+  // Other modules...
+  workflow: any;
+  insight: any;
+  user: any;
+}
+```
+
+---
+
+## 10. Testing Checklist
+
+Before deploying your Hailer app:
+
+- [ ] Data loads successfully (`hailer.activity.list()` works)
+- [ ] Field IDs are correct (checked with `get_workflow_schema`)
+- [ ] Field values display properly (using `getFieldValue()`)
+- [ ] All required fields are accessible
+- [ ] Error handling is in place
+- [ ] Loading states are handled
+- [ ] Console has no errors
+- [ ] Data refreshes correctly
+- [ ] Multiple phases work (if applicable)
+- [ ] TypeScript types are correct
+
+---
+
+## Summary
+
+**Key Points to Remember:**
+
+1. **SDK vs MCP API** - Frontend uses `hailer.activity`, NOT `hailer.api.activity`
+2. **3 Positional Params** - `list(workflowId, phaseId, options)`
+3. **Field IDs, Not Keys** - Fields are keyed by IDs, not readable names
+4. **Get Schema First** - Always use MCP `get_workflow_schema` tool
+5. **Use Constants** - Store field IDs in `src/fieldIds.ts`
+6. **Helper Functions** - Use `getFieldValue()` for safe access
+
+**Critical Pattern:**
+```typescript
+// 1. Get schema (in Claude Code)
+await get_workflow_schema({ workflowId, phaseId });
+
+// 2. Create constants
+export const FIELDS = { NAME: 'field-id-from-schema' };
+
+// 3. Load data
+const data = await hailer.activity.list(workflowId, phaseId, { limit: 100 });
+
+// 4. Access fields
+const name = getFieldValue(data[0].fields, FIELDS.NAME);
+```
+
+Follow these patterns and your Hailer app will load data correctly from the start!