@hailer/mcp 0.0.1

package/.claude/skills/insight-api/references/insight-endpoints.md

@@ -0,0 +1,514 @@
+# Insight API Endpoints Reference
+
+Complete reference for Hailer Insight API endpoints. Insights provide SQL-like reporting over workflow/activity data.
+
+## Table of Contents
+
+- [v3.insight.create](#v3insightcreate) - Create new insight
+- [v3.insight.update](#v3insightupdate) - Update existing insight
+- [v3.insight.copy](#v3insightcopy) - Copy/duplicate an insight
+- [v3.insight.remove](#v3insightremove) - Delete an insight
+- [v3.insight.list](#v3insightlist) - List all insights
+- [v3.insight.public](#v3insightpublic) - Get public insight data
+- [v3.insight.data](#v3insightdata) - Execute insight query and get results
+- [v3.insight.preview](#v3insightpreview) - Preview insight during design
+- [v3.insight.member.add](#v3insightmemberadd) - Add member permissions
+- [v3.insight.member.remove](#v3insightmemberremove) - Remove member permissions
+
+---
+
+## Prerequisites
+
+Before using Insights:
+1. Must have workflows created with activities
+2. Understand workflow schema (field IDs, field types)
+3. Basic SQL knowledge (SELECT, JOIN, WHERE, etc.)
+4. Use `v3.insight.preview` while designing to test queries
+
+---
+
+## v3.insight.create
+
+Create new Insight with SQL query over workflow data.
+
+**Endpoint**: `POST /v3/insight/create`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // workspaceId
+  "1": {
+    "name": "string",
+    "public": false,
+    "sources": [
+      {
+        "name": "tableName",        // SQL table alias
+        "workflowId": "workflowId", // Which workflow to query
+        "fields": [
+          { "name": "columnName", "meta": "name" },       // Activity name
+          { "name": "columnName", "fieldId": "fieldId" }  // Custom field
+        ]
+      }
+    ],
+    "query": "SELECT columnName FROM tableName"  // SQL query
+  }
+}
+```
+
+**Example 1 - Single Workflow**:
+```javascript
+v3.insight.create(
+  workspaceId,
+  {
+    name: 'Book Insights',
+    sources: [{
+      name: 'books',
+      workflowId: bookWorkflowId,
+      fields: [
+        { name: 'title', meta: 'name' },           // Activity name
+        { name: 'publishDate', fieldId: fieldId }   // Custom field
+      ]
+    }],
+    query: 'SELECT title, publishDate FROM books',
+  }
+)
+```
+
+**Example 2 - Join Two Workflows**:
+```javascript
+v3.insight.create(
+  workspaceId,
+  {
+    name: 'Books with Authors',
+    sources: [
+      {
+        name: 'books',
+        workflowId: bookWorkflowId,
+        fields: [
+          { name: 'title', meta: 'name' },
+          { name: 'author', fieldId: authorLinkFieldId }
+        ]
+      },
+      {
+        name: 'authors',
+        workflowId: authorWorkflowId,
+        fields: [
+          { name: 'id', meta: '_id' },          // Activity ID
+          { name: 'authorName', meta: 'name' },  // Activity Name
+          { name: 'born', fieldId: bornFieldId }
+        ]
+      }
+    ],
+    query: `
+      SELECT title, publishDate, authorName
+      FROM authors
+      LEFT JOIN books ON books.author = authors.id
+    `
+  }
+)
+```
+
+**Meta Fields** (built-in activity properties):
+- `meta: 'name'` - Activity name
+- `meta: '_id'` - Activity ID
+- `meta: 'created'` - Creation timestamp
+- `meta: 'updated'` - Last update timestamp
+- `meta: 'phase'` - Current phase ID
+- `meta: 'team'` - Owner team ID
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "insightId": "stringstringstringstring"
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.update
+
+Update an existing insight (name, query, sources, permissions, etc.).
+
+**Endpoint**: `POST /v3/insight/update`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // insightId
+  "1": {
+    "name": "string",
+    "public": true,
+    "sources": [],
+    "query": "string",
+    "presets": []
+  }
+}
+```
+
+**Note**: Only workspace admins can modify `sources`. Regular users with edit permission can only update `name`, `query`, and `presets` if sources remain unchanged.
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {},
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.copy
+
+Duplicate an existing insight.
+
+**Endpoint**: `POST /v3/insight/copy`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // insightId to copy
+  "1": {
+    "name": "Copy of Original Insight"
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "insightId": "stringstringstringstring"  // New insight ID
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.remove
+
+Delete an insight.
+
+**Endpoint**: `POST /v3/insight/remove`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring"  // insightId
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {},
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.list
+
+List all insights in a workspace that the user has access to.
+
+**Endpoint**: `POST /v3/insight/list`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring"  // workspaceId
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "insights": [
+      {
+        "_id": "stringstringstringstring",
+        "name": "Insight Name",
+        "public": false,
+        "sources": [],
+        "query": "SELECT ...",
+        "created": 1234567890,
+        "updated": 1234567890
+      }
+    ]
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.public
+
+Get public data for a publicly shared insight (no authentication required).
+
+**Endpoint**: `POST /v3/insight/public`
+
+**Request Body**:
+```json
+{
+  "0": "string"  // insightKey (max 32 chars)
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "insight": {},
+    "data": []
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.data
+
+Execute the insight query and get results (actual data).
+
+**Endpoint**: `POST /v3/insight/data`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // insightId
+  "1": {
+    "update": true  // Whether to refresh/recalculate data
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "columns": ["title", "publishDate", "authorName"],
+    "rows": [
+      ["Book 1", "2024-01-01", "Author A"],
+      ["Book 2", "2024-02-01", "Author B"]
+    ]
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.preview
+
+Preview partial insight during design. Used for testing SQL queries before saving.
+
+**Key Features**:
+- Can be called frequently during design
+- Returns errors if SQL is invalid
+- Limited to ~20 activities for performance
+- Workspace admins can modify sources
+- Regular users cannot change sources (security)
+
+**Endpoint**: `POST /v3/insight/preview`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // workspaceId
+  "1": {
+    "query": "SELECT title FROM books WHERE publishDate > '2024-01-01'",
+    "sources": [
+      {
+        "name": "books",
+        "workflowId": "workflowId",
+        "fields": [
+          { "name": "title", "meta": "name" },
+          { "name": "publishDate", "fieldId": "fieldId" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {
+    "columns": ["title"],
+    "rows": [
+      ["Book 1"],
+      ["Book 2"]
+    ],
+    "limited": true  // Indicates data was limited for preview
+  },
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "SQL syntax error near 'SELEC'",
+  "details": {},
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.member.add
+
+Add member permissions to an insight (user, team, workspace, or group).
+
+**Endpoint**: `POST /v3/insight.member.add`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // insightId
+  "1": "network_<networkId>"        // OR: team_<teamId>, user_<userId>, group_<groupId>
+}
+```
+
+**Member Format**:
+- Workspace: `network_<networkId>`
+- Team: `team_<teamId>`
+- User: `user_<userId>`
+- Group: `group_<groupId>`
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {},
+  "debug": null
+}
+```
+
+---
+
+## v3.insight.member.remove
+
+Remove member permissions from an insight.
+
+**Endpoint**: `POST /v3/insight.member.remove`
+
+**Request Body**:
+```json
+{
+  "0": "stringstringstringstring",  // insightId
+  "1": "user_<userId>"              // OR: network_<networkId>, team_<teamId>, group_<groupId>
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "string",
+  "details": {},
+  "debug": null
+}
+```
+
+---
+
+## SQL Query Guidelines
+
+### Supported SQL Features
+- SELECT with column names or * (all)
+- FROM with table aliases (source names)
+- WHERE clauses with AND/OR
+- JOIN (INNER, LEFT, RIGHT, FULL)
+- GROUP BY with aggregations
+- ORDER BY with ASC/DESC
+- LIMIT and OFFSET
+
+### Common Patterns
+
+**Filter by phase**:
+```sql
+SELECT title FROM books WHERE phase = 'phaseId'
+```
+
+**Count activities**:
+```sql
+SELECT COUNT(*) as total FROM books
+```
+
+**Group and aggregate**:
+```sql
+SELECT author, COUNT(*) as bookCount
+FROM books
+GROUP BY author
+ORDER BY bookCount DESC
+```
+
+**Join workflows**:
+```sql
+SELECT b.title, a.name as authorName
+FROM books b
+LEFT JOIN authors a ON b.authorId = a.id
+WHERE b.publishDate > '2024-01-01'
+```
+
+---
+
+## Common Response Format
+
+All endpoints return this format:
+
+```json
+{
+  "code": 0,        // 0 = success, 403 = error
+  "msg": "string",  // Success/error message
+  "details": {},    // Response data
+  "debug": null     // Optional debug info
+}
+```
+
+---
+
+## Permissions
+
+**Workspace Admins**:
+- Create, update, delete insights
+- Modify insight sources
+- Share insights (make public)
+- Manage all insight permissions
+
+**Regular Users**:
+- View insights they have access to
+- Edit insights (name, query) if given permission
+- Cannot modify sources (security restriction)
+- Cannot change permissions
+
+**Public Insights**:
+- Accessible without authentication via `insightKey`
+- Read-only access
+- Good for public dashboards/reports