@hailer/mcp 0.0.1

package/.claude/skills/hailer-api/references/workspaces-users.md

@@ -0,0 +1,445 @@
+# Hailer Workspaces & Users API
+
+## Workspaces
+
+Workspaces are top-level organizational units containing activities, datasets, files, and users.
+
+### Get Workspace
+
+```http
+GET /v3/workspaces/{workspace_id}
+```
+
+**Response:**
+```json
+{
+  "id": "ws_123",
+  "name": "Rekna Production",
+  "description": "Main workspace for Rekna operations",
+  "created_at": "2024-01-01T00:00:00Z",
+  "settings": {
+    "timezone": "Europe/Helsinki",
+    "language": "fi",
+    "date_format": "DD.MM.YYYY"
+  },
+  "member_count": 25,
+  "activity_count": 1523
+}
+```
+
+### List Workspaces
+
+```http
+GET /v3/workspaces
+```
+
+Returns all workspaces the authenticated user has access to.
+
+### Create Workspace
+
+```http
+POST /v3/workspaces
+Content-Type: application/json
+
+{
+  "name": "New Project Workspace",
+  "description": "Workspace for new project",
+  "settings": {
+    "timezone": "Europe/Helsinki",
+    "language": "fi"
+  }
+}
+```
+
+### Update Workspace
+
+```http
+PATCH /v3/workspaces/{workspace_id}
+Content-Type: application/json
+
+{
+  "name": "Updated Workspace Name",
+  "description": "New description"
+}
+```
+
+### Delete Workspace
+
+```http
+DELETE /v3/workspaces/{workspace_id}
+```
+
+⚠️ **Warning:** Deletes all activities, datasets, files, and content within the workspace.
+
+## Workspace Settings
+
+### Update Settings
+
+```http
+PATCH /v3/workspaces/{workspace_id}/settings
+Content-Type: application/json
+
+{
+  "timezone": "Europe/Helsinki",
+  "language": "fi",
+  "date_format": "DD.MM.YYYY",
+  "time_format": "24h",
+  "first_day_of_week": 1,
+  "working_hours": {
+    "start": "08:00",
+    "end": "17:00"
+  }
+}
+```
+
+## Users
+
+### Get User Profile
+
+```http
+GET /v3/users/me
+```
+
+**Response:**
+```json
+{
+  "id": "user_123",
+  "name": "Johan Rekna",
+  "email": "johan@rekna.fi",
+  "avatar_url": "https://avatars.hailer.com/user_123",
+  "timezone": "Europe/Helsinki",
+  "language": "fi",
+  "created_at": "2023-01-01T00:00:00Z"
+}
+```
+
+### Update User Profile
+
+```http
+PATCH /v3/users/me
+Content-Type: application/json
+
+{
+  "name": "Johan Rekna",
+  "timezone": "Europe/Helsinki",
+  "language": "fi"
+}
+```
+
+### Get User by ID
+
+```http
+GET /v3/users/{user_id}
+```
+
+### List Users in Workspace
+
+```http
+GET /v3/workspaces/{workspace_id}/users
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "user_123",
+      "name": "Johan Rekna",
+      "email": "johan@rekna.fi",
+      "role": "admin",
+      "joined_at": "2023-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+## Workspace Members
+
+### Add Member to Workspace
+
+```http
+POST /v3/workspaces/{workspace_id}/members
+Content-Type: application/json
+
+{
+  "email": "newuser@company.com",
+  "role": "member",
+  "send_invitation": true
+}
+```
+
+**Roles:**
+- `admin` - Full workspace control
+- `member` - Standard access
+- `guest` - Limited access (read-only to assigned activities)
+
+### Update Member Role
+
+```http
+PATCH /v3/workspaces/{workspace_id}/members/{user_id}
+Content-Type: application/json
+
+{
+  "role": "admin"
+}
+```
+
+### Remove Member
+
+```http
+DELETE /v3/workspaces/{workspace_id}/members/{user_id}
+```
+
+## Permissions System
+
+### Permission Levels
+
+Hailer uses role-based and object-based permissions:
+
+**Workspace Level:**
+- `admin` - Full control
+- `member` - Standard access
+- `guest` - Limited access
+
+**Activity Level:**
+- `owner` - Created the activity
+- `assigned` - Assigned to activity
+- `follower` - Following activity
+- `workspace_member` - Has workspace access
+
+**Dataset Level:**
+- `admin` - Full control
+- `editor` - Can modify records
+- `viewer` - Read-only
+
+### Check Permissions
+
+```http
+GET /v3/activities/{activity_id}/permissions/me
+```
+
+**Response:**
+```json
+{
+  "can_read": true,
+  "can_update": true,
+  "can_delete": false,
+  "can_assign": true,
+  "can_comment": true
+}
+```
+
+### List Activity Permissions
+
+```http
+GET /v3/activities/{activity_id}/permissions
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "user_id": "user_123",
+      "name": "Johan Rekna",
+      "role": "owner",
+      "permissions": ["read", "update", "delete", "assign"]
+    },
+    {
+      "user_id": "user_456",
+      "name": "Team Member",
+      "role": "assigned",
+      "permissions": ["read", "update", "comment"]
+    }
+  ]
+}
+```
+
+### Set Activity Permissions
+
+```http
+POST /v3/activities/{activity_id}/permissions
+Content-Type: application/json
+
+{
+  "user_id": "user_456",
+  "role": "assigned"
+}
+```
+
+### Grant Workspace-Wide Permissions
+
+```http
+POST /v3/workspaces/{workspace_id}/permissions
+Content-Type: application/json
+
+{
+  "user_id": "user_456",
+  "permissions": {
+    "can_create_activities": true,
+    "can_create_datasets": false,
+    "can_manage_workflows": false
+  }
+}
+```
+
+## Teams
+
+Groups of users within a workspace.
+
+### Create Team
+
+```http
+POST /v3/workspaces/{workspace_id}/teams
+Content-Type: application/json
+
+{
+  "name": "Development Team",
+  "description": "Software development team",
+  "member_ids": ["user_123", "user_456"]
+}
+```
+
+### Add Users to Team
+
+```http
+POST /v3/teams/{team_id}/members
+Content-Type: application/json
+
+{
+  "user_ids": ["user_789"]
+}
+```
+
+### Assign Team to Activity
+
+```http
+POST /v3/activities/{activity_id}/assignments
+Content-Type: application/json
+
+{
+  "team_id": "team_123"
+}
+```
+
+## API Keys
+
+Create API keys for programmatic access:
+
+### Create API Key
+
+```http
+POST /v3/api-keys
+Content-Type: application/json
+
+{
+  "name": "Automation Script",
+  "workspace_id": "ws_123",
+  "scopes": ["activities:read", "activities:write", "datasets:read"],
+  "expires_at": "2026-12-31T23:59:59Z"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "key_789",
+  "name": "Automation Script",
+  "key": "hsk_abc123def456...",
+  "scopes": ["activities:read", "activities:write", "datasets:read"],
+  "created_at": "2025-01-15T10:30:00Z",
+  "expires_at": "2026-12-31T23:59:59Z"
+}
+```
+
+⚠️ **Warning:** API key is only shown once. Store it securely.
+
+### List API Keys
+
+```http
+GET /v3/api-keys
+```
+
+### Revoke API Key
+
+```http
+DELETE /v3/api-keys/{key_id}
+```
+
+## Available Scopes
+
+### Activity Scopes
+- `activities:read` - Read activities
+- `activities:write` - Create/update activities
+- `activities:delete` - Delete activities
+
+### Dataset Scopes
+- `datasets:read` - Read datasets and records
+- `datasets:write` - Create/update datasets and records
+- `datasets:delete` - Delete datasets and records
+
+### File Scopes
+- `files:read` - Read files
+- `files:write` - Upload files
+- `files:delete` - Delete files
+
+### Workspace Scopes
+- `workspaces:read` - Read workspace information
+- `workspaces:write` - Update workspace settings
+- `workspaces:admin` - Full workspace administration
+
+### User Scopes
+- `users:read` - Read user information
+- `users:write` - Update user profiles
+
+## Audit Logs
+
+Track actions within workspace:
+
+### List Audit Logs
+
+```http
+GET /v3/workspaces/{workspace_id}/audit-logs
+```
+
+**Query Parameters:**
+- `user_id` - Filter by user
+- `action` - Filter by action type
+- `resource_type` - Filter by resource (activity, dataset, etc.)
+- `start_date` - ISO 8601 timestamp
+- `end_date` - ISO 8601 timestamp
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "log_123",
+      "action": "activity.created",
+      "user": {
+        "id": "user_123",
+        "name": "Johan Rekna"
+      },
+      "resource": {
+        "type": "activity",
+        "id": "act_456"
+      },
+      "timestamp": "2025-01-15T10:30:00Z",
+      "metadata": {
+        "ip_address": "192.168.1.1",
+        "user_agent": "Mozilla/5.0..."
+      }
+    }
+  ]
+}
+```
+
+## Best Practices
+
+1. **Use teams for group permissions** - Easier than managing individual user permissions
+2. **Create API keys with minimal scopes** - Principle of least privilege
+3. **Rotate API keys regularly** - Set expiration dates
+4. **Monitor audit logs** - Track suspicious activity
+5. **Remove inactive members** - Clean up workspace regularly
+6. **Use guest role for external collaborators** - Limit access appropriately
+7. **Check permissions before operations** - Avoid unnecessary API calls

package/.claude/skills/insight-api/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: Insight API Reference
+description: Complete reference for Hailer Insight API (SQL-like reporting over workflow data) - use when building insight-related MCP tools
+---
+
+# Insight API Reference Skill
+
+This skill provides comprehensive documentation for Hailer Insight API endpoints. Insights are SQL-like reports that query activity data from workflows, with support for joins across multiple workflows.
+
+## When to Use This Skill
+
+Invoke this skill when:
+- Building insight/reporting MCP tools
+- Creating SQL queries over workflow data
+- Working with cross-workflow data analysis
+- Implementing data visualization features
+- Managing insight permissions and sharing
+
+## What are Insights?
+
+**Insights = SQL queries over Hailer workflow data**
+
+Think of it as:
+- **Workflows** = Database tables
+- **Activities** = Rows in those tables
+- **Fields** = Columns in those tables
+- **Insights** = SQL SELECT queries with JOINs
+
+## Quick Navigation
+
+### Core Insight Operations
+- **v3.insight.create** - Create new insight with SQL query
+- **v3.insight.update** - Update existing insight
+- **v3.insight.list** - List all insights in workspace
+- **v3.insight.data** - Get query results (execute the SQL)
+- **v3.insight.preview** - Preview insight while designing (debugging)
+- **v3.insight.remove** - Delete an insight
+
+### Insight Management
+- **v3.insight.copy** - Duplicate an insight
+- **v3.insight.public** - Get public insight data (shared insights)
+- **v3.insight.member.add** - Add member permissions
+- **v3.insight.member.remove** - Remove member permissions
+
+## Key Concepts
+
+### Insight Structure
+
+```javascript
+{
+  name: 'Insight Name',
+  public: false,  // Whether insight is publicly accessible
+  sources: [
+    {
+      name: 'books',           // Table alias for SQL
+      workflowId: '<id>',      // Which workflow to query
+      fields: [
+        { name: 'title', meta: 'name' },      // Activity name
+        { name: 'publishDate', fieldId: '<fieldId>' }  // Custom field
+      ]
+    }
+  ],
+  query: 'SELECT title, publishDate FROM books'  // Standard SQL
+}
+```
+
+### Field References
+
+**Meta fields** (built-in):
+- `meta: '_id'` - Activity ID (for JOINs)
+- `meta: 'uid'` - User ID (creator)
+- `meta: 'team'` - Owner team ID
+- `meta: 'createdBy'` - Creator user ID
+- `meta: 'name'` - Activity name/title
+- `meta: 'created'` - Creation timestamp
+- `meta: 'updated'` - Last update timestamp
+- `meta: 'phaseId'` - Current phase ID
+- `meta: 'phaseName'` - Current phase name
+- `meta: 'phaseLastMove'` - Last phase change timestamp
+- `meta: 'workflowId'` - Workflow ID
+- `meta: 'workflowName'` - Workflow name
+- `meta: 'priority'` - Activity priority
+
+**Custom fields**:
+- `fieldId: '<fieldId>'` - Reference a workflow field by ID
+
+### SQL Query Support
+
+- Standard SELECT syntax
+- JOINs across multiple workflows
+- WHERE clauses
+- GROUP BY, ORDER BY
+- Aggregation functions (COUNT, SUM, AVG, etc.)
+
+## Common Use Cases
+
+1. **Single Workflow Report**: Query activities from one workflow
+2. **Cross-Workflow Join**: Join data from related workflows (via ActivityLinks)
+3. **Aggregated Reports**: COUNT, SUM, AVG across activities
+4. **Filtered Views**: WHERE clauses to filter activity data
+5. **Public Dashboards**: Share insights publicly with `public: true`
+
+## Documentation
+
+See [Insight API Endpoints](references/insight-endpoints.md) for complete endpoint documentation with request/response schemas and examples.
+
+## MCP Tool Building Rules
+
+When building Insight MCP tools:
+
+1. **Use PlaygroundTools.ts** for testing first
+2. **Follow the three-part pattern**:
+   - Description method (with SQL examples)
+   - Schema method (Zod validation)
+   - Handler method (implementation)
+3. **Use HailerApiClient** with socket calls
+4. **Validate SQL queries** before sending (basic syntax check)
+5. **Format responses** as markdown tables for readability
+6. **Handle permissions** - only workspace admins can modify sources
+
+## Example Patterns
+
+### Simple Report
+```javascript
+create_insight({
+  name: 'All Books',
+  sources: [{
+    name: 'books',
+    workflowId: bookWorkflowId,
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'author', fieldId: authorFieldId }
+    ]
+  }],
+  query: 'SELECT title, author FROM books'
+})
+```
+
+### Cross-Workflow Join
+```javascript
+create_insight({
+  name: 'Books with Authors',
+  sources: [
+    {
+      name: 'books',
+      workflowId: bookWorkflowId,
+      fields: [
+        { name: 'title', meta: 'name' },
+        { name: 'authorId', fieldId: authorLinkFieldId }
+      ]
+    },
+    {
+      name: 'authors',
+      workflowId: authorWorkflowId,
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'authorName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT books.title, authors.authorName
+    FROM books
+    LEFT JOIN authors ON books.authorId = authors.id
+  `
+})
+```
+
+## Preview vs Execute
+
+**v3.insight.preview**:
+- Used during design/debugging
+- Limited to ~20 activities for performance
+- Can be called frequently
+- Shows errors in SQL syntax
+
+**v3.insight.data**:
+- Executes full query on all activities
+- Returns complete results
+- Use after insight is finalized
+
+## Next Steps
+
+For complete endpoint documentation with request/response schemas and SQL examples, see:
+- [Insight API Endpoints](references/insight-endpoints.md) - All v3.insight.* endpoints