@velaro/cli 1.4.165 → 1.4.167

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/README.md CHANGED
@@ -136,6 +136,19 @@ velaro kb article screenshot 1234 \
136
136
  --annotate 120,80,1
137
137
  ```
138
138
 
139
+ ### `velaro kb override <subcommand>`
140
+ Authoritative facts the bot must follow, optionally shown as a notice on your public Knowledge Base pages (the MCP tool `manage_knowledge_override` takes the same fields: `showOnKb`, `kbScope`, `kbPageKey`, `kbMessage`, `kbSeverity`, `kbDismissible`, `startsAt`, `expiresAt`).
141
+
142
+ ```bash
143
+ velaro kb override list
144
+ velaro kb override add --title "Holiday hours" --content "Closed Dec 25" \
145
+ --show-on-kb --kb-page all --kb-message "We are closed Dec 25." --kb-severity notice --expires-at 2026-12-26
146
+ velaro kb override update 12 --kb-page home --no-dismiss # only the flags you pass change
147
+ velaro kb override delete 12
148
+ ```
149
+
150
+ `--kb-page` is `all`, `home`, `search`, or a numeric article id. `--kb-severity` is `info`, `notice` or `warning`. `--kb-message` cannot contain `<` or `>`. Showing notices on KB pages requires Velaro AI Chatbot.
151
+
139
152
  > Titles are auto-normalized to Title Case with no dashes, even if you pass a slug-style name — use `--no-title-normalize` to skip that.
140
153
 
141
154
  ### `velaro status`
@@ -75,7 +75,7 @@ export const checkCommand = {
75
75
  try {
76
76
  const [qna, overrides] = await Promise.all([
77
77
  messagingGet('/BotQnA').catch(() => []),
78
- messagingGet('/Ticket/knowledge-overrides').catch(() => []),
78
+ get('/KnowledgeOverride').catch(() => []),
79
79
  ]);
80
80
  ok(`${qna?.length ?? 0} Q&A pair(s) · ${overrides?.length ?? 0} override(s)`);
81
81
  } catch { warn('Could not load knowledge base'); }
@@ -39,6 +39,30 @@ export const dynamicsCommand = {
39
39
  console.log(JSON.stringify(await request('PUT', `${base(argv.config)}/${argv.team}`, body), null, 2));
40
40
  }),
41
41
  })
42
- .demandCommand(1, 'Specify a subcommand: team-overrides'),
42
+ .command({
43
+ command: 'copy-mappings',
44
+ describe: 'Copy field mappings + activity type from one Dynamics connection to another on the same site',
45
+ builder: y => y
46
+ .option('config', { type: 'number', demandOption: true, describe: 'Target Dynamics config id' })
47
+ .option('from', { type: 'number', demandOption: true, describe: 'Source Dynamics config id' })
48
+ .option('team-overrides', { type: 'boolean', default: false, describe: 'Also replace the target\'s per-group overrides with the source\'s' }),
49
+ handler: runCommand(async argv => {
50
+ const res = await request('POST', `/Dynamics/Configs/${argv.config}/copy-mappings-from/${argv.from}`, { includeTeamOverrides: argv.teamOverrides === true });
51
+ console.log(JSON.stringify(res, null, 2));
52
+ }),
53
+ })
54
+ .command({
55
+ command: 'restore-mappings',
56
+ describe: 'Put the connection field mappings + activity type back to given values (undo of copy-mappings; uses PUT Configs/{id}, other settings untouched)',
57
+ builder: y => y
58
+ .option('config', { type: 'number', demandOption: true, describe: 'Dynamics config id to restore' })
59
+ .option('mappings', { type: 'string', demandOption: true, describe: 'customFieldMappingsJson to put back (the `previous` value; empty string if it was empty)' })
60
+ .option('activity', { type: 'string', demandOption: true, describe: 'activityLogicalName to put back (empty string if it was empty)' }),
61
+ handler: runCommand(async argv => {
62
+ const res = await request('PUT', `/Dynamics/Configs/${argv.config}`, { customFieldMappingsJson: argv.mappings, activityLogicalName: argv.activity });
63
+ console.log(JSON.stringify(res, null, 2));
64
+ }),
65
+ })
66
+ .demandCommand(1, 'Specify a subcommand: team-overrides | copy-mappings | restore-mappings'),
43
67
  handler: () => {},
44
68
  };
@@ -41,6 +41,7 @@ const REPORTS = {
41
41
  'workload-balance': 'Chats per available hour by agent with over- and under-loaded flags',
42
42
  'benchmarks': 'Your theme share against the industry vertical median and spread, vertical level only',
43
43
  'commerce-sales-loss': 'Sales-loss themes by revenue affected, refund rate, repeat purchase after contact and abandoned carts, by platform',
44
+ 'speed-to-answer': 'Phone speed to answer by queue, team, agent and day (avg/median/p90, % within --threshold seconds, abandoned, voicemail)',
44
45
  'weekly-brief-send-test': 'Email this week\'s brief to the signed-in user',
45
46
  'year-in-review': 'Build the 12-month Year in review document: --from/--to (default last 12 whole Pacific months) starts a build and prints its id; --id <id> checks status and the download link',
46
47
  };
@@ -77,6 +78,7 @@ export const enterpriseReportsCommand = {
77
78
  .option('deflection-pct', { type: 'number', describe: 'bonus: assumed deflection percent (0-100)' })
78
79
  .option('cost-per-chat', { type: 'number', describe: 'bonus: assumed cost per chat (0-1000)' })
79
80
  .option('wait-minutes', { type: 'number', describe: 'bonus: wait minutes that counts as abandoned (1-1440)' })
81
+ .option('threshold-seconds', { type: 'number', describe: 'speed-to-answer: seconds that count as answered on target (5-600, default 20)' })
80
82
  .option('id', { type: 'string', describe: 'promise-dismiss: the promise id; year-in-review: the build id to check' }),
81
83
  handler: runCommand(async (argv) => {
82
84
  if (argv.report === 'weekly-brief-send-test') {
@@ -111,7 +113,7 @@ export const enterpriseReportsCommand = {
111
113
  seg = `bonus/${encodeURIComponent(String(argv.name).replace(/-/g, '_'))}`;
112
114
  }
113
115
  const qs = new URLSearchParams();
114
- const map = { minutesPerReview: 'minutesPerReview', hourlyCost: 'hourlyCost', deflectionPct: 'deflectionPct', costPerChat: 'costPerChat', waitMinutes: 'waitMinutes', narrative: 'narrative', from: 'from', to: 'to', groupBy: 'groupBy', deploymentId: 'deploymentId', teamId: 'teamId', threshold: 'threshold', perAgent: 'perAgent', limit: 'limit', days: 'days', windowDays: 'windowDays', weeks: 'weeks', handleMinutes: 'handleMinutes', maxConcurrent: 'maxConcurrent', timeZone: 'timeZone', lowScore: 'lowScore', includeDemo: 'includeDemo' };
116
+ const map = { minutesPerReview: 'minutesPerReview', hourlyCost: 'hourlyCost', deflectionPct: 'deflectionPct', costPerChat: 'costPerChat', waitMinutes: 'waitMinutes', narrative: 'narrative', from: 'from', to: 'to', groupBy: 'groupBy', deploymentId: 'deploymentId', teamId: 'teamId', threshold: 'threshold', perAgent: 'perAgent', limit: 'limit', days: 'days', windowDays: 'windowDays', weeks: 'weeks', handleMinutes: 'handleMinutes', maxConcurrent: 'maxConcurrent', timeZone: 'timeZone', lowScore: 'lowScore', includeDemo: 'includeDemo', thresholdSeconds: 'thresholdSeconds' };
115
117
  for (const [arg, key] of Object.entries(map)) if (argv[arg] != null && argv[arg] !== '') qs.set(key, String(argv[arg]));
116
118
  const q = qs.toString();
117
119
  console.log(JSON.stringify(await messagingGet(`/api/enterprise-reports/${seg}${q ? `?${q}` : ''}`), null, 2));
@@ -1,9 +1,10 @@
1
1
  import { readFileSync } from 'fs';
2
2
  import { basename } from 'path';
3
- import { get, post, del, messagingGet, messagingPost, messagingDel } from '../api.js';
3
+ import { get, post, put, del, messagingGet, messagingPost, messagingDel } from '../api.js';
4
4
  import { requireFeature } from '../subscription.js';
5
5
  import { runCommand } from '../run.js';
6
6
  import { articleCommand } from './article.js';
7
+ import { addBody, updateBody, checkResult, friendlyError } from '../kb-override.js';
7
8
  import { loadStaff } from '../staff-optional.js';
8
9
 
9
10
  const staffKb = await loadStaff('commands/kb-staff.js');
@@ -205,35 +206,48 @@ const overrideCommand = {
205
206
  describe: 'List knowledge overrides',
206
207
  handler: runCommand(async () => {
207
208
  await requireFeature('enableKnowledgeBase', 'Knowledge Base');
208
- const items = await messagingGet('/Ticket/knowledge-overrides');
209
+ const items = await get('/KnowledgeOverride');
209
210
  if (!items?.length) { console.log('No overrides found.'); return; }
210
211
 
211
212
  console.log(`\nFound ${items.length} override(s):\n`);
212
213
  for (const item of items) {
213
214
  const status = item.isActive ? 'active ' : 'inactive';
214
215
  const expiry = item.expiresAt ? ` expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
215
- console.log(` [${item.id}] ${status} ${truncate(item.topic ?? item.title ?? item.overrideFact ?? item.content, 60)}${expiry}`);
216
+ const kb = item.showOnKb ? ` [KB ${item.kbScope === 'all' ? 'all pages' : item.kbPageKey}]` : '';
217
+ console.log(` [${item.id}] ${status} ${truncate(item.topic ?? item.title ?? item.overrideFact ?? item.content, 60)}${kb}${expiry}`);
216
218
  }
217
219
  }),
218
220
  })
219
221
  .command({
220
222
  command: 'add',
221
- describe: 'Add a knowledge override',
222
- builder: (y) =>
223
- y
224
- .option('title', { type: 'string', demandOption: true, describe: 'Override title' })
225
- .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
226
- .option('search-terms', { type: 'string', describe: 'Comma-separated keywords; the override only fires when the visitor message contains one' })
227
- .option('expires', { type: 'string', describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
223
+ describe: 'Add a knowledge override (optionally shown as a notice on KB pages)',
224
+ builder: (y) => noticeOptions(y)
225
+ .option('title', { type: 'string', demandOption: true, describe: 'Override title' })
226
+ .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
227
+ .option('expires', { type: 'string', describe: 'Expiry date (alias of --expires-at)' }),
228
+ handler: runCommand(async (argv) => {
229
+ await requireFeature('enableKnowledgeBase', 'Knowledge Base');
230
+ const body = addBody(argv);
231
+ let result;
232
+ try { result = checkResult(await post('/KnowledgeOverride', body)); } catch (e) { throw friendlyError(e); }
233
+ console.log(`Override added: [${result?.id ?? ''}] "${argv.title}"`);
234
+ }),
235
+ })
236
+ .command({
237
+ command: 'update <id>',
238
+ describe: 'Update a knowledge override (only the flags you pass change)',
239
+ builder: (y) => noticeOptions(y)
240
+ .positional('id', { type: 'number', describe: 'Override ID' })
241
+ .option('title', { type: 'string', describe: 'Override title' })
242
+ .option('content', { type: 'string', describe: 'Authoritative content' }),
228
243
  handler: runCommand(async (argv) => {
229
244
  await requireFeature('enableKnowledgeBase', 'Knowledge Base');
230
- // The messaging API model is { topic, overrideFact, searchTerms, priority, expiresAt }; sending
231
- // title/content returned 400 "Topic and fact are required." (fixed 2026-10-27).
232
- const payload = { topic: argv.title, overrideFact: argv.content };
233
- if (argv['search-terms']) payload.searchTerms = argv['search-terms'];
234
- if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
235
- const result = await messagingPost('/Ticket/knowledge-overrides', payload);
236
- console.log(`Override added: [${result.id}] "${argv.title}"`);
245
+ const items = await get('/KnowledgeOverride');
246
+ const existing = (items ?? []).find((o) => o.id === argv.id);
247
+ if (!existing) throw new Error(`Override ${argv.id} not found.`);
248
+ const body = updateBody(existing, argv);
249
+ try { checkResult(await put(`/KnowledgeOverride/${argv.id}`, body)); } catch (e) { throw friendlyError(e); }
250
+ console.log(`Override ${argv.id} updated.`);
237
251
  }),
238
252
  })
239
253
  .command({
@@ -242,14 +256,27 @@ const overrideCommand = {
242
256
  builder: (y) => y.positional('id', { type: 'number', describe: 'Override ID' }),
243
257
  handler: runCommand(async (argv) => {
244
258
  await requireFeature('enableKnowledgeBase', 'Knowledge Base');
245
- await messagingDel(`/Ticket/knowledge-overrides/${argv.id}`);
259
+ checkResult(await del(`/KnowledgeOverride/${argv.id}`));
246
260
  console.log(`Override ${argv.id} deleted.`);
247
261
  }),
248
262
  })
249
- .demandCommand(1, 'Specify a subcommand: list, add, delete'),
263
+ .demandCommand(1, 'Specify a subcommand: list, add, update, delete'),
250
264
  handler: () => {},
251
265
  };
252
266
 
267
+ function noticeOptions(y) {
268
+ return y
269
+ .option('show-on-kb', { type: 'boolean', describe: 'Show this override as a notice on Knowledge Base pages' })
270
+ .option('kb-page', { type: 'string', describe: 'Where to show it: all | home | search | <article-id>' })
271
+ .option('kb-message', { type: 'string', describe: 'Notice text (max 500 chars, no < or >)' })
272
+ .option('kb-severity', { type: 'string', choices: ['info', 'notice', 'warning'], describe: 'Notice style' })
273
+ .option('dismiss', { type: 'boolean', describe: 'Visitors can dismiss (use --no-dismiss to disable)' })
274
+ .option('starts-at', { type: 'string', describe: 'Start date/time (ISO 8601)' })
275
+ .option('expires-at', { type: 'string', describe: 'Expiry date/time (ISO 8601, e.g. 2026-12-31)' })
276
+ .option('search-terms', { type: 'string', describe: 'Comma-separated bot trigger keywords' })
277
+ .option('priority', { type: 'number', describe: 'Injection priority (lower = higher)' });
278
+ }
279
+
253
280
  // ────────────────────────────────────────────────────────────────────────────
254
281
  // Custom content — push arbitrary text/files into the site's KB index
255
282
  // ────────────────────────────────────────────────────────────────────────────
@@ -11,6 +11,9 @@
11
11
  * velaro teams-phone agents list List agents and their Teams user object IDs
12
12
  * velaro teams-phone agents set <agentId> <teamsUserId> Map an agent to an Entra user Object ID
13
13
  * velaro teams-phone agents delete <agentId> Clear an agent's mapping
14
+ * velaro teams-phone queues list List Teams Phone queues (extra resource accounts per call queue)
15
+ * velaro teams-phone queues set --object-id <guid> --name <queue> [--team-id n] [--phone +1...] [--ring-seconds n]
16
+ * velaro teams-phone queues delete <id> Remove a queue
14
17
  *
15
18
  * Backend contract: server/Velaro.Messaging/Controllers/Voice/TeamsPhoneConfigController.cs
16
19
  * (velaro-messaging). Site is resolved server-side from the auth context — never
@@ -208,6 +211,45 @@ ${GRN}✓${RST} Agent ${argv.agentId} mapping cleared.
208
211
  `);
209
212
  }
210
213
 
214
+ // -- queues (extra Teams resource accounts, one per call queue) -------------------------
215
+
216
+ async function queuesListHandler() {
217
+ const r = await messagingGet('/TeamsPhone/Queues');
218
+ const queues = Array.isArray(r?.queues) ? r.queues : [];
219
+ if (queues.length === 0) {
220
+ console.log(`
221
+ ${DIM}No Teams Phone queues. Calls ring through the main Teams setup.${RST}
222
+ `);
223
+ return;
224
+ }
225
+ console.log(`
226
+ ${BOLD}Teams Phone queues${RST}`);
227
+ for (const q of queues) {
228
+ console.log(` ${String(q.id).padEnd(6)} ${String(q.queueName ?? '').padEnd(24)} ${String(q.assignedPhoneNumber ?? '-').padEnd(16)} team ${q.teamId ?? 'any'} ${DIM}${q.applicationInstanceObjectId}${RST}`);
229
+ }
230
+ console.log('');
231
+ }
232
+
233
+ async function queuesSetHandler(argv) {
234
+ const r = await messagingPost('/TeamsPhone/Queues', {
235
+ applicationInstanceObjectId: argv.objectId,
236
+ queueName: argv.name,
237
+ assignedPhoneNumber: argv.phone,
238
+ teamId: argv.teamId,
239
+ ringTimeoutSeconds: argv.ringSeconds,
240
+ });
241
+ console.log(`
242
+ ${GRN}✓${RST} Queue "${r?.queue?.queueName ?? argv.name}" saved (id ${r?.queue?.id}).
243
+ `);
244
+ }
245
+
246
+ async function queuesDeleteHandler(argv) {
247
+ await messagingDel(`/TeamsPhone/Queues/${encodeURIComponent(argv.id)}`);
248
+ console.log(`
249
+ ${GRN}✓${RST} Queue ${argv.id} removed.
250
+ `);
251
+ }
252
+
211
253
  // -- command export ------------------------------------------------------------------
212
254
 
213
255
  export const teamsPhoneCommand = {
@@ -305,6 +347,31 @@ export const teamsPhoneCommand = {
305
347
  .demandCommand(1, 'Specify list, set or delete.'),
306
348
  handler: () => {},
307
349
  })
350
+ .command({
351
+ command: 'queues <action>',
352
+ describe: 'Teams Phone queues: extra resource accounts (e.g. Service, Parts) that ring a Velaro team and are reported as their own queue (list | set | delete)',
353
+ builder: yy => yy
354
+ .command({ command: 'list', describe: 'List Teams Phone queues', builder: z => z, handler: queuesListHandler })
355
+ .command({
356
+ command: 'set',
357
+ describe: 'Add or update a queue by resource account object id',
358
+ builder: z => z
359
+ .option('object-id', { type: 'string', demandOption: true, describe: 'Queue resource account object id (GUID)' })
360
+ .option('name', { type: 'string', demandOption: true, describe: 'Queue name shown in reports and on the call pop' })
361
+ .option('team-id', { type: 'number', describe: 'Velaro team the queue rings (omit for any available agent)' })
362
+ .option('phone', { type: 'string', describe: 'Queue phone number (E.164)' })
363
+ .option('ring-seconds', { type: 'number', describe: 'Ring timeout seconds (5-120)' }),
364
+ handler: queuesSetHandler,
365
+ })
366
+ .command({
367
+ command: 'delete <id>',
368
+ describe: 'Remove a queue',
369
+ builder: z => z.positional('id', { type: 'number', describe: 'Queue id from queues list' }),
370
+ handler: queuesDeleteHandler,
371
+ })
372
+ .demandCommand(1, 'Specify list, set or delete.'),
373
+ handler: () => {},
374
+ })
308
375
  .demandCommand(1, 'Specify a teams-phone subcommand.')
309
376
  .strict(),
310
377
  handler: () => {},
@@ -5,7 +5,7 @@ import { enterpriseReportsCommand, ADMIN_HOSTED_REPORTS } from './commands/enter
5
5
  import { yearInReviewBody, lastTwelveWholeMonthsKeys } from './year-in-review-range.js';
6
6
 
7
7
  test('describe lists the five novel reports and the promise dismiss action', () => {
8
- for (const r of ['repeat-contact', 'demand-coverage', 'bot-containment', 'effort-index', 'promise-ledger', 'promise-dismiss', 'new-agent-ramp']) {
8
+ for (const r of ['repeat-contact', 'demand-coverage', 'bot-containment', 'effort-index', 'promise-ledger', 'promise-dismiss', 'new-agent-ramp', 'speed-to-answer']) {
9
9
  assert.ok(enterpriseReportsCommand.describe.includes(r), `${r} missing from describe`);
10
10
  }
11
11
  });
@@ -0,0 +1,73 @@
1
+ // Pure helpers for `velaro kb override add|update` (KB page notices, docs/design/kb-page-notices.md 3.7).
2
+ export const UPSELL = 'Flow announcements through to your Knowledge Base pages with Velaro AI Chatbot';
3
+ export const SEVERITIES = ['info', 'notice', 'warning'];
4
+
5
+ export function resolveKbPage(page) {
6
+ const p = String(page).trim().toLowerCase();
7
+ if (p === 'all') return { kbScope: 'all', kbPageKey: null };
8
+ if (p === 'home' || p === 'search') return { kbScope: 'page', kbPageKey: p };
9
+ if (/^\d+$/.test(p)) return { kbScope: 'page', kbPageKey: `article:${p}` };
10
+ throw new Error('--kb-page must be all, home, search, or a numeric article id');
11
+ }
12
+
13
+ function isoDate(label, v) {
14
+ const d = new Date(v);
15
+ if (Number.isNaN(d.getTime())) throw new Error(`${label} is not a valid date: ${v}`);
16
+ return d.toISOString();
17
+ }
18
+
19
+ // Returns only the fields whose flags were passed (camelCase, matches KnowledgeOverrideRequest).
20
+ export function noticeFields(argv) {
21
+ const b = {};
22
+ if (argv.showOnKb !== undefined) b.showOnKb = !!argv.showOnKb;
23
+ if (argv.kbPage !== undefined) Object.assign(b, resolveKbPage(argv.kbPage));
24
+ if (argv.kbMessage !== undefined) {
25
+ if (/[<>]/.test(argv.kbMessage)) throw new Error('--kb-message cannot contain < or >');
26
+ b.kbMessage = argv.kbMessage;
27
+ }
28
+ if (argv.kbSeverity !== undefined) {
29
+ if (!SEVERITIES.includes(argv.kbSeverity)) throw new Error(`--kb-severity must be one of ${SEVERITIES.join(', ')}`);
30
+ b.kbSeverity = argv.kbSeverity;
31
+ }
32
+ if (argv.dismiss === false) b.kbDismissible = false;
33
+ if (argv.startsAt !== undefined) b.startsAt = isoDate('--starts-at', argv.startsAt);
34
+ const exp = argv.expiresAt ?? argv.expires;
35
+ if (exp !== undefined) b.expiresAt = isoDate('--expires-at', exp);
36
+ return b;
37
+ }
38
+
39
+ export function addBody(argv) {
40
+ const body = { topic: argv.title, overrideFact: argv.content, isActive: true, ...noticeFields(argv) };
41
+ if (argv.searchTerms !== undefined) body.searchTerms = argv.searchTerms;
42
+ if (argv.priority !== undefined) body.priority = argv.priority;
43
+ return body;
44
+ }
45
+
46
+ // PUT requires topic + overrideFact: merge the existing row with only the flags present.
47
+ export function updateBody(existing, argv) {
48
+ const body = {
49
+ topic: existing.topic, overrideFact: existing.overrideFact, searchTerms: existing.searchTerms,
50
+ priority: existing.priority, isActive: existing.isActive,
51
+ showOnKb: existing.showOnKb, kbScope: existing.kbScope, kbPageKey: existing.kbPageKey,
52
+ kbMessage: existing.kbMessage, kbSeverity: existing.kbSeverity, kbDismissible: existing.kbDismissible,
53
+ startsAt: existing.startsAt, expiresAt: existing.expiresAt,
54
+ };
55
+ if (argv.title !== undefined) body.topic = argv.title;
56
+ if (argv.content !== undefined) body.overrideFact = argv.content;
57
+ if (argv.searchTerms !== undefined) body.searchTerms = argv.searchTerms;
58
+ if (argv.priority !== undefined) body.priority = argv.priority;
59
+ return { ...body, ...noticeFields(argv) };
60
+ }
61
+
62
+ // Throws a friendly error for {success:false} bodies and bot_plan_required.
63
+ export function checkResult(res) {
64
+ const text = res && typeof res === 'object' ? JSON.stringify(res) : String(res ?? '');
65
+ if (text.includes('bot_plan_required')) throw new Error(UPSELL);
66
+ if (res && typeof res === 'object' && res.success === false) throw new Error(res.message || 'Request failed');
67
+ return res;
68
+ }
69
+
70
+ // bot_plan_required can also arrive inside an HTTP error message (api.js embeds the response body).
71
+ export function friendlyError(err) {
72
+ return String(err?.message ?? '').includes('bot_plan_required') ? new Error(UPSELL) : err;
73
+ }
@@ -0,0 +1,40 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { resolveKbPage, noticeFields, addBody, updateBody, checkResult, friendlyError, UPSELL } from './kb-override.js';
4
+
5
+ test('resolveKbPage maps all/home/search/article id', () => {
6
+ assert.deepEqual(resolveKbPage('all'), { kbScope: 'all', kbPageKey: null });
7
+ assert.deepEqual(resolveKbPage('home'), { kbScope: 'page', kbPageKey: 'home' });
8
+ assert.deepEqual(resolveKbPage('search'), { kbScope: 'page', kbPageKey: 'search' });
9
+ assert.deepEqual(resolveKbPage('42'), { kbScope: 'page', kbPageKey: 'article:42' });
10
+ assert.throws(() => resolveKbPage('faq'), /--kb-page/);
11
+ });
12
+
13
+ test('noticeFields sends only passed flags and validates', () => {
14
+ assert.deepEqual(noticeFields({}), {});
15
+ assert.deepEqual(noticeFields({ showOnKb: true, kbSeverity: 'warning', dismiss: false, expiresAt: '2026-12-31T00:00:00Z' }),
16
+ { showOnKb: true, kbSeverity: 'warning', kbDismissible: false, expiresAt: '2026-12-31T00:00:00.000Z' });
17
+ assert.throws(() => noticeFields({ kbMessage: 'a <b>x</b>' }), /< or >/);
18
+ assert.throws(() => noticeFields({ kbMessage: 'a > b' }), /< or >/);
19
+ assert.throws(() => noticeFields({ kbSeverity: 'red' }), /one of/);
20
+ assert.throws(() => noticeFields({ startsAt: 'nope' }), /valid date/);
21
+ });
22
+
23
+ test('addBody and updateBody merge the existing row', () => {
24
+ assert.deepEqual(addBody({ title: 'T', content: 'C', showOnKb: true, kbPage: 'home', kbMessage: 'Hi' }),
25
+ { topic: 'T', overrideFact: 'C', isActive: true, showOnKb: true, kbScope: 'page', kbPageKey: 'home', kbMessage: 'Hi' });
26
+ const ex = { topic: 'T', overrideFact: 'C', priority: 3, isActive: true, showOnKb: true, kbScope: 'all', kbMessage: 'Old' };
27
+ const b = updateBody(ex, { kbMessage: 'New' });
28
+ assert.equal(b.topic, 'T');
29
+ assert.equal(b.overrideFact, 'C');
30
+ assert.equal(b.priority, 3);
31
+ assert.equal(b.kbMessage, 'New');
32
+ assert.equal(b.showOnKb, true);
33
+ });
34
+
35
+ test('bot_plan_required prints the upsell text', () => {
36
+ assert.throws(() => checkResult({ success: false, code: 'bot_plan_required' }), (e) => e.message === UPSELL);
37
+ assert.equal(friendlyError(new Error('POST /KnowledgeOverride -> 403: {"code":"bot_plan_required"}')).message, UPSELL);
38
+ assert.throws(() => checkResult({ success: false, message: 'Topic is required.' }), /Topic is required/);
39
+ assert.deepEqual(checkResult({ success: true, id: 1 }), { success: true, id: 1 });
40
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/cli",
3
- "version": "1.4.165",
3
+ "version": "1.4.167",
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": {