@xema/omni-protocol 0.1.31 → 0.1.33

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
+import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HANDLING_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -67,6 +67,10 @@ const ACCESS_APPLIES_TO = membersOf({
     "initial-url": true, "all-navigation": true,
 });
 const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number": true });
+const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true, unreachable: true, rejected: true });
+const ON_CALL_ROLES = membersOf({ party: true, agent: true, consulted: true, conferenced: true });
+/** The task capabilities under which a command dials, and so need the manifest to say how a dial ends. */
+const DIALLING_CAPABILITIES = ["callback", "blindTransfer", "consultTransfer", "conference"];
 const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
@@ -92,6 +96,8 @@ const TASK_CAPABILITIES = {
     chat: membersOf({ browsers: true, dispositions: true, custom: true, reject: true, hold: true }),
     email: membersOf({ browsers: true, dispositions: true, custom: true, reject: true }),
 };
+// The published list and the type's keys are the same set, or one of them is wrong.
+true;
 /** Idle capabilities each channel may declare. Only voice may dial, and runtime has to say so too. */
 const IDLE_CAPABILITIES_BY_CHANNEL = {
     voice: IDLE_CAPABILITIES,
@@ -266,6 +272,36 @@ function validateIdleCapabilities(value, channel, path, into) {
         }
     }
 }
+/**
+ * A provider that dials says how a dial can end, both ways: `answered`, or the desk cannot tell
+ * reached from still ringing, and at least one way of not reaching, or it can never say failed.
+ * Off voice nothing dials, and the idle dialpad is a dial, so declaring it is declaring this.
+ */
+function validateDialOutcomes(manifest, path, into) {
+    const declared = manifest.dialOutcomes;
+    const dials = isPlainObject(manifest.idleCapabilities) && manifest.idleCapabilities.dial !== undefined;
+    if (declared === undefined) {
+        into.require(!dials, "manifest.dialOutcomes.required", path, "a manifest that declares dial says how a dial ends: dialOutcomes with answered and at least one way of not reaching");
+        return;
+    }
+    if (!into.require(manifest.channel === "voice", "manifest.dialOutcomes.channel", path, `a ${String(manifest.channel)} provider dials nothing and declares no dial outcomes`))
+        return;
+    if (!Array.isArray(declared) || declared.length === 0) {
+        into.add("manifest.dialOutcomes.shape", path, "dialOutcomes is a non-empty array of the outcomes the platform distinguishes");
+        return;
+    }
+    declared.forEach((outcome, index) => {
+        if (into.oneOf(outcome, DIAL_OUTCOMES, "manifest.dialOutcome", `${path}[${index}]`) && declared.indexOf(outcome) !== index) {
+            into.add("manifest.dialOutcome.unique", `${path}[${index}]`, `duplicate dial outcome: ${String(outcome)}`);
+        }
+    });
+    into.require(declared.includes("answered"), "manifest.dialOutcomes.answered", path, "a dial that reached its destination is stated, never inferred: dialOutcomes includes answered");
+    into.require(declared.some((outcome) => outcome !== "answered"), "manifest.dialOutcomes.failure", path, "a provider that can only say answered can never say a destination was not reached: declare at least one other outcome");
+}
+/** Whether a manifest says how a dial ends, and so may publish tasks that dial. `undefined` where there is no manifest to ask. */
+function manifestDials(manifest) {
+    return isPlainObject(manifest) ? Array.isArray(manifest.dialOutcomes) : undefined;
+}
 export function validateManifest(manifest, path = "manifest") {
     const into = new Collector();
     if (!isPlainObject(manifest)) {
@@ -301,6 +337,7 @@ export function validateManifest(manifest, path = "manifest") {
     }
     if (channelValid)
         validateIdleCapabilities(manifest.idleCapabilities, manifest.channel, `${path}.idleCapabilities`, into);
+    validateDialOutcomes(manifest, `${path}.dialOutcomes`, into);
     if (manifest.phaseLabels !== undefined) {
         if (!isPlainObject(manifest.phaseLabels)) {
             into.add("manifest.phaseLabels.shape", `${path}.phaseLabels`, "phaseLabels must be an object when present");
@@ -312,6 +349,9 @@ export function validateManifest(manifest, path = "manifest") {
             }
         }
     }
+    if (manifest.runningStepReports !== undefined) {
+        into.require(manifest.runningStepReports === true, "manifest.runningStepReports", `${path}.runningStepReports`, "runningStepReports is declared by presence, as true; a provider that takes begin and end only omits it");
+    }
     if (manifest.orgLevels !== undefined) {
         if (!Array.isArray(manifest.orgLevels)) {
             into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
@@ -628,13 +668,27 @@ function validateTaskAttributes(value, path, into) {
 function validateHandlingHistory(value, path, into) {
     if (value === undefined)
         return;
-    if (!Array.isArray(value)) {
-        into.add("task.handlingHistory.shape", path, "handlingHistory must be an array when present");
+    if (!isPlainObject(value)) {
+        into.add("task.handlingHistory.shape", path, "handlingHistory must be an object with its steps when present");
+        return;
+    }
+    // What the record adds up to before this agent: each total present when the provider knows it
+    // and absent when it does not, never a plausible nought.
+    for (const field of ["handleSeconds", "holdSeconds", "queueSeconds"]) {
+        if (value[field] !== undefined) {
+            into.require(isDurationSeconds(value[field]), `task.handlingHistory.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
+        }
+    }
+    if (value.transfers !== undefined) {
+        into.require(typeof value.transfers === "number" && Number.isInteger(value.transfers) && value.transfers >= 0, "task.handlingHistory.transfers", `${path}.transfers`, "transfers must be a whole number, zero or more, or omitted when unknown");
+    }
+    if (!Array.isArray(value.steps)) {
+        into.add("task.handlingHistory.steps.shape", `${path}.steps`, "handlingHistory carries its steps as an array, empty when the task has had none");
         return;
     }
     let previous;
-    value.forEach((entry, index) => {
-        const at = `${path}[${index}]`;
+    value.steps.forEach((entry, index) => {
+        const at = `${path}.steps[${index}]`;
         if (!isPlainObject(entry)) {
             into.add("task.handlingHistory.entry", at, "each handling step must be an object");
             return;
@@ -658,6 +712,15 @@ function validateHandlingHistory(value, path, into) {
             // On `queued` nobody takes part, so there is nothing to name.
             into.require(entry.step !== "queued", "task.handlingHistory.by.unexpected", `${at}.by`, "a queued step names nobody");
         }
+        // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
+        const dialled = typeof entry.step === "string" && HANDLING_STEPS_THAT_DIAL.includes(entry.step);
+        for (const field of ["dialId", "destination"]) {
+            if (entry[field] === undefined)
+                continue;
+            if (into.filled(entry[field], `task.handlingHistory.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
+                into.require(dialled, `task.handlingHistory.${field}.unexpected`, `${at}.${field}`, `${String(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
+            }
+        }
     });
 }
 /** Present only while consulting, and only on voice: elsewhere there is nobody to consult. */
@@ -670,21 +733,57 @@ function validateTaskMedia(value, channel, path, into) {
         return;
     into.oneOf(value, TASK_MEDIA_STATES, "task.media", path);
 }
-function validateConsultation(value, channel, path, into) {
+/**
+ * Who is on the call, as the provider states it. Voice only. Each entry is a role with what that
+ * role needs and nothing another role would: a party or an agent dialled nowhere, so neither
+ * carries a destination; somebody consulted or conferenced came from one, so both do.
+ */
+function validateOnCall(value, channel, path, into) {
     if (value === undefined)
         return;
-    if (!into.require(channel === "voice", "task.consultation.channel", path, `a ${channel} task cannot carry a consultation`))
+    if (!into.require(channel === "voice", "task.onCall.channel", path, `a ${channel} task has nobody on a call`))
         return;
-    if (!isPlainObject(value)) {
-        into.add("task.consultation.shape", path, "a consultation must be an object when present");
+    if (!Array.isArray(value)) {
+        into.add("task.onCall.shape", path, "onCall is an array of who is on the call, when the provider knows");
         return;
     }
-    into.filled(value.destination, "task.consultation.destination", `${path}.destination`, "a consultation names the destination being consulted");
-    if (value.label !== undefined) {
-        into.filled(value.label, "task.consultation.label", `${path}.label`, "a label must not be empty when present");
-    }
-    if (value.since !== undefined)
-        into.timestamp(value.since, "task.consultation.since", `${path}.since`);
+    const counted = { party: 0, consulted: 0 };
+    value.forEach((entry, index) => {
+        const at = `${path}[${index}]`;
+        if (!isPlainObject(entry)) {
+            into.add("task.onCall.entry", at, "each entry on the call must be an object");
+            return;
+        }
+        if (!into.oneOf(entry.role, ON_CALL_ROLES, "task.onCall.role", `${at}.role`))
+            return;
+        const role = entry.role;
+        into.timestamp(entry.since, "task.onCall.since", `${at}.since`);
+        if (entry.held !== undefined) {
+            into.require(entry.held === true, "task.onCall.held", `${at}.held`, "held is stated by presence: send true or omit it");
+        }
+        if (role === "party" || role === "consulted")
+            counted[role] += 1;
+        if (role === "agent") {
+            into.require(isUserId(entry.userId), "task.onCall.userId", `${at}.userId`, "an agent on the call is named by their user id");
+        }
+        else {
+            into.require(entry.userId === undefined, "task.onCall.userId.unexpected", `${at}.userId`, `a ${role} is not named by a user id`);
+        }
+        if (role === "consulted" || role === "conferenced") {
+            into.filled(entry.destination, "task.onCall.destination", `${at}.destination`, `a ${role} entry names the destination that was dialled`);
+            if (entry.dialId !== undefined)
+                into.filled(entry.dialId, "task.onCall.dialId", `${at}.dialId`, "dialId must not be empty when present");
+            if (entry.label !== undefined)
+                into.filled(entry.label, "task.onCall.label", `${at}.label`, "a label must not be empty when present");
+        }
+        else {
+            for (const field of ["destination", "dialId", "label"]) {
+                into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a ${role} was dialled from nowhere; ${field} belongs on consulted or conferenced`);
+            }
+        }
+    });
+    into.require(counted.party <= 1, "task.onCall.party.single", path, "a call has one party; a second is somebody else's role");
+    into.require(counted.consulted <= 1, "task.onCall.consulted.single", path, "one consultation at a time: transfer complete and cancel name no destination because there is exactly one");
 }
 const LEAD_STAGES = membersOf({ requested: true, joined: true });
 /** The agent's request for a lead. Voice only; `joined` names the lead, `requested` cannot. */
@@ -773,7 +872,7 @@ function validateTaskInto(task, context, path, into) {
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
-    validateConsultation(task.consultation, context.channel, `${path}.consultation`, into);
+    validateOnCall(task.onCall, context.channel, `${path}.onCall`, into);
     validateTaskMedia(task.media, context.channel, `${path}.media`, into);
     validateLead(task.lead, context.channel, `${path}.lead`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
@@ -797,6 +896,10 @@ function validateTaskInto(task, context, path, into) {
             continue;
         if (!into.require(allowed.includes(name), "task.capability.channel", `${path}.capabilities.${name}`, `a ${context.channel} task may not declare ${name}`))
             continue;
+        // A control that dials needs the manifest to have said how a dial ends, or its outcome has no words.
+        if (DIALLING_CAPABILITIES.includes(name) && context.dialOutcomesDeclared === false) {
+            into.add("task.capability.dialOutcomes.required", `${path}.capabilities.${name}`, `${name} dials, and the manifest declares no dialOutcomes to say how a dial ends`);
+        }
         // A control the queue could allow may stand locked in its place, saying whose. What the
         // queue provides -- browsers, dispositions, custom controls -- is content, not a control.
         if (isLocked(declared)) {
@@ -1032,7 +1135,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         const seen = new Set();
         let assisting;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -1219,7 +1322,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
@@ -1230,7 +1333,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");
@@ -1242,6 +1345,21 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             into.require(isTaskId(event.taskId), "event.taskEnded.taskId", `${at}.taskId`, "a task id is required");
             validateTaskOutcome(event.outcome, `${at}.outcome`, into);
             break;
+        case "dial-outcome": {
+            into.filled(event.dialId, "event.dialOutcome.dialId", `${at}.dialId`, "an outcome names the dial it ends, by the host's dialId");
+            // Only a distinction the manifest declared: an undeclared word is a guess dressed as a code.
+            const declared = isPlainObject(manifest) && Array.isArray(manifest.dialOutcomes) ? manifest.dialOutcomes : undefined;
+            if (into.oneOf(event.outcome, DIAL_OUTCOMES, "event.dialOutcome.outcome", `${at}.outcome`)) {
+                into.require(declared !== undefined && declared.includes(event.outcome), "event.dialOutcome.undeclared", `${at}.outcome`, `the manifest does not declare ${String(event.outcome)} among its dialOutcomes`);
+            }
+            if (event.taskId !== undefined)
+                into.require(isTaskId(event.taskId), "event.dialOutcome.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            if (event.destination !== undefined)
+                into.filled(event.destination, "event.dialOutcome.destination", `${at}.destination`, "a destination must not be empty when present");
+            if (event.reason !== undefined)
+                into.filled(event.reason, "event.dialOutcome.reason", `${at}.reason`, "a reason must not be empty when present");
+            break;
+        }
         case "announcement":
             into.filled(event.text, "event.announcement.text", `${at}.text`, "an announcement needs text");
             into.timestamp(event.announcedAt, "event.announcement.announcedAt", `${at}.announcedAt`);
@@ -1400,6 +1518,35 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees") {
     }
     return into.violations;
 }
+/**
+ * What the host reports of a leg it performed, as an adapter may validate it before forwarding:
+ * a task, a step, when it began, how long so far if the host says, and an explicit end that
+ * carries the final duration.
+ */
+export function validateHandlingReport(report, path = "handlingReport", manifest) {
+    const into = new Collector();
+    if (!isPlainObject(report)) {
+        into.add("handlingReport.shape", path, "a handling report must be an object");
+        return into.violations;
+    }
+    into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
+    into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
+    into.timestamp(report.at, "handlingReport.at", `${path}.at`);
+    if (report.seconds !== undefined) {
+        into.require(isDurationSeconds(report.seconds) && report.seconds > 0, "handlingReport.seconds", `${path}.seconds`, "seconds must be a positive whole number; omit it rather than report nought");
+    }
+    if (report.ended !== undefined) {
+        if (into.require(report.ended === true, "handlingReport.ended", `${path}.ended`, "ended is declared by presence, as true; a running leg omits it")) {
+            into.require(report.seconds !== undefined, "handlingReport.ended.seconds", `${path}.seconds`, "an ended leg states its final duration");
+        }
+    }
+    else if (report.seconds !== undefined && manifest !== undefined) {
+        // A running report crosses only to a provider that asked for one: begin and end are the whole
+        // of what the rest receive.
+        into.require(isPlainObject(manifest) && manifest.runningStepReports === true, "handlingReport.running.unexpected", `${path}.seconds`, "this provider takes begin and end only; a running report was never asked for");
+    }
+    return into.violations;
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {
@@ -1455,7 +1602,7 @@ export function validateHostReport(report, path = "host") {
 // failure. A method added to `Connection` without a row here is a compile error at the call site.
 const RESULT_STATUSES = {
     execute: { success: "applied", failure: "failed" },
-    dial: { success: "dialled", failure: "failed" },
+    dial: { success: "dialling", failure: "failed" },
     setCapacity: { success: "applied", failure: "failed" },
     requestBreak: { success: "requested", failure: "failed" },
     commitBreak: { success: "committed", failure: "failed" },
@@ -1465,6 +1612,7 @@ const RESULT_STATUSES = {
     executeTeamConsult: { success: "applied", failure: "failed" },
     openMedia: { success: "opened", failure: "unavailable" },
     setPreference: { success: "applied", failure: "failed" },
+    recordStep: { success: "recorded", failure: "failed" },
     executeTeamPolicy: { success: "applied", failure: "failed" },
 };
 /**
@@ -1473,9 +1621,12 @@ const RESULT_STATUSES = {
  * shows the agent what it says. A status the method does not answer, a failure status without a
  * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
  */
-export function validateResult(result, method, path = "result") {
+export function validateResult(result, method, path = "result", dialId) {
     const into = new Collector();
-    const statuses = RESULT_STATUSES[method];
+    // A command that dials -- `dial`, or `execute` with a command carrying a `dialId` -- answers
+    // `dialling` and restates the host's identity, so the host compares and confirms.
+    const dials = method === "dial" || (method === "execute" && dialId !== undefined);
+    const statuses = dials ? { success: "dialling", failure: RESULT_STATUSES[method].failure } : RESULT_STATUSES[method];
     if (!isPlainObject(result)) {
         into.add("result.shape", path, `${method} must answer an object`);
         return into.violations;
@@ -1485,6 +1636,14 @@ export function validateResult(result, method, path = "result") {
         if (method === "openMedia") {
             into.require(isPlainObject(result.session), "result.session", `${path}.session`, "opened carries the media session");
         }
+        if (dials) {
+            if (into.filled(result.dialId, "result.dialId", `${path}.dialId`, "dialling restates the dialId the host sent") && dialId !== undefined) {
+                into.require(result.dialId === dialId, "result.dialId.mismatch", `${path}.dialId`, `the host dialled ${dialId} and the provider answered for ${String(result.dialId)}`);
+            }
+        }
+        else {
+            into.require(result.dialId === undefined, "result.dialId.unexpected", `${path}.dialId`, `${statuses.success} dialled nothing and names no dial`);
+        }
     }
     else if (result.status === statuses.failure) {
         if (result.failure === undefined) {