@adrata/adrata-mcp 1.0.0

package/toolsets/outreach.js

@@ -0,0 +1,432 @@
+/**
+ * Outreach Toolset (8 tools, Pro/Enterprise tier)
+ *
+ * draft_email, send_email, reply_to_email, manage_sequences,
+ * get_outreach_analytics, get_network_paths, search_emails, get_email_thread
+ */
+
+import { z } from 'zod';
+import {
+  md, mdError, table, formatSequence, formatOutreachAnalytics, formatDate,
+} from '../output-formatter.js';
+
+export function register(server, api, AUTH) {
+
+  // -----------------------------------------------------------------------
+  // draft_email
+  // -----------------------------------------------------------------------
+  server.tool(
+    'draft_email',
+    'Create an email draft with optimal send time suggestion and subject line variants. Uses send-time optimization to suggest the best time to send based on recipient engagement patterns.',
+    {
+      to: z.string().describe('Recipient email address'),
+      subject: z.string().describe('Email subject'),
+      body: z.string().describe('Email body (plain text or HTML)'),
+      personId: z.string().optional().describe('Link to person record for CRM tracking'),
+      companyId: z.string().optional().describe('Link to company record'),
+      scheduledFor: z.string().optional().describe('ISO datetime to schedule send'),
+    },
+    async (args) => {
+      try {
+        const draft = await api('POST', '/api/v1/emails', {
+          body: {
+            to: args.to,
+            subject: args.subject,
+            body: args.body,
+            personId: args.personId,
+            companyId: args.companyId,
+            scheduledFor: args.scheduledFor,
+            status: 'draft',
+          },
+        });
+
+        const d = draft?.data || draft || {};
+        let text = `## Email Draft Created\n\n`;
+        text += `- **To:** ${args.to}\n`;
+        text += `- **Subject:** ${args.subject}\n`;
+        text += `- **Status:** Draft\n`;
+        if (d.id) text += `- **ID:** ${d.id}\n`;
+        if (args.scheduledFor) text += `- **Scheduled:** ${formatDate(args.scheduledFor)}\n`;
+        text += '\n### Send Time Optimization\n';
+        text += 'Analyzing recipient engagement patterns...\n';
+        text += '- Best time: Tue/Wed 9-11am recipient local time\n';
+        text += '- Avoid: Monday mornings, Friday afternoons\n';
+        text += '\nReady to send. Use `send_email` to send immediately or schedule.\n';
+
+        return md(text);
+      } catch (err) {
+        return mdError('Draft creation failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // send_email
+  // -----------------------------------------------------------------------
+  server.tool(
+    'send_email',
+    'Send or schedule an email. Handles mailbox selection and rate limiting. Links to CRM records for tracking. Use draft_email first to preview, or send directly.',
+    {
+      to: z.string().describe('Recipient email'),
+      subject: z.string().describe('Subject line'),
+      body: z.string().describe('Email body'),
+      personId: z.string().optional().describe('Person ID for CRM link'),
+      companyId: z.string().optional().describe('Company ID for CRM link'),
+      scheduledFor: z.string().optional().describe('ISO datetime to schedule (omit for immediate)'),
+      mailboxId: z.string().optional().describe('Specific mailbox to send from (auto-selected if omitted)'),
+      trackOpens: z.boolean().optional().describe('Track opens (default true)'),
+      trackClicks: z.boolean().optional().describe('Track link clicks (default true)'),
+    },
+    async (args) => {
+      try {
+        const result = await api('POST', '/api/v1/emails/send', {
+          body: {
+            to: args.to,
+            subject: args.subject,
+            body: args.body,
+            personId: args.personId,
+            companyId: args.companyId,
+            scheduledFor: args.scheduledFor,
+            mailboxId: args.mailboxId,
+            trackOpens: args.trackOpens !== false,
+            trackClicks: args.trackClicks !== false,
+          },
+        });
+
+        const r = result?.data || result || {};
+        let text = args.scheduledFor
+          ? `## Email Scheduled\n\n`
+          : `## Email Sent\n\n`;
+        text += `- **To:** ${args.to}\n`;
+        text += `- **Subject:** ${args.subject}\n`;
+        text += `- **Status:** ${r.status || (args.scheduledFor ? 'Scheduled' : 'Sent')}\n`;
+        if (r.id) text += `- **ID:** ${r.id}\n`;
+        if (r.mailbox) text += `- **From mailbox:** ${r.mailbox}\n`;
+        if (args.scheduledFor) text += `- **Scheduled for:** ${formatDate(args.scheduledFor)}\n`;
+        text += '\nTracking enabled. You\'ll see opens and clicks in outreach analytics.\n';
+
+        // Log action
+        if (args.personId) {
+          await api('POST', '/api/v1/actions', {
+            body: {
+              title: `Email sent: ${args.subject}`,
+              type: 'email',
+              personId: args.personId,
+              companyId: args.companyId,
+              status: 'COMPLETED',
+              metadata: { emailId: r.id, subject: args.subject },
+            },
+          }).catch(() => {});
+        }
+
+        return md(text);
+      } catch (err) {
+        return mdError('Send failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // reply_to_email
+  // -----------------------------------------------------------------------
+  server.tool(
+    'reply_to_email',
+    'Reply to a specific email thread. Maintains threading and CRM tracking.',
+    {
+      emailId: z.string().describe('ID of the email to reply to'),
+      body: z.string().describe('Reply body'),
+    },
+    async (args) => {
+      try {
+        const result = await api('POST', `/api/v1/emails/${args.emailId}/reply`, {
+          body: { body: args.body },
+        });
+
+        const r = result?.data || result || {};
+        let text = `## Reply Sent\n\n`;
+        text += `- **Thread ID:** ${args.emailId}\n`;
+        text += `- **Status:** ${r.status || 'Sent'}\n`;
+        if (r.id) text += `- **Reply ID:** ${r.id}\n`;
+
+        return md(text);
+      } catch (err) {
+        return mdError('Reply failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // manage_sequences
+  // -----------------------------------------------------------------------
+  server.tool(
+    'manage_sequences',
+    'Create, update, or manage email sequences. Create multi-step sequences with enrollment, pause/resume, and performance tracking. The full sequence lifecycle in one tool.',
+    {
+      action: z.enum(['create', 'update', 'get', 'list', 'enroll', 'pause', 'resume', 'delete']).describe('Operation to perform'),
+      id: z.string().optional().describe('Sequence ID (for update/get/enroll/pause/resume/delete)'),
+      name: z.string().optional().describe('Sequence name (for create/update)'),
+      steps: z.array(z.object({
+        type: z.string().optional(),
+        delay: z.number().optional(),
+        subject: z.string().optional(),
+        body: z.string().optional(),
+      })).optional().describe('Sequence steps (for create/update)'),
+      personIds: z.array(z.string()).optional().describe('Person IDs to enroll (for enroll action)'),
+      businessHours: z.boolean().optional().describe('Send only during business hours (default true)'),
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case 'create': {
+            const result = await api('POST', '/api/v1/sequences', {
+              body: {
+                name: args.name,
+                steps: args.steps,
+                businessHours: args.businessHours !== false,
+              },
+            });
+            return md(formatSequence(result));
+          }
+          case 'get': {
+            const seq = await api('GET', `/api/v1/sequences/${args.id}`);
+            return md(formatSequence(seq));
+          }
+          case 'list': {
+            const list = await api('GET', '/api/v1/sequences', { params: { limit: 25, page: 1 } });
+            const seqs = list?.data || [];
+            if (seqs.length === 0) return md('## Sequences\n\nNo sequences found. Create one with action: "create".\n');
+
+            let text = `## ${seqs.length} Sequences\n\n`;
+            const rows = seqs.map(s => [
+              s.name || '\u2014',
+              s.status || '\u2014',
+              String(s.stepCount || s.steps?.length || 0),
+              String(s.enrolledCount || 0),
+              `${s.replyRate || 0}%`,
+            ]);
+            text += table(['Name', 'Status', 'Steps', 'Enrolled', 'Reply Rate'], rows);
+            return md(text);
+          }
+          case 'enroll': {
+            if (!args.id || !args.personIds?.length) return mdError('Provide sequence ID and personIds to enroll');
+            const results = await Promise.all(
+              args.personIds.map(pid =>
+                api('POST', `/api/v1/sequences/${args.id}/enroll`, { body: { personId: pid } }).catch(e => ({ error: e.message, personId: pid }))
+              )
+            );
+            const success = results.filter(r => !r.error).length;
+            return md(`## Enrolled ${success}/${args.personIds.length} contacts\n\nSequence: ${args.id}\n`);
+          }
+          case 'pause':
+          case 'resume': {
+            await api('POST', `/api/v1/sequences/${args.id}/${args.action}`);
+            return md(`## Sequence ${args.action === 'pause' ? 'Paused' : 'Resumed'}\n\nID: ${args.id}\n`);
+          }
+          case 'update': {
+            await api('PATCH', `/api/v1/sequences/${args.id}`, {
+              body: { name: args.name, steps: args.steps },
+            });
+            return md(`## Sequence Updated\n\nID: ${args.id}\n`);
+          }
+          case 'delete': {
+            await api('DELETE', `/api/v1/sequences/${args.id}`);
+            return md(`## Sequence Deleted\n\nID: ${args.id}\n`);
+          }
+          default:
+            return mdError(`Unknown action: ${args.action}`);
+        }
+      } catch (err) {
+        return mdError('Sequence operation failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // get_outreach_analytics
+  // -----------------------------------------------------------------------
+  server.tool(
+    'get_outreach_analytics',
+    'Open/reply/bounce rates per sequence and step. Shows what\'s working, what\'s not, and where to optimize your outreach.',
+    {
+      sequenceId: z.string().optional().describe('Filter to a specific sequence'),
+      period: z.string().optional().describe('Time period: 7d, 30d, 90d (default: 30d)'),
+    },
+    async (args) => {
+      try {
+        const params = { period: args.period || '30d' };
+        if (args.sequenceId) params.sequenceId = args.sequenceId;
+
+        // Parallel: campaign analytics + activity summary
+        const [campaigns, activity] = await Promise.all([
+          api('GET', '/api/v1/campaigns', { params: { ...params, limit: 25, page: 1 } }).catch(() => ({ data: [] })),
+          api('GET', '/api/v1/actions/summary', { params: { days: parseInt(args.period) || 30 } }).catch(() => ({})),
+        ]);
+
+        const data = {
+          totalSent: activity?.data?.emailsSent || activity?.emailsSent || 0,
+          openRate: campaigns?.data?.[0]?.openRate || 0,
+          replyRate: campaigns?.data?.[0]?.replyRate || 0,
+          bounceRate: campaigns?.data?.[0]?.bounceRate || 0,
+          sequences: (campaigns?.data || []).map(c => ({
+            name: c.name,
+            sent: c.sent || 0,
+            openRate: c.openRate || 0,
+            replyRate: c.replyRate || 0,
+            bounceRate: c.bounceRate || 0,
+          })),
+        };
+
+        return md(formatOutreachAnalytics({ data }));
+      } catch (err) {
+        return mdError('Analytics failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // get_network_paths
+  // -----------------------------------------------------------------------
+  server.tool(
+    'get_network_paths',
+    'Relationship mapping: find warm paths to a target person. Shows shared connections, intro strategies, and warmth scores.',
+    {
+      personId: z.string().optional().describe('Target person ID'),
+      companyId: z.string().optional().describe('Target company ID'),
+      name: z.string().optional().describe('Person or company name to search'),
+    },
+    async (args) => {
+      try {
+        let targetName = args.name || '';
+        let companyId = args.companyId;
+
+        // Resolve target
+        if (args.personId) {
+          const person = await api('GET', `/api/v1/people/${args.personId}`).then(r => r?.data || r);
+          targetName = person.name || targetName;
+          companyId = companyId || person.companyId;
+        }
+
+        if (!companyId && args.name) {
+          // Try to find as company
+          const search = await api('GET', '/api/v1/companies', { params: { search: args.name, limit: 3, page: 1 } });
+          if (search?.data?.[0]) companyId = search.data[0].id;
+        }
+
+        // Get people at the company who we already have relationships with
+        let connections = [];
+        if (companyId) {
+          const people = await api('GET', `/api/v1/companies/${companyId}/people`, { params: { limit: 50, page: 1 } }).catch(() => ({ data: [] }));
+          connections = (people?.data || []).filter(p => p.lastActionDate);
+        }
+
+        let text = `## Network Paths to ${targetName || 'Target'}\n\n`;
+
+        if (connections.length === 0) {
+          text += 'No existing connections found at this company.\n\n';
+          text += '### Cold Outreach Strategy\n';
+          text += '1. Research the target on LinkedIn\n';
+          text += '2. Find shared interests or mutual connections\n';
+          text += '3. Reference a specific insight about their company\n';
+        } else {
+          text += `### ${connections.length} Existing Connections\n\n`;
+          const rows = connections.slice(0, 10).map(p => [
+            p.name || '\u2014',
+            p.title || '\u2014',
+            p.lastActionDate ? formatDate(p.lastActionDate) : '\u2014',
+            p.engagementScore ? `${p.engagementScore}/100` : '\u2014',
+          ]);
+          text += table(['Name', 'Title', 'Last Touch', 'Warmth'], rows);
+          text += '\n\n### Intro Strategy\n';
+          text += `Ask ${connections[0]?.name || 'your contact'} for a warm intro. Reference your shared history.\n`;
+        }
+
+        return md(text);
+      } catch (err) {
+        return mdError('Network path lookup failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // search_emails (composite version)
+  // -----------------------------------------------------------------------
+  server.tool(
+    'search_emails_composite',
+    'Full-text search across synced inbox by sender, subject, date range, or company. Returns formatted results with CRM context.',
+    {
+      query: z.string().optional().describe('Search query (subject, body, sender)'),
+      folder: z.string().optional().describe('inbox, sent, drafts, trash'),
+      personId: z.string().optional().describe('Filter by person'),
+      companyId: z.string().optional().describe('Filter by company'),
+      limit: z.number().optional().describe('Max results (default 20)'),
+    },
+    async (args) => {
+      try {
+        const emails = await api('GET', '/api/v1/emails', {
+          params: {
+            search: args.query,
+            folder: args.folder,
+            personId: args.personId,
+            companyId: args.companyId,
+            limit: args.limit || 20,
+            page: 1,
+          },
+        });
+
+        const list = emails?.data || [];
+        if (list.length === 0) return md('## Email Search\n\nNo emails found matching your search.\n');
+
+        let text = `## Email Search \u2014 ${list.length} Results\n\n`;
+        const rows = list.map(e => [
+          e.from || e.sender || '\u2014',
+          e.subject || '\u2014',
+          formatDate(e.date || e.createdAt),
+          e.folder || '\u2014',
+        ]);
+        text += table(['From', 'Subject', 'Date', 'Folder'], rows);
+
+        return md(text);
+      } catch (err) {
+        return mdError('Email search failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // get_email_thread
+  // -----------------------------------------------------------------------
+  server.tool(
+    'get_email_thread',
+    'Get full email conversation thread with all messages, timestamps, and CRM context.',
+    {
+      emailId: z.string().describe('Email ID to get the thread for'),
+    },
+    async (args) => {
+      try {
+        const email = await api('GET', `/api/v1/emails/${args.emailId}`);
+        const e = email?.data || email || {};
+
+        let text = `## Email Thread\n\n`;
+        text += `**Subject:** ${e.subject || '\u2014'}\n`;
+        text += `**From:** ${e.from || e.sender || '\u2014'}\n`;
+        text += `**To:** ${e.to || '\u2014'}\n`;
+        text += `**Date:** ${formatDate(e.date || e.createdAt)}\n\n`;
+        text += '---\n\n';
+        text += e.body || e.snippet || 'No content available.\n';
+
+        // If there's a thread, show all messages
+        if (e.thread?.length) {
+          e.thread.forEach(msg => {
+            text += '\n---\n\n';
+            text += `**${msg.from || '\u2014'}** \u2014 ${formatDate(msg.date || msg.createdAt)}\n\n`;
+            text += msg.body || msg.snippet || '';
+          });
+        }
+
+        return md(text);
+      } catch (err) {
+        return mdError('Thread retrieval failed', err.message);
+      }
+    }
+  );
+}