@xema/omni-protocol 0.1.77 → 0.1.78

package/dist/validation.js

@@ -54,7 +54,7 @@ const BREAK_APPROVALS = membersOf({
     "not-requested": true, "awaiting-decision": true, granted: true, "starting-after-task": true, "in-effect": true,
 });
 const TEAM_AVAILABILITIES = membersOf({
-    ready: true, "on-task": true, "on-break": true, "signed-out": true,
+    ready: true, "on-task": true, "on-break": true, reserved: true, "signed-out": true,
 });
 const HANDLING_STEPS = membersOf({
     queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
@@ -82,7 +82,7 @@ const MEMBER_BREAKS = membersOf({
     "awaiting-decision": true, granted: true, "starting-after-task": true,
 });
 const OFFERABLE_PHASES = membersOf({
-    pending: true, confirmed: true, preview: true,
+    pending: true,
 });
 const PREVIEW_DEADLINES = membersOf({ calls: true, expires: true });
 const PHONES = membersOf({ softphone: true, deskPhone: true });
@@ -279,9 +279,8 @@ function validateIdleCapabilities(value, channel, path, into) {
         }
         else {
             validateBrowserAccess(browser.access, `${path}.personalBrowser.access`, into);
-            if (browser.accessAppliesTo !== undefined) {
-                into.oneOf(browser.accessAppliesTo, ACCESS_APPLIES_TO, "manifest.personalBrowser.accessAppliesTo", `${path}.personalBrowser.accessAppliesTo`);
-            }
+            // Stated, never defaulted: an absent value read as all-navigation was a second spelling of one fact.
+            into.oneOf(browser.accessAppliesTo, ACCESS_APPLIES_TO, "manifest.personalBrowser.accessAppliesTo", `${path}.personalBrowser.accessAppliesTo`);
         }
     }
     if (value.dial !== undefined) {
@@ -568,8 +567,7 @@ function validateCustomCapabilities(value, path, into) {
         into.oneOf(custom.ui.control, CUSTOM_UI_CONTROLS, "task.custom.ui.control", `${at}.ui.control`);
         into.filled(custom.ui.label, "task.custom.ui.label", `${at}.ui.label`, "a custom control needs a label");
         into.oneOf(custom.ui.placement, CUSTOM_UI_PLACEMENTS, "task.custom.ui.placement", `${at}.ui.placement`);
-        if (custom.ui.render !== undefined)
-            into.oneOf(custom.ui.render, CUSTOM_RENDERS, "task.custom.ui.render", `${at}.ui.render`);
+        into.oneOf(custom.ui.render, CUSTOM_RENDERS, "task.custom.ui.render", `${at}.ui.render`);
         if (custom.prompt !== undefined) {
             if (!isPlainObject(custom.prompt) || !Array.isArray(custom.prompt.fields)) {
                 into.add("task.custom.prompt.shape", `${at}.prompt`, "a prompt is an object with the fields the agent fills");
@@ -661,8 +659,8 @@ function validateLockedInto(value, rule, path, levels, into) {
 }
 /** What every resolved value carries: who set it, and who locked it if anyone. */
 function validateResolvedInto(value, rule, path, levels, into) {
-    if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a level, or provisioning")) {
-        into.require(value.setBy === "provider" || levelIds(levels).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${String(value.setBy)} is neither provisioning nor a level this manifest declares`);
+    if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a level, or provider")) {
+        into.require(value.setBy === "provider" || levelIds(levels).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${String(value.setBy)} is neither provider nor a level this manifest declares`);
     }
     if (value.lockedBy !== undefined)
         validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, levels, into);
@@ -859,7 +857,11 @@ function validateHandlingHistory(value, path, into, task = {}) {
 /** Present only while consulting, and only on voice: elsewhere there is nobody to consult. */
 const TASK_MEDIA_STATES = membersOf({ started: true, ended: true });
 /** Real-time media is a voice affair, and its state is one of two words. */
-function validateTaskMedia(value, channel, phase, path, into) {
+/** Whether a host dial is ringing the party: the party entry carries `stage: "ringing"` and the host's `dialId`. */
+function partyRingingByHost(task) {
+    return Array.isArray(task.onCall) && task.onCall.some(entry => isPlainObject(entry) && entry.role === "party" && entry.stage === "ringing" && typeof entry.dialId === "string");
+}
+function validateTaskMedia(task, value, channel, phase, path, into) {
     if (value === undefined)
         return;
     if (!into.require(channel === "voice", "task.media.channel", path, `a ${channel} task carries no real-time media state`))
@@ -867,7 +869,9 @@ function validateTaskMedia(value, channel, phase, path, into) {
     if (into.oneOf(value, TASK_MEDIA_STATES, "task.media", path)) {
         // Nothing is acquired while pending, and a preview has placed no call: media names a task whose
         // work has begun, on a snapshot as on the event, or a host would open the microphone on an offer.
-        into.require(!WORK_NOT_BEGUN.includes(phase), "task.media.beforeWork", path, `a ${String(phase)} task has no media: audio arrives once its work has begun`);
+        // The one task not yet at work that has audio is one whose party the host is dialling: ring-back
+        // is audio, and every host-placed dial's media starts on dialling.
+        into.require(!WORK_NOT_BEGUN.includes(phase) || partyRingingByHost(task), "task.media.beforeWork", path, `a ${String(phase)} task has no media: audio arrives once its work has begun, or once the host is dialling its party`);
     }
 }
 const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
@@ -1100,7 +1104,7 @@ function validateTaskInto(task, context, path, into) {
     if (Array.isArray(task.onCall) && task.onCall.length > 0 && (task.phase === "completing" || task.media === "ended")) {
         into.add("task.onCall.ended", `${path}.onCall`, `the call has ended (${task.phase === "completing" ? "the task is completing" : "its media ended"}) and onCall still names people on it: the room is who is on the call now, and now nobody is`);
     }
-    validateTaskMedia(task.media, context.channel, task.phase, `${path}.media`, into);
+    validateTaskMedia(task, task.media, context.channel, task.phase, `${path}.media`, into);
     validateLeadAssist(task.leadAssist, context.channel, `${path}.leadAssist`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
     validateMonitoring(task.monitoring, context.channel, `${path}.monitoring`, into);
@@ -1217,7 +1221,9 @@ function validateBreakState(value, path, into) {
     if (value.imposed !== undefined) {
         validateImposedBreak(value.imposed, `${path}.imposed`, into);
         // An imposed break is a break somebody placed; beside `not-requested` there is no break.
-        into.require(value.approval !== "not-requested", "break.imposed.approval", `${path}.imposed`, "an imposed break is a break in progress; not-requested says there is none");
+        // An imposed break is a break in progress or about to be: it travels with in-effect or
+        // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
+        into.require(value.approval === "in-effect" || value.approval === "starting-after-task", "break.imposed.approval", `${path}.imposed`, `an imposed break is in effect or starting after the task; ${String(value.approval)} says the agent asked, or that there is none`);
     }
     if (value.reasons === undefined)
         return;
@@ -1252,6 +1258,13 @@ function validateBreakState(value, path, into) {
     if (typeof value.activeReasonId === "string" && value.activeReasonId.length > 0) {
         into.require(seen.has(value.activeReasonId), "break.activeReasonId.known", `${path}.activeReasonId`, `activeReasonId names a reason the provider did not publish: ${value.activeReasonId}`);
     }
+    // A break in effect, or about to be, on a provider that publishes reasons is on one of them: an
+    // imposed one included, since the lead's place named it. A break of no kind is a break whose
+    // rules -- who may monitor through it, whether it counts -- nobody can apply.
+    ruleEvaluated("break.activeReasonId.required");
+    if (seen.size > 0 && (value.approval === "in-effect" || value.approval === "starting-after-task")) {
+        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${String(value.approval)} on a provider that publishes reasons names the one it is on`);
+    }
 }
 export function validateTeamRoster(roster, path = "team", context = {}) {
     const into = new Collector();
@@ -1408,6 +1421,14 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     // describes a state the agent cannot be in, whichever half is stale. The one exception is a
     // lead listening to a call during a break that is work of another sort -- coaching,
     // administrative, training -- and on no other.
+    // The converse: a committed break with nothing outstanding has begun. starting-after-task beside
+    // no task is a break waiting on work that does not exist, and an empty list reading as "still
+    // finishing" is the plausible nought.
+    ruleEvaluated("break.starting-after-task.tasks");
+    if (isPlainObject(snapshot.break) && snapshot.break.approval === "starting-after-task"
+        && Array.isArray(snapshot.tasks) && snapshot.tasks.length === 0) {
+        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is in-effect");
+    }
     if (isPlainObject(snapshot.break) && snapshot.break.approval === "in-effect"
         && Array.isArray(snapshot.tasks) && snapshot.tasks.length > 0) {
         const listening = snapshot.tasks.every((task) => isPlainObject(task) && task.monitoring !== undefined);
@@ -1487,6 +1508,10 @@ function validateTaskOutcome(value, path, into) {
                 into.filled(value.destinationId, "event.taskEnded.outcome.transferred", `${path}.destinationId`, "a destinationId must not be empty when present");
             }
             break;
+        case "taken-over":
+            // A lead is not a directory item: the ending names the lead, and the host resolves the name.
+            into.require(isUserId(value.leadId), "event.taskEnded.outcome.takenOver", `${path}.leadId`, "a take-over names the lead who took the call, by user id");
+            break;
         case "cancelled":
             // One word covered the agent declining, the provider withdrawing and the party abandoning the
             // ring; a record that cannot tell them apart is not a record. by says who, as completed does.
@@ -2186,7 +2211,8 @@ export function validateTaskCommand(command, task, path = "command") {
 const RESULT_STATUSES = {
     execute: { success: "applied", failure: "failed" },
     dial: { success: "dialling", failure: "failed" },
-    setCapacity: { success: "applied", failure: "failed" },
+    // A statement, not a request: taken, never refused.
+    setCapacity: { success: "applied", failure: undefined },
     requestBreak: { success: "requested", failure: "failed" },
     commitBreak: { success: "committed", failure: "failed" },
     cancelBreak: { success: "cancelled", failure: "failed" },
@@ -2229,7 +2255,7 @@ export function validateResult(result, method, path = "result", dialId) {
             into.require(result.dialId === undefined, "result.dialId.unexpected", `${path}.dialId`, `${statuses.success} dialled nothing and names no dial`);
         }
     }
-    else if (result.status === statuses.failure) {
+    else if (statuses.failure !== undefined && result.status === statuses.failure) {
         if (result.failure === undefined) {
             into.add("result.failure.required", `${path}.failure`, `${statuses.failure} carries the failure that says why`);
         }