@startanaicompany/crm 2.14.0 → 2.16.0

package/index.js

@@ -580,21 +580,39 @@ leadsCmd
   });
 
 leadsCmd
-  .command('score')
-  .description('Set lead score (0-100). Conventions: 0-19 Cold, 20-39 Warm, 40-59 Developing, 60-79 Qualified, 80-100 Hot')
-  .requiredOption('--id <uuid>', 'Lead UUID')
-  .requiredOption('--score <n>', 'Score value (0-100 integer)')
-  .option('--reason <text>', 'Score reason/explanation')
-  .action(async (opts) => {
+  .command('score <lead-id>')
+  .description('Get or set lead score. Without --set shows current score + history. Score conventions: 0-19 Cold, 20-39 Warm, 40-59 Developing, 60-79 Qualified, 80-100 Hot (Sprint 53 T1)')
+  .option('--set <n>', 'Set score to this value (0-100 integer)')
+  .option('--reason <text>', 'Score reason/explanation (used with --set)')
+  .action(async (leadId, opts) => {
     const globalOpts = program.opts();
     const client = getClient(globalOpts);
-    const body = {
-      score: parseInt(opts.score),
-      ...(opts.reason && { score_reason: opts.reason })
-    };
     try {
-      const res = await client.patch(`/leads/${opts.id}/score`, body);
-      printJSON(res.data);
+      if (opts.set !== undefined) {
+        // SET mode: PATCH /leads/:id/score
+        const body = { score: parseInt(opts.set) };
+        if (opts.reason) body.score_reason = opts.reason;
+        const res = await client.patch(`/leads/${leadId}/score`, body);
+        const d = res.data.data;
+        console.log(`Score set to ${d.score}${d.score_reason ? ' — ' + d.score_reason : ''}`);
+        printJSON(res.data);
+      } else {
+        // GET mode: show current score + history
+        const [leadRes, histRes] = await Promise.all([
+          client.get(`/leads/${leadId}`),
+          client.get(`/leads/${leadId}/score-history`),
+        ]);
+        const lead = leadRes.data.data;
+        const history = histRes.data.data || [];
+        const label = lead.score >= 80 ? 'Hot' : lead.score >= 60 ? 'Qualified' : lead.score >= 40 ? 'Developing' : lead.score >= 20 ? 'Warm' : 'Cold';
+        console.log(`\nLead: ${lead.name} <${lead.email}>`);
+        console.log(`Current Score: ${lead.score ?? 'N/A'} (${label})`);
+        if (lead.score_reason) console.log(`Reason: ${lead.score_reason}`);
+        if (history.length > 0) {
+          console.log(`\nScore History (${history.length} entries):`);
+          history.slice(0, 10).forEach(h => console.log(`  ${new Date(h.changed_at).toLocaleString()} — ${h.previous_score ?? '?'} → ${h.new_score} (${h.changed_by || 'system'})`));
+        }
+      }
     } catch (err) {
       handleError(err);
     }
@@ -708,13 +726,16 @@ leadsCmd
   });
 
 leadsCmd
-  .command('assign <id> <agent>')
-  .description('Assign a lead to an agent (fires lead.assigned webhook) — S18-2')
-  .action(async (id, agent) => {
+  .command('assign <id> [agent]')
+  .description('Assign a lead to an agent (fires lead.assigned webhook) — S18-2. Use positional [agent] or --to <agent>.')
+  .option('--to <agent>', 'Agent/user to assign to (alias for positional agent arg)')
+  .action(async (id, agent, opts) => {
     const globalOpts = program.opts();
     const client = getClient(globalOpts);
+    const assignTo = agent || opts.to;
+    if (!assignTo) { console.error('Error: specify agent as positional arg or --to <agent>'); process.exit(1); }
     try {
-      const res = await client.patch(`/leads/${id}/assign`, { assigned_to: agent });
+      const res = await client.patch(`/leads/${id}/assign`, { assigned_to: assignTo });
       console.log(`Lead assigned to: ${res.data.data.assigned_to}`);
       printJSON(res.data);
     } catch (err) {
@@ -770,27 +791,67 @@ leadsCmd
     }
   });
 
-// leads search <term> — S19-1
+// Sprint 53 T1: leads stage — get or set pipeline stage
 leadsCmd
-  .command('search <term>')
-  .description('Search leads by name, email, company, or notes')
-  .action(async (term) => {
+  .command('stage <lead-id>')
+  .description('Get current pipeline stage or move lead to a new stage (Sprint 53 T1)')
+  .option('--to <stage>', 'Move lead to this pipeline stage name')
+  .action(async (leadId, opts) => {
     const globalOpts = program.opts();
     const client = getClient(globalOpts);
     try {
-      const res = await client.get('/leads', { params: { q: term, per_page: 50 } });
+      if (opts.to) {
+        // SET mode: PATCH /leads/:id with pipeline_stage
+        const res = await client.patch(`/leads/${leadId}`, { pipeline_stage: opts.to });
+        const d = res.data.data;
+        console.log(`Stage set to: ${d.pipeline_stage}`);
+        printJSON(res.data);
+      } else {
+        // GET mode: show current stage
+        const leadRes = await client.get(`/leads/${leadId}`);
+        const lead = leadRes.data.data;
+        console.log(`\nLead: ${lead.name} <${lead.email}>`);
+        console.log(`Current Stage: ${lead.pipeline_stage || 'N/A'}`);
+        if (lead.pipeline_id) {
+          try {
+            const pipeRes = await client.get(`/pipelines/${lead.pipeline_id}/stages`);
+            const stages = pipeRes.data.data || [];
+            if (stages.length > 0) {
+              console.log(`Available stages: ${stages.map(s => s.name).join(' → ')}`);
+            }
+          } catch (_) { /* pipeline stages not critical */ }
+        }
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// leads search <term> — S19-1 / Sprint 53 T3: added --q flag alias
+leadsCmd
+  .command('search [term]')
+  .description('Search leads by name, email, company, or notes. Use positional term or --q flag.')
+  .option('--q <keyword>', 'Search keyword (alias for positional term)')
+  .option('--fields <fields>', 'Comma-separated fields to display (e.g. name,email,company)')
+  .option('--limit <n>', 'Max results', '50')
+  .action(async (term, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    const query = term || opts.q;
+    if (!query) { console.error('Error: provide a search term (positional or --q)'); process.exit(1); }
+    try {
+      const res = await client.get('/leads', { params: { q: query, per_page: parseInt(opts.limit) } });
       const leads = res.data.data || [];
       if (leads.length === 0) {
-        console.log('No leads found matching: ' + term);
+        console.log('No leads found matching: ' + query);
         return;
       }
-      const rows = leads.map(l => ({
-        id: l.id,
-        name: l.name,
-        email: l.email,
-        company: l.company || '—',
-        status: l.status
-      }));
+      const fields = opts.fields ? opts.fields.split(',').map(f => f.trim()) : ['id', 'name', 'email', 'company', 'status'];
+      const rows = leads.map(l => {
+        const row = {};
+        fields.forEach(f => { row[f] = l[f] ?? '—'; });
+        return row;
+      });
       console.table(rows);
     } catch (err) {
       handleError(err);
@@ -1120,6 +1181,68 @@ leadsCmd
     } catch (err) { handleError(err); }
   });
 
+// Sprint 53 T3: leads due — follow-up due/overdue list
+leadsCmd
+  .command('due')
+  .description('List leads with upcoming or overdue follow-ups (Sprint 53 T3)')
+  .option('--today', 'Leads with follow-up scheduled for today')
+  .option('--overdue', 'Leads with overdue follow-ups (follow_up_at < now)')
+  .option('--assigned-to-me', 'Filter to leads assigned to the current API key name')
+  .option('--limit <n>', 'Max results', '50')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = { per_page: parseInt(opts.limit) };
+      if (opts.overdue) params.follow_up_overdue = 'true';
+      if (opts.today) params.follow_up_today = 'true';
+      if (!opts.overdue && !opts.today) {
+        // default: both overdue + today
+        params.follow_up_overdue = 'true';
+      }
+      const res = await client.get('/leads', { params });
+      const leads = res.data.data || [];
+      if (leads.length === 0) { console.log('No leads with due/overdue follow-ups.'); return; }
+      leads.forEach(l => {
+        const fu = l.follow_up_at ? new Date(l.follow_up_at).toLocaleString() : 'N/A';
+        const overdue = l.follow_up_at && new Date(l.follow_up_at) < new Date() ? ' ⚠️ OVERDUE' : '';
+        console.log(`[${l.id}] ${l.name} <${l.email}> — follow_up: ${fu}${overdue} (${l.assigned_to || 'unassigned'})`);
+      });
+    } catch (err) { handleError(err); }
+  });
+
+// Sprint 52 T2: leads escalate + leads unassign
+leadsCmd
+  .command('escalate <lead-id>')
+  .description('Manually escalate a lead — sets escalated=true and fires lead.escalated webhook (Sprint 52 T2)')
+  .option('--reason <text>', 'Reason for escalation')
+  .option('--to <agent>', 'Reassign to this agent/user on escalation')
+  .action(async (leadId, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {};
+      if (opts.reason) body.reason = opts.reason;
+      if (opts.to) body.to = opts.to;
+      const res = await client.post(`/leads/${leadId}/escalate`, body);
+      console.log(`Lead ${leadId} escalated.`);
+      printJSON(res.data);
+    } catch (err) { handleError(err); }
+  });
+
+leadsCmd
+  .command('unassign <lead-id>')
+  .description('Remove assignment from a lead (sets assigned_to to null) (Sprint 52 T2)')
+  .action(async (leadId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.patch(`/leads/${leadId}`, { assigned_to: null });
+      console.log(`Lead ${leadId} unassigned.`);
+      printJSON(res.data);
+    } catch (err) { handleError(err); }
+  });
+
 // Sprint 51 T3: leads export / leads import
 leadsCmd
   .command('export')
@@ -1187,11 +1310,14 @@ const contactsCmd = program
 contactsCmd
   .command('create')
   .description('Create a new contact')
-  .requiredOption('--first-name <name>', 'First name')
+  .option('--name <name>', 'Full name (alias for --first-name)')
+  .option('--first-name <name>', 'First name')
   .option('--last-name <name>', 'Last name')
-  .option('--email <email>', 'Email address (unique)')
+  .requiredOption('--email <email>', 'Email address (unique)')
   .option('--phone <phone>', 'Phone number')
-  .option('--company <company>', 'Company name')
+  .option('--company <company>', 'Company name (text)')
+  .option('--company-id <uuid>', 'Company UUID (links to companies table)')
+  .option('--lead-id <uuid>', 'Lead UUID to link to this contact on creation')
   .option('--title <title>', 'Job title')
   .option('--tags <tags>', 'Comma-separated tags')
   .option('--do-not-contact', 'Mark as do not contact')
@@ -1203,11 +1329,14 @@ contactsCmd
     const client = getClient(globalOpts, agentName);
     try {
       const body = {
-        first_name: opts.firstName,
+        name: opts.name || opts.firstName,
+        first_name: opts.firstName || opts.name,
         last_name: opts.lastName,
         email: opts.email,
         phone: opts.phone,
         company: opts.company,
+        company_id: opts.companyId,
+        lead_id: opts.leadId,
         title: opts.title,
         notes: opts.notes,
         do_not_contact: opts.doNotContact === true,
@@ -1224,8 +1353,10 @@ contactsCmd
   .command('list')
   .description('List contacts')
   .option('--email <email>', 'Filter by email (partial match)')
-  .option('--company <company>', 'Filter by company (partial match)')
+  .option('--company <company>', 'Filter by company name (partial match)')
+  .option('--company-id <uuid>', 'Filter by company UUID')
   .option('--tag <tag>', 'Filter by tag')
+  .option('--limit <n>', 'Max results per page (default 20)')
   .option('--page <n>', 'Page number', '1')
   .option('--per-page <n>', 'Results per page', '20')
   .action(async (opts) => {
@@ -1233,8 +1364,10 @@ contactsCmd
     const client = getClient(globalOpts);
     try {
       const params = { page: opts.page, per_page: opts.perPage };
+      if (opts.limit) params.limit = opts.limit;
       if (opts.email) params.email = opts.email;
       if (opts.company) params.company = opts.company;
+      if (opts.companyId) params.company_id = opts.companyId;
       if (opts.tag) params.tag = opts.tag;
       const res = await client.get('/contacts', { params });
       printJSON(res.data);
@@ -1260,11 +1393,13 @@ contactsCmd
 contactsCmd
   .command('update <id>')
   .description('Update a contact')
+  .option('--name <name>', 'Full name (alias for --first-name)')
   .option('--first-name <name>', 'First name')
   .option('--last-name <name>', 'Last name')
   .option('--email <email>', 'Email address')
   .option('--phone <phone>', 'Phone number')
-  .option('--company <company>', 'Company name')
+  .option('--company <company>', 'Company name (text)')
+  .option('--company-id <uuid>', 'Company UUID (links to companies table)')
   .option('--title <title>', 'Job title')
   .option('--role <role>', 'Role: champion|economic_buyer|technical_buyer|gatekeeper|influencer|end_user')
   .option('--tags <tags>', 'Comma-separated tags')
@@ -1274,11 +1409,13 @@ contactsCmd
     const client = getClient(globalOpts);
     try {
       const body = {};
+      if (opts.name !== undefined) body.name = opts.name;
       if (opts.firstName !== undefined) body.first_name = opts.firstName;
       if (opts.lastName !== undefined) body.last_name = opts.lastName;
       if (opts.email !== undefined) body.email = opts.email;
       if (opts.phone !== undefined) body.phone = opts.phone;
       if (opts.company !== undefined) body.company = opts.company;
+      if (opts.companyId !== undefined) body.company_id = opts.companyId;
       if (opts.title !== undefined) body.title = opts.title;
       if (opts.role !== undefined) body.role = opts.role;
       if (opts.tags !== undefined) body.tags = opts.tags.split(',').map(t => t.trim());
@@ -3042,6 +3179,59 @@ webhooksCmd
     }
   });
 
+// Sprint 53 T2: webhooks test / logs / retry
+webhooksCmd
+  .command('test <webhook-id>')
+  .description('Send a test payload to a webhook and check delivery (Sprint 53 T2)')
+  .action(async (webhookId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post(`/webhooks/${webhookId}/test`);
+      const d = res.data.data;
+      console.log(`Test queued — event: ${d.event}, webhook_id: ${d.webhook_id}`);
+      printJSON(res.data);
+    } catch (err) { handleError(err); }
+  });
+
+webhooksCmd
+  .command('logs <webhook-id>')
+  .description('View webhook delivery history (Sprint 53 T2)')
+  .option('--limit <n>', 'Max results (default 20)', '20')
+  .option('--status <status>', 'Filter by status: success or failed')
+  .action(async (webhookId, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = { limit: parseInt(opts.limit) };
+      if (opts.status) params.status = opts.status;
+      const res = await client.get(`/webhooks/${webhookId}/deliveries`, { params });
+      const deliveries = res.data.data || [];
+      if (deliveries.length === 0) { console.log('No delivery logs found.'); return; }
+      deliveries.forEach(d => {
+        const icon = d.success ? '✅' : '❌';
+        const retry = d.next_retry_at ? ` | retry: ${new Date(d.next_retry_at).toLocaleString()}` : '';
+        console.log(`${icon} [${d.id}] ${d.event} — HTTP ${d.status_code || '?'} at ${new Date(d.attempted_at).toLocaleString()}${retry}`);
+        if (!d.success && d.error_message) console.log(`   Error: ${d.error_message}`);
+      });
+      const p = res.data.pagination;
+      if (p) console.log(`\nShowing ${deliveries.length} of ${p.total} total deliveries.`);
+    } catch (err) { handleError(err); }
+  });
+
+webhooksCmd
+  .command('retry <webhook-id> <delivery-id>')
+  .description('Retry a failed webhook delivery (Sprint 53 T2)')
+  .action(async (webhookId, deliveryId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post(`/webhooks/${webhookId}/deliveries/${deliveryId}/retry`);
+      console.log(`Retry queued for delivery ${deliveryId}`);
+      printJSON(res.data);
+    } catch (err) { handleError(err); }
+  });
+
 // ── stages ──────────────────────────────────────────────────────────
 const stagesCmd = program.command('stages').description('Manage pipeline stages (admin)');
 
@@ -3442,4 +3632,81 @@ gdprCmd
     }
   });
 
+// ============================================================
+// REPORTS COMMANDS — Sprint 52 T3
+// ============================================================
+const reportsCmd = program.command('reports').description('Manage and run saved CRM reports (Sprint 52 T3)');
+
+reportsCmd
+  .command('list')
+  .description('List all saved reports')
+  .action(async () => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get('/reports');
+      const reports = res.data.data || res.data;
+      if (!reports || reports.length === 0) { console.log('No reports found.'); return; }
+      reports.forEach(r => console.log(`[${r.id}] ${r.name} — type: ${r.dimension}/${r.metric}, period: ${r.period}`));
+    } catch (err) { handleError(err); }
+  });
+
+reportsCmd
+  .command('create')
+  .description('Create and save a report definition')
+  .requiredOption('--name <name>', 'Report name')
+  .option('--type <type>', 'Report type: leads (count by stage) | pipeline (deal value by pipeline) | revenue (deal value by stage)', 'leads')
+  .option('--period <period>', 'Time period: 7d | 30d | 90d | 365d | all', '30d')
+  .option('--filter-status <status>', 'Filter leads by status')
+  .option('--filter-stage <stage>', 'Filter leads by pipeline stage')
+  .option('--chart-type <type>', 'Chart type: bar | line | pie | table', 'bar')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {
+        name: opts.name,
+        type: opts.type,
+        period: opts.period,
+        chart_type: opts.chartType,
+      };
+      if (opts.filterStatus) body.filter_status = opts.filterStatus;
+      if (opts.filterStage) body.filter_stage = opts.filterStage;
+      const res = await client.post('/reports', body);
+      const r = res.data.data || res.data;
+      console.log(`Report created: [${r.id}] ${r.name}`);
+      printJSON(res.data);
+    } catch (err) { handleError(err); }
+  });
+
+reportsCmd
+  .command('run <report-id>')
+  .description('Run a saved report and display or save results')
+  .option('--output <file>', 'Save results to this JSON file')
+  .action(async (reportId, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/reports/${reportId}/run`);
+      if (opts.output) {
+        fs.writeFileSync(opts.output, JSON.stringify(res.data, null, 2));
+        console.log(`Report results saved to ${opts.output}`);
+      } else {
+        printJSON(res.data);
+      }
+    } catch (err) { handleError(err); }
+  });
+
+reportsCmd
+  .command('delete <report-id>')
+  .description('Delete a saved report')
+  .action(async (reportId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      await client.delete(`/reports/${reportId}`);
+      console.log(`Report ${reportId} deleted.`);
+    } catch (err) { handleError(err); }
+  });
+
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/crm",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "AI-first CRM CLI — manage leads and API keys from the terminal",
   "main": "index.js",
   "bin": {