@xema/omni-protocol 0.1.129 → 0.1.130
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/GLOSSARY.md +2 -2
- package/README.md +6 -8
- package/dist/index.d.ts +138 -87
- package/dist/index.js +24 -9
- package/dist/testing.d.ts +14 -14
- package/dist/testing.js +79 -82
- package/dist/validation.d.ts +23 -23
- package/dist/validation.js +174 -121
- package/guide/agent.md +23 -23
- package/guide/breaks.md +1 -1
- package/guide/lead.md +34 -17
- package/guide/phone.md +22 -22
- package/guide/queue.md +7 -7
- package/guide/voice.md +64 -54
- package/guide.md +163 -143
- package/package.json +1 -1
package/dist/validation.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
// Each list is pinned to its type both ways -- a member the type lacks, or a member the list
|
|
10
10
|
// lacks, fails to compile -- so what the validators accept cannot drift from what the
|
|
11
11
|
// declarations say.
|
|
12
|
-
import { RECORDING_ACTIONS, SHIFT_EVENT_KINDS, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, } from "./index.js";
|
|
12
|
+
import { RECORDING_ACTIONS, LEAD_COMMAND_CAPABILITY, SHIFT_EVENT_KINDS, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, } from "./index.js";
|
|
13
13
|
export class ProtocolConformanceError extends Error {
|
|
14
14
|
violations;
|
|
15
15
|
constructor(violations, summary = "Adapter violates the Omni protocol") {
|
|
@@ -58,7 +58,7 @@ const TEAM_AVAILABILITIES = membersOf({
|
|
|
58
58
|
ready: true, "on-task": true, "on-break": true, elsewhere: true, "signed-out": true,
|
|
59
59
|
});
|
|
60
60
|
const HISTORY_STEPS = membersOf({
|
|
61
|
-
arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true,
|
|
61
|
+
arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, added: true, unanswered: true,
|
|
62
62
|
"callback-requested": true,
|
|
63
63
|
});
|
|
64
64
|
const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
|
|
@@ -72,14 +72,15 @@ const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number
|
|
|
72
72
|
const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true, unreachable: true, rejected: true, cancelled: true, unexplained: true });
|
|
73
73
|
/** The outcomes that name a cause. `unexplained` is declarable only beside one of these. */
|
|
74
74
|
const EXPLAINED_FAILURES = ["busy", "no-answer", "unreachable", "rejected", "cancelled"];
|
|
75
|
-
const ON_CALL_ROLES = membersOf({ party: true, agent: true,
|
|
75
|
+
const ON_CALL_ROLES = membersOf({ party: true, agent: true, added: true });
|
|
76
76
|
const ON_CALL_STAGES = membersOf({ ringing: true, joined: true });
|
|
77
77
|
/** The task capabilities under which a command dials, and so need the manifest to say how a dial ends. */
|
|
78
|
-
const DIALLING_CAPABILITIES = ["connectBack", "
|
|
78
|
+
const DIALLING_CAPABILITIES = ["connectBack", "addToCall"];
|
|
79
79
|
const SNAPSHOT_REASONS = membersOf({
|
|
80
80
|
reconnected: true, "provider-requested": true,
|
|
81
81
|
});
|
|
82
82
|
const SESSION_CAPABILITIES = membersOf({ breaks: true, lead: true, preferences: true, nextCall: true });
|
|
83
|
+
const LEAD_CAPABILITY_NAMES = Object.values(LEAD_COMMAND_CAPABILITY);
|
|
83
84
|
const MEMBER_BREAKS = membersOf({
|
|
84
85
|
"awaiting-approval": true, granted: true, "starting-after-task": true,
|
|
85
86
|
});
|
|
@@ -101,7 +102,7 @@ const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
|
|
|
101
102
|
const TASK_CAPABILITIES = {
|
|
102
103
|
voice: membersOf({
|
|
103
104
|
browsers: true, outcomes: true, custom: true, decline: true, hold: true,
|
|
104
|
-
endCall: true, terminateCall: true, connectBack: true, schedule: true, leadAssist: true,
|
|
105
|
+
endCall: true, terminateCall: true, connectBack: true, schedule: true, leadAssist: true, addToCall: true, recording: true,
|
|
105
106
|
}),
|
|
106
107
|
chat: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, hold: true, schedule: true }),
|
|
107
108
|
email: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, schedule: true }),
|
|
@@ -378,7 +379,7 @@ function validatePhones(manifest, path, into) {
|
|
|
378
379
|
}
|
|
379
380
|
}
|
|
380
381
|
/**
|
|
381
|
-
* The host's choice of phone for a
|
|
382
|
+
* The host's choice of phone for a session, held to the manifest: one the platform listed, required
|
|
382
383
|
* on voice, absent elsewhere.
|
|
383
384
|
*/
|
|
384
385
|
export function validatePhone(value, manifest, path = "context.phone") {
|
|
@@ -386,10 +387,10 @@ export function validatePhone(value, manifest, path = "context.phone") {
|
|
|
386
387
|
const channel = isPlainObject(manifest) ? manifest.channel : undefined;
|
|
387
388
|
const phones = isPlainObject(manifest) && Array.isArray(manifest.phones) ? manifest.phones : [];
|
|
388
389
|
if (channel !== "voice") {
|
|
389
|
-
into.require(value === undefined, "context.phone.unexpected", path, `a ${describeValue(channel)}
|
|
390
|
+
into.require(value === undefined, "context.phone.unexpected", path, `a ${describeValue(channel)} session has no call to hear and chooses no phone`);
|
|
390
391
|
return into.violations;
|
|
391
392
|
}
|
|
392
|
-
if (!into.require(value !== undefined, "context.phone.required", path, "a voice
|
|
393
|
+
if (!into.require(value !== undefined, "context.phone.required", path, "a voice session says how the agent hears the call: one of the manifest's phones"))
|
|
393
394
|
return into.violations;
|
|
394
395
|
if (into.oneOf(value, PHONES, "context.phone", path)) {
|
|
395
396
|
into.require(phones.includes(value), "context.phone.unsupported", path, `the host chose ${describeValue(value)} and the manifest lists ${phones.length === 0 ? "no phones" : phones.map(describeValue).join(", ")}`);
|
|
@@ -408,25 +409,25 @@ function manifestCalendar(manifest) {
|
|
|
408
409
|
export function validateProviderTimeEstimate(value, scope, path = "estimate") {
|
|
409
410
|
const into = new Collector();
|
|
410
411
|
if (!isPlainObject(scope)) {
|
|
411
|
-
into.add("timeEstimate.scope", path, "provider/
|
|
412
|
+
into.add("timeEstimate.scope", path, "provider/session scope is required");
|
|
412
413
|
return into.violations;
|
|
413
414
|
}
|
|
414
|
-
for (const key of ["providerId", "
|
|
415
|
-
into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/
|
|
415
|
+
for (const key of ["providerId", "sessionId"])
|
|
416
|
+
into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/session scope is required");
|
|
416
417
|
if (value === undefined)
|
|
417
418
|
return into.violations;
|
|
418
419
|
if (!isPlainObject(value)) {
|
|
419
420
|
into.add("timeEstimate.shape", path, "expected a provider time estimate or undefined");
|
|
420
421
|
return into.violations;
|
|
421
422
|
}
|
|
422
|
-
for (const key of ["providerId", "
|
|
423
|
-
into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/
|
|
423
|
+
for (const key of ["providerId", "sessionId"])
|
|
424
|
+
into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/session");
|
|
424
425
|
into.timestamp(value.at, "timeEstimate.at", `${path}.at`);
|
|
425
426
|
into.filled(value.clockId, "timeEstimate.clock", `${path}.clockId`, "estimate must identify its clock domain");
|
|
426
427
|
if (value.uncertaintyMs !== undefined)
|
|
427
428
|
into.require(typeof value.uncertaintyMs === "number" && Number.isFinite(value.uncertaintyMs) && value.uncertaintyMs >= 0, "timeEstimate.uncertainty", `${path}.uncertaintyMs`, "estimated uncertainty must be finite and nonnegative");
|
|
428
429
|
for (const key of Object.keys(value))
|
|
429
|
-
into.require(["providerId", "
|
|
430
|
+
into.require(["providerId", "sessionId", "at", "clockId", "uncertaintyMs"].includes(key), "timeEstimate.field", `${path}.${key}`, "unsupported estimate field");
|
|
430
431
|
return into.violations;
|
|
431
432
|
}
|
|
432
433
|
/** Validate host-local periodic clock-check configuration. Omission disables checking. */
|
|
@@ -459,21 +460,21 @@ export function validateProviderTimeCheckRequest(value, path = "request") {
|
|
|
459
460
|
return into.violations;
|
|
460
461
|
}
|
|
461
462
|
/** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
|
|
462
|
-
export function validateProviderTimeCheckResult(value, request,
|
|
463
|
+
export function validateProviderTimeCheckResult(value, request, sessionId, path = "result") {
|
|
463
464
|
const into = new Collector();
|
|
464
465
|
into.violations.push(...validateProviderTimeCheckRequest(request));
|
|
465
|
-
into.filled(
|
|
466
|
+
into.filled(sessionId, "timeCheck.session", "sessionId", "current authenticated session is required");
|
|
466
467
|
if (!isPlainObject(value)) {
|
|
467
468
|
into.add("timeCheck.result.shape", path, "expected a clock-check response");
|
|
468
469
|
return into.violations;
|
|
469
470
|
}
|
|
470
471
|
into.filled(value.requestId, "timeCheck.result.id", `${path}.requestId`, "response must identify its request");
|
|
471
472
|
into.require(isPlainObject(request) && value.requestId === request.requestId, "timeCheck.result.request", `${path}.requestId`, "response must match the outstanding check");
|
|
472
|
-
into.require(value.
|
|
473
|
+
into.require(value.sessionId === sessionId, "timeCheck.result.session", `${path}.sessionId`, "response belongs to the current session");
|
|
473
474
|
into.filled(value.clockId, "timeCheck.result.clock", `${path}.clockId`, "provider clock domain/incarnation is required");
|
|
474
475
|
into.timestamp(value.providerTime, "timeCheck.result.time", `${path}.providerTime`);
|
|
475
476
|
for (const key of Object.keys(value))
|
|
476
|
-
into.require(["requestId", "
|
|
477
|
+
into.require(["requestId", "sessionId", "clockId", "providerTime"].includes(key), "timeCheck.result.field", `${path}.${key}`, "unsupported response field");
|
|
477
478
|
return into.violations;
|
|
478
479
|
}
|
|
479
480
|
export function validateManifest(manifest, path = "manifest") {
|
|
@@ -657,32 +658,38 @@ function validateLocalizedText(value, rule, path, into) {
|
|
|
657
658
|
// ---------------------------------------------------------------------------
|
|
658
659
|
// Task.
|
|
659
660
|
// ---------------------------------------------------------------------------
|
|
660
|
-
function
|
|
661
|
+
function validateAddToCallCapability(value, path, into) {
|
|
661
662
|
if (!isPlainObject(value)) {
|
|
662
|
-
into.add("task.
|
|
663
|
+
into.add("task.addToCall.shape", path, "addToCall says whom the agent may add to the call, as the dialpad does: { destinations: \"contacts-only\" | \"any-number\" }");
|
|
663
664
|
return;
|
|
664
665
|
}
|
|
665
|
-
|
|
666
|
-
|
|
666
|
+
into.oneOf(value.destinations, DIAL_DESTINATION_POLICIES, "task.addToCall.destinations", `${path}.destinations`);
|
|
667
|
+
if (value.contactIds === undefined)
|
|
668
|
+
return;
|
|
669
|
+
if (!Array.isArray(value.contactIds) || value.contactIds.length === 0) {
|
|
670
|
+
into.add("task.addToCall.contactIds", `${path}.contactIds`, "contactIds narrows the contacts offered: a non-empty list of ids, or omitted for every contact");
|
|
667
671
|
return;
|
|
668
|
-
}
|
|
669
|
-
// Nothing is typed, so a directory with nothing in it is a control with nothing to offer.
|
|
670
|
-
if (value.destinations.length === 0) {
|
|
671
|
-
into.add("task.destinations.offer", path, "a directory offers at least one item; with none, omit the capability");
|
|
672
672
|
}
|
|
673
673
|
const seen = new Set();
|
|
674
|
-
value.
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
return;
|
|
674
|
+
value.contactIds.forEach((id, index) => {
|
|
675
|
+
if (into.filled(id, "task.addToCall.contactIds", `${path}.contactIds[${index}]`, "each contact id is a non-empty string")) {
|
|
676
|
+
into.require(!seen.has(id), "task.addToCall.contactIds.unique", `${path}.contactIds[${index}]`, `${describeValue(id)} is listed twice`);
|
|
677
|
+
seen.add(id);
|
|
679
678
|
}
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
679
|
+
});
|
|
680
|
+
}
|
|
681
|
+
/** The provider's contacts, the agent computer's directory: each entry a contact with a unique id. */
|
|
682
|
+
function validateContactEntriesInto(value, path, into, levels) {
|
|
683
|
+
const seen = new Set();
|
|
684
|
+
value.forEach((contact, index) => {
|
|
685
|
+
const at = `${path}[${index}]`;
|
|
686
|
+
validateContactInto(contact, at, into, levels);
|
|
687
|
+
if (!isPlainObject(contact))
|
|
688
|
+
return;
|
|
689
|
+
if (into.filled(contact.id, "contact.id", `${at}.id`, "a contacts entry carries the unique id the wire names it by")) {
|
|
690
|
+
into.require(!seen.has(contact.id), "contact.id.unique", `${at}.id`, `duplicate contact id: ${contact.id}`);
|
|
691
|
+
seen.add(contact.id);
|
|
684
692
|
}
|
|
685
|
-
into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
|
|
686
693
|
});
|
|
687
694
|
}
|
|
688
695
|
function validateOutcomes(value, path, into) {
|
|
@@ -849,12 +856,12 @@ function validateResolvedInto(value, rule, path, levels, into) {
|
|
|
849
856
|
into.require(value.lockedBy !== undefined, `${rule}.reason.unexpected`, `${path}.reason`, "a reason goes with lockedBy: it says why it was locked");
|
|
850
857
|
}
|
|
851
858
|
}
|
|
852
|
-
/** A command context's `levels`, the manifest's level ids the
|
|
859
|
+
/** A command context's `levels`, the manifest's level ids the session is validated against. */
|
|
853
860
|
function contextLevels(context, rule, path, into) {
|
|
854
861
|
const levels = context.levels;
|
|
855
862
|
if (Array.isArray(levels) && levels.every(level => typeof level === "string"))
|
|
856
863
|
return levels;
|
|
857
|
-
into.add(rule, `${path}.levels`, "the context carries levels, the ids of the manifest's orgLevels, to validate the
|
|
864
|
+
into.add(rule, `${path}.levels`, "the context carries levels, the ids of the manifest's orgLevels, to validate the session against");
|
|
858
865
|
return [];
|
|
859
866
|
}
|
|
860
867
|
const inForce = (levels) => levels.length === 0 ? "it declares no ladder" : `in force are ${levels.join(", ")}`;
|
|
@@ -1026,7 +1033,7 @@ function validateHistory(value, path, into, task = {}) {
|
|
|
1026
1033
|
// muted leg is a record that dropped a fact it held rather than one it could not establish.
|
|
1027
1034
|
if (entry.step === "muted") {
|
|
1028
1035
|
into.oneOf(entry.mutedBy, MUTED_BY, "task.history.mutedBy", `${at}.mutedBy`);
|
|
1029
|
-
into.require(entry.by !== undefined, "task.history.muted.by", `${at}.by`, "a muted leg is attributed to the
|
|
1036
|
+
into.require(entry.by !== undefined, "task.history.muted.by", `${at}.by`, "a muted leg is attributed to the session's agent: the host reported it, and the provider knows who the host's agent is");
|
|
1030
1037
|
}
|
|
1031
1038
|
else if (HISTORY_STEPS.includes(entry.step)) {
|
|
1032
1039
|
into.require(entry.mutedBy === undefined, "task.history.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
|
|
@@ -1038,11 +1045,11 @@ function validateHistory(value, path, into, task = {}) {
|
|
|
1038
1045
|
}
|
|
1039
1046
|
// A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
|
|
1040
1047
|
const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);
|
|
1041
|
-
for (const field of ["dialId", "
|
|
1048
|
+
for (const field of ["dialId", "contactId"]) {
|
|
1042
1049
|
if (entry[field] === undefined)
|
|
1043
1050
|
continue;
|
|
1044
1051
|
if (into.filled(entry[field], `task.history.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
|
|
1045
|
-
into.require(dialled, `task.history.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred,
|
|
1052
|
+
into.require(dialled, `task.history.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, added, or unanswered`);
|
|
1046
1053
|
}
|
|
1047
1054
|
}
|
|
1048
1055
|
});
|
|
@@ -1071,7 +1078,7 @@ const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
|
|
|
1071
1078
|
/**
|
|
1072
1079
|
* Who is on the call, as the provider states it. Voice only. Each entry is a role with what that
|
|
1073
1080
|
* role needs and nothing another role would: a party or an agent dialled nowhere, so neither
|
|
1074
|
-
* carries a destination; somebody
|
|
1081
|
+
* carries a destination; somebody added came from one, so they do.
|
|
1075
1082
|
*/
|
|
1076
1083
|
function validateOnCall(value, channel, path, into) {
|
|
1077
1084
|
if (value === undefined)
|
|
@@ -1098,14 +1105,18 @@ function validateOnCall(value, channel, path, into) {
|
|
|
1098
1105
|
}
|
|
1099
1106
|
if (role === "party")
|
|
1100
1107
|
parties += 1;
|
|
1108
|
+
if (entry.coaching !== undefined) {
|
|
1109
|
+
into.require(entry.coaching === true, "task.onCall.coaching", `${at}.coaching`, "coaching is stated by presence: send true or omit it");
|
|
1110
|
+
into.require(role === "agent", "task.onCall.coaching.unexpected", `${at}.coaching`, "only a lead, on the call as an agent, coaches");
|
|
1111
|
+
}
|
|
1101
1112
|
if (role === "agent") {
|
|
1102
1113
|
into.require(isUserId(entry.userId), "task.onCall.userId", `${at}.userId`, "an agent on the call is named by their user id");
|
|
1103
1114
|
}
|
|
1104
1115
|
else {
|
|
1105
1116
|
into.require(entry.userId === undefined, "task.onCall.userId.unexpected", `${at}.userId`, `a ${role} is not named by a user id`);
|
|
1106
1117
|
}
|
|
1107
|
-
if (role === "
|
|
1108
|
-
into.filled(entry.
|
|
1118
|
+
if (role === "added") {
|
|
1119
|
+
into.filled(entry.contactId, "task.onCall.contactId", `${at}.contactId`, `a ${role} entry names the contact that was dialled, by its id in the provider's contacts`);
|
|
1109
1120
|
// Stated, so a snapshot says who is present without anyone having seen the dial's outcome.
|
|
1110
1121
|
if (into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
|
|
1111
1122
|
into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
|
|
@@ -1125,13 +1136,13 @@ function validateOnCall(value, channel, path, into) {
|
|
|
1125
1136
|
if (entry.stage !== undefined && into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
|
|
1126
1137
|
into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
|
|
1127
1138
|
}
|
|
1128
|
-
for (const field of ["
|
|
1129
|
-
into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on
|
|
1139
|
+
for (const field of ["contactId", "label"]) {
|
|
1140
|
+
into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on added`);
|
|
1130
1141
|
}
|
|
1131
1142
|
}
|
|
1132
1143
|
else {
|
|
1133
|
-
for (const field of ["
|
|
1134
|
-
into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, role === "party" ? `a party carries ${field} on a connect-back alone, with its dial and stage together` : `a ${role} was dialled from nowhere; ${field} belongs on
|
|
1144
|
+
for (const field of ["contactId", "dialId", "label", "stage"]) {
|
|
1145
|
+
into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, role === "party" ? `a party carries ${field} on a connect-back alone, with its dial and stage together` : `a ${role} was dialled from nowhere; ${field} belongs on added`);
|
|
1135
1146
|
}
|
|
1136
1147
|
}
|
|
1137
1148
|
});
|
|
@@ -1386,8 +1397,8 @@ function validateTaskInto(task, context, path, into) {
|
|
|
1386
1397
|
case "custom":
|
|
1387
1398
|
validateCustomCapabilities(declared, `${path}.capabilities.custom`, into);
|
|
1388
1399
|
break;
|
|
1389
|
-
case "
|
|
1390
|
-
|
|
1400
|
+
case "addToCall":
|
|
1401
|
+
validateAddToCallCapability(declared, `${path}.capabilities.${name}`, into);
|
|
1391
1402
|
break;
|
|
1392
1403
|
default:
|
|
1393
1404
|
// Presence is the permission: the flag capabilities carry no payload, so anything but
|
|
@@ -1444,7 +1455,7 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
|
|
|
1444
1455
|
/**
|
|
1445
1456
|
* Checks a lead command before dispatch, against the current authentication, transport and team
|
|
1446
1457
|
* member list (`team`) and, for force-break and end-forced-break, the target's full `memberBreak`.
|
|
1447
|
-
* The authority is the
|
|
1458
|
+
* The authority is the lead capability the command needs, on the session's `lead`; the provider rechecks the target and the state
|
|
1448
1459
|
* atomically, since a team member list is not authority to act after it has changed.
|
|
1449
1460
|
*/
|
|
1450
1461
|
export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
@@ -1456,8 +1467,9 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1456
1467
|
const auth = isPlainObject(context.authentication) ? context.authentication : {};
|
|
1457
1468
|
into.violations.push(...validateAuthenticationState(auth, `${path}.authentication`, { levels: contextLevels(context, "team.command.levels", path, into) }));
|
|
1458
1469
|
const caps = isPlainObject(auth.capabilities) ? auth.capabilities : {};
|
|
1459
|
-
into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.command.connection", path, "lead commands require a live
|
|
1460
|
-
|
|
1470
|
+
into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.command.connection", path, "lead commands require a live session and active transport");
|
|
1471
|
+
const lead = isPlainObject(caps.lead) ? caps.lead : undefined;
|
|
1472
|
+
into.require(lead !== undefined, "team.command.capability", path, "the session must declare lead");
|
|
1461
1473
|
const command = request.command;
|
|
1462
1474
|
const member = ["type", "memberId", "assignmentId"];
|
|
1463
1475
|
const allowed = {
|
|
@@ -1472,6 +1484,12 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1472
1484
|
into.add("team.command.type", path, `unknown lead command: ${describeValue(command.type)}`);
|
|
1473
1485
|
return into.violations;
|
|
1474
1486
|
}
|
|
1487
|
+
// Every lead switches the feature and leaves a call; every other command is the lead capability it needs.
|
|
1488
|
+
const needs = Object.hasOwn(LEAD_COMMAND_CAPABILITY, command.type)
|
|
1489
|
+
? LEAD_COMMAND_CAPABILITY[command.type] : undefined;
|
|
1490
|
+
if (needs !== undefined && lead !== undefined) {
|
|
1491
|
+
into.require(lead[needs] === true, "team.command.notGranted", path, `${describeValue(command.type)} needs the lead capability ${needs}, which this lead does not hold`);
|
|
1492
|
+
}
|
|
1475
1493
|
for (const key of Object.keys(request))
|
|
1476
1494
|
into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
|
|
1477
1495
|
for (const key of Object.keys(command))
|
|
@@ -1550,8 +1568,8 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1550
1568
|
}
|
|
1551
1569
|
into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication`, { levels: contextLevels(context, "break.command.levels", path, into) }));
|
|
1552
1570
|
const auth = isPlainObject(context.authentication) ? context.authentication : {};
|
|
1553
|
-
into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated
|
|
1554
|
-
into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the
|
|
1571
|
+
into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated session");
|
|
1572
|
+
into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the session must declare breaks");
|
|
1555
1573
|
into.require(context.transport === "active", "break.command.transport", path, "break commands require active transport");
|
|
1556
1574
|
if (!["requestBreak", "commitBreak", "cancelBreak", "endBreak"].includes(method)) {
|
|
1557
1575
|
into.add("break.command.method", path, "unknown break method");
|
|
@@ -1593,7 +1611,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1593
1611
|
return into.violations;
|
|
1594
1612
|
}
|
|
1595
1613
|
/**
|
|
1596
|
-
* Checks two complete break states within one provider/
|
|
1614
|
+
* Checks two complete break states within one provider/session's ordered event stream.
|
|
1597
1615
|
* Call before replacing accepted state; report violations and reconcile on failure.
|
|
1598
1616
|
* This is not a freshness check: validate a fresh authoritative snapshot separately and
|
|
1599
1617
|
* use it as a new baseline, never as an event transition. Source ordering and connection
|
|
@@ -1706,10 +1724,10 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
|
|
|
1706
1724
|
into.add("team.shape", path, "a team member list must be an object");
|
|
1707
1725
|
return;
|
|
1708
1726
|
}
|
|
1709
|
-
// The
|
|
1710
|
-
// and nobody else. Only a caller holding the
|
|
1711
|
-
if (context.capabilities !== undefined && context.capabilities.lead
|
|
1712
|
-
into.add("team.unentitled", path, "a team member list published to a
|
|
1727
|
+
// The user's capabilities are the permission: a team member list reaches a user whose capabilities include `lead`
|
|
1728
|
+
// and nobody else. Only a caller holding the session can check it.
|
|
1729
|
+
if (context.capabilities !== undefined && context.capabilities.lead === undefined) {
|
|
1730
|
+
into.add("team.unentitled", path, "a team member list published to a user whose capabilities do not include lead: the user's capabilities are the permission");
|
|
1713
1731
|
}
|
|
1714
1732
|
// Policies are present where the provider offers policy control, absent where it does not.
|
|
1715
1733
|
if (teamMembers.policies !== undefined)
|
|
@@ -1808,10 +1826,21 @@ function validateTeamMemberInto(member, at, context, into) {
|
|
|
1808
1826
|
if (into.require(isAssignmentId(entry.assignmentId), "team.member.listening.assignmentId", `${here}.assignmentId`, "a listening entry names which of the member's calls the lead is on: the application opens its own audio on it") && Array.isArray(member.tasks)) {
|
|
1809
1827
|
into.require(task !== undefined, "team.member.listening.assignment", `${here}.assignmentId`, "the call the lead is on is one the member's tasks carry");
|
|
1810
1828
|
}
|
|
1811
|
-
if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`)
|
|
1829
|
+
if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`)
|
|
1812
1830
|
&& isPlainObject(task) && Array.isArray(task.onCall) && isUserId(entry.leadId)) {
|
|
1813
|
-
// A lead who is heard is in the room the member sees
|
|
1814
|
-
|
|
1831
|
+
// A lead who is heard is in the room the member sees -- marked coaching where the member alone
|
|
1832
|
+
// hears them -- and a silent one is not.
|
|
1833
|
+
const inRoom = task.onCall.find((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId);
|
|
1834
|
+
const coaching = isPlainObject(inRoom) && inRoom.coaching === true;
|
|
1835
|
+
if (entry.mode === "join-call") {
|
|
1836
|
+
into.require(inRoom !== undefined && !coaching, "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard by everyone, so the task's onCall carries them as an agent, not coaching`);
|
|
1837
|
+
}
|
|
1838
|
+
else if (entry.mode === "coach") {
|
|
1839
|
+
into.require(coaching, "team.member.listening.coaching", `${here}.mode`, `${entry.leadId} is coaching and the member hears them, so the task's onCall carries them as an agent marked coaching`);
|
|
1840
|
+
}
|
|
1841
|
+
else {
|
|
1842
|
+
into.require(inRoom === undefined, "team.member.listening.silent", `${here}.mode`, `${entry.leadId} is listening in silence, so the task's onCall does not carry them`);
|
|
1843
|
+
}
|
|
1815
1844
|
}
|
|
1816
1845
|
into.timestamp(entry.since, "team.member.listening.since", `${here}.since`);
|
|
1817
1846
|
});
|
|
@@ -1900,7 +1929,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1900
1929
|
return;
|
|
1901
1930
|
const here = `${path}.phone.channels[${index}]`;
|
|
1902
1931
|
const task = tasks.find(task => task.assignmentId === channel.assignmentId);
|
|
1903
|
-
if (!into.require(task !== undefined, "phone.channel.assignment", `${here}.assignmentId`, `${String(channel.assignmentId)} is not a task this
|
|
1932
|
+
if (!into.require(task !== undefined, "phone.channel.assignment", `${here}.assignmentId`, `${String(channel.assignmentId)} is not a task this session holds: a channel names the task its call is, or nothing`))
|
|
1904
1933
|
return;
|
|
1905
1934
|
const agrees = channel.state === "active" ? task.phase === "in-progress" && task.audio === "started"
|
|
1906
1935
|
: channel.state === "held" ? task.phase === "paused"
|
|
@@ -1915,9 +1944,9 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1915
1944
|
});
|
|
1916
1945
|
}
|
|
1917
1946
|
}
|
|
1918
|
-
if (into.filled(snapshot.
|
|
1919
|
-
&& context.
|
|
1920
|
-
into.require(snapshot.
|
|
1947
|
+
if (into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to")
|
|
1948
|
+
&& context.sessionId !== undefined) {
|
|
1949
|
+
into.require(snapshot.sessionId === context.sessionId, "snapshot.sessionId.mismatch", `${path}.sessionId`, `a snapshot for session ${describeValue(snapshot.sessionId)} while the current session is ${context.sessionId}`);
|
|
1921
1950
|
}
|
|
1922
1951
|
// The count is the provider's confirmation of how much work it answered with. Stated, never
|
|
1923
1952
|
// inferred: an unanswered or blank state lacks it, and cannot pass as a confirmed empty.
|
|
@@ -1955,7 +1984,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1955
1984
|
if (snapshot.contacts !== undefined) {
|
|
1956
1985
|
into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
|
|
1957
1986
|
if (Array.isArray(snapshot.contacts)) {
|
|
1958
|
-
snapshot.contacts
|
|
1987
|
+
validateContactEntriesInto(snapshot.contacts, `${path}.contacts`, into, levels);
|
|
1959
1988
|
}
|
|
1960
1989
|
else {
|
|
1961
1990
|
into.add("snapshot.contacts.shape", `${path}.contacts`, "contacts must be an array when present");
|
|
@@ -1981,7 +2010,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1981
2010
|
}
|
|
1982
2011
|
// The switch is the permission: once the application has said the team feature is on, a
|
|
1983
2012
|
// snapshot carries the team, `members: []` included. Before it has said, the provider assumes
|
|
1984
|
-
// nothing and owes nothing. The other direction -- a team member list to a
|
|
2013
|
+
// nothing and owes nothing. The other direction -- a team member list to a session that does not
|
|
1985
2014
|
// lead, or to a lead who turned the feature off -- is the team member list's own rule.
|
|
1986
2015
|
if (context.leadFeatures === true && snapshot.team === undefined) {
|
|
1987
2016
|
into.add("team.required", `${path}.team`, "the team feature is on, so every snapshot carries a team member list: members: [] when nobody is in it");
|
|
@@ -2076,9 +2105,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2076
2105
|
const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
|
|
2077
2106
|
const levels = context.levels ?? manifestLevels(manifest);
|
|
2078
2107
|
into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
|
|
2079
|
-
if (into.filled(envelope.
|
|
2080
|
-
&& context.
|
|
2081
|
-
into.require(envelope.
|
|
2108
|
+
if (into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to")
|
|
2109
|
+
&& context.sessionId !== undefined) {
|
|
2110
|
+
into.require(envelope.sessionId === context.sessionId, "event.sessionId.mismatch", `${path}.sessionId`, `an event for session ${describeValue(envelope.sessionId)} while the current session is ${context.sessionId}`);
|
|
2082
2111
|
}
|
|
2083
2112
|
const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
|
|
2084
2113
|
into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
|
|
@@ -2152,8 +2181,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2152
2181
|
}
|
|
2153
2182
|
if (event.assignmentId !== undefined)
|
|
2154
2183
|
into.require(isAssignmentId(event.assignmentId), "event.dialOutcome.assignmentId", `${at}.assignmentId`, "assignmentId must name an assignment when present");
|
|
2155
|
-
if (event.
|
|
2156
|
-
into.filled(event.
|
|
2184
|
+
if (event.contactId !== undefined)
|
|
2185
|
+
into.filled(event.contactId, "event.dialOutcome.contactId", `${at}.contactId`, "a contactId must not be empty when present");
|
|
2157
2186
|
if (event.reason !== undefined)
|
|
2158
2187
|
into.filled(event.reason, "event.dialOutcome.reason", `${at}.reason`, "a reason must not be empty when present");
|
|
2159
2188
|
break;
|
|
@@ -2181,7 +2210,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2181
2210
|
case "team-member-removed":
|
|
2182
2211
|
case "team-policies-updated": {
|
|
2183
2212
|
const field = event.type === "team-updated" ? "team" : event.type === "team-member-updated" ? "member" : event.type === "team-member-removed" ? "memberId" : "policies";
|
|
2184
|
-
into.require(context.capabilities === undefined || context.capabilities.lead
|
|
2213
|
+
into.require(context.capabilities === undefined || context.capabilities.lead !== undefined, "event.team.capability", `${at}.${field}`, `${event.type} reaches a user whose capabilities include lead, and nobody else`);
|
|
2185
2214
|
into.require(context.leadFeatures !== false, "event.team.features", `${at}.${field}`, "the team feature is not on for this lead: nothing of the team reaches them until the application switches it on, and nothing after it switches it off");
|
|
2186
2215
|
const teamContext = { ...context, levels, channel: isChannel(channel) ? channel : undefined };
|
|
2187
2216
|
if (event.type === "team-updated")
|
|
@@ -2203,7 +2232,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2203
2232
|
into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
|
|
2204
2233
|
}
|
|
2205
2234
|
else {
|
|
2206
|
-
event.contacts
|
|
2235
|
+
validateContactEntriesInto(event.contacts, `${at}.contacts`, into, levels);
|
|
2207
2236
|
}
|
|
2208
2237
|
break;
|
|
2209
2238
|
case "next-call":
|
|
@@ -2352,7 +2381,7 @@ function validatePhoneStateInto(value, path, context, into) {
|
|
|
2352
2381
|
return;
|
|
2353
2382
|
}
|
|
2354
2383
|
if (into.oneOf(value.phone, PHONES, "phone.phone", `${path}.phone`) && context.phone !== undefined) {
|
|
2355
|
-
into.require(value.phone === context.phone, "phone.phone.mismatch", `${path}.phone`, `the host chose a ${context.phone} for this
|
|
2384
|
+
into.require(value.phone === context.phone, "phone.phone.mismatch", `${path}.phone`, `the host chose a ${context.phone} for this session at connect and the platform reports a ${describeValue(value.phone)}: the phone state is the phone the agent hears this provider's calls on`);
|
|
2356
2385
|
}
|
|
2357
2386
|
into.oneOf(value.status, PHONE_STATUSES, "phone.status", `${path}.status`);
|
|
2358
2387
|
if (value.muted !== undefined) {
|
|
@@ -2486,7 +2515,7 @@ const HOST_GUARANTEES = membersOf({ browserUrlVisibility: true, personConsent: t
|
|
|
2486
2515
|
const MUTED_BY = membersOf({ host: true, station: true });
|
|
2487
2516
|
const HOST_MUTES = membersOf({ stream: true, station: true });
|
|
2488
2517
|
/**
|
|
2489
|
-
* What pressing Mute does on this host, stated on a softphone
|
|
2518
|
+
* What pressing Mute does on this host, stated on a softphone session and nowhere else: on an agent computer
|
|
2490
2519
|
* phone the microphone is the phone's, and off voice there is none. Neither the value nor its
|
|
2491
2520
|
* absence is inferred from what kind of application the host is.
|
|
2492
2521
|
*/
|
|
@@ -2500,24 +2529,24 @@ export function validateCapacity(capacity, path = "capacity") {
|
|
|
2500
2529
|
into.require(typeof capacity.count === "number" && Number.isInteger(capacity.count) && capacity.count >= 0, "capacity.count", `${path}.count`, "count is a whole number, zero or more: how many tasks this provider may assign at once, zero while the agent's capacity is elsewhere");
|
|
2501
2530
|
return into.violations;
|
|
2502
2531
|
}
|
|
2503
|
-
/** The
|
|
2504
|
-
export function
|
|
2532
|
+
/** The session's store, which the host provides on every connection: three functions, and nothing else is a store. */
|
|
2533
|
+
export function validateSessionStore(store, path = "store") {
|
|
2505
2534
|
const into = new Collector();
|
|
2506
2535
|
if (!isPlainObject(store)) {
|
|
2507
|
-
into.add("store.shape", path, "a connection carries the
|
|
2536
|
+
into.add("store.shape", path, "a connection carries the session's store: an object with get, set and delete");
|
|
2508
2537
|
return into.violations;
|
|
2509
2538
|
}
|
|
2510
2539
|
for (const method of ["get", "set", "delete"]) {
|
|
2511
|
-
into.require(typeof store[method] === "function", `store.${method}`, `${path}.${method}`, `a
|
|
2540
|
+
into.require(typeof store[method] === "function", `store.${method}`, `${path}.${method}`, `a session store ${method}s by key`);
|
|
2512
2541
|
}
|
|
2513
2542
|
return into.violations;
|
|
2514
2543
|
}
|
|
2515
2544
|
export function validateHostMute(mute, softphone, path = "host.mute") {
|
|
2516
2545
|
const into = new Collector();
|
|
2517
2546
|
if (mute === undefined) {
|
|
2518
|
-
into.require(!softphone, "host.mute.required", path, "a softphone
|
|
2547
|
+
into.require(!softphone, "host.mute.required", path, "a softphone session's host states what its Mute does: stream or station");
|
|
2519
2548
|
}
|
|
2520
|
-
else if (into.require(softphone, "host.mute.unexpected", path, "only a softphone
|
|
2549
|
+
else if (into.require(softphone, "host.mute.unexpected", path, "only a softphone session's host holds a microphone to mute; a hardphone's is the phone's, and a conversation has none")) {
|
|
2521
2550
|
into.oneOf(mute, HOST_MUTES, "host.mute", path);
|
|
2522
2551
|
}
|
|
2523
2552
|
return into.violations;
|
|
@@ -2532,14 +2561,14 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees", pho
|
|
|
2532
2561
|
into.add("host.guarantees.shape", path, "a host declares its guarantees as an object, empty when it makes none");
|
|
2533
2562
|
return into.violations;
|
|
2534
2563
|
}
|
|
2535
|
-
// The
|
|
2564
|
+
// The session's phone decides who holds the mute: a softphone host owns it and promises to keep it
|
|
2536
2565
|
// off the hold; a hardphone's is the handset's, and a host off voice has none.
|
|
2537
2566
|
if (phone !== undefined) {
|
|
2538
2567
|
if (phone === "softphone") {
|
|
2539
|
-
into.require(guarantees.muteUnavailableOnHold === true, "host.guarantee.muteUnavailableOnHold.required", `${path}.muteUnavailableOnHold`, "a softphone
|
|
2568
|
+
into.require(guarantees.muteUnavailableOnHold === true, "host.guarantee.muteUnavailableOnHold.required", `${path}.muteUnavailableOnHold`, "a softphone session's host holds the mute and promises it is unavailable while the task is paused");
|
|
2540
2569
|
}
|
|
2541
2570
|
else {
|
|
2542
|
-
into.require(guarantees.muteUnavailableOnHold === undefined, "host.guarantee.muteUnavailableOnHold.unexpected", `${path}.muteUnavailableOnHold`, `a ${describeValue(phone)}
|
|
2571
|
+
into.require(guarantees.muteUnavailableOnHold === undefined, "host.guarantee.muteUnavailableOnHold.unexpected", `${path}.muteUnavailableOnHold`, `a ${describeValue(phone)} session's host holds no mute to promise anything of`);
|
|
2543
2572
|
}
|
|
2544
2573
|
}
|
|
2545
2574
|
for (const [name, declared] of Object.entries(guarantees)) {
|
|
@@ -2668,7 +2697,6 @@ export function validateHostReport(report, path = "host") {
|
|
|
2668
2697
|
// Commands.
|
|
2669
2698
|
// ---------------------------------------------------------------------------
|
|
2670
2699
|
const LEAD_ASSIST_ACTIONS = ["request", "cancel"];
|
|
2671
|
-
const CONFERENCE_ACTIONS = ["add", "remove"];
|
|
2672
2700
|
/** Validate the exact interaction/assignment target before provider command dispatch. */
|
|
2673
2701
|
export function validateTaskCommandRequest(request, task, path, taskContext) {
|
|
2674
2702
|
const into = new Collector();
|
|
@@ -2721,9 +2749,11 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2721
2749
|
if (command.action === "request")
|
|
2722
2750
|
fields.push("note");
|
|
2723
2751
|
break;
|
|
2724
|
-
case "
|
|
2725
|
-
fields.push("
|
|
2726
|
-
|
|
2752
|
+
case "add-to-call":
|
|
2753
|
+
fields.push("dialId", "contactId", "number");
|
|
2754
|
+
break;
|
|
2755
|
+
case "remove-from-call":
|
|
2756
|
+
fields.push("contactId", "party");
|
|
2727
2757
|
break;
|
|
2728
2758
|
}
|
|
2729
2759
|
for (const key of Object.keys(command))
|
|
@@ -2747,19 +2777,22 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2747
2777
|
if (command.note !== undefined)
|
|
2748
2778
|
into.filled(command.note, "command.leadAssist.note", `${path}.note`, "a note must not be empty when present");
|
|
2749
2779
|
break;
|
|
2750
|
-
case "
|
|
2751
|
-
|
|
2752
|
-
|
|
2753
|
-
|
|
2754
|
-
|
|
2755
|
-
|
|
2756
|
-
|
|
2757
|
-
|
|
2758
|
-
const item = isFilled(command.destinationId);
|
|
2759
|
-
into.require(party !== item, "command.conference.remove.target", path, "a remove names one person: the party, or a conferenced entry by its destinationId, never both and never neither");
|
|
2760
|
-
}
|
|
2780
|
+
case "add-to-call":
|
|
2781
|
+
dial("command.addToCall.dialId");
|
|
2782
|
+
if (command.number === undefined) {
|
|
2783
|
+
into.filled(command.contactId, "command.addToCall.contactId", `${path}.contactId`, "an add names the contact it dials in, or the number typed");
|
|
2784
|
+
}
|
|
2785
|
+
else {
|
|
2786
|
+
into.filled(command.number, "command.addToCall.number", `${path}.number`, "a typed number must not be empty");
|
|
2787
|
+
into.require(command.contactId === undefined, "command.addToCall.number.both", path, "an add names a contact or a typed number, never both");
|
|
2761
2788
|
}
|
|
2762
2789
|
break;
|
|
2790
|
+
case "remove-from-call": {
|
|
2791
|
+
const party = command.party === true;
|
|
2792
|
+
const contact = isFilled(command.contactId);
|
|
2793
|
+
into.require(party !== contact, "command.removeFromCall.target", path, "a remove names one person: the party, or an added entry by its contactId, never both and never neither");
|
|
2794
|
+
break;
|
|
2795
|
+
}
|
|
2763
2796
|
case "recording":
|
|
2764
2797
|
into.violations.push(...validateRecordingCommandShape(command, "provider", path));
|
|
2765
2798
|
break;
|
|
@@ -2825,12 +2858,6 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2825
2858
|
// to act on yet, and in completing this agent's interaction has ended. The caller and other
|
|
2826
2859
|
// channels may continue elsewhere; this task's phase no longer permits these controls.
|
|
2827
2860
|
const interaction = () => inPhase("command.phase.interaction", "in-progress", "paused");
|
|
2828
|
-
// A destination is one the directory offered: the id Omni sends is the id the provider published.
|
|
2829
|
-
const listed = (name) => {
|
|
2830
|
-
const declared = capabilities[name];
|
|
2831
|
-
const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
|
|
2832
|
-
into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${describeValue(command.destinationId)} is not a destination the task's ${name} directory offered`);
|
|
2833
|
-
};
|
|
2834
2861
|
const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
|
|
2835
2862
|
switch (type) {
|
|
2836
2863
|
case "answer":
|
|
@@ -2889,19 +2916,27 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2889
2916
|
into.require(isPlainObject(task.leadAssist) && task.leadAssist.stage === "requested", "command.leadAssist.requested", path, "cancel needs a request standing: leadAssist with stage requested");
|
|
2890
2917
|
}
|
|
2891
2918
|
break;
|
|
2892
|
-
case "
|
|
2919
|
+
case "add-to-call":
|
|
2920
|
+
case "remove-from-call": {
|
|
2893
2921
|
interaction();
|
|
2894
|
-
const
|
|
2895
|
-
if (
|
|
2896
|
-
|
|
2897
|
-
|
|
2922
|
+
const adding = offered("addToCall");
|
|
2923
|
+
if (adding && type === "add-to-call" && command.contactId !== undefined) {
|
|
2924
|
+
const declared = capabilities.addToCall;
|
|
2925
|
+
const narrowed = isPlainObject(declared) && Array.isArray(declared.contactIds) ? declared.contactIds : undefined;
|
|
2926
|
+
into.require(narrowed === undefined || narrowed.includes(command.contactId), "command.addToCall.contactId.unlisted", `${path}.contactId`, `${describeValue(command.contactId)} is not among the contacts this task offers to add`);
|
|
2927
|
+
}
|
|
2928
|
+
if (adding && type === "add-to-call" && command.number !== undefined) {
|
|
2929
|
+
const declared = capabilities.addToCall;
|
|
2930
|
+
into.require(isPlainObject(declared) && declared.destinations === "any-number", "command.addToCall.number.contactsOnly", `${path}.number`, "this task adds contacts only: a typed number needs any-number");
|
|
2931
|
+
}
|
|
2932
|
+
if (adding && type === "remove-from-call") {
|
|
2898
2933
|
const others = onCall.filter(entry => entry.role !== "agent");
|
|
2899
2934
|
if (command.party === true) {
|
|
2900
|
-
into.require(others.some(entry => entry.role !== "party"), "command.
|
|
2935
|
+
into.require(others.some(entry => entry.role !== "party"), "command.removeFromCall.alone", path, "removing the party would leave the agent alone: that is end-call");
|
|
2901
2936
|
}
|
|
2902
|
-
else if (isFilled(command.
|
|
2903
|
-
into.require(onCall.some(entry => entry.role === "
|
|
2904
|
-
into.require(others.length > 1, "command.
|
|
2937
|
+
else if (isFilled(command.contactId)) {
|
|
2938
|
+
into.require(onCall.some(entry => entry.role === "added" && entry.contactId === command.contactId), "command.removeFromCall.unknown", path, `no added entry on onCall has contactId ${describeValue(command.contactId)}`);
|
|
2939
|
+
into.require(others.length > 1, "command.removeFromCall.alone", path, "removing the last other person would leave the agent alone: that is end-call");
|
|
2905
2940
|
}
|
|
2906
2941
|
}
|
|
2907
2942
|
break;
|
|
@@ -3080,7 +3115,7 @@ function validateUser(value, rule, path, into) {
|
|
|
3080
3115
|
}
|
|
3081
3116
|
function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
3082
3117
|
if (!isPlainObject(value)) {
|
|
3083
|
-
into.add("authentication.capabilities.shape", path, "a usable
|
|
3118
|
+
into.add("authentication.capabilities.shape", path, "a usable state declares the user's capabilities: an object, {} when there are none");
|
|
3084
3119
|
return;
|
|
3085
3120
|
}
|
|
3086
3121
|
for (const [name, declared] of Object.entries(value)) {
|
|
@@ -3088,9 +3123,13 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
|
3088
3123
|
continue;
|
|
3089
3124
|
if (!into.require(SESSION_CAPABILITIES.includes(name), "authentication.capability.unknown", `${path}.${name}`, `unsupported session capability: ${name}`))
|
|
3090
3125
|
continue;
|
|
3126
|
+
if (name === "lead") {
|
|
3127
|
+
validateLeadCapabilitiesInto(declared, `${path}.lead`, into);
|
|
3128
|
+
continue;
|
|
3129
|
+
}
|
|
3091
3130
|
if (name === "preferences") {
|
|
3092
3131
|
if (Array.isArray(declared) && declared.length === 0) {
|
|
3093
|
-
into.add("authentication.capability.preferences.empty", `${path}.preferences`, "a
|
|
3132
|
+
into.add("authentication.capability.preferences.empty", `${path}.preferences`, "a user with nothing left to them omits preferences rather than declaring an empty list");
|
|
3094
3133
|
}
|
|
3095
3134
|
validatePreferencesInto(declared, `${path}.preferences`, into, levels);
|
|
3096
3135
|
continue;
|
|
@@ -3098,6 +3137,20 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
|
3098
3137
|
into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
|
|
3099
3138
|
}
|
|
3100
3139
|
}
|
|
3140
|
+
/** A lead's capabilities: an object of the lead commands it allows, each by presence, at least one. */
|
|
3141
|
+
function validateLeadCapabilitiesInto(value, path, into) {
|
|
3142
|
+
if (!isPlainObject(value)) {
|
|
3143
|
+
into.add("authentication.capability.lead.shape", path, "lead states the lead capabilities this session holds: an object such as { listen: true, coach: true }");
|
|
3144
|
+
return;
|
|
3145
|
+
}
|
|
3146
|
+
const granted = Object.entries(value).filter(([, declared]) => declared !== undefined);
|
|
3147
|
+
into.require(granted.length > 0, "authentication.capability.lead.empty", path, "a lead holds at least one lead capability; a session with none omits lead");
|
|
3148
|
+
for (const [name, declared] of granted) {
|
|
3149
|
+
if (!into.require(LEAD_CAPABILITY_NAMES.includes(name), "authentication.capability.lead.unknown", `${path}.${name}`, `unsupported lead capability: ${name}`))
|
|
3150
|
+
continue;
|
|
3151
|
+
into.require(declared === true, "authentication.capability.lead.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
|
|
3152
|
+
}
|
|
3153
|
+
}
|
|
3101
3154
|
/**
|
|
3102
3155
|
* A failure an authentication reports: on a `rejected` start or completion, or on an `expired`
|
|
3103
3156
|
* state. A provider names its own codes freely; an `omni.` code is the contract's and has to be one
|
|
@@ -3192,8 +3245,8 @@ function validateAuthenticationChallenge(value, path, into) {
|
|
|
3192
3245
|
}
|
|
3193
3246
|
}
|
|
3194
3247
|
/**
|
|
3195
|
-
* What `start()` or `complete()` answered: a challenge or a rejection from `start`, a
|
|
3196
|
-
* rejection from `complete`. A rejection carries a failure the host can show, and a
|
|
3248
|
+
* What `start()` or `complete()` answered: a challenge or a rejection from `start`, a session or a
|
|
3249
|
+
* rejection from `complete`. A rejection carries a failure the host can show, and a session is held
|
|
3197
3250
|
* to the same rules as any `authenticated` state.
|
|
3198
3251
|
*/
|
|
3199
3252
|
export function validateAuthenticationResult(result, method, path, context) {
|