@hailer/mcp 1.1.13 → 1.1.15

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

@@ -0,0 +1,518 @@
+---
+name: hailer-api-client
+description: Hailer API client patterns using @hailer/cli - authentication, requests, signals, reconnection
+version: 1.1.0
+triggers: Hailer client, API connection, WebSocket, session management, real-time signals
+---
+
+# Hailer API Client
+
+## Installation
+
+```bash
+npm install @hailer/cli
+```
+
+---
+
+## Basic Setup
+
+```typescript
+import { HailerCli } from '@hailer/cli';
+
+const client = new HailerCli({
+  host: 'https://api.hailer.com',  // or 'https://api.hailer.biz' for staging
+  reconnect: true,                  // Auto-reconnect on disconnect
+  reconnectInterval: 5000           // Retry every 5 seconds
+});
+```
+
+---
+
+## Authentication
+
+### Login with Credentials
+
+```typescript
+async function connect(email: string, password: string) {
+  try {
+    await client.login(email, password);
+    console.log('Connected to Hailer');
+  } catch (error) {
+    console.error('Login failed:', error.message);
+    throw error;
+  }
+}
+```
+
+### Login with Session Token
+
+```typescript
+// If you have an existing session token
+await client.loginWithToken(sessionToken);
+```
+
+### Logout
+
+```typescript
+await client.request('core.logout', []);
+```
+
+---
+
+## Making Requests
+
+### Basic Request
+
+```typescript
+const result = await client.request('endpoint.name', [arg1, arg2]);
+```
+
+### Common Endpoints
+
+```typescript
+// Initialize session (get workspaces, user info)
+const init = await client.request('v2.core.init', []);
+
+// List workflows
+const workflows = await client.request('v3.process.list', [workspaceId]);
+
+// Get workflow schema
+const schema = await client.request('v3.process.getOne', [workflowId]);
+
+// List activities
+const activities = await client.request('v3.activity.list', [{
+  processId: workflowId,
+  phaseId: phaseId,        // Optional
+  limit: 100,              // Default 50
+  offset: 0
+}]);
+
+// Create activity
+const created = await client.request('v3.activity.create', [{
+  processId: workflowId,
+  phaseId: phaseId,
+  name: 'Activity Name',   // Optional
+  fields: {
+    fieldId1: 'value1',
+    fieldId2: 123
+  }
+}]);
+
+// Update activity
+await client.request('v3.activity.update', [activityId, {
+  fields: { fieldId: 'new value' },
+  phaseId: newPhaseId      // Optional: move to phase
+}]);
+
+// Bulk update
+await client.request('v3.activity.updateMany', [
+  [activityId1, activityId2],
+  { phaseId: targetPhaseId }
+]);
+
+// Get linked activities
+const linked = await client.request('v3.activity.linkedFrom.overview', [activityId]);
+
+// Post to discussion
+await client.request('discussion2.send_message', [{
+  targetId: discussionId,
+  targetType: 'activity',
+  message: 'Hello from integration'
+}]);
+```
+
+---
+
+## Pagination for Large Datasets
+
+The API returns max ~500 activities per request. For workflows with more activities, paginate:
+
+### Fetch All Activities
+
+```typescript
+async function fetchAllActivities(
+  client: HailerCli,
+  workflowId: string,
+  phaseId?: string
+): Promise<any[]> {
+  const allActivities: any[] = [];
+  let offset = 0;
+  const limit = 500;
+
+  while (true) {
+    const batch = await client.request('v3.activity.list', [{
+      processId: workflowId,
+      phaseId,
+      limit,
+      offset
+    }]);
+
+    allActivities.push(...batch);
+
+    if (batch.length < limit) break; // Last page
+    offset += limit;
+
+    // Rate limiting - avoid hammering API
+    await new Promise(r => setTimeout(r, 100));
+  }
+
+  return allActivities;
+}
+```
+
+### Fetch All from Multiple Phases
+
+```typescript
+async function fetchAllFromWorkflow(
+  client: HailerCli,
+  workflowId: string,
+  phaseIds: string[]
+): Promise<any[]> {
+  // Fetch all phases in parallel
+  const results = await Promise.all(
+    phaseIds.map(phaseId => fetchAllActivities(client, workflowId, phaseId))
+  );
+
+  return results.flat();
+}
+```
+
+### Streaming Large Datasets
+
+For very large datasets, process in batches to avoid memory issues:
+
+```typescript
+async function* streamActivities(
+  client: HailerCli,
+  workflowId: string,
+  phaseId?: string
+): AsyncGenerator<any[], void, unknown> {
+  let offset = 0;
+  const limit = 500;
+
+  while (true) {
+    const batch = await client.request('v3.activity.list', [{
+      processId: workflowId,
+      phaseId,
+      limit,
+      offset
+    }]);
+
+    if (batch.length === 0) break;
+    yield batch;
+
+    if (batch.length < limit) break;
+    offset += limit;
+    await new Promise(r => setTimeout(r, 100));
+  }
+}
+
+// Usage: process batch by batch
+for await (const batch of streamActivities(client, workflowId)) {
+  await processBatch(batch);
+}
+```
+
+---
+
+## Real-Time Signals
+
+### Listening for Events
+
+```typescript
+// Activity updates
+client.on('activities.updated', (data) => {
+  console.log('Activity updated:', data);
+  // data: { activityIds: string[], processId: string, phaseId?: string }
+});
+
+// Activity created
+client.on('activities.created', (data) => {
+  console.log('Activity created:', data);
+});
+
+// Activity deleted
+client.on('activities.removed', (data) => {
+  console.log('Activity removed:', data);
+});
+
+// Discussion message
+client.on('discussion.sync', (data) => {
+  console.log('New message:', data);
+});
+
+// Generic signal handler
+client.on('rpc-response', (response) => {
+  if (response.sig) {
+    console.log('Signal:', response.sig, response.meta);
+  }
+});
+```
+
+### Common Signals
+
+| Signal | Description | Payload |
+|--------|-------------|---------|
+| `activities.created` | New activities | `{ activityIds, processId, phaseId }` |
+| `activities.updated` | Activities modified | `{ activityIds, processId }` |
+| `activities.removed` | Activities deleted | `{ activityIds, processId }` |
+| `discussion.sync` | New message | `{ targetId, message }` |
+| `process.updated` | Workflow changed | `{ processId }` |
+| `notification.reload` | New notification | `{ userId }` |
+
+---
+
+## Connection Management
+
+### Reconnection Handling
+
+```typescript
+const client = new HailerCli({
+  host: 'https://api.hailer.com',
+  reconnect: true,
+  reconnectInterval: 5000
+});
+
+client.on('disconnect', () => {
+  console.log('Disconnected from Hailer');
+});
+
+client.on('reconnect', () => {
+  console.log('Reconnected to Hailer');
+});
+
+client.on('error', (error) => {
+  console.error('Connection error:', error);
+});
+```
+
+### Manual Reconnection with Backoff
+
+```typescript
+class HailerConnection {
+  private client: HailerCli;
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 10;
+  private baseDelay = 1000;
+
+  async connect(email: string, password: string) {
+    try {
+      await this.client.login(email, password);
+      this.reconnectAttempts = 0;
+      console.log('Connected');
+    } catch (error) {
+      await this.handleConnectionError(email, password, error);
+    }
+  }
+
+  private async handleConnectionError(email: string, password: string, error: Error) {
+    this.reconnectAttempts++;
+
+    if (this.reconnectAttempts > this.maxReconnectAttempts) {
+      console.error('Max reconnection attempts reached');
+      process.exit(1);
+    }
+
+    const delay = this.baseDelay * Math.pow(2, this.reconnectAttempts - 1);
+    console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+
+    await this.sleep(delay);
+    await this.connect(email, password);
+  }
+
+  private sleep(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Common Error Codes
+
+| Code | Description | Action |
+|------|-------------|--------|
+| `InvalidArguments` | Bad request parameters | Check parameter format |
+| `NotFound` | Resource doesn't exist | Verify IDs |
+| `PermissionDenied` | Insufficient access | Check user permissions |
+| `Failed` | Operation failed | Check error message |
+| `Unauthorized` | Not logged in | Re-authenticate |
+
+### Error Handling Pattern
+
+```typescript
+async function safeRequest<T>(
+  client: HailerCli,
+  method: string,
+  args: any[]
+): Promise<T | null> {
+  try {
+    return await client.request(method, args);
+  } catch (error) {
+    switch (error.code) {
+      case 'NotFound':
+        console.warn(`Resource not found: ${method}`, args);
+        return null;
+
+      case 'PermissionDenied':
+        console.error(`Permission denied: ${method}`);
+        throw error;
+
+      case 'InvalidArguments':
+        console.error(`Invalid arguments: ${method}`, error.message);
+        throw error;
+
+      default:
+        console.error(`Request failed: ${method}`, error);
+        throw error;
+    }
+  }
+}
+```
+
+---
+
+## Complete Client Class
+
+```typescript
+import { HailerCli } from '@hailer/cli';
+
+interface HailerClientConfig {
+  host: string;
+  email: string;
+  password: string;
+}
+
+class HailerClient {
+  private client: HailerCli;
+  private config: HailerClientConfig;
+  private connected = false;
+
+  constructor(config: HailerClientConfig) {
+    this.config = config;
+    this.client = new HailerCli({
+      host: config.host,
+      reconnect: true
+    });
+
+    this.setupEventHandlers();
+  }
+
+  private setupEventHandlers() {
+    this.client.on('disconnect', () => {
+      this.connected = false;
+      console.log('Disconnected');
+    });
+
+    this.client.on('reconnect', async () => {
+      await this.client.login(this.config.email, this.config.password);
+      this.connected = true;
+      console.log('Reconnected');
+    });
+  }
+
+  async connect() {
+    await this.client.login(this.config.email, this.config.password);
+    this.connected = true;
+  }
+
+  async disconnect() {
+    await this.client.request('core.logout', []);
+    this.connected = false;
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  // Activity operations
+  async createActivity(workflowId: string, phaseId: string, fields: Record<string, any>) {
+    return this.client.request('v3.activity.create', [{
+      processId: workflowId,
+      phaseId,
+      fields
+    }]);
+  }
+
+  async updateActivity(activityId: string, updates: { fields?: Record<string, any>; phaseId?: string }) {
+    return this.client.request('v3.activity.update', [activityId, updates]);
+  }
+
+  async getActivity(activityId: string) {
+    return this.client.request('v3.activity.get', [activityId]);
+  }
+
+  async listActivities(workflowId: string, options: { phaseId?: string; limit?: number } = {}) {
+    return this.client.request('v3.activity.list', [{
+      processId: workflowId,
+      ...options
+    }]);
+  }
+
+  async moveToPhase(activityIds: string[], phaseId: string) {
+    return this.client.request('v3.activity.updateMany', [activityIds, { phaseId }]);
+  }
+
+  // Signal handling
+  onActivityUpdate(callback: (data: any) => void) {
+    this.client.on('activities.updated', callback);
+  }
+
+  onActivityCreate(callback: (data: any) => void) {
+    this.client.on('activities.created', callback);
+  }
+
+  // Raw request access
+  async request(method: string, args: any[]) {
+    return this.client.request(method, args);
+  }
+}
+
+export { HailerClient, HailerClientConfig };
+```
+
+---
+
+## Environment Configuration
+
+```typescript
+// config.ts
+interface Config {
+  hailer: {
+    host: string;
+    email: string;
+    password: string;
+  };
+}
+
+async function loadConfig(): Promise<Config> {
+  if (process.env.NODE_ENV === 'production') {
+    // Load from AWS Secrets Manager
+    return await loadFromSecretsManager();
+  }
+
+  // Local development
+  return {
+    hailer: {
+      host: process.env.HAILER_HOST || 'https://api.hailer.com',
+      email: process.env.HAILER_EMAIL || '',
+      password: process.env.HAILER_PASSWORD || ''
+    }
+  };
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always handle disconnections** - Use reconnect: true and handle events
+2. **Use exponential backoff** - Don't hammer the server on failures
+3. **Log all operations** - Structured logging for debugging
+4. **Validate before sending** - Check IDs and field formats
+5. **Use bulk operations** - updateMany instead of multiple updates
+6. **Cache workflow schemas** - Don't fetch on every request
+7. **Handle rate limits** - Back off on 429 responses