@velaro/cli 1.4.203 → 1.4.205
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/velaro.js +5 -0
- package/lib/api.js +1 -0
- package/lib/commands/campaigns.js +31 -0
- package/lib/commands/crm-import-dedupe-audit.js +222 -0
- package/package.json +1 -1
package/bin/velaro.js
CHANGED
|
@@ -137,6 +137,7 @@ import { contactSegmentCommand } from '../lib/commands/contact-segment.js';
|
|
|
137
137
|
import { recycleBinCommand, aiUsageCommand, siteInfoCommand, billingReceiptsCommand } from '../lib/commands/endpoint-parity.js';
|
|
138
138
|
import { aiFollowupsCommand, businessActionCommand, callCommand, conversationCommand, conversionCommand, ivrCommand } from '../lib/commands/ops-groups.js';
|
|
139
139
|
import { crmViewCommand, crmBulkCommand, crmWebformCommand } from '../lib/commands/crm-views-bulk-webforms.js';
|
|
140
|
+
import { crmImportCommand, crmTagCommand, crmDedupeCommand, crmAuditCommand } from '../lib/commands/crm-import-dedupe-audit.js';
|
|
140
141
|
import { featureDiscoveryGroup } from '../lib/commands/feature-discovery.js';
|
|
141
142
|
import { billingInsightsGroup } from '../lib/commands/billing-insights.js';
|
|
142
143
|
import { supportTicketsCommand } from '../lib/commands/support-tickets.js';
|
|
@@ -321,6 +322,10 @@ await (registerStaffCommands ? registerStaffCommands(baseYargs) : baseYargs)
|
|
|
321
322
|
.command(crmViewCommand)
|
|
322
323
|
.command(crmBulkCommand)
|
|
323
324
|
.command(crmWebformCommand)
|
|
325
|
+
.command(crmImportCommand)
|
|
326
|
+
.command(crmTagCommand)
|
|
327
|
+
.command(crmDedupeCommand)
|
|
328
|
+
.command(crmAuditCommand)
|
|
324
329
|
.demandCommand(1, 'Specify a command. Run "velaro --help" for options.')
|
|
325
330
|
.strict()
|
|
326
331
|
.fail((msg, err, y) => {
|
package/lib/api.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* velaro campaigns benchmarks Your broadcast open/click rate vs. the Velaro average
|
|
5
5
|
* velaro campaigns revenue [--days N] Order revenue attributed to campaign email
|
|
6
6
|
* velaro campaigns revenue-window [--set DAYS] Read or set the attribution window (1-30 days)
|
|
7
|
+
* velaro campaigns sender [--source campaign|ticket|notification] [--name N] [--address A] [--reset] Read or set the From sender per mail source
|
|
7
8
|
*/
|
|
8
9
|
|
|
9
10
|
import { request } from '../api.js';
|
|
@@ -50,6 +51,26 @@ async function revenueWindowHandler(argv) {
|
|
|
50
51
|
console.log(`Attribution window: ${r.windowDays} days (max ${r.maxWindowDays})`);
|
|
51
52
|
}
|
|
52
53
|
|
|
54
|
+
async function senderHandler(argv) {
|
|
55
|
+
const src = argv.source || 'campaign';
|
|
56
|
+
if (argv.reset) {
|
|
57
|
+
const r = await request('DELETE', `/SiteSenderSettings/${encodeURIComponent(src)}`);
|
|
58
|
+
console.log(`Sender for ${r.source} reset to the account default (${r.effective.fromAddress}).`);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
if (argv.name !== undefined || argv.address !== undefined) {
|
|
62
|
+
const body = {};
|
|
63
|
+
if (argv.name !== undefined) body.fromName = String(argv.name);
|
|
64
|
+
if (argv.address !== undefined) body.fromAddress = String(argv.address);
|
|
65
|
+
const r = await request('PUT', `/SiteSenderSettings/${encodeURIComponent(src)}`, body);
|
|
66
|
+
console.log(`Sender for ${r.source}: ${r.effective.fromName} <${r.effective.fromAddress}>`);
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
const r = await request('GET', '/SiteSenderSettings');
|
|
70
|
+
for (const s of r.sources || []) console.log(`${s.source}: ${s.effective.fromName} <${s.effective.fromAddress}> (from ${s.effective.origin})`);
|
|
71
|
+
console.log(`Verified sending domains: ${(r.verifiedDomains || []).join(', ') || 'none'}`);
|
|
72
|
+
}
|
|
73
|
+
|
|
53
74
|
// -- command export ------------------------------------------------------------------
|
|
54
75
|
|
|
55
76
|
export const campaignsCommand = {
|
|
@@ -73,6 +94,16 @@ export const campaignsCommand = {
|
|
|
73
94
|
builder: y2 => y2.option('set', { type: 'number', describe: 'New window in days' }),
|
|
74
95
|
handler: runCommand(revenueWindowHandler),
|
|
75
96
|
})
|
|
97
|
+
.command({
|
|
98
|
+
command: 'sender',
|
|
99
|
+
describe: 'Read or set the From name/address per mail source (address must be on a verified sending domain)',
|
|
100
|
+
builder: y2 => y2
|
|
101
|
+
.option('source', { type: 'string', describe: 'Mail source (campaign, ticket, notification)' })
|
|
102
|
+
.option('name', { type: 'string', describe: 'From name' })
|
|
103
|
+
.option('address', { type: 'string', describe: 'From address (plain email)' })
|
|
104
|
+
.option('reset', { type: 'boolean', describe: 'Back to the account default' }),
|
|
105
|
+
handler: runCommand(senderHandler),
|
|
106
|
+
})
|
|
76
107
|
.demandCommand(1, 'Specify a subcommand. Try: velaro campaigns --help')
|
|
77
108
|
.strict(),
|
|
78
109
|
handler: () => {},
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import { messagingGet, messagingPost, messagingDel, messagingRequest } from '../api.js';
|
|
2
|
+
import { runCommand } from '../run.js';
|
|
3
|
+
|
|
4
|
+
// -- velaro crm-import / crm-tag / crm-dedupe / crm-audit ----------------------
|
|
5
|
+
// CLI for CRM Studio features 11 to 14 (docs/architecture/crm-studio-program.md):
|
|
6
|
+
// crm-import CrmImportController /CrmImport (CSV preview, commit and export)
|
|
7
|
+
// crm-tag CrmTagsController /CrmTags (tags on companies and deals)
|
|
8
|
+
// crm-dedupe CrmDealDuplicatesController /CrmDealDuplicates (find and merge duplicate deals)
|
|
9
|
+
// crm-audit CrmAuditController /CrmAudit (field-change history of one record)
|
|
10
|
+
// The site always comes from the signed-in credential; no command takes a site id.
|
|
11
|
+
// MCP parity: mcp/parity/crm-import-dedupe-audit.customer.js (crm_import_*, crm_tag_*, crm_dedupe_*, crm_audit_* tools).
|
|
12
|
+
|
|
13
|
+
const BOLD = '\x1b[1m';
|
|
14
|
+
const DIM = '\x1b[2m';
|
|
15
|
+
const RST = '\x1b[0m';
|
|
16
|
+
|
|
17
|
+
const ENTITIES = ['contact', 'company', 'deal'];
|
|
18
|
+
const TAG_ENTITIES = ['company', 'deal'];
|
|
19
|
+
|
|
20
|
+
const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
|
|
21
|
+
const printJson = (v) => console.log(JSON.stringify(v, null, 2));
|
|
22
|
+
const q = (o) => {
|
|
23
|
+
const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
|
|
24
|
+
return p.length ? `?${p.join('&')}` : '';
|
|
25
|
+
};
|
|
26
|
+
const json = (y) => y.option('json', { type: 'boolean', default: false, describe: 'Print raw JSON' });
|
|
27
|
+
const csvIds = (s) => String(s ?? '').split(',').map((x) => Number(x.trim())).filter((n) => Number.isFinite(n) && n > 0);
|
|
28
|
+
const parseJson = (text, what) => {
|
|
29
|
+
try { return JSON.parse(text); } catch { throw new Error(`[CRM] ${what} must be valid JSON.`); }
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
// ---------------------------------------------------------------- import and export
|
|
33
|
+
|
|
34
|
+
async function importBody(argv) {
|
|
35
|
+
const fs = await import('node:fs');
|
|
36
|
+
if (!argv.file) throw new Error('[CRM] --file must name the CSV file to import.');
|
|
37
|
+
const body = { entity: argv.entity, csv: fs.readFileSync(argv.file, 'utf8'), duplicates: argv.duplicates };
|
|
38
|
+
if (argv.mapping !== undefined) body.mapping = parseJson(argv.mapping, '--mapping');
|
|
39
|
+
if (argv.pipelineId !== undefined) body.pipelineId = argv.pipelineId;
|
|
40
|
+
return body;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function printImport(r, label) {
|
|
44
|
+
console.log(`\n${BOLD}${label}${RST}: ${r.entity ?? ''} rows`);
|
|
45
|
+
for (const [k, v] of Object.entries(r.counts ?? r.summary ?? {})) console.log(` ${k}: ${v}`);
|
|
46
|
+
for (const row of (r.rows ?? []).filter((x) => x.action === 'error' || x.action === 'skip').slice(0, 25)) {
|
|
47
|
+
console.log(` row ${row.row} ${row.action} ${DIM}${row.message ?? ''}${RST}`);
|
|
48
|
+
}
|
|
49
|
+
console.log('');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
async function importMetaHandler() {
|
|
53
|
+
printJson(data(await messagingGet('/CrmImport/meta')));
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
async function importPreviewHandler(argv) {
|
|
57
|
+
const r = data(await messagingPost('/CrmImport/preview', await importBody(argv)));
|
|
58
|
+
if (argv.json) return printJson(r);
|
|
59
|
+
printImport(r, 'Preview (nothing was written)');
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
async function importCommitHandler(argv) {
|
|
63
|
+
if (!argv.yes) throw new Error('[CRM] Importing writes records. Run crm-import preview first, then add --yes to commit.');
|
|
64
|
+
const r = data(await messagingPost('/CrmImport/commit', await importBody(argv)));
|
|
65
|
+
if (argv.json) return printJson(r);
|
|
66
|
+
printImport(r, 'Imported');
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
async function exportHandler(argv) {
|
|
70
|
+
const csv = await messagingRequest('GET', `/CrmImport/export${q({ entity: argv.entity, skip: argv.skip, take: argv.take })}`, undefined, undefined, {}, { text: true });
|
|
71
|
+
if (argv.out) {
|
|
72
|
+
const fs = await import('node:fs');
|
|
73
|
+
fs.writeFileSync(argv.out, csv, 'utf8');
|
|
74
|
+
console.log(`\n Exported to ${argv.out}.\n`);
|
|
75
|
+
} else {
|
|
76
|
+
process.stdout.write(csv);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const importOptions = (y) => json(y
|
|
81
|
+
.option('entity', { choices: ENTITIES, demandOption: true })
|
|
82
|
+
.option('file', { type: 'string', demandOption: true, describe: 'Path to the CSV file' })
|
|
83
|
+
.option('mapping', { type: 'string', describe: 'JSON object of column header to field (built-in name or cf:<fieldId>); unlisted columns are matched by name' })
|
|
84
|
+
.option('duplicates', { choices: ['skip', 'update'], default: 'skip', describe: 'Existing contact (email) or company (name): skip it, or update only the filled-in cells' })
|
|
85
|
+
.option('pipeline-id', { type: 'number', alias: 'pipelineId', describe: 'Deals: pipeline for rows without a pipeline column' }));
|
|
86
|
+
|
|
87
|
+
export const crmImportCommand = {
|
|
88
|
+
command: 'crm-import <subcommand>',
|
|
89
|
+
describe: 'CRM CSV import and export for contacts, companies and deals',
|
|
90
|
+
builder: (y) => y
|
|
91
|
+
.command({ command: 'meta', describe: 'List the fields, mapping rules and file limits', handler: runCommand(importMetaHandler) })
|
|
92
|
+
.command({ command: 'preview', describe: 'Dry run: show what each row would do without writing anything', builder: importOptions, handler: runCommand(importPreviewHandler) })
|
|
93
|
+
.command({
|
|
94
|
+
command: 'commit',
|
|
95
|
+
describe: 'Import the file (Manager or Administrator)',
|
|
96
|
+
builder: (yy) => importOptions(yy).option('yes', { type: 'boolean', default: false, describe: 'Confirm the import' }),
|
|
97
|
+
handler: runCommand(importCommitHandler),
|
|
98
|
+
})
|
|
99
|
+
.command({
|
|
100
|
+
command: 'export',
|
|
101
|
+
describe: 'Export records as CSV; the file imports back with no mapping',
|
|
102
|
+
builder: (yy) => yy
|
|
103
|
+
.option('entity', { choices: ENTITIES, demandOption: true })
|
|
104
|
+
.option('skip', { type: 'number' })
|
|
105
|
+
.option('take', { type: 'number' })
|
|
106
|
+
.option('out', { type: 'string', describe: 'Write to this file instead of the screen' }),
|
|
107
|
+
handler: runCommand(exportHandler),
|
|
108
|
+
})
|
|
109
|
+
.demandCommand(1),
|
|
110
|
+
handler: () => {},
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
// ---------------------------------------------------------------- tags on companies and deals
|
|
114
|
+
|
|
115
|
+
async function tagListHandler(argv) {
|
|
116
|
+
const r = data(await messagingGet(`/CrmTags/${argv.entity}/${argv.id}`));
|
|
117
|
+
if (argv.json) return printJson(r);
|
|
118
|
+
const list = Array.isArray(r) ? r : r?.tags ?? [];
|
|
119
|
+
console.log(`\n${BOLD}Tags on ${argv.entity} #${argv.id}${RST} (${list.length})`);
|
|
120
|
+
for (const t of list) console.log(` #${t.id ?? t.tagId} ${t.name ?? ''}`);
|
|
121
|
+
console.log('');
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
async function tagAddHandler(argv) {
|
|
125
|
+
printJson(data(await messagingPost(`/CrmTags/${argv.entity}/${argv.id}/${argv.tagId}`, {})));
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
async function tagRemoveHandler(argv) {
|
|
129
|
+
await messagingDel(`/CrmTags/${argv.entity}/${argv.id}/${argv.tagId}`);
|
|
130
|
+
console.log(`\n Tag ${argv.tagId} removed from ${argv.entity} #${argv.id}.\n`);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
const tagEntity = (yy) => yy.positional('entity', { choices: TAG_ENTITIES });
|
|
134
|
+
|
|
135
|
+
export const crmTagCommand = {
|
|
136
|
+
command: 'crm-tag <subcommand>',
|
|
137
|
+
describe: 'Tags on CRM companies and deals (the same site tag list contacts use)',
|
|
138
|
+
builder: (y) => y
|
|
139
|
+
.command({ command: 'list <entity> <id>', describe: 'List the tags on a company or deal', builder: (yy) => json(tagEntity(yy)), handler: runCommand(tagListHandler) })
|
|
140
|
+
.command({ command: 'add <entity> <id> <tagId>', describe: 'Tag a company or deal (adding twice keeps one tag)', builder: tagEntity, handler: runCommand(tagAddHandler) })
|
|
141
|
+
.command({ command: 'remove <entity> <id> <tagId>', describe: 'Remove a tag from a company or deal', builder: tagEntity, handler: runCommand(tagRemoveHandler) })
|
|
142
|
+
.demandCommand(1),
|
|
143
|
+
handler: () => {},
|
|
144
|
+
};
|
|
145
|
+
|
|
146
|
+
// ---------------------------------------------------------------- duplicate deals
|
|
147
|
+
|
|
148
|
+
async function dedupeFindHandler(argv) {
|
|
149
|
+
const r = data(await messagingGet(`/CrmDealDuplicates${q({ pipelineId: argv.pipelineId, amountWindowPercent: argv.amountWindowPercent, maxGroups: argv.maxGroups })}`));
|
|
150
|
+
if (argv.json) return printJson(r);
|
|
151
|
+
const groups = r?.groups ?? [];
|
|
152
|
+
console.log(`\n${BOLD}Possible duplicate deals${RST} (${groups.length} group(s))`);
|
|
153
|
+
for (const g of groups) console.log(` ${(g.deals ?? g.items ?? []).map((d) => `#${d.id}${d.title ? ` ${d.title}` : ''}`).join(' | ')}`);
|
|
154
|
+
console.log('');
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
async function dedupeMergeHandler(argv) {
|
|
158
|
+
const duplicateIds = csvIds(argv.duplicateIds);
|
|
159
|
+
if (duplicateIds.length === 0) throw new Error('[CRM] --duplicate-ids must list at least one deal id.');
|
|
160
|
+
if (!argv.dryRun && !argv.yes) throw new Error('[CRM] Merging archives the duplicate deals. Run with --dry-run first, then add --yes to merge.');
|
|
161
|
+
const r = data(await messagingPost('/CrmDealDuplicates/merge', { survivorId: argv.survivorId, duplicateIds, dryRun: !!argv.dryRun }));
|
|
162
|
+
if (argv.json) return printJson(r);
|
|
163
|
+
console.log(`\n${BOLD}${argv.dryRun ? 'Dry run' : 'Merged'}${RST} into deal #${argv.survivorId}`);
|
|
164
|
+
for (const row of r?.results ?? []) console.log(` #${row.id} ${row.ok ? 'ok' : `failed: ${row.error}`}`);
|
|
165
|
+
console.log('');
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
export const crmDedupeCommand = {
|
|
169
|
+
command: 'crm-dedupe <subcommand>',
|
|
170
|
+
describe: 'Find and merge duplicate CRM deals (Manager or Administrator to merge)',
|
|
171
|
+
builder: (y) => y
|
|
172
|
+
.command({
|
|
173
|
+
command: 'find',
|
|
174
|
+
describe: 'List groups of open deals that look like duplicates',
|
|
175
|
+
builder: (yy) => json(yy
|
|
176
|
+
.option('pipeline-id', { type: 'number', alias: 'pipelineId' })
|
|
177
|
+
.option('amount-window-percent', { type: 'number', alias: 'amountWindowPercent', describe: 'How close the amounts must be' })
|
|
178
|
+
.option('max-groups', { type: 'number', alias: 'maxGroups' })),
|
|
179
|
+
handler: runCommand(dedupeFindHandler),
|
|
180
|
+
})
|
|
181
|
+
.command({
|
|
182
|
+
command: 'merge',
|
|
183
|
+
describe: 'Fold duplicate deals into a survivor; each duplicate is archived and can be restored with crm-bulk restore',
|
|
184
|
+
builder: (yy) => json(yy
|
|
185
|
+
.option('survivor-id', { type: 'number', alias: 'survivorId', demandOption: true })
|
|
186
|
+
.option('duplicate-ids', { type: 'string', alias: 'duplicateIds', demandOption: true, describe: 'Comma-separated deal ids' })
|
|
187
|
+
.option('dry-run', { type: 'boolean', alias: 'dryRun', default: false })
|
|
188
|
+
.option('yes', { type: 'boolean', default: false, describe: 'Confirm a real merge' })),
|
|
189
|
+
handler: runCommand(dedupeMergeHandler),
|
|
190
|
+
})
|
|
191
|
+
.demandCommand(1),
|
|
192
|
+
handler: () => {},
|
|
193
|
+
};
|
|
194
|
+
|
|
195
|
+
// ---------------------------------------------------------------- audit trail
|
|
196
|
+
|
|
197
|
+
async function auditListHandler(argv) {
|
|
198
|
+
const r = data(await messagingGet(`/CrmAudit${q({ entity: argv.entity, id: argv.id, page: argv.page, pageSize: argv.pageSize })}`));
|
|
199
|
+
if (argv.json) return printJson(r);
|
|
200
|
+
const rows = r?.items ?? r?.entries ?? [];
|
|
201
|
+
console.log(`\n${BOLD}Change history${RST} for ${argv.entity} #${argv.id} (${r?.total ?? rows.length} change(s), newest first)`);
|
|
202
|
+
for (const e of rows) console.log(` ${e.at ?? e.changedAt ?? ''} ${e.field}: ${e.before ?? ''} -> ${e.after ?? ''} ${DIM}${e.actor ?? ''}${e.source ? `, ${e.source}` : ''}${RST}`);
|
|
203
|
+
console.log('');
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export const crmAuditCommand = {
|
|
207
|
+
command: 'crm-audit <subcommand>',
|
|
208
|
+
describe: 'Field-change history of a CRM record',
|
|
209
|
+
builder: (y) => y
|
|
210
|
+
.command({
|
|
211
|
+
command: 'list',
|
|
212
|
+
describe: 'Show who changed which field, from what to what',
|
|
213
|
+
builder: (yy) => json(yy
|
|
214
|
+
.option('entity', { choices: ENTITIES, demandOption: true })
|
|
215
|
+
.option('id', { type: 'number', demandOption: true })
|
|
216
|
+
.option('page', { type: 'number', default: 1 })
|
|
217
|
+
.option('page-size', { type: 'number', alias: 'pageSize' })),
|
|
218
|
+
handler: runCommand(auditListHandler),
|
|
219
|
+
})
|
|
220
|
+
.demandCommand(1),
|
|
221
|
+
handler: () => {},
|
|
222
|
+
};
|
package/package.json
CHANGED