@hailer/mcp 0.0.1

package/.claude/skills/hailer-api/references/insights.md

@@ -0,0 +1,469 @@
+# Hailer Insights API
+
+## Overview
+
+The Insights API provides SQL-based querying capabilities for analyzing data across workspaces, activities, and datasets. Powered by SQLite, it supports complex queries, joins, aggregations, and analytics.
+
+## Key Features
+
+- SQLite-compatible SQL syntax
+- Query activities, datasets, and workspace data
+- Aggregations and analytics functions
+- Saved queries for reuse
+- Parameterized queries for security
+- Export results to CSV/JSON/XLSX
+
+## Endpoints
+
+### Execute Query
+
+```http
+POST /v3/insights/query
+Content-Type: application/json
+
+{
+  "sql": "SELECT * FROM activities WHERE status = 'open'",
+  "workspace_id": "ws_123",
+  "parameters": {}
+}
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "act_123",
+      "title": "Task 1",
+      "status": "open",
+      "created_at": "2025-01-15T10:30:00Z"
+    }
+  ],
+  "meta": {
+    "rows": 1,
+    "execution_time_ms": 45
+  }
+}
+```
+
+### List Saved Queries
+
+```http
+GET /v3/insights/queries?workspace_id=ws_123
+```
+
+### Save Query
+
+```http
+POST /v3/insights/queries
+{
+  "name": "Open High Priority Tasks",
+  "sql": "SELECT * FROM activities WHERE status = 'open' AND priority = 'high'",
+  "workspace_id": "ws_123",
+  "description": "All open high priority tasks"
+}
+```
+
+### Execute Saved Query
+
+```http
+POST /v3/insights/queries/{query_id}/execute
+{
+  "parameters": {
+    "status": "open"
+  }
+}
+```
+
+## Available Tables
+
+### activities Table
+
+All activities in the workspace.
+
+**Columns:**
+- `id` (text) - Activity ID
+- `title` (text) - Activity title
+- `description` (text) - Activity description
+- `status` (text) - Current status
+- `priority` (text) - Priority level
+- `workspace_id` (text) - Workspace ID
+- `created_at` (datetime) - Creation timestamp
+- `updated_at` (datetime) - Last update timestamp
+- `completed_at` (datetime) - Completion timestamp (null if not completed)
+- `due_date` (datetime) - Due date
+- `created_by` (text) - Creator user ID
+- `assigned_to` (text) - Assigned user ID (first assignee)
+- `parent_id` (text) - Parent activity ID
+- `tags` (text) - Comma-separated tags
+
+**Example:**
+```sql
+SELECT 
+    status,
+    COUNT(*) as count,
+    AVG(julianday(completed_at) - julianday(created_at)) as avg_days_to_complete
+FROM activities
+WHERE completed_at IS NOT NULL
+GROUP BY status
+```
+
+### dataset_{id} Tables
+
+Each dataset is accessible as a table with name `dataset_{id}`.
+
+**Columns:** Based on dataset field definitions
+
+**Example:**
+```sql
+SELECT 
+    company_name,
+    annual_revenue
+FROM dataset_customers
+WHERE annual_revenue > 1000000
+ORDER BY annual_revenue DESC
+```
+
+### users Table
+
+Workspace users.
+
+**Columns:**
+- `id` (text) - User ID
+- `name` (text) - User name
+- `email` (text) - Email address
+- `role` (text) - Workspace role
+- `created_at` (datetime) - Join timestamp
+
+**Example:**
+```sql
+SELECT 
+    u.name,
+    COUNT(a.id) as activity_count
+FROM users u
+LEFT JOIN activities a ON a.assigned_to = u.id
+GROUP BY u.id
+ORDER BY activity_count DESC
+```
+
+### files Table
+
+Uploaded files.
+
+**Columns:**
+- `id` (text) - File ID
+- `filename` (text) - Original filename
+- `size` (integer) - File size in bytes
+- `mime_type` (text) - MIME type
+- `activity_id` (text) - Associated activity
+- `workspace_id` (text) - Workspace ID
+- `created_at` (datetime) - Upload timestamp
+- `created_by` (text) - Uploader user ID
+
+### comments Table
+
+Activity comments.
+
+**Columns:**
+- `id` (text) - Comment ID
+- `activity_id` (text) - Activity ID
+- `text` (text) - Comment text
+- `created_at` (datetime) - Creation timestamp
+- `created_by` (text) - Author user ID
+
+### time_entries Table
+
+Time tracking entries.
+
+**Columns:**
+- `id` (text) - Entry ID
+- `activity_id` (text) - Activity ID
+- `user_id` (text) - User who logged time
+- `hours` (real) - Hours logged
+- `description` (text) - Entry description
+- `date` (date) - Entry date
+- `created_at` (datetime) - Creation timestamp
+
+## SQL Capabilities
+
+### Basic Queries
+
+```sql
+-- Select all open activities
+SELECT * FROM activities WHERE status = 'open';
+
+-- Count activities by status
+SELECT status, COUNT(*) as count
+FROM activities
+GROUP BY status;
+
+-- Activities due this week
+SELECT title, due_date
+FROM activities
+WHERE due_date BETWEEN datetime('now') AND datetime('now', '+7 days');
+```
+
+### Joins
+
+```sql
+-- Activities with creator names
+SELECT 
+    a.title,
+    a.status,
+    u.name as creator
+FROM activities a
+JOIN users u ON a.created_by = u.id
+WHERE a.status = 'open';
+
+-- Activities with file counts
+SELECT 
+    a.id,
+    a.title,
+    COUNT(f.id) as file_count
+FROM activities a
+LEFT JOIN files f ON f.activity_id = a.id
+GROUP BY a.id;
+```
+
+### Aggregations
+
+```sql
+-- Average completion time by priority
+SELECT 
+    priority,
+    AVG(julianday(completed_at) - julianday(created_at)) as avg_days,
+    COUNT(*) as count
+FROM activities
+WHERE completed_at IS NOT NULL
+GROUP BY priority;
+
+-- Total time logged per activity
+SELECT 
+    a.title,
+    SUM(t.hours) as total_hours
+FROM activities a
+LEFT JOIN time_entries t ON t.activity_id = a.id
+GROUP BY a.id;
+```
+
+### Window Functions
+
+```sql
+-- Rank users by activity completion rate
+SELECT 
+    name,
+    completed,
+    total,
+    RANK() OVER (ORDER BY completed * 1.0 / total DESC) as rank
+FROM (
+    SELECT 
+        u.name,
+        SUM(CASE WHEN a.status = 'completed' THEN 1 ELSE 0 END) as completed,
+        COUNT(*) as total
+    FROM users u
+    LEFT JOIN activities a ON a.assigned_to = u.id
+    GROUP BY u.id
+);
+```
+
+### Common Table Expressions (CTEs)
+
+```sql
+WITH monthly_stats AS (
+    SELECT 
+        STRFTIME('%Y-%m', created_at) as month,
+        COUNT(*) as created,
+        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed
+    FROM activities
+    WHERE created_at >= datetime('now', '-12 months')
+    GROUP BY month
+)
+SELECT 
+    month,
+    created,
+    completed,
+    completed * 100.0 / created as completion_rate
+FROM monthly_stats
+ORDER BY month DESC;
+```
+
+## Date Functions
+
+### SQLite Date Functions
+
+```sql
+-- Current date/time
+SELECT datetime('now');
+SELECT date('now');
+
+-- Date arithmetic
+SELECT datetime('now', '+7 days');
+SELECT datetime('now', '-1 month');
+SELECT datetime('now', 'start of month');
+
+-- Format dates
+SELECT STRFTIME('%Y-%m-%d', created_at) as date
+FROM activities;
+
+-- Extract components
+SELECT 
+    STRFTIME('%Y', created_at) as year,
+    STRFTIME('%m', created_at) as month,
+    STRFTIME('%d', created_at) as day,
+    STRFTIME('%H', created_at) as hour
+FROM activities;
+
+-- Calculate differences
+SELECT 
+    title,
+    julianday(completed_at) - julianday(created_at) as days_to_complete
+FROM activities
+WHERE completed_at IS NOT NULL;
+```
+
+## Parameterized Queries
+
+Use parameters for security and reusability:
+
+```http
+POST /v3/insights/query
+{
+  "sql": "SELECT * FROM activities WHERE status = :status AND priority = :priority",
+  "workspace_id": "ws_123",
+  "parameters": {
+    "status": "open",
+    "priority": "high"
+  }
+}
+```
+
+## Query Limits
+
+- Maximum execution time: 30 seconds
+- Maximum result rows: 10,000 (use LIMIT for pagination)
+- Maximum query length: 100,000 characters
+
+## Example Queries
+
+### Activity Analytics
+
+```sql
+-- Overdue activities
+SELECT 
+    id,
+    title,
+    assigned_to,
+    due_date,
+    julianday('now') - julianday(due_date) as days_overdue
+FROM activities
+WHERE due_date < datetime('now')
+    AND status NOT IN ('completed', 'cancelled')
+ORDER BY days_overdue DESC;
+```
+
+```sql
+-- Activities created vs completed by month
+SELECT 
+    STRFTIME('%Y-%m', created_at) as month,
+    COUNT(*) as created,
+    SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed
+FROM activities
+GROUP BY month
+ORDER BY month DESC
+LIMIT 12;
+```
+
+### User Performance
+
+```sql
+-- User workload and completion rate
+SELECT 
+    u.name,
+    COUNT(a.id) as total_activities,
+    SUM(CASE WHEN a.status = 'completed' THEN 1 ELSE 0 END) as completed,
+    SUM(CASE WHEN a.status IN ('open', 'in_progress') THEN 1 ELSE 0 END) as active,
+    ROUND(100.0 * SUM(CASE WHEN a.status = 'completed' THEN 1 ELSE 0 END) / COUNT(a.id), 2) as completion_rate
+FROM users u
+LEFT JOIN activities a ON a.assigned_to = u.id
+WHERE u.role IN ('member', 'admin')
+GROUP BY u.id
+ORDER BY completion_rate DESC;
+```
+
+### Time Tracking
+
+```sql
+-- Time logged per user this month
+SELECT 
+    u.name,
+    SUM(t.hours) as total_hours,
+    COUNT(DISTINCT t.activity_id) as activities_worked
+FROM users u
+LEFT JOIN time_entries t ON t.user_id = u.id
+WHERE t.date >= date('now', 'start of month')
+GROUP BY u.id
+ORDER BY total_hours DESC;
+```
+
+### Dataset Analysis
+
+```sql
+-- Join dataset with activities
+SELECT 
+    c.company_name,
+    c.annual_revenue,
+    COUNT(a.id) as related_activities
+FROM dataset_customers c
+LEFT JOIN activities a ON a.custom_fields LIKE '%' || c.company_name || '%'
+GROUP BY c.id
+ORDER BY related_activities DESC;
+```
+
+## Export Results
+
+### Export as CSV
+
+```http
+POST /v3/insights/query
+{
+  "sql": "SELECT * FROM activities WHERE status = 'completed'",
+  "workspace_id": "ws_123",
+  "format": "csv"
+}
+```
+
+Response will be CSV file download.
+
+### Export as Excel
+
+```http
+POST /v3/insights/query
+{
+  "sql": "SELECT * FROM activities WHERE status = 'completed'",
+  "workspace_id": "ws_123",
+  "format": "xlsx"
+}
+```
+
+## Best Practices
+
+1. **Use LIMIT for large result sets** - Prevents timeouts
+2. **Add WHERE clauses** - Filter at database level for performance
+3. **Use indexes** - On frequently queried fields (created via dataset configuration)
+4. **Parameterize queries** - Prevents SQL injection
+5. **Test queries** - Verify on small datasets first
+6. **Use CTEs for readability** - Break complex queries into steps
+7. **Monitor execution time** - Optimize slow queries
+8. **Cache frequently used results** - Store in datasets or client-side
+9. **Use appropriate date functions** - SQLite date functions for date math
+10. **Document saved queries** - Add descriptions for team understanding
+
+## Query Optimization Tips
+
+- Use `EXPLAIN QUERY PLAN` to understand query execution
+- Add indexes on JOIN and WHERE columns
+- Limit result sets with appropriate WHERE clauses
+- Use EXISTS instead of IN for subqueries
+- Avoid SELECT * - specify needed columns
+- Use appropriate JOINs (INNER vs LEFT)
+- Pre-aggregate data in datasets when possible