@velaro/cli 1.4.17 → 1.4.19

package/bin/velaro.js

@@ -81,6 +81,8 @@ import { surveyCommand }            from '../lib/commands/survey.js';
 import { bundleCommand }            from '../lib/commands/bundle.js';
 import { featureDiscoveryCommand }  from '../lib/commands/feature-discovery.js';
 import { campaignsCommand }         from '../lib/commands/campaigns.js';
+import { contactsCommand }          from '../lib/commands/contacts.js';
+import { contactListCommand }       from '../lib/commands/contact-list.js';
 import { startUpdateCheck }  from '../lib/update-check.js';
 import { printBannerIfFirstRun } from '../lib/banner.js';
 
@@ -171,6 +173,8 @@ await yargs(hideBin(process.argv))
   .command(bundleCommand)
   .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
   .command(campaignsCommand)
+  .command(contactsCommand)
+  .command(contactListCommand)
   .demandCommand(1, 'Specify a command. Run "velaro --help" for options.')
   .strict()
   .help()

package/lib/commands/contact-list.js

@@ -0,0 +1,297 @@
+import { request, getCredentials } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro contact-list -------------------------------------------------------
+// CLI surface for Velaro's marketing Contact Lists (server/Velaro.Admin/Controllers/
+// ContactListController.cs). siteId is applied server-side from the authenticated
+// session/service key, never a CLI arg.
+//
+// Backend contract (core CRUD/read surface -- see file-level comment in the
+// controller for why StartImport/GetImportStatus/ImportSuppression/AcceptTerms/
+// ResetTerms/NotifyContactMerge/PurgeInactiveContacts are intentionally NOT here):
+//   GET    ContactLists                                  -> ContactListController.GetLists
+//   POST   ContactLists            { name, description?, color? } -> ContactListController.CreateList
+//   PUT    ContactLists/{id}       { name?, description?, color? } -> ContactListController.UpdateList
+//   DELETE ContactLists/{id}                             -> ContactListController.DeleteList
+//   GET    ContactLists/{id}/Members?page=&pageSize=&search=&sortBy=&sortDir= -> ContactListController.GetMembers
+//   POST   ContactLists/{id}/Members { email, name?, phone?, tags? } -> ContactListController.AddMember
+//   DELETE ContactLists/{id}/Members/{memberId}          -> ContactListController.RemoveMember
+//   GET    ContactLists/{id}/Export                      -> ContactListController.ExportList (CSV)
+//   POST   ContactLists/{id}/Resync                      -> ContactListController.ResyncList
+//   PUT    ContactLists/{id}/AutoResync { enabled }      -> ContactListController.SetAutoResync
+//   GET    Campaigns/Quota                               -> ContactListController.GetQuota
+//   GET    ContactSegments/{id}/Members                  -> ContactListController.GetSegmentMembers
+//   POST   ContactLists/crm-preview     { filters }      -> ContactListController.CrmPreview
+//   POST   ContactLists/import-from-crm { filters, newListName? | listId? } -> ContactListController.ImportFromCrm
+
+function fmtRow(label, value) {
+  console.log(`  ${label.padEnd(24)}${value ?? '—'}`);
+}
+
+// GET ContactLists -> ContactListController.GetLists
+async function listsHandler() {
+  const lists = await request('GET', 'ContactLists');
+  if (!lists.length) {
+    console.log('\nNo contact lists yet.\n');
+    return;
+  }
+  console.log(`\nContact lists (${lists.length}):\n`);
+  for (const l of lists) {
+    console.log(`  #${l.id}  ${(l.name || '').padEnd(30)} ${l.memberCount} member(s)  ${l.syncSource ? `[${l.syncSource}${l.autoResyncEnabled ? ', auto-resync' : ''}]` : ''}`);
+  }
+  console.log('');
+}
+
+async function createListHandler(argv) {
+  const result = await request('POST', 'ContactLists', { name: argv.name, description: argv.description, color: argv.color });
+  console.log(`\n✅ Created list "${argv.name}" (id ${result.id}).\n`);
+}
+
+async function updateListHandler(argv) {
+  await request('PUT', `ContactLists/${argv.id}`, { name: argv.name, description: argv.description, color: argv.color });
+  console.log(`\n✅ List #${argv.id} updated.\n`);
+}
+
+async function deleteListHandler(argv) {
+  await request('DELETE', `ContactLists/${argv.id}`);
+  console.log(`\n✅ List #${argv.id} deleted.\n`);
+}
+
+async function membersHandler(argv) {
+  const params = new URLSearchParams();
+  params.set('page', String(argv.page ?? 1));
+  params.set('pageSize', String(argv.pageSize ?? 50));
+  if (argv.search) params.set('search', argv.search);
+  if (argv.sortBy) params.set('sortBy', argv.sortBy);
+  if (argv.sortDir) params.set('sortDir', argv.sortDir);
+
+  const result = await request('GET', `ContactLists/${argv.id}/Members?${params.toString()}`);
+  const items = result?.items ?? [];
+  if (!items.length) {
+    console.log('\nNo members found.\n');
+    return;
+  }
+  console.log(`\n${result.total} total member(s) (page ${result.page}, showing ${items.length})\n`);
+  for (const m of items) {
+    console.log(`  #${m.id}  ${(m.name || '').padEnd(24)} ${(m.email || '').padEnd(32)} ${m.phone || ''}`);
+  }
+  console.log('');
+}
+
+// POST ContactLists/{listId}/Members -> ContactListController.AddMember
+async function addMemberHandler(argv) {
+  const result = await request('POST', `ContactLists/${argv.id}/Members`, {
+    email: argv.email, name: argv.name, phone: argv.phone, tags: argv.tags,
+  });
+  console.log(result.isNew ? `\n✅ Added ${argv.email} to list #${argv.id}.\n` : `\n${argv.email} was already a member of list #${argv.id}.\n`);
+}
+
+// DELETE ContactLists/{listId}/Members/{memberId} -> ContactListController.RemoveMember
+async function removeMemberHandler(argv) {
+  await request('DELETE', `ContactLists/${argv.id}/Members/${argv.memberId}`);
+  console.log(`\n✅ Member #${argv.memberId} removed from list #${argv.id}.\n`);
+}
+
+// GET ContactLists/{listId}/Export -> ContactListController.ExportList
+async function exportListHandler(argv) {
+  const { writeFileSync } = await import('fs');
+  const creds = await getCredentials();
+  if (!creds.adminApiBase) throw new Error('No adminApiBase configured for this environment. Run: velaro login');
+  const res = await fetch(`${creds.adminApiBase.replace(/\/+$/, '')}/ContactLists/${argv.id}/Export`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}` },
+  });
+  if (!res.ok) throw new Error(`GET ContactLists/${argv.id}/Export -> ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const outPath = argv.out || `contact-list-${argv.id}-export.csv`;
+  writeFileSync(outPath, buf);
+  console.log(`\n✅ List #${argv.id} exported to ${outPath}\n`);
+}
+
+async function resyncListHandler(argv) {
+  const result = await request('POST', `ContactLists/${argv.id}/Resync`, {});
+  if (result.syncError) {
+    console.log(`\nResync failed for list #${argv.id}: ${result.syncError}\n`);
+    return;
+  }
+  console.log(`\n✅ List #${argv.id} resynced. Status: ${result.syncStatus}, members: ${result.memberCount}, last synced: ${result.lastSyncedAt}\n`);
+}
+
+async function autoResyncHandler(argv) {
+  await request('PUT', `ContactLists/${argv.id}/AutoResync`, { enabled: argv.enabled });
+  console.log(`\n✅ Auto-resync ${argv.enabled ? 'enabled' : 'disabled'} for list #${argv.id}.\n`);
+}
+
+// GET Campaigns/Quota -> ContactListController.GetQuota
+async function quotaHandler() {
+  const q = await request('GET', 'Campaigns/Quota');
+  console.log('\nCampaign / Contact Quota\n');
+  fmtRow('Outbound campaigns', q.enableOutboundCampaigns ? 'enabled' : 'disabled');
+  fmtRow('SMS',                q.enableSms ? 'enabled' : 'disabled');
+  fmtRow('Max contacts',       q.maxContacts);
+  fmtRow('Contact count',      q.contactCount);
+  fmtRow('Max emails/month',   q.maxEmailsPerMonth);
+  fmtRow('Emails sent (mo)',   q.currentMonthEmailCount);
+  fmtRow('Remaining emails',   q.remainingEmails ?? 'unlimited');
+  fmtRow('Verified sender domain', q.hasVerifiedDomain ? (q.verifiedDomains ?? []).join(', ') : 'none');
+  fmtRow('Terms accepted',     q.termsAccepted ? `yes (${q.termsAcceptedAt})` : 'no');
+  console.log('');
+}
+
+// GET ContactSegments/{id}/Members -> ContactListController.GetSegmentMembers
+async function segmentMembersHandler(argv) {
+  const params = new URLSearchParams();
+  params.set('page', String(argv.page ?? 1));
+  params.set('pageSize', String(argv.pageSize ?? 50));
+  if (argv.search) params.set('search', argv.search);
+  const result = await request('GET', `ContactSegments/${argv.id}/Members?${params.toString()}`);
+  const items = result?.items ?? [];
+  if (!items.length) {
+    console.log('\nNo members found for this segment.\n');
+    return;
+  }
+  console.log(`\n${result.total} total member(s) in segment #${argv.id} (showing ${items.length})\n`);
+  for (const m of items) console.log(`  ${m.name || m.fullName || ''}  <${m.email}>`);
+  console.log('');
+}
+
+function buildCrmFilters(argv) {
+  return {
+    source:       argv.source ?? 'velaro',
+    requireEmail: argv.requireEmail ?? true,
+    requirePhone: argv.requirePhone ?? false,
+    company:      argv.company,
+    country:      argv.country,
+    createdAfter: argv.createdAfter,
+  };
+}
+
+// POST ContactLists/crm-preview -> ContactListController.CrmPreview
+async function crmPreviewHandler(argv) {
+  const result = await request('POST', 'ContactLists/crm-preview', buildCrmFilters(argv));
+  if (result.stub) { console.log(`\n${result.message}\n`); return; }
+  console.log(`\n${result.count} contact(s) match this filter. Sample:\n`);
+  for (const p of result.preview ?? []) console.log(`  ${p.name}  <${p.email}>  ${p.company ?? ''}`);
+  console.log('');
+}
+
+// POST ContactLists/import-from-crm -> ContactListController.ImportFromCrm
+async function importFromCrmHandler(argv) {
+  const body = {
+    filters: buildCrmFilters(argv),
+    newListName: argv.newListName,
+    listId: argv.listId,
+  };
+  const result = await request('POST', 'ContactLists/import-from-crm', body);
+  if (result.stub) { console.log(`\n${result.message}\n`); return; }
+  console.log(`\n✅ List "${result.listName}" (id ${result.listId}): ${result.added} added, ${result.skipped} skipped.\n`);
+}
+
+const crmFilterOptions = (y) => y
+  .option('source',       { type: 'string',  default: 'velaro', describe: 'CRM source key (only "velaro" is live today; others return a stub)' })
+  .option('requireEmail', { type: 'boolean', default: true,     describe: 'Only include contacts with an email address' })
+  .option('requirePhone', { type: 'boolean', default: false,    describe: 'Only include contacts with a phone number' })
+  .option('company',      { type: 'string',  describe: 'Filter by company name (contains)' })
+  .option('country',      { type: 'string',  describe: 'Filter by exact country' })
+  .option('createdAfter', { type: 'string',  describe: 'Only include contacts created after this ISO date' });
+
+export const contactListCommand = {
+  command:  'contact-list <subcommand>',
+  describe: 'Marketing contact lists: CRUD, members, export, resync, quota, segments, CRM import',
+  builder:  (y) => y
+    .command({ command: 'list', describe: 'List all contact lists for this site', handler: runCommand(listsHandler) })
+    .command({
+      command:  'create',
+      describe: 'Create a new contact list',
+      builder:  (y2) => y2
+        .option('name',        { type: 'string', demandOption: true })
+        .option('description', { type: 'string' })
+        .option('color',       { type: 'string', describe: 'Hex color, e.g. #3B82F6' }),
+      handler: runCommand(createListHandler),
+    })
+    .command({
+      command:  'update <id>',
+      describe: 'Update a contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' })
+        .option('name',        { type: 'string' })
+        .option('description', { type: 'string' })
+        .option('color',       { type: 'string' }),
+      handler: runCommand(updateListHandler),
+    })
+    .command({
+      command:  'delete <id>',
+      describe: 'Delete a contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(deleteListHandler),
+    })
+    .command({
+      command:  'members <id>',
+      describe: 'Paginated list of members in a contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' })
+        .option('page',     { type: 'number', default: 1 })
+        .option('pageSize', { type: 'number', default: 50 })
+        .option('search',   { type: 'string' })
+        .option('sortBy',   { type: 'string', choices: ['email', 'name', 'addedAt'] })
+        .option('sortDir',  { type: 'string', choices: ['asc', 'desc'] }),
+      handler: runCommand(membersHandler),
+    })
+    .command({
+      command:  'add-member <id>',
+      describe: 'Add a member to a contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' })
+        .option('email', { type: 'string', demandOption: true })
+        .option('name',  { type: 'string' })
+        .option('phone', { type: 'string' })
+        .option('tags',  { type: 'string' }),
+      handler: runCommand(addMemberHandler),
+    })
+    .command({
+      command:  'remove-member <id> <memberId>',
+      describe: 'Remove a member from a contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' }).positional('memberId', { type: 'number' }),
+      handler:  runCommand(removeMemberHandler),
+    })
+    .command({
+      command:  'export <id>',
+      describe: 'Export a contact list to CSV',
+      builder:  (y2) => y2.positional('id', { type: 'number' }).option('out', { type: 'string', describe: 'Output file path' }),
+      handler:  runCommand(exportListHandler),
+    })
+    .command({
+      command:  'resync <id>',
+      describe: 'Re-synchronize a CRM-sourced list, or recompute member count for a manual/CSV list',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(resyncListHandler),
+    })
+    .command({
+      command:  'auto-resync <id>',
+      describe: 'Enable/disable nightly auto-resync (crm:velaro-sourced lists only)',
+      builder:  (y2) => y2.positional('id', { type: 'number' }).option('enabled', { type: 'boolean', demandOption: true }),
+      handler:  runCommand(autoResyncHandler),
+    })
+    .command({ command: 'quota', describe: 'Show campaign/contact quota and usage for this site', handler: runCommand(quotaHandler) })
+    .command({
+      command:  'segment-members <id>',
+      describe: 'Paginated list of contacts matching a segment',
+      builder:  (y2) => y2.positional('id', { type: 'number' })
+        .option('page',     { type: 'number', default: 1 })
+        .option('pageSize', { type: 'number', default: 50 })
+        .option('search',   { type: 'string' }),
+      handler: runCommand(segmentMembersHandler),
+    })
+    .command({
+      command:  'crm-preview',
+      describe: 'Preview how many contacts would be imported into a list, without saving',
+      builder:  crmFilterOptions,
+      handler:  runCommand(crmPreviewHandler),
+    })
+    .command({
+      command:  'import-from-crm',
+      describe: 'Import contacts into a new or existing list from a CRM source (Phase 1: "velaro" only)',
+      builder:  (y2) => crmFilterOptions(y2)
+        .option('newListName', { type: 'string', describe: 'Create a new list with this name' })
+        .option('listId',      { type: 'number', describe: 'Import into an existing list instead of creating one' }),
+      handler: runCommand(importFromCrmHandler),
+    })
+    .demandCommand(1, 'Specify a contact-list subcommand: list | create | update | delete | members | add-member | remove-member | export | resync | auto-resync | quota | segment-members | crm-preview | import-from-crm'),
+  handler: () => {},
+};

package/lib/commands/contacts.js

@@ -0,0 +1,232 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro contacts ----------------------------------------------------------
+// CLI surface for Velaro's native Contacts CRM (server/Velaro.Admin/Controllers/
+// ContactsController.cs). siteId is applied server-side from the authenticated
+// session/service key, never a CLI arg.
+//
+// Backend contract:
+//   GET  Contacts?search=&tag=&source=&page=&pageSize=     -> ContactsController.GetContacts
+//   GET  Contacts/{id}                                     -> ContactsController.GetContact
+//   POST Contacts/{id}/Notes            { noteText }       -> ContactsController.AddNote
+//   GET  Contacts/{id}/Timeline                            -> ContactsController.GetTimeline
+//   GET  Contacts/{id}/ImportedHistory                      -> ContactsController.GetImportedHistory
+//   POST Contacts/import-from-crm       { filters }        -> ContactsController.ImportFromCrm
+//   POST Contacts/crm-preview           { filters }        -> ContactsController.CrmPreview
+//   POST Contacts/{id}/Tags             { tagId }          -> ContactsController.AddTag
+//   GET  Contacts/Tags                                     -> ContactsController.GetTags
+
+function fmtRow(label, value) {
+  console.log(`  ${label.padEnd(20)}${value ?? '—'}`);
+}
+
+// GET Contacts -> ContactsController.GetContacts
+async function searchHandler(argv) {
+  const params = new URLSearchParams();
+  if (argv.search)   params.set('search', argv.search);
+  if (argv.tag)      params.set('tag', argv.tag);
+  if (argv.source)   params.set('source', argv.source);
+  params.set('page', String(argv.page ?? 1));
+  params.set('pageSize', String(argv.pageSize ?? 50));
+
+  const result = await request('GET', `Contacts?${params.toString()}`);
+  const items = result?.items ?? [];
+  if (!items.length) {
+    console.log('\nNo contacts found.\n');
+    return;
+  }
+  console.log(`\n${result.total} total contact(s) (page ${result.page}, showing ${items.length})\n`);
+  for (const c of items) {
+    const tags = (c.tags ?? []).map(t => t.name).join(', ');
+    console.log(`  #${c.id}  ${(c.fullName || '(no name)').padEnd(28)} ${(c.email || '').padEnd(30)} ${c.company || ''}${tags ? `  [${tags}]` : ''}`);
+  }
+  console.log('');
+}
+
+// GET Contacts/{id} -> ContactsController.GetContact
+async function getHandler(argv) {
+  const c = await request('GET', `Contacts/${argv.id}`);
+  console.log(`\nContact #${c.id}: ${c.fullName}`);
+  fmtRow('Email',    c.email);
+  fmtRow('Phone',    c.phone || c.mobile);
+  fmtRow('Company',  c.company);
+  fmtRow('Title',    c.jobTitle);
+  fmtRow('Location', [c.city, c.state, c.country].filter(Boolean).join(', '));
+  fmtRow('Created',  c.dateCreated);
+  fmtRow('Last activity', c.lastActivity);
+  if (c.tags?.length) fmtRow('Tags', c.tags.map(t => t.name).join(', '));
+  if (c.notes?.length) {
+    console.log(`\n  Notes (${c.notes.length}):`);
+    for (const n of c.notes) console.log(`    [${n.createdAt}] ${n.noteText}`);
+  }
+  console.log('');
+}
+
+// POST Contacts/{id}/Notes -> ContactsController.AddNote
+async function addNoteHandler(argv) {
+  const note = await request('POST', `Contacts/${argv.id}/Notes`, { noteText: argv.text });
+  console.log(`\n✅ Note added to contact #${argv.id} (note #${note.id}).\n`);
+}
+
+// GET Contacts/{id}/Timeline -> ContactsController.GetTimeline
+async function timelineHandler(argv) {
+  const events = await request('GET', `Contacts/${argv.id}/Timeline`);
+  const list = Array.isArray(events) ? events : (events?.items ?? []);
+  if (!list.length) {
+    console.log('\nNo timeline activity for this contact.\n');
+    return;
+  }
+  console.log(`\nTimeline for contact #${argv.id} (${list.length} events)\n`);
+  for (const e of list) {
+    console.log(`  [${e.timestamp ?? e.date ?? '—'}] ${e.type ?? e.eventType ?? 'event'}: ${e.summary ?? e.description ?? ''}`);
+  }
+  console.log('');
+}
+
+// GET Contacts/{id}/ImportedHistory -> ContactsController.GetImportedHistory
+async function importedHistoryHandler(argv) {
+  const tickets = await request('GET', `Contacts/${argv.id}/ImportedHistory`);
+  if (!tickets.length) {
+    console.log('\nNo imported (backfilled) ticket history for this contact.\n');
+    return;
+  }
+  console.log(`\nImported ticket history for contact #${argv.id} (${tickets.length})\n`);
+  for (const t of tickets) {
+    console.log(`  [${t.providerSlug}] #${t.externalTicketId} ${t.status?.padEnd(10) ?? ''} ${t.subject ?? ''} (${t.createdAtSource})`);
+  }
+  console.log('');
+}
+
+function buildCrmFilters(argv) {
+  return {
+    source:       argv.source ?? 'velaro',
+    requireEmail: argv.requireEmail ?? true,
+    requirePhone: argv.requirePhone ?? false,
+    company:      argv.company,
+    country:      argv.country,
+    createdAfter: argv.createdAfter,
+  };
+}
+
+// POST Contacts/crm-preview -> ContactsController.CrmPreview
+async function crmPreviewHandler(argv) {
+  const result = await request('POST', 'Contacts/crm-preview', buildCrmFilters(argv));
+  if (result.stub) {
+    console.log(`\n${result.message}\n`);
+    return;
+  }
+  console.log(`\n${result.count} contact(s) match this filter. Sample:\n`);
+  for (const p of result.preview ?? []) console.log(`  ${p.name}  <${p.email}>  ${p.company ?? ''}`);
+  console.log('');
+}
+
+// POST Contacts/import-from-crm -> ContactsController.ImportFromCrm
+async function importFromCrmHandler(argv) {
+  // ContactCrmImportRequest wraps the filters in a `Filters` property -- unlike crm-preview,
+  // which binds ContactCrmImportFilters flat. Sending the filters unwrapped here silently no-ops
+  // (request?.Filters is null server-side, which reads as "unknown CRM source").
+  const result = await request('POST', 'Contacts/import-from-crm', { filters: buildCrmFilters(argv) });
+  if (result.stub) {
+    console.log(`\n${result.message}\n`);
+    return;
+  }
+  console.log(`\n✅ Imported ${result.added} new contact(s), skipped ${result.skipped} existing (of ${result.total} matched).\n`);
+}
+
+// GET Contacts/Tags -> ContactsController.GetTags
+async function tagsListHandler() {
+  const tags = await request('GET', 'Contacts/Tags');
+  if (!tags.length) {
+    console.log('\nNo contact tags defined for this site.\n');
+    return;
+  }
+  console.log(`\nContact tags (${tags.length}):\n`);
+  for (const t of tags) console.log(`  #${t.id}  ${t.name}  (${t.color})`);
+  console.log('');
+}
+
+// POST Contacts/{id}/Tags -> ContactsController.AddTag
+async function addTagHandler(argv) {
+  const result = await request('POST', `Contacts/${argv.id}/Tags`, { tagId: argv.tagId });
+  console.log(result.success ? `\n✅ Tag ${argv.tagId} added to contact #${argv.id}.\n` : '\nFailed to add tag.\n');
+}
+
+const tagsCommand = {
+  command:  'tags <subcommand>',
+  describe: 'Manage contact tags',
+  builder:  (y) => y
+    .command({ command: 'list', describe: 'List all contact tags for this site', handler: runCommand(tagsListHandler) })
+    .command({
+      command:  'add <id> <tagId>',
+      describe: 'Add an existing tag to a contact',
+      builder:  (y2) => y2.positional('id', { type: 'number' }).positional('tagId', { type: 'number' }),
+      handler:  runCommand(addTagHandler),
+    })
+    .demandCommand(1, 'Specify a tags subcommand: list | add'),
+  handler: () => {},
+};
+
+const crmFilterOptions = (y) => y
+  .option('source',       { type: 'string',  default: 'velaro', describe: 'CRM source key (only "velaro" is live today; others return a stub)' })
+  .option('requireEmail', { type: 'boolean', default: true,     describe: 'Only include contacts with an email address' })
+  .option('requirePhone', { type: 'boolean', default: false,    describe: 'Only include contacts with a phone number' })
+  .option('company',      { type: 'string',  describe: 'Filter by company name (contains)' })
+  .option('country',      { type: 'string',  describe: 'Filter by exact country' })
+  .option('createdAfter', { type: 'string',  describe: 'Only include contacts created after this ISO date' });
+
+export const contactsCommand = {
+  command:  'contacts <subcommand>',
+  describe: 'Velaro native Contacts CRM: search, profile, notes, timeline, tags, CRM import',
+  builder:  (y) => y
+    .command({
+      command:  'search',
+      describe: 'Paginated contact search',
+      builder:  (y2) => y2
+        .option('search',   { type: 'string', describe: 'Full-text search across name/email/company' })
+        .option('tag',      { type: 'string', describe: 'Filter by tag name' })
+        .option('source',   { type: 'string', describe: '"chat" (conversation-sourced, default) or "crm"' })
+        .option('page',     { type: 'number', default: 1 })
+        .option('pageSize', { type: 'number', default: 50 }),
+      handler: runCommand(searchHandler),
+    })
+    .command({
+      command:  'get <id>',
+      describe: 'Show a contact profile (with tags + recent notes)',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(getHandler),
+    })
+    .command({
+      command:  'add-note <id>',
+      describe: 'Add a note to a contact',
+      builder:  (y2) => y2.positional('id', { type: 'number' }).option('text', { type: 'string', demandOption: true, describe: 'Note text' }),
+      handler:  runCommand(addNoteHandler),
+    })
+    .command({
+      command:  'timeline <id>',
+      describe: 'Merged chronological activity feed for a contact (notes, campaign emails, broadcasts)',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(timelineHandler),
+    })
+    .command({
+      command:  'imported-history <id>',
+      describe: 'Read-only backfilled ticket history for a contact (e.g. from a Zendesk import)',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(importedHistoryHandler),
+    })
+    .command({
+      command:  'crm-preview',
+      describe: 'Preview how many contacts would be imported by a CRM import filter, without saving',
+      builder:  crmFilterOptions,
+      handler:  runCommand(crmPreviewHandler),
+    })
+    .command({
+      command:  'import-from-crm',
+      describe: 'Import contacts from a CRM source (Phase 1: "velaro" only). Deduplicates by email.',
+      builder:  crmFilterOptions,
+      handler:  runCommand(importFromCrmHandler),
+    })
+    .command(tagsCommand)
+    .demandCommand(1, 'Specify a contacts subcommand: search | get | add-note | timeline | imported-history | crm-preview | import-from-crm | tags'),
+  handler: () => {},
+};

package/lib/commands/report.js

@@ -1,4 +1,6 @@
+import { writeFileSync } from 'fs';
 import { getCredentials, request, messagingRequest } from '../api.js';
+import { runCommand } from '../run.js';
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -446,17 +448,198 @@ const workedHoursCommand = {
   },
 };
 
+// ── scheduled reports (Reports/Schedules) ──────────────────────────────────────
+// Backend: server/Velaro.Admin/Controllers/ReportsController.cs
+//   GET  Reports/Schedules -> scheduledReport[]
+//   PUT  Reports/Schedules { reportType, frequency?, recipientEmails?, isEnabled } -> { saved }
+
+// GET Reports/Schedules -> ReportsController.GetSchedules
+async function schedulesListHandler() {
+  const rows = await request('GET', 'Reports/Schedules');
+  if (!rows.length) {
+    console.log('\nNo scheduled reports configured for this site.\n');
+    return;
+  }
+  section('Scheduled Reports');
+  for (const s of rows) {
+    console.log(`  ${(s.reportType ?? '').padEnd(24)} ${s.isEnabled ? 'enabled ' : 'disabled'}  ${(s.frequency ?? '').padEnd(12)} -> ${s.recipientEmails || '(no recipients)'}`);
+  }
+  console.log('');
+}
+
+// PUT Reports/Schedules -> ReportsController.UpsertSchedule
+async function schedulesUpsertHandler(argv) {
+  const result = await request('PUT', 'Reports/Schedules', {
+    reportType:      argv.type,
+    frequency:       argv.frequency,
+    recipientEmails: argv.recipients,
+    isEnabled:       argv.enabled,
+  });
+  console.log(result.saved ? `\n✅ Schedule saved for report type "${argv.type}".\n` : '\nFailed to save schedule.\n');
+}
+
+const schedulesCommand = {
+  command:  'schedules <subcommand>',
+  describe: 'Manage recurring report email schedules (Reports/Schedules)',
+  builder:  (y) => y
+    .command({
+      command:  'list',
+      describe: 'List scheduled reports for this site',
+      handler:  runCommand(schedulesListHandler),
+    })
+    .command({
+      command:  'upsert',
+      describe: 'Create or update the schedule for a report type',
+      builder:  (y2) => y2
+        .option('type',       { type: 'string',  demandOption: true, describe: 'Report type, e.g. account-overview | agent-utilization | compliance' })
+        .option('frequency',  { type: 'string',  choices: ['daily', 'weekly', 'bi-monthly', 'monthly'], describe: 'How often to send (default: monthly on create)' })
+        .option('recipients', { type: 'string',  describe: 'Comma-separated recipient email addresses' })
+        .option('enabled',    { type: 'boolean', demandOption: true, describe: 'Enable or disable this schedule' }),
+      handler: runCommand(schedulesUpsertHandler),
+    })
+    .demandCommand(1, 'Specify a schedules subcommand: list | upsert'),
+  handler: () => {},
+};
+
+// ── async report exports (Reports/ExportAsync, /ExportStatus, /MyExports) ─────
+// Backend: server/Velaro.Admin/Controllers/ReportsController.cs
+//   POST Reports/ExportAsync         { startDate, endDate, reportType?, format?, recipientEmail? } -> { exportId, status }
+//   GET  Reports/ExportStatus/{id}   -> exportStatus
+//   GET  Reports/MyExports           -> exportStatus[] (last 30 days)
+//   POST Reports/Compliance          { startDate?, endDate? } -> xlsx (activity audit log)
+//   POST Reports/AgentUtilization/Export { startDate?, endDate? } -> xlsx
+
+// POST Reports/ExportAsync -> ReportsController.StartAsyncExport
+async function exportStartHandler(argv) {
+  const result = await request('POST', 'Reports/ExportAsync', {
+    startDate:      argv.start,
+    endDate:        argv.end,
+    reportType:     argv.type,
+    format:         argv.format,
+    recipientEmail: argv.recipient,
+  });
+  console.log(`\nExport queued (id ${result.exportId}). ${result.message}\n`);
+}
+
+// GET Reports/ExportStatus/{id} -> ReportsController.GetExportStatus
+async function exportStatusHandler(argv) {
+  const s = await request('GET', `Reports/ExportStatus/${argv.id}`);
+  section(`Export #${s.id}`);
+  fmtRow('Status',       s.status);
+  fmtRow('Report type',  s.reportType);
+  fmtRow('Format',       s.format);
+  fmtRow('Range',        `${s.startDate} -> ${s.endDate}`);
+  fmtRow('Download URL', s.downloadUrl || '(not ready)');
+  if (s.errorMessage) fmtRow('Error', s.errorMessage);
+  console.log('');
+}
+
+// GET Reports/MyExports -> ReportsController.GetMyExports
+async function myExportsHandler() {
+  const rows = await request('GET', 'Reports/MyExports');
+  if (!rows.length) {
+    console.log('\nNo report exports in the last 30 days.\n');
+    return;
+  }
+  section('Recent Report Exports (last 30 days)');
+  for (const e of rows) {
+    console.log(`  #${e.id}  ${(e.status ?? '').padEnd(10)} ${(e.reportType ?? '').padEnd(20)} ${e.startDate} -> ${e.endDate}${e.isExpired ? '  (expired)' : ''}`);
+  }
+  console.log('');
+}
+
+async function downloadXlsxViaPost(path, body, outPath) {
+  const creds = await getCredentials();
+  if (!creds.adminApiBase) throw new Error('No adminApiBase configured for this environment. Run: velaro login');
+  const res = await fetch(`${creds.adminApiBase.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`POST /${path} -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  writeFileSync(outPath, buf);
+  return outPath;
+}
+
+// POST Reports/Compliance -> ReportsController.GenerateComplianceReport
+async function complianceReportHandler(argv) {
+  const outPath = argv.out || `compliance-report-${Date.now()}.xlsx`;
+  await downloadXlsxViaPost('Reports/Compliance', { startDate: argv.start, endDate: argv.end }, outPath);
+  console.log(`\n✅ Compliance report saved to ${outPath}\n`);
+}
+
+// POST Reports/AgentUtilization/Export -> ReportsController.ExportAgentUtilization
+async function agentUtilizationExportHandler(argv) {
+  const outPath = argv.out || `agent-utilization-${Date.now()}.xlsx`;
+  await downloadXlsxViaPost('Reports/AgentUtilization/Export', { startDate: argv.start, endDate: argv.end }, outPath);
+  console.log(`\n✅ Agent utilization report saved to ${outPath}\n`);
+}
+
+const exportCommand = {
+  command:  'export <subcommand>',
+  describe: 'Generate and track large/async report exports (Reports/ExportAsync, Compliance, AgentUtilization)',
+  builder:  (y) => y
+    .command({
+      command:  'start',
+      describe: 'Queue an async report export (emailed download link when ready)',
+      builder:  (y2) => y2
+        .option('start',     { type: 'string', demandOption: true, describe: 'Start date (YYYY-MM-DD)' })
+        .option('end',       { type: 'string', demandOption: true, describe: 'End date (YYYY-MM-DD)' })
+        .option('type',      { type: 'string', describe: 'account-overview | agent-utilization | compliance (default account-overview)' })
+        .option('format',    { type: 'string', choices: ['xlsx', 'csv'], describe: 'Output format (default xlsx)' })
+        .option('recipient', { type: 'string', describe: 'Override recipient email (default: the authenticated user)' }),
+      handler: runCommand(exportStartHandler),
+    })
+    .command({
+      command:  'status <id>',
+      describe: 'Check the status of a queued export',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler:  runCommand(exportStatusHandler),
+    })
+    .command({
+      command:  'list',
+      describe: 'List recent report exports for this site (last 30 days)',
+      handler:  runCommand(myExportsHandler),
+    })
+    .command({
+      command:  'compliance',
+      describe: 'Download the activity-audit-log compliance report as xlsx (synchronous, <=366 days)',
+      builder:  (y2) => y2
+        .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD), default 30 days ago' })
+        .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD), default now' })
+        .option('out',   { type: 'string', describe: 'Output file path (default compliance-report-<timestamp>.xlsx)' }),
+      handler: runCommand(complianceReportHandler),
+    })
+    .command({
+      command:  'agent-utilization',
+      describe: 'Download agent utilization as xlsx (synchronous, <=366 days). For the JSON table view use "velaro report callcenter" instead.',
+      builder:  (y2) => y2
+        .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD), default 30 days ago' })
+        .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD), default now' })
+        .option('out',   { type: 'string', describe: 'Output file path (default agent-utilization-<timestamp>.xlsx)' }),
+      handler: runCommand(agentUtilizationExportHandler),
+    })
+    .demandCommand(1, 'Specify an export subcommand: start | status | list | compliance | agent-utilization'),
+  handler: () => {},
+};
+
 // ── top-level report command ──────────────────────────────────────────────────
 
 export const reportCommand = {
   command:  'report',
-  describe: 'Analytics reports: call center, service level, conversations, call activity',
+  describe: 'Analytics reports: call center, service level, conversations, call activity, schedules, exports',
   builder:  (y) => y
     .command(callcenterCommand)
     .command(servicelevelCommand)
     .command(conversationsCommand)
     .command(callactivityCommand)
     .command(workedHoursCommand)
+    .command(schedulesCommand)
+    .command(exportCommand)
     .demandCommand(1, 'Specify a report type. Run "velaro report --help" for options.'),
   handler: () => {},
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.17",
+  "version": "1.4.19",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {