@startanaicompany/crm 2.0.0 → 2.3.1

package/index.js

@@ -99,7 +99,7 @@ const program = new Command();
 program
   .name('saac_crm')
   .description('AI-first CRM CLI — manage leads and API keys')
-  .version('1.0.3')
+  .version('2.3.0')
   .option('--api-key <key>', 'API key (overrides SAAC_CRM_API_KEY env and config)')
   .option('--url <url>', 'API base URL (overrides config)');
 
@@ -766,7 +766,7 @@ callsCmd
   .requiredOption('--direction <dir>', 'inbound or outbound')
   .option('--lead-id <id>', 'Lead ID associated with this call')
   .option('--contact-id <id>', 'Contact ID associated with this call')
-  .option('--outcome <outcome>', 'connected | left_voicemail | no_answer | busy | wrong_number | meeting_booked | demo_completed')
+  .option('--outcome <outcome>', 'connected | no_answer | voicemail | busy | failed | callback_requested | not_interested | wrong_number | left_message_with_gatekeeper | disconnected | scheduled')
   .option('--duration <seconds>', 'Duration in seconds')
   .option('--notes <notes>', 'Call notes')
   .option('--call-time <iso>', 'Call time (ISO8601, defaults to now)')
@@ -917,4 +917,971 @@ leadsStageCmd
   });
 
 
+// ============================================================
+// MEETINGS
+// ============================================================
+
+const meetingsCmd = program
+  .command('meetings')
+  .description('Manage booked meetings');
+
+meetingsCmd
+  .command('create')
+  .description('Log a new meeting')
+  .requiredOption('--title <title>', 'Meeting title')
+  .requiredOption('--scheduled-at <iso>', 'Scheduled datetime (ISO8601, e.g. 2026-03-01T14:00:00Z)')
+  .option('--contact-id <id>', 'Contact ID')
+  .option('--lead-id <id>', 'Lead ID')
+  .option('--duration <minutes>', 'Duration in minutes')
+  .option('--location <location>', 'Physical location or address')
+  .option('--video-link <url>', 'Video call link (Zoom, Meet, etc.)')
+  .option('--notes <notes>', 'Meeting notes or agenda')
+  .option('--outcome <outcome>', 'scheduled | completed | cancelled | no_show')
+  .option('--sentiment <sentiment>', 'positive | neutral | negative | unknown')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {
+        title: opts.title,
+        scheduled_at: opts.scheduledAt,
+      };
+      if (opts.contactId) body.contact_id = opts.contactId;
+      if (opts.leadId) body.lead_id = opts.leadId;
+      if (opts.duration) body.duration_minutes = parseInt(opts.duration);
+      if (opts.location) body.location = opts.location;
+      if (opts.videoLink) body.video_link = opts.videoLink;
+      if (opts.notes) body.notes = opts.notes;
+      if (opts.outcome) body.outcome = opts.outcome;
+      if (opts.sentiment) body.sentiment = opts.sentiment;
+      const res = await client.post('/meetings', body);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+meetingsCmd
+  .command('list')
+  .description('List meetings')
+  .option('--contact-id <id>', 'Filter by contact ID')
+  .option('--lead-id <id>', 'Filter by lead ID')
+  .option('--outcome <outcome>', 'Filter by outcome')
+  .option('--scheduled-after <iso>', 'Filter meetings scheduled after date')
+  .option('--scheduled-before <iso>', 'Filter meetings scheduled before date')
+  .option('--page <n>', 'Page number', '1')
+  .option('--per-page <n>', 'Results per page', '20')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = { page: opts.page, per_page: opts.perPage };
+      if (opts.contactId) params.contact_id = opts.contactId;
+      if (opts.leadId) params.lead_id = opts.leadId;
+      if (opts.outcome) params.outcome = opts.outcome;
+      if (opts.scheduledAfter) params.scheduled_after = opts.scheduledAfter;
+      if (opts.scheduledBefore) params.scheduled_before = opts.scheduledBefore;
+      const res = await client.get('/meetings', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+meetingsCmd
+  .command('get <id>')
+  .description('Get a meeting by ID')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/meetings/${id}`);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+meetingsCmd
+  .command('update <id>')
+  .description('Update a meeting')
+  .option('--title <title>', 'New title')
+  .option('--scheduled-at <iso>', 'New scheduled time (ISO8601)')
+  .option('--duration <minutes>', 'Duration in minutes')
+  .option('--location <location>', 'Location')
+  .option('--video-link <url>', 'Video link')
+  .option('--notes <notes>', 'Notes')
+  .option('--outcome <outcome>', 'scheduled | completed | cancelled | no_show')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {};
+      if (opts.title !== undefined) body.title = opts.title;
+      if (opts.scheduledAt !== undefined) body.scheduled_at = opts.scheduledAt;
+      if (opts.duration !== undefined) body.duration_minutes = parseInt(opts.duration);
+      if (opts.location !== undefined) body.location = opts.location;
+      if (opts.videoLink !== undefined) body.video_link = opts.videoLink;
+      if (opts.notes !== undefined) body.notes = opts.notes;
+      if (opts.outcome !== undefined) body.outcome = opts.outcome;
+      const res = await client.patch(`/meetings/${id}`, body);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+meetingsCmd
+  .command('cancel <id>')
+  .description('Cancel a meeting')
+  .option('--reason <reason>', 'Cancellation reason')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {};
+      if (opts.reason) body.reason = opts.reason;
+      const res = await client.delete(`/meetings/${id}`, { data: body });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// ============================================================
+// EMAILS
+// ============================================================
+
+const emailsCmd = program
+  .command('emails')
+  .description('Log and retrieve email interactions');
+
+emailsCmd
+  .command('log')
+  .description('Log an email interaction (sent or received)')
+  .requiredOption('--direction <dir>', 'sent or received')
+  .requiredOption('--subject <subject>', 'Email subject line')
+  .option('--contact-id <id>', 'Contact ID')
+  .option('--lead-id <id>', 'Lead ID')
+  .option('--body-summary <summary>', 'Body summary (max 1000 chars)')
+  .option('--thread-id <id>', 'Thread ID for grouping related emails')
+  .option('--email-timestamp <iso>', 'When the email was sent/received (ISO8601, defaults to now)')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {
+        direction: opts.direction,
+        subject: opts.subject,
+      };
+      if (opts.contactId) body.contact_id = opts.contactId;
+      if (opts.leadId) body.lead_id = opts.leadId;
+      if (opts.bodySummary) body.body_summary = opts.bodySummary;
+      if (opts.threadId) body.thread_id = opts.threadId;
+      if (opts.emailTimestamp) body.email_timestamp = opts.emailTimestamp;
+      const res = await client.post('/emails', body);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+emailsCmd
+  .command('list')
+  .description('List email logs')
+  .option('--contact-id <id>', 'Filter by contact ID')
+  .option('--lead-id <id>', 'Filter by lead ID')
+  .option('--direction <dir>', 'Filter by direction (sent/received)')
+  .option('--thread-id <id>', 'Filter by thread ID')
+  .option('--after <iso>', 'Filter emails after this date')
+  .option('--before <iso>', 'Filter emails before this date')
+  .option('--page <n>', 'Page number', '1')
+  .option('--per-page <n>', 'Results per page', '20')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = { page: opts.page, per_page: opts.perPage };
+      if (opts.contactId) params.contact_id = opts.contactId;
+      if (opts.leadId) params.lead_id = opts.leadId;
+      if (opts.direction) params.direction = opts.direction;
+      if (opts.threadId) params.thread_id = opts.threadId;
+      if (opts.after) params.after = opts.after;
+      if (opts.before) params.before = opts.before;
+      const res = await client.get('/emails', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+emailsCmd
+  .command('get <id>')
+  .description('Get an email log entry by ID')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/emails/${id}`);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+emailsCmd
+  .command('thread <thread-id>')
+  .description('Get all emails in a thread by thread ID')
+  .action(async (threadId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/emails/thread/${threadId}`);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+
+
+// ============================================================
+// QUOTES commands
+// ============================================================
+const quotesCmd = program.command('quotes').description('Manage quotes');
+
+quotesCmd
+  .command('create')
+  .description('Create a new quote')
+  .requiredOption('--title <title>', 'Quote title')
+  .option('--lead-id <id>', 'Lead ID to link')
+  .option('--contact-id <id>', 'Contact ID to link')
+  .option('--currency <code>', 'Currency code (default: USD)')
+  .option('--validity-date <date>', 'Validity date (YYYY-MM-DD)')
+  .option('--notes <notes>', 'Notes')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post('/quotes', {
+        title: opts.title,
+        lead_id: opts.leadId,
+        contact_id: opts.contactId,
+        currency: opts.currency,
+        validity_date: opts.validityDate,
+        notes: opts.notes
+      });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('list')
+  .description('List quotes')
+  .option('--status <status>', 'Filter by status (draft/sent/accepted/rejected/expired)')
+  .option('--lead-id <id>', 'Filter by lead ID')
+  .option('--contact-id <id>', 'Filter by contact ID')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const params = {};
+      if (opts.status) params.status = opts.status;
+      if (opts.leadId) params.lead_id = opts.leadId;
+      if (opts.contactId) params.contact_id = opts.contactId;
+      const res = await client.get('/quotes', { params });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('get <id>')
+  .description('Get a quote with all line items and totals')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.get(`/quotes/${id}`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('update <id>')
+  .description('Update quote metadata')
+  .option('--title <title>', 'New title')
+  .option('--currency <code>', 'Currency code')
+  .option('--validity-date <date>', 'Validity date (YYYY-MM-DD)')
+  .option('--notes <notes>', 'Notes')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const body = {};
+      if (opts.title) body.title = opts.title;
+      if (opts.currency) body.currency = opts.currency;
+      if (opts.validityDate) body.validity_date = opts.validityDate;
+      if (opts.notes) body.notes = opts.notes;
+      const res = await client.patch(`/quotes/${id}`, body);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('add-line <quote-id>')
+  .description('Add a line item to a quote')
+  .requiredOption('--description <desc>', 'Line item description')
+  .requiredOption('--unit-price <price>', 'Unit price', parseFloat)
+  .option('--quantity <qty>', 'Quantity (default: 1)', parseFloat)
+  .option('--discount <pct>', 'Discount percentage 0-100 (default: 0)', parseFloat)
+  .option('--sort-order <n>', 'Sort order (default: 0)', parseInt)
+  .action(async (quoteId, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/quotes/${quoteId}/lines`, {
+        description: opts.description,
+        unit_price: opts.unitPrice,
+        quantity: opts.quantity || 1,
+        discount_percentage: opts.discount || 0,
+        sort_order: opts.sortOrder || 0
+      });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('remove-line <quote-id> <line-id>')
+  .description('Remove a line item from a quote')
+  .action(async (quoteId, lineId) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.delete(`/quotes/${quoteId}/lines/${lineId}`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('send <id>')
+  .description('Mark a quote as sent')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/quotes/${id}/status`, { status: 'sent' });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('accept <id>')
+  .description('Mark a quote as accepted (auto-creates draft contract)')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/quotes/${id}/status`, { status: 'accepted' });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('reject <id>')
+  .description('Mark a quote as rejected')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/quotes/${id}/status`, { status: 'rejected' });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('version <id>')
+  .description('Create a new version of a quote (copies all line items)')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/quotes/${id}/version`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+quotesCmd
+  .command('delete <id>')
+  .description('Soft-delete a quote')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.delete(`/quotes/${id}`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// ============================================================
+// CONTRACTS commands
+// ============================================================
+const contractsCmd = program.command('contracts').description('Manage contracts');
+
+contractsCmd
+  .command('create')
+  .description('Create a new contract')
+  .requiredOption('--title <title>', 'Contract title')
+  .option('--lead-id <id>', 'Lead ID to link')
+  .option('--contact-id <id>', 'Contact ID to link')
+  .option('--quote-id <id>', 'Quote ID to link')
+  .option('--value <amount>', 'Contract value', parseFloat)
+  .option('--currency <code>', 'Currency code (default: USD)')
+  .option('--start-date <date>', 'Start date (YYYY-MM-DD)')
+  .option('--end-date <date>', 'End date (YYYY-MM-DD)')
+  .option('--document-url <url>', 'Document URL reference')
+  .option('--notes <notes>', 'Notes')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post('/contracts', {
+        title: opts.title,
+        lead_id: opts.leadId,
+        contact_id: opts.contactId,
+        quote_id: opts.quoteId,
+        value: opts.value,
+        currency: opts.currency,
+        start_date: opts.startDate,
+        end_date: opts.endDate,
+        document_url: opts.documentUrl,
+        notes: opts.notes
+      });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('list')
+  .description('List contracts')
+  .option('--status <status>', 'Filter by status (draft/sent/signed/expired/void)')
+  .option('--lead-id <id>', 'Filter by lead ID')
+  .option('--contact-id <id>', 'Filter by contact ID')
+  .option('--quote-id <id>', 'Filter by quote ID')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const params = {};
+      if (opts.status) params.status = opts.status;
+      if (opts.leadId) params.lead_id = opts.leadId;
+      if (opts.contactId) params.contact_id = opts.contactId;
+      if (opts.quoteId) params.quote_id = opts.quoteId;
+      const res = await client.get('/contracts', { params });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('get <id>')
+  .description('Get a contract by ID')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.get(`/contracts/${id}`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('update <id>')
+  .description('Update contract metadata')
+  .option('--title <title>', 'New title')
+  .option('--value <amount>', 'Contract value', parseFloat)
+  .option('--currency <code>', 'Currency code')
+  .option('--start-date <date>', 'Start date')
+  .option('--end-date <date>', 'End date')
+  .option('--notes <notes>', 'Notes')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const body = {};
+      if (opts.title) body.title = opts.title;
+      if (opts.value !== undefined) body.value = opts.value;
+      if (opts.currency) body.currency = opts.currency;
+      if (opts.startDate) body.start_date = opts.startDate;
+      if (opts.endDate) body.end_date = opts.endDate;
+      if (opts.notes) body.notes = opts.notes;
+      const res = await client.patch(`/contracts/${id}`, body);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('send <id>')
+  .description('Mark a contract as sent')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/contracts/${id}/status`, { status: 'sent' });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('sign <id>')
+  .description('Sign a contract (auto-moves linked lead to closed_won)')
+  .option('--signed-by <name>', 'Name of signatory')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/contracts/${id}/status`, { status: 'signed', signed_by: opts.signedBy });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('void <id>')
+  .description('Void a contract')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.post(`/contracts/${id}/status`, { status: 'void' });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('attach-doc <id>')
+  .description('Attach or update document URL on a contract')
+  .requiredOption('--url <url>', 'Document URL')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.patch(`/contracts/${id}/document`, { document_url: opts.url });
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+contractsCmd
+  .command('delete <id>')
+  .description('Soft-delete a contract')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+
+      const res = await client.delete(`/contracts/${id}`);
+      printJSON(res.data);
+  
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+
+// ============================================================
+// BUDGETS commands — Sprint 5
+// ============================================================
+const budgetsCmd = program.command('budgets').description('Manage sales budgets');
+
+budgetsCmd
+  .command('create')
+  .description('Create a new budget allocation')
+  .requiredOption('--name <name>', 'Budget name')
+  .requiredOption('--amount <amount>', 'Total budget amount', parseFloat)
+  .requiredOption('--period-start <date>', 'Period start date (YYYY-MM-DD)')
+  .requiredOption('--period-end <date>', 'Period end date (YYYY-MM-DD)')
+  .option('--period-type <type>', 'Period type: monthly, quarterly, annual, custom (default: custom)')
+  .option('--currency <code>', 'Currency code (default: USD)')
+  .option('--owner-key <key>', 'API key of budget owner')
+  .option('--tags <tags>', 'Comma-separated tags')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post('/budgets', {
+        name: opts.name,
+        total_amount: opts.amount,
+        period_start: opts.periodStart,
+        period_end: opts.periodEnd,
+        period_type: opts.periodType || 'custom',
+        currency: opts.currency,
+        owner_key: opts.ownerKey,
+        tags: opts.tags ? opts.tags.split(',').map(t => t.trim()) : undefined
+      });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('list')
+  .description('List budgets with spend summary')
+  .option('--status <status>', 'Filter by status (active/paused/exhausted/archived)')
+  .option('--period-type <type>', 'Filter by period type')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = {};
+      if (opts.status) params.status = opts.status;
+      if (opts.periodType) params.period_type = opts.periodType;
+      const res = await client.get('/budgets', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('get <id>')
+  .description('Get a budget with line items and spend summary')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/budgets/${id}`);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('update <id>')
+  .description('Update budget metadata')
+  .option('--name <name>', 'New name')
+  .option('--amount <amount>', 'New total amount', parseFloat)
+  .option('--status <status>', 'New status (active/paused/exhausted/archived)')
+  .option('--period-start <date>', 'New period start')
+  .option('--period-end <date>', 'New period end')
+  .option('--currency <code>', 'Currency code')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {};
+      if (opts.name) body.name = opts.name;
+      if (opts.amount !== undefined) body.total_amount = opts.amount;
+      if (opts.status) body.status = opts.status;
+      if (opts.periodStart) body.period_start = opts.periodStart;
+      if (opts.periodEnd) body.period_end = opts.periodEnd;
+      if (opts.currency) body.currency = opts.currency;
+      const res = await client.patch(`/budgets/${id}`, body);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('spend <id>')
+  .description('Log a spend event against a budget')
+  .requiredOption('--description <desc>', 'What was purchased')
+  .requiredOption('--amount <amount>', 'Spend amount', parseFloat)
+  .requiredOption('--date <date>', 'Transaction date (YYYY-MM-DD)')
+  .option('--category <cat>', 'Category: data_enrichment, advertising, events, tools, other (default: other)')
+  .option('--lead-id <id>', 'Link to a lead')
+  .option('--reference <ref>', 'Invoice or order reference')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post(`/budgets/${id}/spend`, {
+        description: opts.description,
+        amount: opts.amount,
+        transaction_date: opts.date,
+        category: opts.category || 'other',
+        lead_id: opts.leadId,
+        reference: opts.reference
+      });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('line-items <id>')
+  .description('List spend line items for a budget')
+  .option('--category <cat>', 'Filter by category')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = {};
+      if (opts.category) params.category = opts.category;
+      const res = await client.get(`/budgets/${id}/line-items`, { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+budgetsCmd
+  .command('check <id>')
+  .description('Check if a spend amount is approved (APPROVED/INSUFFICIENT_FUNDS)')
+  .requiredOption('--amount <amount>', 'Amount to check', parseFloat)
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/budgets/${id}/check`, { params: { amount: opts.amount } });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// ============================================================
+// TARGETS commands — Sprint 5
+// ============================================================
+const targetsCmd = program.command('targets').description('Manage sales targets');
+
+targetsCmd
+  .command('create')
+  .description('Create a new sales target')
+  .requiredOption('--name <name>', 'Target name')
+  .requiredOption('--metric <metric>', 'Metric: calls_made, emails_sent, meetings_booked, leads_qualified, revenue_closed, deals_closed, contracts_signed, or any custom')
+  .requiredOption('--goal <value>', 'Goal value', parseFloat)
+  .requiredOption('--period-start <date>', 'Period start date (YYYY-MM-DD)')
+  .requiredOption('--period-end <date>', 'Period end date (YYYY-MM-DD)')
+  .option('--type <type>', 'Target type: activity, revenue, pipeline, conversion (default: activity)')
+  .option('--period-type <type>', 'Period type: daily, weekly, monthly, quarterly, annual (default: monthly)')
+  .option('--unit <unit>', 'Unit label: calls, USD, leads, % (default: count)')
+  .option('--owner-key <key>', 'API key owner of this target')
+  .option('--tags <tags>', 'Comma-separated tags')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post('/targets', {
+        name: opts.name,
+        metric: opts.metric,
+        goal_value: opts.goal,
+        period_start: opts.periodStart,
+        period_end: opts.periodEnd,
+        target_type: opts.type || 'activity',
+        period_type: opts.periodType || 'monthly',
+        unit: opts.unit || 'count',
+        owner_key: opts.ownerKey,
+        tags: opts.tags ? opts.tags.split(',').map(t => t.trim()) : undefined
+      });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+targetsCmd
+  .command('list')
+  .description('List targets with live-computed actuals and status')
+  .option('--status <status>', 'Filter by status: on_track, at_risk, behind, achieved, failed')
+  .option('--type <type>', 'Filter by target_type')
+  .option('--metric <metric>', 'Filter by metric')
+  .option('--owner-key <key>', 'Filter by owner API key')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = {};
+      if (opts.status) params.status = opts.status;
+      if (opts.type) params.target_type = opts.type;
+      if (opts.metric) params.metric = opts.metric;
+      if (opts.ownerKey) params.owner_key = opts.ownerKey;
+      const res = await client.get('/targets', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+targetsCmd
+  .command('get <id>')
+  .description('Get a target with full breakdown: current, remaining, attainment %, days remaining')
+  .action(async (id) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.get(`/targets/${id}`);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+targetsCmd
+  .command('update <id>')
+  .description('Update a target')
+  .option('--name <name>', 'New name')
+  .option('--goal <value>', 'New goal value', parseFloat)
+  .option('--period-start <date>', 'New period start')
+  .option('--period-end <date>', 'New period end')
+  .option('--unit <unit>', 'New unit label')
+  .option('--owner-key <key>', 'New owner API key')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const body = {};
+      if (opts.name) body.name = opts.name;
+      if (opts.goal !== undefined) body.goal_value = opts.goal;
+      if (opts.periodStart) body.period_start = opts.periodStart;
+      if (opts.periodEnd) body.period_end = opts.periodEnd;
+      if (opts.unit) body.unit = opts.unit;
+      if (opts.ownerKey) body.owner_key = opts.ownerKey;
+      const res = await client.patch(`/targets/${id}`, body);
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+targetsCmd
+  .command('progress <id>')
+  .description('Log manual progress toward a target')
+  .requiredOption('--value <n>', 'Progress value to add', parseFloat)
+  .option('--source <src>', 'Source: manual, auto_calls, auto_emails, auto_meetings, auto_leads (default: manual)')
+  .option('--note <note>', 'Context note')
+  .option('--logged-at <iso>', 'When this progress happened (ISO8601, defaults to now)')
+  .action(async (id, opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const res = await client.post(`/targets/${id}/progress`, {
+        value: opts.value,
+        source: opts.source || 'manual',
+        note: opts.note,
+        logged_at: opts.loggedAt
+      });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+targetsCmd
+  .command('dashboard')
+  .description('Show all active targets with attainment % and status summary')
+  .option('--owner-key <key>', 'Filter by owner API key')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = {};
+      if (opts.ownerKey) params.owner_key = opts.ownerKey;
+      const res = await client.get('/targets/dashboard', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// ============================================================
+// PERFORMANCE REPORT command — Sprint 5
+// ============================================================
+program
+  .command('performance')
+  .description('Combined performance report: all targets + budgets in one JSON response')
+  .option('--period-start <date>', 'Filter from date (YYYY-MM-DD)')
+  .option('--period-end <date>', 'Filter to date (YYYY-MM-DD)')
+  .option('--owner-key <key>', 'Filter by owner API key')
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const client = getClient(globalOpts);
+    try {
+      const params = {};
+      if (opts.periodStart) params.period_start = opts.periodStart;
+      if (opts.periodEnd) params.period_end = opts.periodEnd;
+      if (opts.ownerKey) params.owner_key = opts.ownerKey;
+      const res = await client.get('/performance', { params });
+      printJSON(res.data);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
 program.parse(process.argv);

package/package.json

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