@hailer/mcp 1.1.11 → 1.1.13

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

@@ -1,518 +0,0 @@
----
-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