@hailer/mcp 0.0.1

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

@@ -0,0 +1,216 @@
+# Hailer Authentication & Core API
+
+## Authentication Methods
+
+### 1. Access Token Authentication
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  https://api.hailer.local.gd/v3/activities
+```
+
+### 2. Session-based Authentication
+```python
+import requests
+
+session = requests.Session()
+session.post('https://api.hailer.local.gd/v3/auth/login', 
+             json={'email': 'user@example.com', 'password': 'password'})
+
+# Session cookie is now stored
+response = session.get('https://api.hailer.local.gd/v3/activities')
+```
+
+### 3. OAuth 2.0 (Recommended for Apps)
+- Authorization endpoint: `/oauth/authorize`
+- Token endpoint: `/oauth/token`
+- Supports authorization code and client credentials flows
+
+## API Base URLs
+
+- **Production**: `https://api.hailer.local.gd`
+- **API Version**: `/v3` (current, with some `/v2` endpoints)
+- **Full base**: `https://api.hailer.local.gd/v3`
+
+## Request Headers
+
+```http
+Authorization: Bearer {access_token}
+Content-Type: application/json
+Accept: application/json
+```
+
+## Response Format
+
+All responses are JSON with standard structure:
+
+### Success Response
+```json
+{
+  "data": { /* resource data */ },
+  "meta": {
+    "page": 1,
+    "per_page": 50,
+    "total": 150
+  }
+}
+```
+
+### Error Response
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid field value",
+    "details": {
+      "field": "email",
+      "issue": "Email format is invalid"
+    }
+  }
+}
+```
+
+## Common HTTP Status Codes
+
+- `200 OK` - Request successful
+- `201 Created` - Resource created successfully
+- `204 No Content` - Success with no response body
+- `400 Bad Request` - Invalid request parameters
+- `401 Unauthorized` - Authentication required or failed
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource does not exist
+- `422 Unprocessable Entity` - Validation error
+- `429 Too Many Requests` - Rate limit exceeded
+- `500 Internal Server Error` - Server error
+
+## Rate Limiting
+
+- Default: 1000 requests per hour per user
+- Headers returned:
+  - `X-RateLimit-Limit`: Total requests allowed
+  - `X-RateLimit-Remaining`: Requests remaining
+  - `X-RateLimit-Reset`: Unix timestamp when limit resets
+
+## Pagination
+
+Most list endpoints support pagination:
+
+```http
+GET /v3/activities?page=2&per_page=100
+```
+
+Parameters:
+- `page` - Page number (default: 1)
+- `per_page` - Items per page (default: 50, max: 100)
+
+Response includes:
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 2,
+    "per_page": 100,
+    "total": 523,
+    "total_pages": 6
+  }
+}
+```
+
+## Filtering & Sorting
+
+### Filtering
+```http
+GET /v3/activities?filter[status]=open&filter[priority]=high
+```
+
+### Sorting
+```http
+GET /v3/activities?sort=-created_at,priority
+```
+- Prefix with `-` for descending order
+- Multiple sort fields comma-separated
+
+## Field Selection
+
+Request specific fields only:
+```http
+GET /v3/activities?fields=id,title,status,created_at
+```
+
+## Batch Operations
+
+Some endpoints support batch operations:
+
+```json
+POST /v3/activities/batch
+{
+  "operations": [
+    {
+      "method": "POST",
+      "path": "/v3/activities",
+      "body": { "title": "Task 1" }
+    },
+    {
+      "method": "PATCH",
+      "path": "/v3/activities/123",
+      "body": { "status": "completed" }
+    }
+  ]
+}
+```
+
+## Webhooks
+
+Subscribe to events:
+
+```json
+POST /v3/webhooks
+{
+  "url": "https://your-server.com/webhook",
+  "events": ["activity.created", "activity.updated"],
+  "active": true
+}
+```
+
+Event payload:
+```json
+{
+  "event": "activity.created",
+  "data": { /* activity object */ },
+  "timestamp": "2025-01-15T10:30:00Z",
+  "workspace_id": "ws_123"
+}
+```
+
+## Error Handling Best Practices
+
+```python
+try:
+    response = requests.get(
+        'https://api.hailer.local.gd/v3/activities',
+        headers={'Authorization': f'Bearer {token}'},
+        timeout=30
+    )
+    response.raise_for_status()
+    data = response.json()
+except requests.exceptions.Timeout:
+    # Handle timeout
+    pass
+except requests.exceptions.HTTPError as e:
+    if e.response.status_code == 401:
+        # Re-authenticate
+        pass
+    elif e.response.status_code == 429:
+        # Back off and retry
+        pass
+    else:
+        # Handle other errors
+        pass
+```
+
+## API Versioning
+
+- Current version: v3 (with some v2 endpoints still in use)
+- Version specified in URL path
+- Old versions supported for 12 months after new version release
+- Breaking changes only in new versions
+- Deprecation warnings sent via email and in response headers

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

@@ -0,0 +1,437 @@
+# Hailer Datasets API
+
+## Overview
+
+Datasets in Hailer provide structured storage for tabular data with type validation, relationships, and SQL querying capabilities.
+
+## Dataset Structure
+
+A dataset is a collection of records with defined fields (columns):
+
+```json
+{
+  "id": "dataset_123",
+  "name": "Customers",
+  "description": "Customer master data",
+  "fields": [
+    {
+      "name": "company_name",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "revenue",
+      "type": "number",
+      "required": false
+    },
+    {
+      "name": "created_at",
+      "type": "datetime",
+      "required": true
+    }
+  ],
+  "workspace_id": "ws_456",
+  "record_count": 1523
+}
+```
+
+## Field Types
+
+- `text` - String values
+- `number` - Numeric values (integer or decimal)
+- `boolean` - True/false values
+- `datetime` - ISO 8601 timestamps
+- `date` - Date only (YYYY-MM-DD)
+- `reference` - Reference to another dataset record
+- `user` - Reference to Hailer user
+- `activity` - Reference to activity
+- `file` - Reference to file
+- `json` - Structured JSON data
+- `array` - Array of values
+
+## Endpoints
+
+### Create Dataset
+
+```http
+POST /v3/datasets
+Content-Type: application/json
+
+{
+  "name": "Customers",
+  "description": "Customer master data",
+  "workspace_id": "ws_456",
+  "fields": [
+    {
+      "name": "company_name",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "contact_email",
+      "type": "text",
+      "required": false
+    },
+    {
+      "name": "annual_revenue",
+      "type": "number",
+      "required": false
+    }
+  ]
+}
+```
+
+### Get Dataset
+
+```http
+GET /v3/datasets/{dataset_id}
+```
+
+### Update Dataset
+
+```http
+PATCH /v3/datasets/{dataset_id}
+Content-Type: application/json
+
+{
+  "name": "Updated Customer List",
+  "description": "New description"
+}
+```
+
+### Delete Dataset
+
+```http
+DELETE /v3/datasets/{dataset_id}
+```
+
+### List Datasets
+
+```http
+GET /v3/datasets?workspace_id=ws_456
+```
+
+## Dataset Records
+
+### Create Record
+
+```http
+POST /v3/datasets/{dataset_id}/records
+Content-Type: application/json
+
+{
+  "company_name": "Acme Corp",
+  "contact_email": "contact@acme.com",
+  "annual_revenue": 5000000
+}
+```
+
+**Response:**
+```json
+{
+  "id": "rec_789",
+  "company_name": "Acme Corp",
+  "contact_email": "contact@acme.com",
+  "annual_revenue": 5000000,
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-15T10:30:00Z",
+  "created_by": {
+    "id": "user_123",
+    "name": "Johan Rekna"
+  }
+}
+```
+
+### Get Record
+
+```http
+GET /v3/datasets/{dataset_id}/records/{record_id}
+```
+
+### Update Record
+
+```http
+PATCH /v3/datasets/{dataset_id}/records/{record_id}
+Content-Type: application/json
+
+{
+  "annual_revenue": 5500000
+}
+```
+
+### Delete Record
+
+```http
+DELETE /v3/datasets/{dataset_id}/records/{record_id}
+```
+
+### List Records
+
+```http
+GET /v3/datasets/{dataset_id}/records?page=1&per_page=100
+```
+
+**Query Parameters:**
+- `page` - Page number
+- `per_page` - Records per page (max 1000)
+- `sort` - Sort field (e.g., `-created_at`)
+- `filter[field_name]` - Filter by field value
+
+**Example with filters:**
+```http
+GET /v3/datasets/{dataset_id}/records?filter[annual_revenue]=>1000000&sort=-annual_revenue
+```
+
+## Batch Operations
+
+### Batch Create Records
+
+```http
+POST /v3/datasets/{dataset_id}/records/batch
+Content-Type: application/json
+
+{
+  "records": [
+    {
+      "company_name": "Company 1",
+      "annual_revenue": 1000000
+    },
+    {
+      "company_name": "Company 2",
+      "annual_revenue": 2000000
+    }
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "created": 2,
+  "failed": 0,
+  "records": [
+    {
+      "id": "rec_123",
+      "success": true
+    },
+    {
+      "id": "rec_124",
+      "success": true
+    }
+  ]
+}
+```
+
+### Batch Update Records
+
+```http
+PATCH /v3/datasets/{dataset_id}/records/batch
+Content-Type: application/json
+
+{
+  "records": [
+    {
+      "id": "rec_123",
+      "annual_revenue": 1100000
+    },
+    {
+      "id": "rec_124",
+      "annual_revenue": 2200000
+    }
+  ]
+}
+```
+
+### Batch Delete Records
+
+```http
+DELETE /v3/datasets/{dataset_id}/records/batch
+Content-Type: application/json
+
+{
+  "record_ids": ["rec_123", "rec_124", "rec_125"]
+}
+```
+
+## SQL Queries
+
+Query datasets using SQL through the Insights API:
+
+```http
+POST /v3/insights/query
+Content-Type: application/json
+
+{
+  "sql": "SELECT company_name, annual_revenue FROM dataset_123 WHERE annual_revenue > 1000000 ORDER BY annual_revenue DESC",
+  "workspace_id": "ws_456"
+}
+```
+
+### Available SQL Functions
+
+**Aggregates:**
+- `COUNT(*)`, `COUNT(field)`
+- `SUM(field)`
+- `AVG(field)`
+- `MIN(field)`, `MAX(field)`
+
+**String Functions:**
+- `UPPER(field)`, `LOWER(field)`
+- `LENGTH(field)`
+- `SUBSTR(field, start, length)`
+- `REPLACE(field, from, to)`
+
+**Date Functions:**
+- `DATE(field)` - Extract date
+- `DATETIME(field)` - Convert to datetime
+- `STRFTIME(format, field)` - Format date
+
+**Example Complex Query:**
+```sql
+SELECT 
+  STRFTIME('%Y-%m', created_at) as month,
+  COUNT(*) as customer_count,
+  SUM(annual_revenue) as total_revenue,
+  AVG(annual_revenue) as avg_revenue
+FROM dataset_123
+WHERE created_at >= '2024-01-01'
+GROUP BY month
+ORDER BY month DESC
+```
+
+## Field Constraints
+
+### Validation Rules
+
+```http
+PATCH /v3/datasets/{dataset_id}/fields/{field_name}
+Content-Type: application/json
+
+{
+  "validation": {
+    "type": "text",
+    "min_length": 3,
+    "max_length": 100,
+    "pattern": "^[A-Za-z0-9]+$"
+  }
+}
+```
+
+### Reference Fields
+
+Create relationships between datasets:
+
+```json
+{
+  "name": "customer_id",
+  "type": "reference",
+  "reference_dataset_id": "dataset_123",
+  "required": true
+}
+```
+
+Query with references:
+```sql
+SELECT 
+  orders.id,
+  orders.amount,
+  customers.company_name
+FROM dataset_orders AS orders
+JOIN dataset_customers AS customers 
+  ON orders.customer_id = customers.id
+WHERE orders.amount > 10000
+```
+
+## Dataset Import/Export
+
+### Export Dataset
+
+```http
+GET /v3/datasets/{dataset_id}/export?format=csv
+GET /v3/datasets/{dataset_id}/export?format=json
+GET /v3/datasets/{dataset_id}/export?format=xlsx
+```
+
+**Response:** File download with appropriate Content-Type
+
+### Import from CSV
+
+```http
+POST /v3/datasets/{dataset_id}/import
+Content-Type: multipart/form-data
+
+file: (CSV file)
+options: {
+  "skip_header": true,
+  "delimiter": ",",
+  "update_existing": false
+}
+```
+
+**Response:**
+```json
+{
+  "imported": 150,
+  "updated": 25,
+  "failed": 3,
+  "errors": [
+    {
+      "row": 45,
+      "error": "Invalid email format"
+    }
+  ]
+}
+```
+
+## Dataset Permissions
+
+Control who can access datasets:
+
+```http
+POST /v3/datasets/{dataset_id}/permissions
+Content-Type: application/json
+
+{
+  "user_id": "user_123",
+  "role": "editor"
+}
+```
+
+**Roles:**
+- `viewer` - Read-only access
+- `editor` - Can create, update, delete records
+- `admin` - Full control including dataset structure
+
+### List Permissions
+
+```http
+GET /v3/datasets/{dataset_id}/permissions
+```
+
+## Webhooks for Datasets
+
+Subscribe to dataset changes:
+
+```http
+POST /v3/webhooks
+{
+  "url": "https://your-server.com/webhook",
+  "events": [
+    "dataset.record.created",
+    "dataset.record.updated",
+    "dataset.record.deleted"
+  ],
+  "dataset_id": "dataset_123"
+}
+```
+
+## Best Practices
+
+1. **Define field types carefully** - Hard to change after records exist
+2. **Use references for relationships** - Better than storing IDs as text
+3. **Add indexes for frequently queried fields** - Improves query performance
+4. **Use batch operations** - More efficient than individual operations
+5. **Validate data before import** - Check formats, required fields
+6. **Use SQL for complex queries** - More powerful than filter parameters
+7. **Set appropriate permissions** - Protect sensitive data
+8. **Consider dataset size** - Performance degrades beyond ~100k records