@velaro/cli 1.4.173 → 1.4.175

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.
@@ -5,6 +5,7 @@ import { runCommand } from '../run.js';
5
5
  // CLI for CRM Studio (docs/architecture/crm-studio-program.md):
6
6
  // field-* CrmCustomFieldsController /CrmCustomFields
7
7
  // layout-* CrmFormLayoutsController /CrmFormLayouts
8
+ // formula-test POST /CrmCustomFields/formula/test (dry run of a calculated field or rollup; writes nothing)
8
9
  // The site always comes from the signed-in credential; no command takes a site id.
9
10
  // MCP parity: mcp/parity/crm-studio.customer.js (crm_* tools).
10
11
 
@@ -26,6 +27,29 @@ const q = (o) => {
26
27
  return p.length ? `?${p.join('&')}` : '';
27
28
  };
28
29
 
30
+ // Calculated fields (CRM Studio): a field whose FormulaJson is { kind: 'formula'|'rollup', expr, resultType, when|where }.
31
+ // Expressions: + - * / %, comparisons, && || !, IF ROUND MIN MAX ABS CONCAT COALESCE TODAY DAYS_BETWEEN; refs are built-in field
32
+ // names or cf:<id>. Rollups: SUM|COUNT|MIN|MAX|AVG of lineItems (deal), deals (company, contact) or tickets (contact).
33
+ const RESULT_TYPES = ['number', 'text', 'date', 'boolean'];
34
+ const RESULT_FOR_FIELD = { Number: 'number', Currency: 'number', Percent: 'number', Text: 'text', LongText: 'text', Date: 'date', Checkbox: 'boolean' };
35
+ const parseJsonOpt = (v, name) => {
36
+ try { return JSON.parse(v); } catch { throw new Error(`[CRM] --${name} must be valid JSON.`); }
37
+ };
38
+
39
+ // --formula takes the whole spec as JSON ("" clears it); --expr builds one from the pieces.
40
+ function formulaArg(argv) {
41
+ if (argv.formula !== undefined) return argv.formula;
42
+ if (argv.expr === undefined) return undefined;
43
+ const kind = argv.kind ?? 'formula';
44
+ const spec = { kind, expr: argv.expr };
45
+ const resultType = argv.resultType ?? (kind === 'rollup' ? 'number' : RESULT_FOR_FIELD[argv.type]);
46
+ if (!resultType) throw new Error('[CRM] --result-type is required (number, text, date or boolean) when it cannot be taken from --type.');
47
+ spec.resultType = resultType;
48
+ if (argv.when !== undefined) spec.when = parseJsonOpt(argv.when, 'when');
49
+ if (argv.where !== undefined) spec.where = parseJsonOpt(argv.where, 'where');
50
+ return JSON.stringify(spec);
51
+ }
52
+
29
53
  const json = (y) => y.option('json', { type: 'boolean', default: false, describe: 'Print raw JSON' });
30
54
  const entity = (y) => y.option('entity', { choices: ENTITIES, demandOption: true, describe: 'Record type' });
31
55
 
@@ -58,11 +82,27 @@ async function fieldDefineHandler(argv) {
58
82
  set('readRolesJson', listArg(argv.readRoles));
59
83
  set('writeRolesJson', listArg(argv.writeRoles));
60
84
  set('visibleWhenJson', argv.visibleWhen);
85
+ set('formulaJson', formulaArg(argv));
61
86
  const r = data(argv.id ? await messagingPut(`/CrmCustomFields/${argv.id}`, body) : await messagingPost('/CrmCustomFields', body));
62
87
  if (argv.json) return printJson(r);
63
88
  console.log(`\n Field saved: ${argv.label}${r?.id ? ` (#${r.id})` : ''}.\n`);
64
89
  }
65
90
 
91
+ async function formulaTestHandler(argv) {
92
+ const body = { entity: argv.entity };
93
+ if (argv.formula !== undefined) body.formulaJson = argv.formula;
94
+ else {
95
+ body.expr = argv.expr;
96
+ body.resultType = argv.resultType ?? 'number';
97
+ }
98
+ if (argv.sample !== undefined) body.sampleValues = parseJsonOpt(argv.sample, 'sample');
99
+ if (argv.recordId !== undefined) body.recordId = argv.recordId;
100
+ const r = data(await messagingPost('/CrmCustomFields/formula/test', body));
101
+ if (argv.json) return printJson(r);
102
+ if (r?.error) console.log(`\n ${BOLD}Could not calculate:${RST} ${r.error}\n`);
103
+ else console.log(`\n ${BOLD}Result${RST} (${r?.resultType}): ${r?.value === null || r?.value === undefined ? 'no value' : r.value}\n`);
104
+ }
105
+
66
106
  async function fieldArchiveHandler(argv) {
67
107
  await messagingDel(`/CrmCustomFields/${argv.id}`);
68
108
  console.log(`\n Field ${argv.id} archived. Saved values are kept.\n`);
@@ -143,9 +183,27 @@ export const crmCommand = {
143
183
  .option('validation', { type: 'string', describe: 'JSON, for example {"min":0,"max":100}' })
144
184
  .option('read-roles', { type: 'string', alias: 'readRoles', describe: 'Comma-separated role names; empty means everyone' })
145
185
  .option('write-roles', { type: 'string', alias: 'writeRoles', describe: 'Comma-separated role names; empty means everyone' })
146
- .option('visible-when', { type: 'string', alias: 'visibleWhen', describe: 'JSON rule' })),
186
+ .option('visible-when', { type: 'string', alias: 'visibleWhen', describe: 'JSON rule' })
187
+ .option('formula', { type: 'string', describe: 'Calculated field spec as JSON, for example {"kind":"formula","expr":"amount * 2","resultType":"number"}; empty clears it' })
188
+ .option('expr', { type: 'string', describe: 'Calculated field expression, for example "ROUND(amount * probability / 100, 2)" or "SUM(lineItems.total)" (builds --formula)' })
189
+ .option('kind', { choices: ['formula', 'rollup'], describe: 'With --expr: a formula (default) or a rollup over related records' })
190
+ .option('result-type', { choices: RESULT_TYPES, alias: 'resultType', describe: 'With --expr: defaults from --type (Number, Currency, Percent = number); rollups are numbers' })
191
+ .option('when', { type: 'string', describe: 'With --expr (formula): JSON rule; the field has a value only when it is true' })
192
+ .option('where', { type: 'string', describe: 'With --expr (rollup): JSON rule over the related rows; only matching rows are counted' })),
147
193
  handler: runCommand(fieldDefineHandler),
148
194
  })
195
+ .command({
196
+ command: 'formula-test',
197
+ describe: 'Dry-run a calculated field expression or rollup against sample values or a real record (Administrator; writes nothing)',
198
+ builder: (yy) => json(entity(yy)
199
+ .option('expr', { type: 'string', describe: 'Expression, for example "amount * 2"' })
200
+ .option('formula', { type: 'string', describe: 'Whole spec as JSON instead of --expr (use for rollups)' })
201
+ .option('result-type', { choices: RESULT_TYPES, alias: 'resultType', describe: 'Defaults to number' })
202
+ .option('sample', { type: 'string', describe: 'JSON object of sample values, for example {"amount":100,"cf:12":"Gold"}' })
203
+ .option('record-id', { type: 'number', alias: 'recordId', describe: "Use this record's real values underneath the samples (required to test a rollup)" })
204
+ .check((a) => (a.expr || a.formula !== undefined) ? true : '[CRM] Pass --expr or --formula.')),
205
+ handler: runCommand(formulaTestHandler),
206
+ })
149
207
  .command({ command: 'field-archive <id>', describe: 'Archive a CRM custom field (Administrator)', handler: runCommand(fieldArchiveHandler) })
150
208
  .command({
151
209
  command: 'layout-list',
@@ -824,6 +824,87 @@ const customRunCommand = {
824
824
  handler: runCommand(customRunHandler),
825
825
  };
826
826
 
827
+ // ── report range policy: long ranges are emailed as a link (ReportRangeController) ─────────────
828
+ // Backend: server/Velaro.Admin/Controllers/ReportRangeController.cs (docs/architecture/long-range-emailed-links.md)
829
+ // GET ReportRange/range-policy?start&end -> ReportRangeController.GetRangePolicy: what a range will do, before running it
830
+ // POST ReportRange/export -> ReportRangeController.StartRangeExport: 202 { exportId, deliverTo } over the limit, 200 inline otherwise
831
+ // Dates are yyyy-MM-dd inclusive Pacific days (or ISO instants, end exclusive). The server owns every limit; nothing is computed here.
832
+
833
+ function printWindow(r) {
834
+ fmtRow('Mode', r.mode === 'EmailLink' ? 'Emailed as a link' : 'On screen / inline');
835
+ fmtRow('Window', `${r.effectiveStartDay} to ${r.effectiveLastDay} (${r.timeZone})`);
836
+ fmtRow('Days', `${r.effectiveDays} (asked for ${r.requestedDays})`);
837
+ fmtRow('Limit', `${r.inlineLimitDays} days${r.thresholdLifted ? ' (raised by your package)' : ''}`);
838
+ if (r.retentionDays) fmtRow('Data kept', `${r.retentionDays} days`);
839
+ fmtRow('Shortened', r.clampedToRetention ? 'yes, to the data your account keeps' : (r.clampedToMaximum ? 'yes, to the maximum for one report' : 'no'));
840
+ if (r.notice) fmtRow('Note', r.notice);
841
+ if (r.defaultRecipient) fmtRow('Default email', r.defaultRecipient);
842
+ }
843
+
844
+ // GET ReportRange/range-policy -> ReportRangeController.GetRangePolicy
845
+ async function rangePolicyHandler(argv) {
846
+ const q = new URLSearchParams();
847
+ if (argv.start) q.set('start', argv.start);
848
+ if (argv.end) q.set('end', argv.end);
849
+ if (argv.inlineMaxDays) q.set('inlineMaxDays', String(argv.inlineMaxDays));
850
+ const r = await request('GET', `ReportRange/range-policy${q.toString() ? '?' + q : ''}`);
851
+ if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
852
+ section('Report range');
853
+ printWindow(r);
854
+ console.log('');
855
+ }
856
+
857
+ // POST ReportRange/export -> ReportRangeController.StartRangeExport
858
+ async function longRangeHandler(argv) {
859
+ const options = {};
860
+ for (const kv of [].concat(argv.option || [])) {
861
+ const i = String(kv).indexOf('=');
862
+ if (i < 1) throw new Error(`--option must look like name=value (got "${kv}")`);
863
+ options[String(kv).slice(0, i)] = String(kv).slice(i + 1);
864
+ }
865
+ const r = await request('POST', 'ReportRange/export', {
866
+ reportType: argv.type,
867
+ startDate: argv.start,
868
+ endDate: argv.end,
869
+ format: argv.format,
870
+ deliverTo: argv.to,
871
+ options: Object.keys(options).length ? options : undefined,
872
+ });
873
+ if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
874
+ if (r.mode === 'Inline') {
875
+ console.log(`\n${r.message}\n`);
876
+ return;
877
+ }
878
+ console.log(`\nExport queued (id ${r.exportId}). ${r.message}`);
879
+ if (r.notice?.message) console.log(`Note: ${r.notice.message}`);
880
+ console.log(`Check progress: velaro report export status ${r.exportId}\n`);
881
+ }
882
+
883
+ const rangePolicyCommand = {
884
+ command: 'range-policy',
885
+ describe: 'Show what a date range will do before you run it: shortened to the data your account keeps, and on screen or emailed as a link',
886
+ builder: (y) => y
887
+ .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD, Pacific). Default: 30 days ago' })
888
+ .option('end', { type: 'string', describe: 'End date (YYYY-MM-DD, Pacific, inclusive). Default: today' })
889
+ .option('inline-max-days', { type: 'number', describe: 'Lower the limit to what the report can show on screen' })
890
+ .option('json', { type: 'boolean', describe: 'Print the raw response' }),
891
+ handler: runCommand(rangePolicyHandler),
892
+ };
893
+
894
+ const longRangeCommand = {
895
+ command: 'long-range',
896
+ describe: 'Email a long-range report as a download link (ranges over the limit are built in the background; shorter ranges are not queued)',
897
+ builder: (y) => y
898
+ .option('type', { type: 'string', demandOption: true, describe: 'Report type, e.g. conversations' })
899
+ .option('start', { type: 'string', demandOption: true, describe: 'Start date (YYYY-MM-DD, Pacific)' })
900
+ .option('end', { type: 'string', demandOption: true, describe: 'End date (YYYY-MM-DD, Pacific, inclusive)' })
901
+ .option('format', { type: 'string', choices: ['xlsx', 'csv'], describe: 'Output format (default xlsx)' })
902
+ .option('to', { type: 'string', describe: 'Email address for the link (default: your own email)' })
903
+ .option('option', { type: 'string', array: true, describe: 'Report option as name=value, e.g. teamId=3 (repeatable)' })
904
+ .option('json', { type: 'boolean', describe: 'Print the raw response' }),
905
+ handler: runCommand(longRangeHandler),
906
+ };
907
+
827
908
  // ── top-level report command ──────────────────────────────────────────────────
828
909
 
829
910
  export const reportCommand = {
@@ -838,6 +919,8 @@ export const reportCommand = {
838
919
  .command(visitorTrafficCommand)
839
920
  .command(schedulesCommand)
840
921
  .command(exportCommand)
922
+ .command(rangePolicyCommand)
923
+ .command(longRangeCommand)
841
924
  .command(countryCommand)
842
925
  .command(customCatalogCommand)
843
926
  .command(customRunCommand)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/cli",
3
- "version": "1.4.173",
3
+ "version": "1.4.175",
4
4
  "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
5
5
  "type": "module",
6
6
  "bin": {