@velaro/cli 1.4.121 → 1.4.123

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.
@@ -1,4 +1,4 @@
1
- import { messagingGet, messagingPut } from '../api.js';
1
+ import { messagingGet, messagingPut, messagingPost } from '../api.js';
2
2
  import { buildPolicyBody, findPolicy, describeMode, parseTeamId } from '../signature-policy.js';
3
3
 
4
4
  // velaro signature policy get|set
@@ -19,6 +19,8 @@ function printRow(label, row) {
19
19
  const dis = row.disclaimerEnabled === null || row.disclaimerEnabled === undefined ? 'follows company-wide (off if none set)' : row.disclaimerEnabled ? 'on' : 'off';
20
20
  console.log(` disclaimer ${dis}`);
21
21
  if (row.disclaimerText) console.log(` text ${row.disclaimerText}`);
22
+ console.log(` name line ${row.nameFormat ?? 'follows (none if nothing set)'}${row.nameSource ? `, ${row.nameSource}` : ''}${row.teamLabel ? `, team label "${row.teamLabel}"` : ''}`);
23
+ if (row.teamId === 0) console.log(` overrides team admins ${row.allowTeamOverrides === false ? 'blocked' : 'allowed'}, agents ${row.allowAgentOverrides === false ? 'blocked' : 'allowed'}`);
22
24
  }
23
25
 
24
26
  const getCommand = {
@@ -47,7 +49,13 @@ const setCommand = {
47
49
  .option('signature', { type: 'string', describe: 'Company signature HTML (empty string clears it)' })
48
50
  .option('disclaimer', { type: 'boolean', describe: 'Turn the legal disclaimer on or off' })
49
51
  .option('disclaimer-default', { type: 'boolean', describe: 'Clear the disclaimer on/off choice back to company-wide' })
50
- .option('disclaimer-text', { type: 'string', describe: 'Legal disclaimer text (empty string clears it)' }),
52
+ .option('disclaimer-text', { type: 'string', describe: 'Legal disclaimer text (empty string clears it)' })
53
+ .option('name-format', { type: 'string', describe: 'none | name | team | name-and-team | default' })
54
+ .option('name-source', { type: 'string', describe: 'real-name | display-name | default' })
55
+ .option('team-label', { type: 'string', describe: 'Team name shown by the team formats (empty string clears it)' })
56
+ .option('allow-team-overrides', { type: 'boolean', describe: 'Company-wide only: may team admins change group settings' })
57
+ .option('allow-agent-overrides', { type: 'boolean', describe: 'Company-wide only: may agents choose their own name line' })
58
+ .option('apply-to', { type: 'string', describe: 'Company-wide only: inheritingGroups | allGroups | newGroupsOnly' }),
51
59
  handler: async (argv) => {
52
60
  const teamId = parseTeamId(argv['team-id']);
53
61
  const data = await messagingGet('/Signatures/policy');
@@ -58,16 +66,44 @@ const setCommand = {
58
66
  corporateSignature: argv.signature,
59
67
  disclaimerEnabled: argv['disclaimer-default'] ? null : argv.disclaimer,
60
68
  disclaimerText: argv['disclaimer-text'],
69
+ nameFormat: argv['name-format'],
70
+ nameSource: argv['name-source'],
71
+ teamLabel: argv['team-label'],
72
+ allowTeamOverrides: argv['allow-team-overrides'],
73
+ allowAgentOverrides: argv['allow-agent-overrides'],
74
+ applyTo: argv['apply-to'],
61
75
  });
62
76
  await messagingPut('/Signatures/policy', body);
63
77
  console.log(`${GRN}Signature policy updated.${RESET} Run \`velaro signature policy get\` to review.`);
64
78
  },
65
79
  };
66
80
 
81
+ const historyCommand = {
82
+ command: 'history',
83
+ describe: 'List saved versions of the policy (newest first)',
84
+ builder: (y) => y.option('team-id', { type: 'number', default: 0, describe: '0 = company-wide' }),
85
+ handler: async (argv) => {
86
+ const list = await messagingGet(`/Signatures/policy/history?teamId=${parseTeamId(argv['team-id'])}`);
87
+ for (const v of Array.isArray(list) ? list : []) {
88
+ console.log(`${v.id} ${v.changedAt} ${v.changedByName || 'unknown'} ${v.action}`);
89
+ }
90
+ },
91
+ };
92
+
93
+ const rollbackCommand = {
94
+ command: 'rollback <versionId>',
95
+ describe: 'Restore a saved version (saved as a new version)',
96
+ builder: (y) => y.positional('versionId', { type: 'number' }),
97
+ handler: async (argv) => {
98
+ await messagingPost(`/Signatures/policy/rollback/${Number(argv.versionId)}`, {});
99
+ console.log(`${GRN}Rolled back.${RESET} Run \`velaro signature policy get\` to review.`);
100
+ },
101
+ };
102
+
67
103
  const policyCommand = {
68
104
  command: 'policy <subcommand>',
69
105
  describe: 'View and update the company email signature policy',
70
- builder: (y) => y.command(getCommand).command(setCommand).demandCommand(1, 'Specify a subcommand: get | set'),
106
+ builder: (y) => y.command(getCommand).command(setCommand).command(historyCommand).command(rollbackCommand).demandCommand(1, 'Specify a subcommand: get | set | history | rollback'),
71
107
  handler: () => {},
72
108
  };
73
109
 
@@ -4,7 +4,10 @@
4
4
  * velaro teams-phone status Show current configuration
5
5
  * velaro teams-phone set --tenant-id ... Create or update the configuration
6
6
  * velaro teams-phone remove Delete the configuration
7
- * velaro teams-phone test Run the inbound-calling readiness checks
7
+ * velaro teams-phone test Run the calling readiness checks (ACS connection, callback, consent, resource account)
8
+ * velaro teams-phone queue list List queues with their max wait for a free agent
9
+ * velaro teams-phone queue set --resource-account-id <guid> [--max-wait-seconds 30-600] ... Create or update a queue
10
+ * velaro teams-phone queue delete <id> Delete a queue
8
11
  * velaro teams-phone agents list List agents and their Teams user object IDs
9
12
  * velaro teams-phone agents set <agentId> <teamsUserId> Map an agent to an Entra user Object ID
10
13
  * velaro teams-phone agents delete <agentId> Clear an agent's mapping
@@ -87,8 +90,11 @@ async function removeHandler() {
87
90
 
88
91
  async function testHandler() {
89
92
  const result = await messagingPost('/TeamsPhone/Config/Test', {});
90
- const color = result?.success ? GRN : RED;
91
- console.log(`\n${color}${result?.success ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}`);
93
+ // No checks reported is never a pass: an empty body must not read as ready.
94
+ const noChecks = !Array.isArray(result?.checks) || result.checks.length === 0;
95
+ const passed = result?.success === true && !noChecks;
96
+ const color = passed ? GRN : RED;
97
+ console.log(`\n${color}${passed ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}${noChecks ? ' The test returned no checks, so nothing was verified.' : ''}`);
92
98
  if (typeof result?.callingReady === 'boolean') {
93
99
  console.log(` Inbound calling ready: ${result.callingReady ? GRN : RED}${result.callingReady}${RST}`);
94
100
  }
@@ -98,7 +104,75 @@ async function testHandler() {
98
104
  }
99
105
  }
100
106
  console.log('');
101
- if (!result?.success) process.exitCode = 1;
107
+ if (!passed) process.exitCode = 1;
108
+ }
109
+
110
+ // -- queue (extra resource accounts, each with its own max wait) -------------------
111
+
112
+ /** GET /TeamsPhone/Queues returns { queues: [...] }. Any other shape is an error, never an empty list. */
113
+ export function queuesFromResponse(res) {
114
+ if (!res || !Array.isArray(res.queues)) {
115
+ throw new Error(`Unexpected response from GET /TeamsPhone/Queues (expected { queues: [...] }): ${JSON.stringify(res)?.slice(0, 300)}`);
116
+ }
117
+ return res.queues;
118
+ }
119
+
120
+ async function queueListHandler() {
121
+ let queues;
122
+ try {
123
+ queues = queuesFromResponse(await messagingGet('/TeamsPhone/Queues'));
124
+ } catch (err) {
125
+ console.error(`
126
+ ${RED}${err.message}${RST}
127
+ `);
128
+ process.exit(1);
129
+ }
130
+ if (queues.length === 0) {
131
+ console.log(`
132
+ ${DIM}No queues found.${RST}
133
+ `);
134
+ return;
135
+ }
136
+ console.log(`
137
+ ${BOLD}Teams Phone queues${RST}`);
138
+ for (const q of queues) {
139
+ const wait = typeof q.maxWaitSeconds === 'number' ? `${q.maxWaitSeconds}s` : `${DIM}default${RST}`;
140
+ console.log(` ${String(q.id).padEnd(6)} ${String(q.queueName ?? q.assignedPhoneNumber ?? '').padEnd(28)} ring ${String(q.ringTimeoutSeconds ?? '').padEnd(4)} max wait ${wait}`);
141
+ }
142
+ console.log('');
143
+ }
144
+
145
+ async function queueSetHandler(argv) {
146
+ const wait = argv.maxWaitSeconds;
147
+ if (wait !== undefined && (!Number.isInteger(wait) || wait < 30 || wait > 600)) {
148
+ throw new Error('--max-wait-seconds must be a whole number from 30 to 600.');
149
+ }
150
+ // POST is an upsert keyed by resource account: fields left undefined would overwrite stored values with null. So read
151
+ // the existing queue first and pass its current values through for every flag the admin did not give.
152
+ const listed = await messagingGet('/TeamsPhone/Queues');
153
+ const existing = Array.isArray(listed?.queues)
154
+ ? listed.queues.find((q) => q.applicationInstanceObjectId === argv.resourceAccountId)
155
+ : undefined;
156
+ const pick = (given, key) => (given !== undefined ? given : existing?.[key]);
157
+ const body = {
158
+ applicationInstanceObjectId: argv.resourceAccountId,
159
+ assignedPhoneNumber: pick(argv.phoneNumber, 'assignedPhoneNumber'),
160
+ queueName: pick(argv.name, 'queueName'),
161
+ teamId: pick(argv.teamId, 'teamId'),
162
+ ringTimeoutSeconds: pick(argv.ringTimeoutSeconds, 'ringTimeoutSeconds'),
163
+ maxWaitSeconds: pick(wait, 'maxWaitSeconds'),
164
+ };
165
+ const r = await messagingPost('/TeamsPhone/Queues', body);
166
+ const q = r?.queue;
167
+ const saved = q?.maxWaitSeconds ?? body.maxWaitSeconds;
168
+ console.log(`
169
+ ${GRN}✓${RST} Queue saved${q?.id !== undefined ? ` (id ${q.id})` : ''}. Max wait: ${saved !== undefined && saved !== null ? `${saved} seconds` : 'default'}.
170
+ `);
171
+ }
172
+
173
+ async function queueDeleteHandler(argv) {
174
+ await messagingDel(`/TeamsPhone/Queues/${encodeURIComponent(argv.id)}`);
175
+ console.log(`\n${GRN}✓${RST} Queue ${argv.id} deleted.\n`);
102
176
  }
103
177
 
104
178
  // -- agents (agent -> Entra user object id) ---------------------------------------
@@ -169,10 +243,41 @@ export const teamsPhoneCommand = {
169
243
  })
170
244
  .command({
171
245
  command: 'test',
172
- describe: 'Run the Teams Phone readiness checks (consent, resource account, Graph reachability) and print each check',
246
+ describe: 'Run the Teams Phone calling readiness checks (tenant ID, resource account, admin consent, inbound call routing) and print each check as PASS or FAIL',
173
247
  builder: yy => yy,
174
248
  handler: testHandler,
175
249
  })
250
+ .command({
251
+ command: 'queue <action>',
252
+ describe: 'Queues: extra resource accounts, each with its own max wait for a free agent (list | set | delete)',
253
+ builder: yy => yy
254
+ .command({
255
+ command: 'list',
256
+ describe: 'List queues with their max wait',
257
+ builder: z => z,
258
+ handler: queueListHandler,
259
+ })
260
+ .command({
261
+ command: 'set',
262
+ describe: 'Create or update a queue (keyed by --resource-account-id)',
263
+ builder: z => z
264
+ .option('resource-account-id', { describe: 'Teams resource account (application instance) object ID of the queue', type: 'string', demandOption: true })
265
+ .option('phone-number', { describe: 'Queue phone number (E.164)', type: 'string' })
266
+ .option('name', { describe: 'Queue name shown in reports and on the call pop', type: 'string' })
267
+ .option('team-id', { describe: 'Velaro team whose agents this queue rings; omit for any available agent', type: 'number' })
268
+ .option('ring-timeout-seconds', { describe: 'Seconds each agent is rung before moving on', type: 'number' })
269
+ .option('max-wait-seconds', { describe: 'Longest a caller waits for a free agent, 30 to 600 (default 120)', type: 'number' }),
270
+ handler: queueSetHandler,
271
+ })
272
+ .command({
273
+ command: 'delete <id>',
274
+ describe: 'Delete a queue',
275
+ builder: z => z.positional('id', { type: 'number', describe: 'Queue id from queue list' }),
276
+ handler: queueDeleteHandler,
277
+ })
278
+ .demandCommand(1, 'Specify list, set or delete.'),
279
+ handler: () => {},
280
+ })
176
281
  .command({
177
282
  command: 'agents <action>',
178
283
  describe: 'Agent mapping: which Entra user Object ID is which Velaro agent (list | set | delete)',
@@ -22,6 +22,28 @@ export function parseMode(value) {
22
22
  return mode;
23
23
  }
24
24
 
25
+ const NAME_SOURCES = ['real_name', 'display_name'];
26
+ const NAME_FORMATS = ['none', 'name', 'team', 'name_and_team'];
27
+ const APPLY_TO = ['inheritingGroups', 'allGroups', 'newGroupsOnly'];
28
+
29
+ // undefined = not supplied, null = inherit, else a validated API value. Accepts dashes ("display-name").
30
+ function parseEnum(value, allowed, label) {
31
+ if (value === undefined) return undefined;
32
+ if (value === null) return null;
33
+ const v = String(value).trim().toLowerCase().replace(/-/g, '_');
34
+ if (v === '' || v === 'default' || v === 'inherit') return null;
35
+ if (!allowed.includes(v)) throw new Error(`${label} must be one of ${allowed.join(', ')} or default`);
36
+ return v;
37
+ }
38
+ export const parseNameSource = (v) => parseEnum(v, NAME_SOURCES, 'nameSource');
39
+ export const parseNameFormat = (v) => parseEnum(v, NAME_FORMATS, 'nameFormat');
40
+
41
+ export function parseApplyTo(value) {
42
+ if (value === undefined || value === null || value === '') return undefined;
43
+ if (!APPLY_TO.includes(value)) throw new Error(`applyTo must be one of ${APPLY_TO.join(', ')}`);
44
+ return value;
45
+ }
46
+
25
47
  export function parseTeamId(value) {
26
48
  if (value === undefined || value === null || value === '') return 0;
27
49
  const n = Number(value);
@@ -39,6 +61,12 @@ export function buildPolicyBody(current, opts = {}) {
39
61
  corporateSignature: cur.corporateSignature || null,
40
62
  disclaimerEnabled: cur.disclaimerEnabled ?? null,
41
63
  disclaimerText: cur.disclaimerText || null,
64
+ // PUT replaces the whole row, so the flow-down fields must be carried or a mode change would wipe them.
65
+ nameSource: cur.nameSource ?? null,
66
+ nameFormat: cur.nameFormat ?? null,
67
+ teamLabel: cur.teamLabel || null,
68
+ allowTeamOverrides: cur.allowTeamOverrides ?? null,
69
+ allowAgentOverrides: cur.allowAgentOverrides ?? null,
42
70
  };
43
71
  const mode = parseMode(opts.mode);
44
72
  if (mode !== undefined) body.mode = mode;
@@ -50,6 +78,20 @@ export function buildPolicyBody(current, opts = {}) {
50
78
  body.disclaimerEnabled = opts.disclaimerEnabled;
51
79
  }
52
80
  if (opts.disclaimerText !== undefined) body.disclaimerText = opts.disclaimerText || null;
81
+ const nameSource = parseNameSource(opts.nameSource);
82
+ if (nameSource !== undefined) body.nameSource = nameSource;
83
+ const nameFormat = parseNameFormat(opts.nameFormat);
84
+ if (nameFormat !== undefined) body.nameFormat = nameFormat;
85
+ if (opts.teamLabel !== undefined) body.teamLabel = opts.teamLabel || null;
86
+ for (const k of ['allowTeamOverrides', 'allowAgentOverrides']) {
87
+ if (opts[k] !== undefined) {
88
+ if (opts[k] !== null && typeof opts[k] !== 'boolean') throw new Error(`${k} must be true, false or null`);
89
+ body[k] = opts[k];
90
+ }
91
+ }
92
+ const applyTo = parseApplyTo(opts.applyTo);
93
+ if (applyTo !== undefined) body.applyTo = applyTo;
94
+ if (body.teamLabel && body.teamLabel.length > 100) throw new Error('teamLabel is limited to 100 characters');
53
95
  if (body.corporateSignature && body.corporateSignature.length > 4000) throw new Error('corporateSignature is limited to 4000 characters');
54
96
  if (body.disclaimerText && body.disclaimerText.length > 2000) throw new Error('disclaimerText is limited to 2000 characters');
55
97
  return body;
@@ -21,12 +21,12 @@ test('parseTeamId defaults to company-wide and rejects junk', () => {
21
21
  test('buildPolicyBody keeps current values for fields that are not passed', () => {
22
22
  const cur = { teamId: 0, mode: 'company_default', corporateSignature: '<b>Acme</b>', disclaimerEnabled: true, disclaimerText: 'Confidential' };
23
23
  const body = buildPolicyBody(cur, { mode: 'locked' });
24
- assert.deepEqual(body, { teamId: 0, mode: 'admin_locked', corporateSignature: '<b>Acme</b>', disclaimerEnabled: true, disclaimerText: 'Confidential' });
24
+ assert.deepEqual(body, { teamId: 0, mode: 'admin_locked', corporateSignature: '<b>Acme</b>', disclaimerEnabled: true, disclaimerText: 'Confidential', nameSource: null, nameFormat: null, teamLabel: null, allowTeamOverrides: null, allowAgentOverrides: null });
25
25
  });
26
26
 
27
27
  test('buildPolicyBody with no existing row starts from all-null (follow company-wide)', () => {
28
28
  const body = buildPolicyBody(undefined, { teamId: 5, disclaimerEnabled: true });
29
- assert.deepEqual(body, { teamId: 5, mode: null, corporateSignature: null, disclaimerEnabled: true, disclaimerText: null });
29
+ assert.deepEqual(body, { teamId: 5, mode: null, corporateSignature: null, disclaimerEnabled: true, disclaimerText: null, nameSource: null, nameFormat: null, teamLabel: null, allowTeamOverrides: null, allowAgentOverrides: null });
30
30
  });
31
31
 
32
32
  test('null clears a field and over-long text is rejected before sending', () => {
@@ -46,3 +46,29 @@ test('findPolicy picks the row for a team and describeMode is readable', () => {
46
46
  assert.match(describeMode('admin_locked'), /locked/);
47
47
  assert.match(describeMode(null), /follows/);
48
48
  });
49
+
50
+ test('a mode change keeps the name line, team label and override switches (PUT replaces the row)', () => {
51
+ const cur = { teamId: 0, mode: 'company_default', nameSource: 'display_name', nameFormat: 'name_and_team', teamLabel: 'Customer Support', allowTeamOverrides: false, allowAgentOverrides: true };
52
+ const body = buildPolicyBody(cur, { mode: 'locked' });
53
+ assert.equal(body.mode, 'admin_locked');
54
+ assert.equal(body.nameSource, 'display_name');
55
+ assert.equal(body.nameFormat, 'name_and_team');
56
+ assert.equal(body.teamLabel, 'Customer Support');
57
+ assert.equal(body.allowTeamOverrides, false);
58
+ assert.equal(body.allowAgentOverrides, true);
59
+ });
60
+
61
+ test('name line options validate, accept dashes and clear with default', () => {
62
+ const body = buildPolicyBody(undefined, { nameFormat: 'name-and-team', nameSource: 'display-name', teamLabel: 'Support', allowAgentOverrides: false, applyTo: 'allGroups' });
63
+ assert.equal(body.nameFormat, 'name_and_team');
64
+ assert.equal(body.nameSource, 'display_name');
65
+ assert.equal(body.teamLabel, 'Support');
66
+ assert.equal(body.allowAgentOverrides, false);
67
+ assert.equal(body.applyTo, 'allGroups');
68
+ assert.equal(buildPolicyBody({ nameFormat: 'team' }, { nameFormat: 'default' }).nameFormat, null);
69
+ assert.throws(() => buildPolicyBody(undefined, { nameFormat: 'loud' }), /nameFormat must be one of/);
70
+ assert.throws(() => buildPolicyBody(undefined, { nameSource: 'nick' }), /nameSource must be one of/);
71
+ assert.throws(() => buildPolicyBody(undefined, { applyTo: 'some' }), /applyTo/);
72
+ assert.throws(() => buildPolicyBody(undefined, { allowTeamOverrides: 'no' }), /true, false or null/);
73
+ assert.throws(() => buildPolicyBody(undefined, { teamLabel: 'x'.repeat(101) }), /100/);
74
+ });
@@ -0,0 +1,15 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { queuesFromResponse } from './commands/teams-phone.js';
4
+
5
+ test('queue list reads the queues key', () => {
6
+ const q = [{ id: 1, maxWaitSeconds: 90 }];
7
+ assert.deepEqual(queuesFromResponse({ queues: q }), q);
8
+ assert.deepEqual(queuesFromResponse({ queues: [] }), []);
9
+ });
10
+
11
+ test('queue list rejects a bare array or error body instead of reporting no queues', () => {
12
+ assert.throws(() => queuesFromResponse([{ id: 1 }]), /Unexpected response/);
13
+ assert.throws(() => queuesFromResponse({ error: 'boom' }), /Unexpected response/);
14
+ assert.throws(() => queuesFromResponse(null), /Unexpected response/);
15
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/cli",
3
- "version": "1.4.121",
3
+ "version": "1.4.123",
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": {