@xema/omni-protocol 0.1.129 → 0.1.131

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.
@@ -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, conferenced: true, unanswered: 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, conferenced: 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", "conference"];
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, conference: true, recording: 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 login, held to the manifest: one the platform listed, required
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)} login has no call to hear and chooses no phone`);
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 login says how the agent hears the call: one of the manifest's phones"))
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/login scope is required");
412
+ into.add("timeEstimate.scope", path, "provider/session scope is required");
412
413
  return into.violations;
413
414
  }
414
- for (const key of ["providerId", "loginId"])
415
- into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/login scope is required");
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", "loginId"])
423
- into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/login");
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", "loginId", "at", "clockId", "uncertaintyMs"].includes(key), "timeEstimate.field", `${path}.${key}`, "unsupported estimate field");
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, loginId, path = "result") {
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(loginId, "timeCheck.login", "loginId", "current authenticated login is required");
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.loginId === loginId, "timeCheck.result.login", `${path}.loginId`, "response belongs to the current login");
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", "loginId", "clockId", "providerTime"].includes(key), "timeCheck.result.field", `${path}.${key}`, "unsupported response field");
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 validateDestinationDirectory(value, path, into) {
661
+ function validateAddToCallCapability(value, path, into) {
661
662
  if (!isPlainObject(value)) {
662
- into.add("task.destinations.shape", path, "a conference control carries the directory it offers: { destinations: [...] }");
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
- if (!Array.isArray(value.destinations)) {
666
- into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array");
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.destinations.forEach((destination, index) => {
675
- const at = `${path}.destinations[${index}]`;
676
- if (!isPlainObject(destination)) {
677
- into.add("task.destination.shape", at, "each destination must be an object");
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
- if (into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id")) {
681
- if (seen.has(destination.id))
682
- into.add("task.destination.unique", `${at}.id`, `duplicate destination id: ${destination.id}`);
683
- seen.add(destination.id);
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 login is validated against. */
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 login against");
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(", ")}`;
@@ -887,7 +894,7 @@ function validateBrowsers(value, path, into) {
887
894
  seen.add(browser.id);
888
895
  }
889
896
  // The name is an input to a `TAB_NAME` isolation scheme: two tabs with one name would
890
- // silently share a session.
897
+ // silently share a profile.
891
898
  if (into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name")) {
892
899
  if (names.has(browser.name))
893
900
  into.add("task.browser.name.unique", `${at}.name`, `duplicate browser name: ${browser.name}`);
@@ -910,7 +917,7 @@ function validateBrowsers(value, path, into) {
910
917
  // Reuse and its scheme travel together. A reusing browser with no scheme would otherwise
911
918
  // inherit whatever a host happened to default to, which is how two tasks end up sharing a
912
919
  // session nobody intended. The guide names the rule for the missing case.
913
- if (browser.sharedSession === true) {
920
+ if (browser.sharedProfile === true) {
914
921
  if (browser.isolationScheme === undefined) {
915
922
  into.add("task.browser.isolationScheme.required", `${at}.isolationScheme`, `a reusing browser must declare one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
916
923
  }
@@ -918,11 +925,11 @@ function validateBrowsers(value, path, into) {
918
925
  into.require(ISOLATION_SCHEME_VALUES.includes(browser.isolationScheme), "task.browser.isolationScheme", `${at}.isolationScheme`, `an isolation scheme must be one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
919
926
  }
920
927
  }
921
- else if (browser.sharedSession === false) {
928
+ else if (browser.sharedProfile === false) {
922
929
  into.require(browser.isolationScheme === undefined, "task.browser.isolationScheme.unexpected", `${at}.isolationScheme`, "a browser that does not share its session must not declare an isolation scheme");
923
930
  }
924
931
  else {
925
- into.add("task.browser.sharedSession", `${at}.sharedSession`, "a browser must say whether its session is shared across tasks");
932
+ into.add("task.browser.sharedProfile", `${at}.sharedProfile`, "a browser must say whether its profile is shared across tasks");
926
933
  }
927
934
  });
928
935
  }
@@ -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 login's agent: the host reported it, and the provider knows who the host's agent is");
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", "destinationId"]) {
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, conferenced, or unanswered`);
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 conferenced came from one, so they do.
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 === "conferenced") {
1108
- into.filled(entry.destinationId, "task.onCall.destinationId", `${at}.destinationId`, `a ${role} entry names the directory item that was dialled`);
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 ["destinationId", "label"]) {
1129
- into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on conferenced`);
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 ["destinationId", "dialId", "label", "stage"]) {
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 conferenced`);
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 "conference":
1390
- validateDestinationDirectory(declared, `${path}.capabilities.${name}`, into);
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 login's `lead` flag; the provider rechecks the target and the state
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 login and active transport");
1460
- into.require(caps.lead === true, "team.command.capability", path, "the login must declare lead");
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 login");
1554
- into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the login must declare breaks");
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/login's ordered event stream.
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 login is the permission: a team member list reaches a login that declares `capabilities.lead`
1710
- // and nobody else. Only a caller holding the login can check it.
1711
- if (context.capabilities !== undefined && context.capabilities.lead !== true) {
1712
- into.add("team.unentitled", path, "a team member list published to a login that does not declare capabilities.lead: the login is the permission");
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`) && entry.mode === "join-call"
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; a silent one is not.
1814
- into.require(task.onCall.some((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId), "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard, so the task's onCall carries them as an agent`);
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 login holds: a channel names the task its call is, or nothing`))
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.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
1919
- && context.loginId !== undefined) {
1920
- into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
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.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into, levels));
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 login that does not
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.loginId, "event.loginId", `${path}.loginId`, "an event needs the login id it belongs to")
2080
- && context.loginId !== undefined) {
2081
- into.require(envelope.loginId === context.loginId, "event.loginId.mismatch", `${path}.loginId`, `an event for session ${describeValue(envelope.loginId)} on a login whose session is ${context.loginId}`);
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.destinationId !== undefined)
2156
- into.filled(event.destinationId, "event.dialOutcome.destinationId", `${at}.destinationId`, "a destinationId must not be empty when present");
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 === true, "event.team.capability", `${at}.${field}`, `${event.type} reaches a login that declares lead, and nobody else`);
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.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
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 login at connect and the platform reports a ${describeValue(value.phone)}: the phone state is the phone the agent hears this provider's calls on`);
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 login and nowhere else: on an agent computer
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 login's store, which the host provides on every connection: three functions, and nothing else is a store. */
2504
- export function validateLoginStore(store, path = "store") {
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 login's store: an object with get, set and delete");
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 login store ${method}s by key`);
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 login's host states what its Mute does: stream or station");
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 login's host holds a microphone to mute; a hardphone's is the phone's, and a conversation has none")) {
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 login's phone decides who holds the mute: a softphone host owns it and promises to keep it
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 login's host holds the mute and promises it is unavailable while the task is paused");
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)} login's host holds no mute to promise anything of`);
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 "conference":
2725
- fields.push("action", "destinationId");
2726
- fields.push(command.action === "add" ? "dialId" : "party");
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 "conference":
2751
- if (into.oneOf(command.action, CONFERENCE_ACTIONS, "command.conference.action", `${path}.action`)) {
2752
- if (command.action === "add") {
2753
- dial("command.conference.dialId");
2754
- into.filled(command.destinationId, "command.conference.destinationId", `${path}.destinationId`, "a conference names the directory item it dials in");
2755
- }
2756
- else {
2757
- const party = command.party === true;
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 "conference": {
2919
+ case "add-to-call":
2920
+ case "remove-from-call": {
2893
2921
  interaction();
2894
- const conferencing = offered("conference");
2895
- if (conferencing && command.action === "add")
2896
- listed("conference");
2897
- if (conferencing && command.action === "remove") {
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.conference.remove.alone", path, "removing the party would leave the agent alone: that is end-call");
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.destinationId)) {
2903
- into.require(onCall.some(entry => entry.role === "conferenced" && entry.destinationId === command.destinationId), "command.conference.remove.unknown", path, `no conferenced entry on onCall has destinationId ${describeValue(command.destinationId)}`);
2904
- into.require(others.length > 1, "command.conference.remove.alone", path, "removing the last other person would leave the agent alone: that is end-call");
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 login declares its capabilities: an object, {} when it has none");
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 login with nothing left to the person omits preferences rather than declaring an empty list");
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 login or a
3196
- * rejection from `complete`. A rejection carries a failure the host can show, and a login is held
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) {