@hailer/mcp 0.0.1

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

@@ -0,0 +1,283 @@
+---
+name: Hailer API
+description: Comprehensive technical reference for the Hailer API covering all endpoints (activities, datasets, insights/SQL, workflows, files, users), Python SDK, and best practices for building Hailer integrations.
+---
+
+# Hailer API Skill
+
+Comprehensive technical reference for the Hailer API covering all endpoints, methods, and SDK usage.
+
+## Quick Start
+
+This skill provides comprehensive API reference documentation for the Hailer API. The MCP server uses socket.io via `@hailer/cli` for most operations.
+
+**Local Development Configuration:**
+- Base URL: `https://api.hailer.local.gd`
+- API Version: v2/v3 (mixed usage)
+- Protocol: socket.io via `@hailer/cli`
+
+## API Overview
+
+**Base URL**: `https://api.hailer.local.gd`
+**Current Version**: `/v3` (with some `/v2` endpoints)
+**Authentication**: `hlrkey` header with auth token
+**Response Format**: JSON
+**Protocol**: Socket.io via `@hailer/cli` package
+
+## Core Modules
+
+### 1. Activities (`/v3/activity`)
+Task and project management system. Activities are the core unit of work in Hailer.
+
+**Key Operations:**
+- Create, read, update, delete activities
+- Batch operations for bulk management
+- Comments and discussions
+- File attachments
+- Status tracking and workflows
+- Assignments and permissions
+
+**Reference**: [activities.md](references/activities.md)
+
+### 2. Insights/SQL (`/v3/insights`)
+SQL-based querying system for data analysis across workspaces.
+
+**Key Features:**
+- SQLite-compatible queries
+- Access to activities, datasets, and workspace data
+- Aggregations and analytics
+- Saved queries for reuse
+- Real-time data analysis
+
+**Reference**: [insights.md](references/insights.md)
+
+### 3. Datasets (`/v3/datasets`)
+Structured data storage with type validation and relationships.
+
+**Key Features:**
+- Define custom data schemas
+- CRUD operations on records
+- Batch import/export
+- Reference fields for relationships
+- Field validation and constraints
+
+**Reference**: [datasets.md](references/datasets.md)
+
+### 4. Files (`/v3/files`)
+File upload, download, and management for activities and workspaces.
+
+**Key Features:**
+- Upload files up to 100MB
+- Automatic thumbnail generation
+- File sharing with expiration
+- Batch uploads
+- Direct S3 upload for large files
+
+**Reference**: [files.md](references/files.md)
+
+### 5. Workflows (`/v3/workflows`)
+Automated business process management and activity routing.
+
+**Key Features:**
+- Define multi-step workflows
+- Conditional logic and branching
+- Automatic activity transitions
+- Trigger workflows via API or events
+- Workflow templates
+
+**Reference**: [workflows.md](references/workflows.md)
+
+### 6. Workspaces (`/v2/core/init`)
+Top-level organizational units containing all resources.
+
+**Key Features:**
+- Workspace management
+- Member administration
+- Settings and configuration
+- Teams and groups
+- Audit logging
+
+**Reference**: [workspaces-users.md](references/workspaces-users.md)
+
+### 7. Authentication
+Multiple authentication methods for secure API access.
+
+**Methods:**
+- OAuth 2.0 (recommended for apps)
+- Access tokens
+- Session-based authentication
+- API keys with scoped permissions
+
+**Reference**: [authentication.md](references/authentication.md)
+
+## Integration with MCP Server
+
+The MCP server integrates with Hailer using:
+- `@hailer/cli` package for socket.io connections
+- Shared connection pool across MCP Server and MCP Client
+- User context caching per API key
+- Real-time signal processing for live updates
+
+See CLAUDE.md in the project root for detailed architecture information.
+
+## Common API Patterns
+
+### Activity Listing with v3 API
+
+```javascript
+// POST /v3/activity/list
+body: JSON.stringify([workflowFilter, requestOptions])
+
+// Example:
+[
+  { processId: "workflow-id", phaseId: "phase-id" }, // workflow filter
+  {
+    limit: 10,
+    page: 1, // v3 uses 1-based pagination
+    sortBy: "updated",
+    sortOrder: "desc",
+    returnFlat: true,
+    filters: {
+      and: [
+        { "field-id-company": { equalTo: "company-id" } },
+        { "field-id-created": { between: ["1234567890", "1234999999"] } }
+      ]
+    }
+  }
+]
+```
+
+### Activity Creation with v3 API
+
+```javascript
+// POST /v3/activity/createMany
+body: JSON.stringify([workflowId, [activityData], options])
+
+// Example:
+[
+  "68446dc05b30685f67c6fcd4", // workflowId
+  [{ name: "Task Title", fields: {} }], // activities array
+  { returnDocument: true, phaseId: "phase-id" } // options
+]
+```
+
+### Discussion Messages
+
+```javascript
+// POST /api/messenger/send
+body: JSON.stringify([messageData, discussionId])
+
+// Example:
+[
+  { msg: "Hello world!" }, // message object
+  "684be83f68e9345040ad02a3" // discussionId
+]
+```
+
+## API Best Practices
+
+### 1. Use Batch Operations
+- Batch create/update/delete is more efficient than individual operations
+- Maximum batch size is typically 100-1000 items depending on endpoint
+
+### 2. Handle Rate Limits
+- Default: 1000 requests/hour per user
+- Check `X-RateLimit-*` headers
+- Implement exponential backoff on 429 responses
+
+### 3. Optimize Queries
+- Use SQL `LIMIT` for large result sets
+- Add `WHERE` clauses to filter data at the database level
+- Create dataset indexes for frequently queried fields
+
+### 4. Secure API Keys
+- Use scoped API keys with minimal permissions
+- Set expiration dates
+- Rotate keys regularly
+- Never commit keys to source control
+
+### 5. Webhook Best Practices
+- Return 200 status quickly (< 5 seconds)
+- Process events asynchronously
+- Implement idempotency (handle duplicate events)
+- Verify webhook signatures
+
+### 6. File Uploads
+- Use direct S3 upload for files > 10MB
+- Stream large files instead of loading into memory
+- Generate and use thumbnails for images
+- Clean up temporary files
+
+### 7. Error Recovery
+- Implement retry logic for 5xx errors
+- Log errors with request IDs for debugging
+- Validate data before API calls
+- Check permissions before operations
+
+## Rate Limits
+
+| Tier | Requests/Hour | Burst |
+|------|---------------|-------|
+| Free | 1,000 | 20/minute |
+| Pro | 10,000 | 100/minute |
+| Enterprise | Custom | Custom |
+
+## Webhooks
+
+### Available Events
+
+**Activities:**
+- `activity.created`
+- `activity.updated`
+- `activity.deleted`
+- `activity.assigned`
+- `activity.completed`
+
+**Datasets:**
+- `dataset.record.created`
+- `dataset.record.updated`
+- `dataset.record.deleted`
+
+**Files:**
+- `file.uploaded`
+- `file.deleted`
+
+**Workflows:**
+- `workflow.started`
+- `workflow.completed`
+- `workflow.failed`
+
+### Webhook Payload
+
+```json
+{
+  "event": "activity.created",
+  "data": {
+    "id": "act_123",
+    "title": "New Task",
+    "workspace_id": "ws_456"
+  },
+  "timestamp": "2025-01-15T10:30:00Z",
+  "workspace_id": "ws_456"
+}
+```
+
+## Resources
+
+- **Local API Base**: https://api.hailer.local.gd
+- **MCP Server**: http://localhost:3030/api/mcp
+- **Project Documentation**: See CLAUDE.md in project root
+
+## References
+
+Browse the detailed API references:
+
+- [Activities API](references/activities.md) - Task and project management
+- [Insights API](references/insights.md) - SQL queries and analytics
+- [Datasets API](references/datasets.md) - Structured data storage
+- [Files API](references/files.md) - File management
+- [Workflows API](references/workflows.md) - Process automation
+- [Workspaces & Users](references/workspaces-users.md) - Organization management
+- [Authentication](references/authentication.md) - Security and access
+
+**Note**: Reference documentation may contain v7 endpoint examples. Refer to CLAUDE.md for actual v2/v3 endpoint patterns used in the MCP server.