@xema/omni-protocol 0.1.128 → 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 +144 -113
- package/dist/index.js +24 -23
- package/dist/testing.d.ts +15 -15
- package/dist/testing.js +89 -88
- package/dist/validation.d.ts +40 -35
- package/dist/validation.js +211 -153
- package/guide/agent.md +24 -24
- package/guide/breaks.md +1 -1
- package/guide/lead.md +34 -17
- package/guide/phone.md +22 -22
- package/guide/queue.md +9 -8
- package/guide/voice.md +64 -54
- package/guide.md +187 -163
- 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,
|
|
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 }),
|
|
@@ -217,9 +218,9 @@ function validateAttributes(value, path, into) {
|
|
|
217
218
|
});
|
|
218
219
|
}
|
|
219
220
|
/** Every field is optional, so this checks what is present rather than what is missing. */
|
|
220
|
-
export function validateContact(contact, path = "contact") {
|
|
221
|
+
export function validateContact(contact, levels, path = "contact") {
|
|
221
222
|
const into = new Collector();
|
|
222
|
-
validateContactInto(contact, path, into);
|
|
223
|
+
validateContactInto(contact, path, into, levels);
|
|
223
224
|
return into.violations;
|
|
224
225
|
}
|
|
225
226
|
function validateContactInto(contact, path, into, levels) {
|
|
@@ -238,9 +239,9 @@ function validateContactInto(contact, path, into, levels) {
|
|
|
238
239
|
}
|
|
239
240
|
validateAttributes(contact.attributes, `${path}.attributes`, into);
|
|
240
241
|
}
|
|
241
|
-
export function validateScheduledActivity(activity, path = "scheduledActivity") {
|
|
242
|
+
export function validateScheduledActivity(activity, levels, path = "scheduledActivity") {
|
|
242
243
|
const into = new Collector();
|
|
243
|
-
validateScheduledActivityInto(activity, path, into);
|
|
244
|
+
validateScheduledActivityInto(activity, path, into, levels);
|
|
244
245
|
return into.violations;
|
|
245
246
|
}
|
|
246
247
|
function validateScheduledActivityInto(activity, path, into, levels) {
|
|
@@ -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") {
|
|
@@ -528,9 +529,12 @@ export function validateManifest(manifest, path = "manifest") {
|
|
|
528
529
|
into.require(!Object.hasOwn(manifest, former), "manifest.settleMs.renamed", `${path}.${former}`, "use settleMs; the former field is not accepted");
|
|
529
530
|
}
|
|
530
531
|
into.require(typeof manifest.settleMs === "number" && Number.isInteger(manifest.settleMs) && manifest.settleMs > 0, "manifest.settleMs", `${path}.settleMs`, "settleMs is how long after applied the wire shows what the provider did -- the task-ended after a complete, the calendar-updated after a schedule -- a positive whole number of milliseconds, stated by every provider");
|
|
531
|
-
if (manifest.orgLevels
|
|
532
|
+
if (manifest.orgLevels === undefined) {
|
|
533
|
+
into.add("manifest.orgLevels.required", `${path}.orgLevels`, "orgLevels is required: the organisation's whole ladder, person included, each level labelled in the languages its agents read");
|
|
534
|
+
}
|
|
535
|
+
else {
|
|
532
536
|
if (!Array.isArray(manifest.orgLevels)) {
|
|
533
|
-
into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array
|
|
537
|
+
into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array");
|
|
534
538
|
}
|
|
535
539
|
else {
|
|
536
540
|
const ids = new Set();
|
|
@@ -551,7 +555,9 @@ export function validateManifest(manifest, path = "manifest") {
|
|
|
551
555
|
}
|
|
552
556
|
else
|
|
553
557
|
wellFormed = false;
|
|
554
|
-
|
|
558
|
+
const before = into.violations.length;
|
|
559
|
+
validateLocalizedText(level.label, "manifest.orgLevel.label", `${at}.label`, into);
|
|
560
|
+
if (into.violations.length !== before)
|
|
555
561
|
wellFormed = false;
|
|
556
562
|
});
|
|
557
563
|
if (wellFormed && !ids.has("person")) {
|
|
@@ -652,32 +658,38 @@ function validateLocalizedText(value, rule, path, into) {
|
|
|
652
658
|
// ---------------------------------------------------------------------------
|
|
653
659
|
// Task.
|
|
654
660
|
// ---------------------------------------------------------------------------
|
|
655
|
-
function
|
|
661
|
+
function validateAddToCallCapability(value, path, into) {
|
|
656
662
|
if (!isPlainObject(value)) {
|
|
657
|
-
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\" }");
|
|
658
664
|
return;
|
|
659
665
|
}
|
|
660
|
-
|
|
661
|
-
|
|
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");
|
|
662
671
|
return;
|
|
663
|
-
}
|
|
664
|
-
// Nothing is typed, so a directory with nothing in it is a control with nothing to offer.
|
|
665
|
-
if (value.destinations.length === 0) {
|
|
666
|
-
into.add("task.destinations.offer", path, "a directory offers at least one item; with none, omit the capability");
|
|
667
672
|
}
|
|
668
673
|
const seen = new Set();
|
|
669
|
-
value.
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
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);
|
|
674
678
|
}
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
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);
|
|
679
692
|
}
|
|
680
|
-
into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
|
|
681
693
|
});
|
|
682
694
|
}
|
|
683
695
|
function validateOutcomes(value, path, into) {
|
|
@@ -766,15 +778,12 @@ function validateCustomCapabilities(value, path, into) {
|
|
|
766
778
|
}
|
|
767
779
|
});
|
|
768
780
|
}
|
|
769
|
-
const DEFAULT_LEVEL_IDS = DEFAULT_LEVELS.map(level => level.id);
|
|
770
781
|
const POLICY_SETTINGS = membersOf({ on: true, off: true, person: true });
|
|
771
782
|
const POLICY_KEYS = new Set([
|
|
772
783
|
...TASK_CAPABILITIES.voice, ...TASK_CAPABILITIES.chat, ...TASK_CAPABILITIES.email, "dial",
|
|
773
784
|
].filter(name => name !== "browsers" && name !== "outcomes" && name !== "custom"));
|
|
774
785
|
const PERSON_SETTABLE = /^(hold|skill:.+)$/;
|
|
775
786
|
const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
|
|
776
|
-
/** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
|
|
777
|
-
const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
|
|
778
787
|
/**
|
|
779
788
|
* What the queue locks is locked on the whole task. Given the locked values, every other field an
|
|
780
789
|
* agent reads -- the title, the reference, an attribute, a custom control's label, a browser URL the
|
|
@@ -827,7 +836,7 @@ function validateLockedByInto(value, rule, path, levels, into) {
|
|
|
827
836
|
if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
|
|
828
837
|
return;
|
|
829
838
|
into.require(value !== "person", `${rule}.person`, path, "a person never locks their own value");
|
|
830
|
-
into.require(
|
|
839
|
+
into.require(levels.includes(value), `${rule}.unknown`, path, `${describeValue(value)} is not a level this manifest declares: ${inForce(levels)}`);
|
|
831
840
|
}
|
|
832
841
|
/** `{ lockedBy, reason? }` standing in for a value: who locked it, and a reason if given. */
|
|
833
842
|
function validateLockedInto(value, rule, path, levels, into) {
|
|
@@ -838,7 +847,7 @@ function validateLockedInto(value, rule, path, levels, into) {
|
|
|
838
847
|
/** What every resolved value carries: who set it, and who locked it if anyone. */
|
|
839
848
|
function validateResolvedInto(value, rule, path, levels, into) {
|
|
840
849
|
if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a level, or provider")) {
|
|
841
|
-
into.require(value.setBy === "provider" ||
|
|
850
|
+
into.require(value.setBy === "provider" || levels.includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${describeValue(value.setBy)} is neither provider nor a level this manifest declares: ${inForce(levels)}`);
|
|
842
851
|
}
|
|
843
852
|
if (value.lockedBy !== undefined)
|
|
844
853
|
validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, levels, into);
|
|
@@ -847,14 +856,22 @@ function validateResolvedInto(value, rule, path, levels, into) {
|
|
|
847
856
|
into.require(value.lockedBy !== undefined, `${rule}.reason.unexpected`, `${path}.reason`, "a reason goes with lockedBy: it says why it was locked");
|
|
848
857
|
}
|
|
849
858
|
}
|
|
850
|
-
/**
|
|
859
|
+
/** A command context's `levels`, the manifest's level ids the session is validated against. */
|
|
860
|
+
function contextLevels(context, rule, path, into) {
|
|
861
|
+
const levels = context.levels;
|
|
862
|
+
if (Array.isArray(levels) && levels.every(level => typeof level === "string"))
|
|
863
|
+
return levels;
|
|
864
|
+
into.add(rule, `${path}.levels`, "the context carries levels, the ids of the manifest's orgLevels, to validate the session against");
|
|
865
|
+
return [];
|
|
866
|
+
}
|
|
867
|
+
const inForce = (levels) => levels.length === 0 ? "it declares no ladder" : `in force are ${levels.join(", ")}`;
|
|
868
|
+
/** The level ids a manifest declares, for validators that receive one. A manifest without a ladder declares none, and every level is refused. */
|
|
851
869
|
function manifestLevels(manifest) {
|
|
852
|
-
if (!isPlainObject(manifest))
|
|
853
|
-
return
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
return effectiveLevels(declared).map(level => level.id);
|
|
870
|
+
if (!isPlainObject(manifest) || !Array.isArray(manifest.orgLevels))
|
|
871
|
+
return [];
|
|
872
|
+
return manifest.orgLevels
|
|
873
|
+
.filter((level) => isPlainObject(level) && typeof level.id === "string")
|
|
874
|
+
.map(level => level.id);
|
|
858
875
|
}
|
|
859
876
|
const CUSTOM_RENDERS = membersOf({ inline: true, page: true });
|
|
860
877
|
const CREDENTIAL_FIELD_TYPES = membersOf({ text: true, password: true });
|
|
@@ -1016,7 +1033,7 @@ function validateHistory(value, path, into, task = {}) {
|
|
|
1016
1033
|
// muted leg is a record that dropped a fact it held rather than one it could not establish.
|
|
1017
1034
|
if (entry.step === "muted") {
|
|
1018
1035
|
into.oneOf(entry.mutedBy, MUTED_BY, "task.history.mutedBy", `${at}.mutedBy`);
|
|
1019
|
-
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");
|
|
1020
1037
|
}
|
|
1021
1038
|
else if (HISTORY_STEPS.includes(entry.step)) {
|
|
1022
1039
|
into.require(entry.mutedBy === undefined, "task.history.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
|
|
@@ -1028,11 +1045,11 @@ function validateHistory(value, path, into, task = {}) {
|
|
|
1028
1045
|
}
|
|
1029
1046
|
// A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
|
|
1030
1047
|
const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);
|
|
1031
|
-
for (const field of ["dialId", "
|
|
1048
|
+
for (const field of ["dialId", "contactId"]) {
|
|
1032
1049
|
if (entry[field] === undefined)
|
|
1033
1050
|
continue;
|
|
1034
1051
|
if (into.filled(entry[field], `task.history.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
|
|
1035
|
-
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`);
|
|
1036
1053
|
}
|
|
1037
1054
|
}
|
|
1038
1055
|
});
|
|
@@ -1061,7 +1078,7 @@ const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
|
|
|
1061
1078
|
/**
|
|
1062
1079
|
* Who is on the call, as the provider states it. Voice only. Each entry is a role with what that
|
|
1063
1080
|
* role needs and nothing another role would: a party or an agent dialled nowhere, so neither
|
|
1064
|
-
* carries a destination; somebody
|
|
1081
|
+
* carries a destination; somebody added came from one, so they do.
|
|
1065
1082
|
*/
|
|
1066
1083
|
function validateOnCall(value, channel, path, into) {
|
|
1067
1084
|
if (value === undefined)
|
|
@@ -1088,14 +1105,18 @@ function validateOnCall(value, channel, path, into) {
|
|
|
1088
1105
|
}
|
|
1089
1106
|
if (role === "party")
|
|
1090
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
|
+
}
|
|
1091
1112
|
if (role === "agent") {
|
|
1092
1113
|
into.require(isUserId(entry.userId), "task.onCall.userId", `${at}.userId`, "an agent on the call is named by their user id");
|
|
1093
1114
|
}
|
|
1094
1115
|
else {
|
|
1095
1116
|
into.require(entry.userId === undefined, "task.onCall.userId.unexpected", `${at}.userId`, `a ${role} is not named by a user id`);
|
|
1096
1117
|
}
|
|
1097
|
-
if (role === "
|
|
1098
|
-
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`);
|
|
1099
1120
|
// Stated, so a snapshot says who is present without anyone having seen the dial's outcome.
|
|
1100
1121
|
if (into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
|
|
1101
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");
|
|
@@ -1115,13 +1136,13 @@ function validateOnCall(value, channel, path, into) {
|
|
|
1115
1136
|
if (entry.stage !== undefined && into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
|
|
1116
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");
|
|
1117
1138
|
}
|
|
1118
|
-
for (const field of ["
|
|
1119
|
-
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`);
|
|
1120
1141
|
}
|
|
1121
1142
|
}
|
|
1122
1143
|
else {
|
|
1123
|
-
for (const field of ["
|
|
1124
|
-
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`);
|
|
1125
1146
|
}
|
|
1126
1147
|
}
|
|
1127
1148
|
});
|
|
@@ -1376,8 +1397,8 @@ function validateTaskInto(task, context, path, into) {
|
|
|
1376
1397
|
case "custom":
|
|
1377
1398
|
validateCustomCapabilities(declared, `${path}.capabilities.custom`, into);
|
|
1378
1399
|
break;
|
|
1379
|
-
case "
|
|
1380
|
-
|
|
1400
|
+
case "addToCall":
|
|
1401
|
+
validateAddToCallCapability(declared, `${path}.capabilities.${name}`, into);
|
|
1381
1402
|
break;
|
|
1382
1403
|
default:
|
|
1383
1404
|
// Presence is the permission: the flag capabilities carry no payload, so anything but
|
|
@@ -1434,7 +1455,7 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
|
|
|
1434
1455
|
/**
|
|
1435
1456
|
* Checks a lead command before dispatch, against the current authentication, transport and team
|
|
1436
1457
|
* member list (`team`) and, for force-break and end-forced-break, the target's full `memberBreak`.
|
|
1437
|
-
* 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
|
|
1438
1459
|
* atomically, since a team member list is not authority to act after it has changed.
|
|
1439
1460
|
*/
|
|
1440
1461
|
export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
@@ -1444,10 +1465,11 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1444
1465
|
return into.violations;
|
|
1445
1466
|
}
|
|
1446
1467
|
const auth = isPlainObject(context.authentication) ? context.authentication : {};
|
|
1447
|
-
into.violations.push(...validateAuthenticationState(auth, `${path}.authentication
|
|
1468
|
+
into.violations.push(...validateAuthenticationState(auth, `${path}.authentication`, { levels: contextLevels(context, "team.command.levels", path, into) }));
|
|
1448
1469
|
const caps = isPlainObject(auth.capabilities) ? auth.capabilities : {};
|
|
1449
|
-
into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.command.connection", path, "lead commands require a live
|
|
1450
|
-
|
|
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");
|
|
1451
1473
|
const command = request.command;
|
|
1452
1474
|
const member = ["type", "memberId", "assignmentId"];
|
|
1453
1475
|
const allowed = {
|
|
@@ -1462,6 +1484,12 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1462
1484
|
into.add("team.command.type", path, `unknown lead command: ${describeValue(command.type)}`);
|
|
1463
1485
|
return into.violations;
|
|
1464
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
|
+
}
|
|
1465
1493
|
for (const key of Object.keys(request))
|
|
1466
1494
|
into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
|
|
1467
1495
|
for (const key of Object.keys(command))
|
|
@@ -1538,10 +1566,10 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1538
1566
|
into.add("break.command.context", path, "current authentication and transport are required");
|
|
1539
1567
|
return into.violations;
|
|
1540
1568
|
}
|
|
1541
|
-
into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication
|
|
1569
|
+
into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication`, { levels: contextLevels(context, "break.command.levels", path, into) }));
|
|
1542
1570
|
const auth = isPlainObject(context.authentication) ? context.authentication : {};
|
|
1543
|
-
into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated
|
|
1544
|
-
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");
|
|
1545
1573
|
into.require(context.transport === "active", "break.command.transport", path, "break commands require active transport");
|
|
1546
1574
|
if (!["requestBreak", "commitBreak", "cancelBreak", "endBreak"].includes(method)) {
|
|
1547
1575
|
into.add("break.command.method", path, "unknown break method");
|
|
@@ -1583,7 +1611,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1583
1611
|
return into.violations;
|
|
1584
1612
|
}
|
|
1585
1613
|
/**
|
|
1586
|
-
* Checks two complete break states within one provider/
|
|
1614
|
+
* Checks two complete break states within one provider/session's ordered event stream.
|
|
1587
1615
|
* Call before replacing accepted state; report violations and reconcile on failure.
|
|
1588
1616
|
* This is not a freshness check: validate a fresh authoritative snapshot separately and
|
|
1589
1617
|
* use it as a new baseline, never as an event transition. Source ordering and connection
|
|
@@ -1686,7 +1714,7 @@ function validateBreakState(value, path, into) {
|
|
|
1686
1714
|
into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.status)} on a provider that publishes reasons names the one it is on`);
|
|
1687
1715
|
}
|
|
1688
1716
|
}
|
|
1689
|
-
export function validateTeamMembers(teamMembers, path
|
|
1717
|
+
export function validateTeamMembers(teamMembers, path, context) {
|
|
1690
1718
|
const into = new Collector();
|
|
1691
1719
|
validateTeamMembersInto(teamMembers, path, context, into);
|
|
1692
1720
|
return into.violations;
|
|
@@ -1696,10 +1724,10 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
|
|
|
1696
1724
|
into.add("team.shape", path, "a team member list must be an object");
|
|
1697
1725
|
return;
|
|
1698
1726
|
}
|
|
1699
|
-
// The
|
|
1700
|
-
// and nobody else. Only a caller holding the
|
|
1701
|
-
if (context.capabilities !== undefined && context.capabilities.lead
|
|
1702
|
-
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");
|
|
1703
1731
|
}
|
|
1704
1732
|
// Policies are present where the provider offers policy control, absent where it does not.
|
|
1705
1733
|
if (teamMembers.policies !== undefined)
|
|
@@ -1733,7 +1761,7 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
|
|
|
1733
1761
|
}
|
|
1734
1762
|
}
|
|
1735
1763
|
/** One member as the lead sees them, whole: on the list, and on `team-member-updated` alone. */
|
|
1736
|
-
export function validateTeamMember(member, path
|
|
1764
|
+
export function validateTeamMember(member, path, context) {
|
|
1737
1765
|
const into = new Collector();
|
|
1738
1766
|
validateTeamMemberInto(member, path, context, into);
|
|
1739
1767
|
return into.violations;
|
|
@@ -1798,10 +1826,21 @@ function validateTeamMemberInto(member, at, context, into) {
|
|
|
1798
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)) {
|
|
1799
1827
|
into.require(task !== undefined, "team.member.listening.assignment", `${here}.assignmentId`, "the call the lead is on is one the member's tasks carry");
|
|
1800
1828
|
}
|
|
1801
|
-
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`)
|
|
1802
1830
|
&& isPlainObject(task) && Array.isArray(task.onCall) && isUserId(entry.leadId)) {
|
|
1803
|
-
// A lead who is heard is in the room the member sees
|
|
1804
|
-
|
|
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
|
+
}
|
|
1805
1844
|
}
|
|
1806
1845
|
into.timestamp(entry.since, "team.member.listening.since", `${here}.since`);
|
|
1807
1846
|
});
|
|
@@ -1890,7 +1929,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1890
1929
|
return;
|
|
1891
1930
|
const here = `${path}.phone.channels[${index}]`;
|
|
1892
1931
|
const task = tasks.find(task => task.assignmentId === channel.assignmentId);
|
|
1893
|
-
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`))
|
|
1894
1933
|
return;
|
|
1895
1934
|
const agrees = channel.state === "active" ? task.phase === "in-progress" && task.audio === "started"
|
|
1896
1935
|
: channel.state === "held" ? task.phase === "paused"
|
|
@@ -1905,9 +1944,9 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1905
1944
|
});
|
|
1906
1945
|
}
|
|
1907
1946
|
}
|
|
1908
|
-
if (into.filled(snapshot.
|
|
1909
|
-
&& context.
|
|
1910
|
-
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}`);
|
|
1911
1950
|
}
|
|
1912
1951
|
// The count is the provider's confirmation of how much work it answered with. Stated, never
|
|
1913
1952
|
// inferred: an unanswered or blank state lacks it, and cannot pass as a confirmed empty.
|
|
@@ -1945,7 +1984,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1945
1984
|
if (snapshot.contacts !== undefined) {
|
|
1946
1985
|
into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
|
|
1947
1986
|
if (Array.isArray(snapshot.contacts)) {
|
|
1948
|
-
snapshot.contacts
|
|
1987
|
+
validateContactEntriesInto(snapshot.contacts, `${path}.contacts`, into, levels);
|
|
1949
1988
|
}
|
|
1950
1989
|
else {
|
|
1951
1990
|
into.add("snapshot.contacts.shape", `${path}.contacts`, "contacts must be an array when present");
|
|
@@ -1971,7 +2010,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
|
|
|
1971
2010
|
}
|
|
1972
2011
|
// The switch is the permission: once the application has said the team feature is on, a
|
|
1973
2012
|
// snapshot carries the team, `members: []` included. Before it has said, the provider assumes
|
|
1974
|
-
// 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
|
|
1975
2014
|
// lead, or to a lead who turned the feature off -- is the team member list's own rule.
|
|
1976
2015
|
if (context.leadFeatures === true && snapshot.team === undefined) {
|
|
1977
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");
|
|
@@ -2066,9 +2105,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2066
2105
|
const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
|
|
2067
2106
|
const levels = context.levels ?? manifestLevels(manifest);
|
|
2068
2107
|
into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
|
|
2069
|
-
if (into.filled(envelope.
|
|
2070
|
-
&& context.
|
|
2071
|
-
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}`);
|
|
2072
2111
|
}
|
|
2073
2112
|
const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
|
|
2074
2113
|
into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
|
|
@@ -2142,8 +2181,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2142
2181
|
}
|
|
2143
2182
|
if (event.assignmentId !== undefined)
|
|
2144
2183
|
into.require(isAssignmentId(event.assignmentId), "event.dialOutcome.assignmentId", `${at}.assignmentId`, "assignmentId must name an assignment when present");
|
|
2145
|
-
if (event.
|
|
2146
|
-
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");
|
|
2147
2186
|
if (event.reason !== undefined)
|
|
2148
2187
|
into.filled(event.reason, "event.dialOutcome.reason", `${at}.reason`, "a reason must not be empty when present");
|
|
2149
2188
|
break;
|
|
@@ -2171,7 +2210,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2171
2210
|
case "team-member-removed":
|
|
2172
2211
|
case "team-policies-updated": {
|
|
2173
2212
|
const field = event.type === "team-updated" ? "team" : event.type === "team-member-updated" ? "member" : event.type === "team-member-removed" ? "memberId" : "policies";
|
|
2174
|
-
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`);
|
|
2175
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");
|
|
2176
2215
|
const teamContext = { ...context, levels, channel: isChannel(channel) ? channel : undefined };
|
|
2177
2216
|
if (event.type === "team-updated")
|
|
@@ -2193,7 +2232,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
|
|
|
2193
2232
|
into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
|
|
2194
2233
|
}
|
|
2195
2234
|
else {
|
|
2196
|
-
event.contacts
|
|
2235
|
+
validateContactEntriesInto(event.contacts, `${at}.contacts`, into, levels);
|
|
2197
2236
|
}
|
|
2198
2237
|
break;
|
|
2199
2238
|
case "next-call":
|
|
@@ -2308,7 +2347,7 @@ function validateNextCallInto(value, path, into) {
|
|
|
2308
2347
|
into.require(key === "since", "nextCall.field", `${path}.${key}`, "unsupported field on the ask");
|
|
2309
2348
|
}
|
|
2310
2349
|
/** A call waiting in the agent's own queue: the caller as shown to this audience, the queue, the waits, and whether the agent may let it go. */
|
|
2311
|
-
export function validateLinedUp(value, path = "linedUp"
|
|
2350
|
+
export function validateLinedUp(value, levels, path = "linedUp") {
|
|
2312
2351
|
const into = new Collector();
|
|
2313
2352
|
validateLinedUpInto(value, path, into, levels);
|
|
2314
2353
|
return into.violations;
|
|
@@ -2342,7 +2381,7 @@ function validatePhoneStateInto(value, path, context, into) {
|
|
|
2342
2381
|
return;
|
|
2343
2382
|
}
|
|
2344
2383
|
if (into.oneOf(value.phone, PHONES, "phone.phone", `${path}.phone`) && context.phone !== undefined) {
|
|
2345
|
-
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`);
|
|
2346
2385
|
}
|
|
2347
2386
|
into.oneOf(value.status, PHONE_STATUSES, "phone.status", `${path}.status`);
|
|
2348
2387
|
if (value.muted !== undefined) {
|
|
@@ -2476,7 +2515,7 @@ const HOST_GUARANTEES = membersOf({ browserUrlVisibility: true, personConsent: t
|
|
|
2476
2515
|
const MUTED_BY = membersOf({ host: true, station: true });
|
|
2477
2516
|
const HOST_MUTES = membersOf({ stream: true, station: true });
|
|
2478
2517
|
/**
|
|
2479
|
-
* 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
|
|
2480
2519
|
* phone the microphone is the phone's, and off voice there is none. Neither the value nor its
|
|
2481
2520
|
* absence is inferred from what kind of application the host is.
|
|
2482
2521
|
*/
|
|
@@ -2490,24 +2529,24 @@ export function validateCapacity(capacity, path = "capacity") {
|
|
|
2490
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");
|
|
2491
2530
|
return into.violations;
|
|
2492
2531
|
}
|
|
2493
|
-
/** The
|
|
2494
|
-
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") {
|
|
2495
2534
|
const into = new Collector();
|
|
2496
2535
|
if (!isPlainObject(store)) {
|
|
2497
|
-
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");
|
|
2498
2537
|
return into.violations;
|
|
2499
2538
|
}
|
|
2500
2539
|
for (const method of ["get", "set", "delete"]) {
|
|
2501
|
-
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`);
|
|
2502
2541
|
}
|
|
2503
2542
|
return into.violations;
|
|
2504
2543
|
}
|
|
2505
2544
|
export function validateHostMute(mute, softphone, path = "host.mute") {
|
|
2506
2545
|
const into = new Collector();
|
|
2507
2546
|
if (mute === undefined) {
|
|
2508
|
-
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");
|
|
2509
2548
|
}
|
|
2510
|
-
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")) {
|
|
2511
2550
|
into.oneOf(mute, HOST_MUTES, "host.mute", path);
|
|
2512
2551
|
}
|
|
2513
2552
|
return into.violations;
|
|
@@ -2522,14 +2561,14 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees", pho
|
|
|
2522
2561
|
into.add("host.guarantees.shape", path, "a host declares its guarantees as an object, empty when it makes none");
|
|
2523
2562
|
return into.violations;
|
|
2524
2563
|
}
|
|
2525
|
-
// The
|
|
2564
|
+
// The session's phone decides who holds the mute: a softphone host owns it and promises to keep it
|
|
2526
2565
|
// off the hold; a hardphone's is the handset's, and a host off voice has none.
|
|
2527
2566
|
if (phone !== undefined) {
|
|
2528
2567
|
if (phone === "softphone") {
|
|
2529
|
-
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");
|
|
2530
2569
|
}
|
|
2531
2570
|
else {
|
|
2532
|
-
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`);
|
|
2533
2572
|
}
|
|
2534
2573
|
}
|
|
2535
2574
|
for (const [name, declared] of Object.entries(guarantees)) {
|
|
@@ -2658,9 +2697,8 @@ export function validateHostReport(report, path = "host") {
|
|
|
2658
2697
|
// Commands.
|
|
2659
2698
|
// ---------------------------------------------------------------------------
|
|
2660
2699
|
const LEAD_ASSIST_ACTIONS = ["request", "cancel"];
|
|
2661
|
-
const CONFERENCE_ACTIONS = ["add", "remove"];
|
|
2662
2700
|
/** Validate the exact interaction/assignment target before provider command dispatch. */
|
|
2663
|
-
export function validateTaskCommandRequest(request, task, path
|
|
2701
|
+
export function validateTaskCommandRequest(request, task, path, taskContext) {
|
|
2664
2702
|
const into = new Collector();
|
|
2665
2703
|
if (!isPlainObject(request) || !isPlainObject(task)) {
|
|
2666
2704
|
into.add("command.request.shape", path, "a request and the current published task are required");
|
|
@@ -2674,13 +2712,6 @@ export function validateTaskCommandRequest(request, task, path = "request", task
|
|
|
2674
2712
|
into.violations.push(...validateTaskCommand(request.command, task, `${path}.command`, taskContext));
|
|
2675
2713
|
return into.violations;
|
|
2676
2714
|
}
|
|
2677
|
-
/**
|
|
2678
|
-
* What a command needs to be issuable, checked against the task it names: the capability the
|
|
2679
|
-
* guide's table gates it on, the phase it belongs to, and the state that has to stand -- a
|
|
2680
|
-
* lead requested, somebody else on the call. Without a task only the command's
|
|
2681
|
-
* own shape is checked. A host validates before sending, and an adapter before acting: a command
|
|
2682
|
-
* for a control the task never offered is the host's error, and this names it.
|
|
2683
|
-
*/
|
|
2684
2715
|
export function validateTaskCommand(command, task, path = "command", taskContext) {
|
|
2685
2716
|
const into = new Collector();
|
|
2686
2717
|
if (!isPlainObject(command)) {
|
|
@@ -2718,9 +2749,11 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2718
2749
|
if (command.action === "request")
|
|
2719
2750
|
fields.push("note");
|
|
2720
2751
|
break;
|
|
2721
|
-
case "
|
|
2722
|
-
fields.push("
|
|
2723
|
-
|
|
2752
|
+
case "add-to-call":
|
|
2753
|
+
fields.push("dialId", "contactId", "number");
|
|
2754
|
+
break;
|
|
2755
|
+
case "remove-from-call":
|
|
2756
|
+
fields.push("contactId", "party");
|
|
2724
2757
|
break;
|
|
2725
2758
|
}
|
|
2726
2759
|
for (const key of Object.keys(command))
|
|
@@ -2744,19 +2777,22 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2744
2777
|
if (command.note !== undefined)
|
|
2745
2778
|
into.filled(command.note, "command.leadAssist.note", `${path}.note`, "a note must not be empty when present");
|
|
2746
2779
|
break;
|
|
2747
|
-
case "
|
|
2748
|
-
|
|
2749
|
-
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
2753
|
-
|
|
2754
|
-
|
|
2755
|
-
const item = isFilled(command.destinationId);
|
|
2756
|
-
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");
|
|
2757
|
-
}
|
|
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");
|
|
2758
2788
|
}
|
|
2759
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
|
+
}
|
|
2760
2796
|
case "recording":
|
|
2761
2797
|
into.violations.push(...validateRecordingCommandShape(command, "provider", path));
|
|
2762
2798
|
break;
|
|
@@ -2771,6 +2807,8 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2771
2807
|
}
|
|
2772
2808
|
if (task === undefined)
|
|
2773
2809
|
return into.violations;
|
|
2810
|
+
if (taskContext === undefined)
|
|
2811
|
+
throw new TypeError("validateTaskCommand: a task is validated against the manifest's levels; pass taskContext with it");
|
|
2774
2812
|
// The task the command is held to has to be one the wire published. A host's own mapping of it,
|
|
2775
2813
|
// handed in for want of the original, is not, and checking a command against it would be
|
|
2776
2814
|
// checking against a task nobody has -- so the task is validated first, and a command is held
|
|
@@ -2820,12 +2858,6 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2820
2858
|
// to act on yet, and in completing this agent's interaction has ended. The caller and other
|
|
2821
2859
|
// channels may continue elsewhere; this task's phase no longer permits these controls.
|
|
2822
2860
|
const interaction = () => inPhase("command.phase.interaction", "in-progress", "paused");
|
|
2823
|
-
// A destination is one the directory offered: the id Omni sends is the id the provider published.
|
|
2824
|
-
const listed = (name) => {
|
|
2825
|
-
const declared = capabilities[name];
|
|
2826
|
-
const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
|
|
2827
|
-
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`);
|
|
2828
|
-
};
|
|
2829
2861
|
const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
|
|
2830
2862
|
switch (type) {
|
|
2831
2863
|
case "answer":
|
|
@@ -2884,19 +2916,27 @@ export function validateTaskCommand(command, task, path = "command", taskContext
|
|
|
2884
2916
|
into.require(isPlainObject(task.leadAssist) && task.leadAssist.stage === "requested", "command.leadAssist.requested", path, "cancel needs a request standing: leadAssist with stage requested");
|
|
2885
2917
|
}
|
|
2886
2918
|
break;
|
|
2887
|
-
case "
|
|
2919
|
+
case "add-to-call":
|
|
2920
|
+
case "remove-from-call": {
|
|
2888
2921
|
interaction();
|
|
2889
|
-
const
|
|
2890
|
-
if (
|
|
2891
|
-
|
|
2892
|
-
|
|
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") {
|
|
2893
2933
|
const others = onCall.filter(entry => entry.role !== "agent");
|
|
2894
2934
|
if (command.party === true) {
|
|
2895
|
-
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");
|
|
2896
2936
|
}
|
|
2897
|
-
else if (isFilled(command.
|
|
2898
|
-
into.require(onCall.some(entry => entry.role === "
|
|
2899
|
-
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");
|
|
2900
2940
|
}
|
|
2901
2941
|
}
|
|
2902
2942
|
break;
|
|
@@ -3075,7 +3115,7 @@ function validateUser(value, rule, path, into) {
|
|
|
3075
3115
|
}
|
|
3076
3116
|
function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
3077
3117
|
if (!isPlainObject(value)) {
|
|
3078
|
-
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");
|
|
3079
3119
|
return;
|
|
3080
3120
|
}
|
|
3081
3121
|
for (const [name, declared] of Object.entries(value)) {
|
|
@@ -3083,9 +3123,13 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
|
3083
3123
|
continue;
|
|
3084
3124
|
if (!into.require(SESSION_CAPABILITIES.includes(name), "authentication.capability.unknown", `${path}.${name}`, `unsupported session capability: ${name}`))
|
|
3085
3125
|
continue;
|
|
3126
|
+
if (name === "lead") {
|
|
3127
|
+
validateLeadCapabilitiesInto(declared, `${path}.lead`, into);
|
|
3128
|
+
continue;
|
|
3129
|
+
}
|
|
3086
3130
|
if (name === "preferences") {
|
|
3087
3131
|
if (Array.isArray(declared) && declared.length === 0) {
|
|
3088
|
-
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");
|
|
3089
3133
|
}
|
|
3090
3134
|
validatePreferencesInto(declared, `${path}.preferences`, into, levels);
|
|
3091
3135
|
continue;
|
|
@@ -3093,6 +3137,20 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
|
3093
3137
|
into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
|
|
3094
3138
|
}
|
|
3095
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
|
+
}
|
|
3096
3154
|
/**
|
|
3097
3155
|
* A failure an authentication reports: on a `rejected` start or completion, or on an `expired`
|
|
3098
3156
|
* state. A provider names its own codes freely; an `omni.` code is the contract's and has to be one
|
|
@@ -3187,11 +3245,11 @@ function validateAuthenticationChallenge(value, path, into) {
|
|
|
3187
3245
|
}
|
|
3188
3246
|
}
|
|
3189
3247
|
/**
|
|
3190
|
-
* What `start()` or `complete()` answered: a challenge or a rejection from `start`, a
|
|
3191
|
-
* 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
|
|
3192
3250
|
* to the same rules as any `authenticated` state.
|
|
3193
3251
|
*/
|
|
3194
|
-
export function validateAuthenticationResult(result, method, path
|
|
3252
|
+
export function validateAuthenticationResult(result, method, path, context) {
|
|
3195
3253
|
const into = new Collector();
|
|
3196
3254
|
if (!isPlainObject(result)) {
|
|
3197
3255
|
into.add("authentication.result.shape", path, `${method} must answer an object`);
|
|
@@ -3215,7 +3273,7 @@ export function validateAuthenticationResult(result, method, path = "result", co
|
|
|
3215
3273
|
}
|
|
3216
3274
|
return into.violations;
|
|
3217
3275
|
}
|
|
3218
|
-
export function validateAuthenticationState(state, path
|
|
3276
|
+
export function validateAuthenticationState(state, path, context) {
|
|
3219
3277
|
const into = new Collector();
|
|
3220
3278
|
if (!isPlainObject(state)) {
|
|
3221
3279
|
into.add("authentication.shape", path, "an authentication state must be an object");
|