@hailer/mcp 0.0.1

package/.claude/skills/mcp-tools/references/data-structures.md

@@ -0,0 +1,554 @@
+# Data Structures Reference
+
+Complete schemas for Hailer data types including workflows, activities, fields, and relationships.
+
+---
+
+## Workflow Structure
+
+Workflows (called `processes` in API) define the schema and lifecycle for activities.
+
+### Complete Workflow Schema
+
+```javascript
+{
+  "_id": "68446dc05b30685f67c6fcd4",      // Workflow ID
+  "name": "Topics",                        // Display name
+  "defaultView": "kanban",                 // Default UI view (kanban, list, calendar)
+  "enableMessenger": true,                 // Enable discussion for activities
+  "createdActivities": 42,                 // Activity count
+
+  // Field definitions
+  "fields": {
+    "684d5e4568e9345040ad050e": {
+      "label": "Related to",
+      "type": "activitylink",              // Field type
+      "key": "relatedTo",                  // Readable key for returnFlat mode
+      "required": false,
+      "editable": true,
+      "data": ["68446dc05b30685f67c6fcd4"] // For activitylink: target workflow IDs
+    },
+    "684d5e4568e9345040ad050f": {
+      "label": "Description",
+      "type": "textarea",
+      "key": "description",
+      "required": false
+    },
+    "684d5e4568e9345040ad0510": {
+      "label": "Priority",
+      "type": "text",
+      "key": "priority",
+      "required": false
+    }
+  },
+
+  // Field display order
+  "fieldsOrder": [
+    "684d5e4568e9345040ad050e",
+    "684d5e4568e9345040ad050f",
+    "684d5e4568e9345040ad0510"
+  ],
+
+  // Phase definitions (workflow stages)
+  "phases": {
+    "6901ebb64fd57ff171f43338": {
+      "name": "New",
+      "isInitial": true,                   // Default phase for new activities
+      "isEndpoint": false,                 // Is this a final phase?
+      "possibleNextPhase": [
+        "6901ebb64fd57ff171f43339"
+      ],
+      "fields": [                          // Phase-specific required fields
+        "684d5e4568e9345040ad050e"
+      ]
+    },
+    "6901ebb64fd57ff171f43339": {
+      "name": "In Progress",
+      "isEndpoint": false,
+      "possibleNextPhase": [
+        "6901ebb64fd57ff171f4333a"
+      ]
+    },
+    "6901ebb64fd57ff171f4333a": {
+      "name": "Done",
+      "isEndpoint": true,                  // Final phase
+      "possibleNextPhase": []
+    }
+  },
+
+  // Phase display order
+  "phasesOrder": [
+    "6901ebb64fd57ff171f43338",
+    "6901ebb64fd57ff171f43339",
+    "6901ebb64fd57ff171f4333a"
+  ]
+}
+```
+
+---
+
+## Field Types
+
+### Common Field Types
+
+| Type | Description | Example Use |
+|------|-------------|-------------|
+| `text` | Single-line text | Name, title, status |
+| `textarea` | Multi-line text | Description, notes |
+| `numeric` | Number | Count, amount |
+| `date` | Date only | Due date, start date |
+| `datetime` | Date and time | Created, updated |
+| `activitylink` | Link to other activities | Related to, parent, dependencies |
+| `user` | User reference | Assigned to, created by |
+| `select` | Single selection | Priority, category |
+| `multiselect` | Multiple selections | Tags, labels |
+
+### ActivityLink Field (Relationships)
+
+The most important field type for building hierarchies and relationships.
+
+```javascript
+{
+  "type": "activitylink",
+  "label": "Related to",
+  "key": "relatedTo",                     // Used with returnFlat
+  "data": [                               // Target workflow IDs
+    "68446dc05b30685f67c6fcd4",          // Can link to Project workflow
+    "69021153a27e596689bdf95d"           // Can also link to Topic workflow
+  ],
+  "required": false,
+  "editable": true
+}
+```
+
+**Value Format**:
+- Single link: `"activity-id"`
+- Multiple links: `["activity-id-1", "activity-id-2"]`
+
+**Example Hierarchy**:
+```
+Projects (workflow 1)
+  ↑ linked via "project" field
+Topics (workflow 2)
+  ↑ linked via "relatedTo" field
+Tasks (workflow 3)
+```
+
+---
+
+## Activity Structure
+
+Activities are instances of workflows, containing actual data.
+
+### Activity Without returnFlat
+
+Default format with field IDs as keys:
+
+```javascript
+{
+  "_id": "690300db68e9345040ad078b",
+  "name": "Task Title",
+  "processId": "68446dc05b30685f67c6fcd4",    // Workflow ID
+  "phaseId": "6901ebb64fd57ff171f43338",      // Current phase
+  "discussion": "684be83f68e9345040ad02a3",   // Discussion ID
+  "created": "2025-10-30T09:00:00Z",
+  "updated": "2025-10-30T10:00:00Z",
+  "creator": "user-id",
+
+  "fields": {
+    "684d5e4568e9345040ad050e": {           // Field ID as key
+      "value": "topic-activity-id"          // Actual value
+    },
+    "684d5e4568e9345040ad050f": {
+      "value": "This is the description text"
+    },
+    "684d5e4568e9345040ad0510": {
+      "value": "high"
+    }
+  }
+}
+```
+
+### Activity With returnFlat: true
+
+Cleaner format using field keys instead of IDs:
+
+```javascript
+{
+  "_id": "690300db68e9345040ad078b",
+  "name": "Task Title",
+  "processId": "68446dc05b30685f67c6fcd4",
+  "phaseId": "6901ebb64fd57ff171f43338",
+  "discussion": "684be83f68e9345040ad02a3",
+  "created": "2025-10-30T09:00:00Z",
+  "updated": "2025-10-30T10:00:00Z",
+
+  // Fields directly accessible by key
+  "relatedTo": "topic-activity-id",        // Much cleaner!
+  "description": "This is the description text",
+  "priority": "high"
+}
+```
+
+**Always use returnFlat: true in new code** - it's much easier to work with.
+
+---
+
+## Activity Relationships Example
+
+Real-world example showing how Projects → Topics → Tasks are linked.
+
+### Projects Workflow
+
+```javascript
+{
+  "_id": "69021153a27e596689bdf95d",
+  "name": "Projects",
+  "fields": {
+    "company-field-id": {
+      "label": "Company",
+      "type": "activitylink",
+      "key": "company",
+      "data": ["69021153a27e596689bdf957"]  // Links to Companies workflow
+    }
+  }
+}
+```
+
+### Topics Workflow
+
+```javascript
+{
+  "_id": "68446dc05b30685f67c6fcd4",
+  "name": "Topics",
+  "fields": {
+    "project-field-id": {
+      "label": "Project",
+      "type": "activitylink",
+      "key": "project",
+      "data": ["69021153a27e596689bdf95d"]  // Links to Projects workflow
+    }
+  }
+}
+```
+
+### Tasks Workflow
+
+```javascript
+{
+  "_id": "69021153a27e596689bdf960",
+  "name": "Tasks",
+  "fields": {
+    "related-to-field-id": {
+      "label": "Related to",
+      "type": "activitylink",
+      "key": "relatedTo",
+      "data": ["68446dc05b30685f67c6fcd4"]  // Links to Topics workflow
+    }
+  }
+}
+```
+
+### Sample Activities (with returnFlat)
+
+**Project Activity**:
+```javascript
+{
+  "_id": "project-123",
+  "name": "Website Redesign",
+  "processId": "69021153a27e596689bdf95d",
+  "company": "company-456"                   // Links to company activity
+}
+```
+
+**Topic Activity**:
+```javascript
+{
+  "_id": "topic-789",
+  "name": "Homepage Design",
+  "processId": "68446dc05b30685f67c6fcd4",
+  "project": "project-123"                   // Links to project above
+}
+```
+
+**Task Activity**:
+```javascript
+{
+  "_id": "task-xyz",
+  "name": "Create hero section mockup",
+  "processId": "69021153a27e596689bdf960",
+  "relatedTo": "topic-789"                   // Links to topic above
+}
+```
+
+**Traversing the Hierarchy**:
+```typescript
+// Get task
+const task = await getActivity("task-xyz");  // relatedTo: "topic-789"
+
+// Get parent topic
+const topic = await getActivity(task.relatedTo);  // project: "project-123"
+
+// Get parent project
+const project = await getActivity(topic.project);  // company: "company-456"
+
+// Get parent company
+const company = await getActivity(project.company);
+
+// Full path: company → project → topic → task
+```
+
+---
+
+## Discussion Structure
+
+### Discussion Object
+
+```javascript
+{
+  "_id": "684be83f68e9345040ad02a3",
+  "activity": "activity-id",               // Linked activity (if any)
+  "participants": [
+    {
+      "_id": "user-id",
+      "name": "User Name",
+      "email": "user@example.com"
+    }
+  ],
+  "unreadCount": 3
+}
+```
+
+### Message Object
+
+```javascript
+{
+  "_id": "message-id",
+  "msg": "Message text content",
+  "user": {
+    "_id": "user-id",
+    "name": "User Name"
+  },
+  "discussion": "discussion-id",
+  "created": "2025-10-30T10:00:00Z",
+  "replyTo": "parent-message-id",          // If replying
+  "mentions": ["user-id-1", "user-id-2"],  // @mentioned users
+  "edited": "2025-10-30T10:05:00Z"        // If edited
+}
+```
+
+---
+
+## User Structure
+
+```javascript
+{
+  "_id": "user-id",
+  "name": "Johan Rekna",
+  "email": "johan@example.com",
+  "avatar": "https://...",
+  "role": "admin",                         // admin, member, guest
+  "networks": ["network-id-1"]             // Workspaces user belongs to
+}
+```
+
+---
+
+## Workspace (Network) Structure
+
+```javascript
+{
+  "_id": "68446c045b30685f67c6fc8c",
+  "name": "My Workspace",
+  "owner": "user-id",
+  "members": [
+    {
+      "_id": "user-id",
+      "role": "admin"
+    }
+  ],
+  "processes": [                           // Workflows in this workspace
+    {
+      "_id": "workflow-id",
+      "name": "Projects"
+    }
+  ]
+}
+```
+
+---
+
+## Working with Field Keys
+
+### Setting Up Field Keys
+
+When creating workflows, always define readable keys:
+
+```javascript
+{
+  "label": "Due Date",
+  "type": "date",
+  "key": "dueDate"        // Camel case, readable
+}
+```
+
+### Benefits of returnFlat
+
+**Without returnFlat**:
+```typescript
+const priority = activity.fields["684d5e4568e9345040ad0510"].value;
+const relatedId = activity.fields["684d5e4568e9345040ad050e"].value;
+```
+
+**With returnFlat**:
+```typescript
+const priority = activity.priority;
+const relatedId = activity.relatedTo;
+```
+
+Much cleaner and less error-prone!
+
+---
+
+## Field Validation
+
+### Required Fields
+
+```javascript
+{
+  "type": "text",
+  "required": true         // Must be provided when creating activity
+}
+```
+
+### Phase-Specific Fields
+
+```javascript
+"phases": {
+  "phase-id": {
+    "fields": ["field-id-1", "field-id-2"]  // Required for this phase
+  }
+}
+```
+
+### Field Constraints
+
+```javascript
+{
+  "type": "numeric",
+  "min": 0,
+  "max": 100
+}
+
+{
+  "type": "text",
+  "maxLength": 255
+}
+
+{
+  "type": "select",
+  "options": ["low", "medium", "high"]
+}
+```
+
+---
+
+## Type Definitions (TypeScript)
+
+Useful TypeScript interfaces for type safety:
+
+```typescript
+interface Workflow {
+  _id: string;
+  name: string;
+  fields: Record<string, WorkflowField>;
+  phases: Record<string, Phase>;
+  fieldsOrder: string[];
+  phasesOrder: string[];
+}
+
+interface WorkflowField {
+  label: string;
+  type: FieldType;
+  key?: string;
+  required?: boolean;
+  data?: string[];  // For activitylink: target workflow IDs
+}
+
+type FieldType =
+  | 'text'
+  | 'textarea'
+  | 'numeric'
+  | 'date'
+  | 'datetime'
+  | 'activitylink'
+  | 'user'
+  | 'select'
+  | 'multiselect';
+
+interface Phase {
+  name: string;
+  isInitial?: boolean;
+  isEndpoint?: boolean;
+  possibleNextPhase: string[];
+  fields?: string[];
+}
+
+interface Activity {
+  _id: string;
+  name: string;
+  processId: string;
+  phaseId: string;
+  discussion?: string;
+  created: string;
+  updated: string;
+  [key: string]: any;  // Field values with returnFlat
+}
+```
+
+---
+
+## Common Patterns
+
+### Finding Field IDs from Keys
+
+```typescript
+// Get field ID from key
+function getFieldIdByKey(workflow: Workflow, key: string): string | null {
+  for (const [fieldId, field] of Object.entries(workflow.fields)) {
+    if (field.key === key) {
+      return fieldId;
+    }
+  }
+  return null;
+}
+
+// Usage
+const priorityFieldId = getFieldIdByKey(workflow, 'priority');
+```
+
+### Building Activity Links
+
+```typescript
+// Create activity with link to parent
+await createActivity(workflowId, {
+  name: "Child Task",
+  fields: {
+    relatedTo: parentActivity._id  // Link using returnFlat key
+  }
+});
+```
+
+### Querying by Relationship
+
+```typescript
+// Find all tasks for a specific topic
+await listActivities(tasksWorkflowId, {
+  filters: {
+    and: [
+      { "relatedTo": { equalTo: topicActivityId } }
+    ]
+  },
+  returnFlat: true
+});
+```