@hailer/mcp 1.1.12 → 1.1.13

package/.claude/skills/hailer-monolith-automations/SKILL.md

@@ -1,686 +0,0 @@
----
-name: hailer-monolith-automations
-description: Understanding and building automations in the Hailer project-monolith
-version: 1.2.0
-triggers: monolith, automation, scheduled task, webhook automation, invoicing, data sync
----
-
-# Hailer Monolith Automations
-
-The project-monolith is a centralized backend service for running customer automations without deploying separate microservices.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Internal Network Only                     │
-│  ┌─────────────────┐    ┌─────────────────┐                │
-│  │  Hailer API     │───▶│ project-monolith │───▶ External  │
-│  │  (webhooks)     │    │  (Express.js)    │    APIs       │
-│  └─────────────────┘    └─────────────────┘    (Netvisor,  │
-│                              │                  Procountor, │
-│                              ▼                  etc.)       │
-│                    ┌─────────────────┐                     │
-│                    │  node-schedule  │                     │
-│                    │  (cron jobs)    │                     │
-│                    └─────────────────┘                     │
-└─────────────────────────────────────────────────────────────┘
-
-Config: AWS Secrets Manager
-Logs: Winston structured logging
-```
-
-**Key Points:**
-- Internal-only access (no internet-facing endpoints)
-- NAT Gateway for outgoing requests to external APIs
-- Single server handles 50+ automations
-- Config stored in AWS Secrets Manager
-
----
-
-## Automation Types
-
-### 1. Webhook-Triggered Automations
-
-Receive Hailer activity data via POST request when activities are created/updated.
-
-**Trigger:** Hailer webhook on activity update → POST to monolith endpoint
-
-**⚠️ CRITICAL: Never use SDK enums in automations.** Webhooks receive raw MongoDB ObjectIds, not SDK enum names. Use real IDs from config or extract from payload.
-
-**SDK enums ARE available in monolith context** via imports from workspace, but webhook payloads use real ObjectIds. Example:
-```typescript
-// Available: Import SDK enums for clarity
-import { WorkflowIds, FieldIds } from '../workspace/enums';
-
-// But webhook payload has real IDs
-const workflowId = request.process; // "507f1f77bcf86cd799439011"
-const fieldValue = request.fields.find(f => f.id === FieldIds.customer); // OK to use enum here
-```
-
-**Request payload:**
-```typescript
-interface WebhookPayload {
-  _id: string;           // Activity ID (MongoDB ObjectId)
-  cid: string;           // Workspace ID
-  process: string;       // Workflow ID (MongoDB ObjectId)
-  currentPhase: string;  // Phase ID (MongoDB ObjectId)
-  name: string;
-  fields: Array<{
-    id: string;          // Field ID (MongoDB ObjectId)
-    type: string;        // Field type
-    value: any;          // Field value
-    key?: string;        // Optional field key (human-readable)
-  }>;
-  // ... other activity fields
-}
-
-// Finding field values - two methods:
-// Method 1: By key (if field has key property - preferred when available)
-const tagValue = payload.fields.find(f => f.key === 'tag')?.value;
-
-// Method 2: By fieldId (always works)
-const tagValue = payload.fields.find(f => f.id === config.tagFieldId)?.value;
-```
-
-**Example endpoint:**
-```typescript
-router.post('/my-automation/trigger', jsonParser, async (req, res) => {
-  if (req.headers['content-type'] !== 'application/json') {
-    return res.status(415).send('Content-Type must be application/json');
-  }
-
-  const config = await fetchConfig('monolith-my-automation');
-
-  // Validate trigger conditions
-  if (config.triggerProcessId !== req.body.process) {
-    return res.status(200).send('Not applicable');
-  }
-
-  // Run automation (async, don't block response)
-  void myAutomation(req.body, config);
-
-  res.status(200).send('Ok');
-});
-```
-
-**Use Cases:**
-- Activity data sync to external system on phase change
-- Create linked activities when parent updated
-- Send notifications on specific field changes
-- XML/file import when activity created
-
----
-
-### 2. Scheduled Automations
-
-Run on a schedule using node-schedule (cron-like).
-
-**Schedule patterns:**
-```typescript
-// Run at 3:02 AM on 1st of month
-scheduleJob('Monthly Task', { date: 1, hour: 3, minute: 2 }, async () => {});
-
-// Run at 5:45 AM every day
-scheduleJob('Daily Task', { hour: 5, minute: 45 }, async () => {});
-
-// Run at specific dates
-scheduleJob('Bi-weekly', { date: [1, 15], hour: 3, minute: 0 }, async () => {});
-
-// Run every hour
-scheduleJob('Hourly', { minute: 0 }, async () => {});
-```
-
-**Example:**
-```typescript
-scheduleJob('Invoice Subscriptions', { date: 1, hour: 3, minute: 10 }, async () => {
-  const config = await fetchConfig('monolith-subscription-invoicing');
-  const result = await invoiceSubscriptions(config);
-  Logger.info('Subscription invoicing complete', { content: result });
-});
-```
-
-**Use Cases:**
-- Monthly invoicing runs
-- Daily data sync with external systems
-- Activity archiving (cleanup old completed activities)
-- Alarm/status checks
-- Currency rate updates
-
----
-
-### 3. Third-Party Integration Automations
-
-Sync data between Hailer and external systems.
-
-**Supported Systems:**
-| System | Type | Direction |
-|--------|------|-----------|
-| Netvisor | Accounting | Hailer ↔ Netvisor |
-| Procountor | Accounting | Hailer → Procountor |
-| Severa | Project Management | Hailer ↔ Severa |
-| SignSpace | E-signatures | Hailer → SignSpace |
-| INTU | HR/Payroll | Hailer ↔ INTU |
-| Logiapp | Logistics | Hailer → Logiapp |
-| Torna | Forestry | Torna → Hailer |
-
-**Pattern:**
-1. Authenticate with external API
-2. Fetch data from Hailer (or external system)
-3. Transform data format
-4. Push to destination
-5. Update status fields in Hailer
-
----
-
-## Common Patterns
-
-### Config from AWS Secrets Manager
-
-```typescript
-import { fetchConfig } from './fetch-secrets';
-
-// Config name matches AWS secret: "monolith-{name}"
-const config = await fetchConfig('monolith-my-automation');
-
-// Config structure example
-interface AutomationConfig {
-  credentials: {
-    email: string;
-    password: string;
-  };
-  triggerProcessId: string;
-  targetProcessId: string;
-  fieldMappings: Record<string, string>;
-  // ... custom config
-}
-```
-
-### Hailer Client Connection
-
-```typescript
-import { Client } from '@hailer/cli';
-
-// Connect with retry helper
-const client = await connectWithRetry(config, 5);
-
-// Or direct connection
-const client = await Client.create({
-  host: 'https://api.hailer.com',
-  username: config.credentials.email,
-  password: config.credentials.password
-});
-
-// Always disconnect when done
-client.disconnect();
-```
-
-### Activity Operations
-
-```typescript
-// List activities
-const { activities } = await client.request('v3.activity.list', [
-  { processId: workflowId, phaseId: phaseId },
-  { limit: 1000, filters: { status: { equalTo: 'Active' } }, returnFlat: true }
-]);
-
-// Create activities
-const created = await client.request('v3.activity.createMany', [
-  { processId: workflowId, phaseId: phaseId, name: 'New Activity', fields: { fieldId: value } }
-]);
-
-// Update activities
-const updated = await client.request('v3.activity.updateMany', [
-  { _id: activityId, fields: { fieldId: newValue }, phaseId: newPhaseId }
-]);
-```
-
-### Structured Logging
-
-```typescript
-// Local log array for aggregated logging
-const logArray: any[] = [];
-const log = (level: string, message: string, data?) => {
-  logArray.push({ level, message, data, time: Date.now() });
-};
-
-log('info', 'Process started');
-log('info', 'Fetched activities', { count: activities.length });
-
-// Final structured log
-Logger.info('Automation complete', {
-  content: logArray,
-  workspaceId: req.body.cid,
-  workflowId: req.body.process,
-  activityId: req.body._id
-});
-```
-
-### Deduplication (Prevent Double Processing)
-
-```typescript
-const processingActivities = new Set();
-
-router.post('/my-automation', jsonParser, async (req, res) => {
-  const lockKey = `${req.body.cid}-${req.body._id}`;
-
-  if (processingActivities.has(lockKey)) {
-    return res.status(200).send('Already processing');
-  }
-
-  processingActivities.add(lockKey);
-  try {
-    await runAutomation(req.body, config);
-  } finally {
-    processingActivities.delete(lockKey);
-  }
-
-  res.status(200).send('Ok');
-});
-```
-
----
-
-## File Structure
-
-```
-project-monolith/
-├── src/
-│   ├── run.ts              # Express server, all endpoints
-│   ├── schedules.ts        # All scheduled jobs
-│   ├── fetch-secrets.ts    # AWS Secrets Manager
-│   ├── logger.ts           # Winston logger
-│   ├── types.ts            # Common types
-│   ├── utils/
-│   │   └── hailer-utils.ts # Helper functions
-│   └── automations/
-│       ├── generic-handle-activities.ts  # Reusable CRUD
-│       ├── netvisor/       # Netvisor integrations
-│       ├── procountor/     # Procountor integrations
-│       ├── hailer/         # Hailer-internal automations
-│       └── {customer}/     # Customer-specific automations
-└── package.json
-```
-
----
-
-## When to Use Monolith vs Other Options
-
-| Scenario | Solution |
-|----------|----------|
-| Simple webhook trigger → Hailer CRUD | **Monolith** |
-| Scheduled data sync | **Monolith** |
-| Accounting integration (Netvisor, Procountor) | **Monolith** (existing code) |
-| Real-time activity sync | **activity-mover** |
-| SCIM user provisioning | **microsoft-entra** |
-| Kafka event processing | **digione-integration** |
-| Complex stateful integration | **Dedicated microservice** |
-
----
-
-## Adding a New Automation
-
-### 1. Create automation file
-
-```typescript
-// src/automations/{customer}/{automation-name}.ts
-import { Client } from '@hailer/cli';
-import { Logger } from '../../logger';
-import { connectWithRetry } from '../../utils/hailer-utils';
-
-export const myAutomation = async (request: any, config: any): Promise<boolean> => {
-  const logArray: any[] = [];
-  const log = (level: string, message: string, data?) => {
-    logArray.push({ level, message, data, time: Date.now() });
-  };
-
-  try {
-    log('info', 'Starting automation');
-
-    const client = await connectWithRetry(config, 5);
-
-    // Your automation logic here
-
-    client.disconnect();
-    Logger.info('Automation success', { content: logArray });
-    return true;
-  } catch (error) {
-    log('error', 'Automation failed', error);
-    Logger.error('Automation failed', { content: logArray, error });
-    return false;
-  }
-};
-```
-
-### 2. Add endpoint (webhook) or schedule
-
-**Webhook (run.ts):**
-```typescript
-import { myAutomation } from './automations/{customer}/{automation-name}';
-
-router.post('/{customer}/my-automation', jsonParser, async (req, res) => {
-  const config = await fetchConfig('monolith-my-automation');
-  if (config.triggerProcessId === req.body.process) {
-    void myAutomation(req.body, config);
-  }
-  res.status(200).send('Ok');
-});
-```
-
-**Scheduled (schedules.ts):**
-```typescript
-import { myAutomation } from './automations/{customer}/{automation-name}';
-
-scheduleJob('My Scheduled Task', { hour: 3, minute: 0 }, async () => {
-  const config = await fetchConfig('monolith-my-automation');
-  await myAutomation(null, config);
-});
-```
-
-### 3. Generate AWS Config (User Deploys)
-
-Claude generates the config JSON. User uploads to AWS Secrets Manager manually.
-
-**Secret name:** `monolith-{automation-name}`
-
-```json
-{
-  "credentials": {
-    "email": "integration@customer.com",
-    "password": "USER_PROVIDES_PASSWORD"
-  },
-  "triggerProcessId": "workflow-id",
-  "targetProcessId": "target-workflow-id",
-  "fieldMappings": {
-    "sourceField": "targetField"
-  }
-}
-```
-
-**User action:**
-1. Fill in the integration user password
-2. Upload to AWS Secrets Manager as `monolith-{automation-name}`
-
-### 4. Git Workflow with Symlink
-
-The automation file lives in hailer-integration (for git). The project workspace gets a symlink (for context).
-
-**Step 1: Create feature branch in hailer-integration**
-```bash
-cd ~/hailer-integration
-git checkout -b feature/{customer}-{automation-name}
-mkdir -p packages/project-monolith/src/automations/{customer}
-```
-
-**Step 2: Write the automation file**
-```bash
-# Claude writes to:
-~/hailer-integration/packages/project-monolith/src/automations/{customer}/{automation-name}.ts
-```
-
-**Step 3: Symlink to project workspace**
-```bash
-cd ~/path/to/project-workspace
-mkdir -p integrations
-ln -s ~/hailer-integration/packages/project-monolith/src/automations/{customer}/{automation-name}.ts \
-      integrations/{automation-name}.ts
-```
-
-**Step 4: Commit and push**
-```bash
-cd ~/hailer-integration
-git add packages/project-monolith/src/automations/{customer}/
-git commit -m "Add {automation-name} automation for {customer}"
-git push -u origin feature/{customer}-{automation-name}
-```
-
-**Result:**
-- File in hailer-integration → can push to git, create PR
-- Symlink in project workspace → Claude has context when working on project
-- After PR merge → CI/CD deploys to monolith
-
-### 5. Configure Hailer webhook (for webhook-triggered)
-
-In Hailer admin:
-1. Go to Integrations → Webhooks
-2. Add webhook URL: `https://internal-lb/api/v1/{customer}/my-automation`
-3. Select trigger workflow and events (create, update)
-
----
-
-## Existing Automation Categories
-
-### Invoicing Automations
-- `hailer-invoicing-subscription-v2` - Scheduled subscription billing
-- `hailer-invoicing-billable-work` - Bill tracked time/expenses
-- `hailer-invoicing-project-won` - Invoice on project completion
-- `3pl-invoicing-v2` - 3PL storage billing
-- `kspt-invoicing-v2-webhook` - KSPT rental invoicing
-
-### Data Sync Automations
-- `netvisor-integration` - Netvisor ↔ Hailer sync
-- `procountor-integration-main` - Procountor invoicing
-- `severa-integration` - Severa project sync
-- `fin-forelia-*` - Forelia logistics/forestry
-
-### Activity Management
-- `generic-handle-activities` - Reusable create/update
-- `activity-archiver` - Archive old activities
-- `porvoo-archive` - City-specific archiving
-
-### Notifications & Alarms
-- `porvoo-alarms` - Status checks and alerts
-- `porvoo-notifications` - Send notification messages
-- `3pl-saldo-alarms` - Inventory level alerts
-
-### HR/Employee Automations
-- `siskon-siivous-intu-*` - INTU HR sync
-- `pohjaset-employee-task-automation` - Onboarding tasks
-- `siskon-siivous-synttarionnittelut` - Birthday greetings
-
----
-
-## Built-in Automation Reference
-
-These are reusable, config-driven automations already in the monolith.
-
-### Email Automation
-
-Webhook-based endpoints for sending emails triggered by Hailer workflow events.
-
-**Source:** `packages/project-monolith/src/automations/hailer/email-automation.ts`
-**AWS Secret:** `monolith-hailer-email-automation-{workspaceId}`
-
-**Endpoints:**
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/email-automation/send-emails` | POST | Send emails to mailing list |
-| `/api/email-automation/form-response` | POST | Handle form responses (unsubscribe) |
-
-**Flow:**
-1. Activity enters trigger phase in Hailer
-2. Webhook fires → POST to `/email-automation/send-emails`
-3. Monolith reads email content from activity fields
-4. Fetches mailing list from referenced workflow
-5. Filters out blocklisted and unsubscribed recipients
-6. Sends emails in batches via Mailgun or Nodemailer
-7. Creates batch result activities for tracking
-
-**Config Structure:**
-```typescript
-{
-    email: string;              // Hailer login
-    password: string;
-    senderEmail: string;        // From address
-    actions: {
-        [phaseId: string]: string;  // Phase → action ("send email" | "unsubscribe")
-    };
-    processes: {
-        blockList: { processId, phaseId };   // Global unsubscribe
-        batchResults: { processId, phaseId }; // Result tracking
-        unsubscribe?: { phaseId };           // Unsubscribe target
-    };
-    sendWith?: 'nodemailer';    // Default: Mailgun
-    mailgun?: { url, apiKey };
-    nodemailer?: { host, port, username, password };
-    emailBatchSize: number;     // Default: 250
-}
-```
-
-**Required Workflow Fields:**
-
-| Workflow | Field Key | Type | Purpose |
-|----------|-----------|------|---------|
-| Email Campaign | `subject` | TEXT | Email subject |
-| Email Campaign | `html` | TEXT | HTML body |
-| Email Campaign | `plaintext` | TEXT | Plain text body |
-| Email Campaign | `process` | TEXT | Mailing list workflow ID |
-| Email Campaign | `phase` | TEXT | Mailing list phase ID |
-| Mailing List | `email` | TEXT | Recipient email |
-| Mailing List | `unsubscribed` | NUMBER | 1 = unsubscribed |
-| Block List | `email` | TEXT | Blocked email |
-
-**Personalization (Nodemailer only):** Use `%recipient.id%` in HTML - replaced with activity ID.
-
-**Setup Steps:**
-
-1. **Create AWS Config** - Add `monolith-hailer-email-automation-{workspaceId}` to AWS Secrets Manager with config structure above.
-
-2. **Create Required Workflows** in Hailer:
-   - Email Campaign workflow (with trigger phase, fields: subject, html, plaintext, process, phase)
-   - Mailing List workflow (fields: email, unsubscribed)
-   - Block List workflow (field: email)
-   - Batch Results workflow (for tracking)
-
-3. **Configure Webhook**:
-   - URL: `https://monolith-url/api/email-automation/send-emails`
-   - Trigger: Activity enters "Ready to Send" phase
-   - Phase ID must match key in `config.actions`
-
----
-
-### Generic Activity CRUD
-
-Webhook-based endpoints for bulk creating/updating activities via function fields.
-
-**Source:** `packages/project-monolith/src/automations/generic-handle-activities.ts`
-**AWS Secret:** `monolith-generic-create-update`
-
-**Endpoints:**
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/create-activities` | POST | Bulk create activities |
-| `/api/update-activities` | POST | Bulk update activities |
-
-**Flow:**
-1. User changes Activity A in Hailer
-2. Function field calculates JSON payload for createMany/updateMany
-3. Webhook fires → POST to endpoint
-4. Monolith reads the function field's JSON value
-5. Executes `v3.activity.createMany` or `v3.activity.updateMany`
-
-**Critical Constraints:**
-
-- **Single-workflow per call:** `updateMany` operates on ONE workflow at a time. For cascading updates to multiple target workflows, create separate function fields and separate config entries (one per target).
-- **Config key uniqueness:** When one source workflow triggers updates to multiple target workflows, use pattern `"workflowId_suffix"` (e.g., `"68ca89ca..._tila"`, `"68ca89ca..._henkilo"`). Each config entry points to a different function field.
-
-**Config Structure:**
-```typescript
-{
-    "[workspaceId]": {
-        "credentials": { email, password },
-        "[workflowId_suffix]": {
-            "fieldId": "field-id-containing-json-payload",
-            "description": "Human-readable description"
-        }
-    }
-}
-```
-
-**Field Payload Format:**
-
-For `/create-activities`:
-```json
-[
-    { "name": "New Activity", "fields": { "amount": 100 } }
-]
-```
-
-For `/update-activities`:
-```json
-[
-    { "_id": "activity-id", "fields": { "status": "completed" } }
-]
-```
-
-**CRITICAL: Double-Wrapped Array for Updates**
-
-The monolith generic handler spreads parsed JSON as arguments to `client.request()`. Function fields must output **double-wrapped array** `[[{_id, phaseId}, ...]]` so the first argument to `updateMany` is the array of updates.
-
-**Correct (double-wrapped):**
-```javascript
-const updates = linkedFrom('tasks-workflow').map(task => ({
-  _id: task._id,
-  fields: { parentStatus: field('status') }
-}));
-return JSON.stringify([updates]); // ← double wrap
-```
-
-**Wrong (single-wrapped):** Causes "must be an array" validation error
-```javascript
-return JSON.stringify(updates); // ← single wrap - FAILS
-```
-
-**Example function field (builds payload):**
-```javascript
-const tasks = linkedFrom('tasks-workflow');
-const newStatus = field('status');
-return JSON.stringify([
-  tasks.map(task => ({
-    _id: task._id,
-    fields: { parentStatus: newStatus }
-  }))
-]);
-```
-
-**Setup Steps:**
-
-1. **Create AWS Config** - Add workspace to `monolith-generic-create-update` in AWS Secrets Manager:
-   ```json
-   {
-       "your-workspace-id": {
-           "credentials": { "email": "bot@company.com", "password": "xxx" },
-           "your-workflow-id": {
-               "fieldId": "your-json-field-id",
-               "description": "What this automation does"
-           }
-       }
-   }
-   ```
-
-2. **Create Function Field** - In Hailer workflow, create a TEXT or function field that outputs the JSON payload (the `fieldId` in config must match this field).
-
-3. **Configure Webhook** - In Hailer workflow settings:
-   - URL: `https://monolith-url/api/create-activities` or `/api/update-activities`
-   - Trigger: On activity update (or specific phase)
-   - Method: POST
-
-**Use Cases:**
-- Create child records (order → line items)
-- Cascade updates (project status → task statuses)
-- Sync calculated data (pricing → quotes)
-
----
-
-## Reference
-
-**Location:** `~/hailer-integration/packages/project-monolith/`
-
-**Run locally:**
-```bash
-npm run start:local
-```
-
-**Deploy:** Via GitLab CI/CD pipeline
-
-**Logs:** CloudWatch (production), console (local)