@xema/omni-protocol 0.1.66 → 0.1.68

package/dist/validation.js

@@ -131,14 +131,33 @@ const isDurationSeconds = (value) => typeof value === "number" && Number.isInteg
 /** Opaque, non-empty, provider-issued. Never parsed and never compared across providers. */
 const isUserId = isFilled;
 const isTaskId = isFilled;
+const isAllocationId = isFilled;
+const ruleListeners = new Set();
+/**
+ * Hears every rule a validator evaluates, pass or fail, until the returned function is called. A
+ * green run can then say which rules it looked at rather than only which subjects it reached: a
+ * rule never evaluated is a visible gap, not a pass. The harness registers one for each exercise.
+ */
+export function observeRules(listener) {
+    ruleListeners.add(listener);
+    return () => { ruleListeners.delete(listener); };
+}
+/** Says a rule was evaluated, for code that decides outside a collector: the stream, the drive. */
+export function ruleEvaluated(...rules) {
+    for (const rule of rules)
+        for (const listener of ruleListeners)
+            listener(rule);
+}
 class Collector {
     violations = [];
     add(rule, path, message) {
+        ruleEvaluated(rule);
         this.violations.push({ rule, path, message });
     }
     require(condition, rule, path, message) {
+        ruleEvaluated(rule);
         if (!condition)
-            this.add(rule, path, message);
+            this.violations.push({ rule, path, message });
         return Boolean(condition);
     }
     filled(value, rule, path, message) {
@@ -198,7 +217,7 @@ export function validateScheduledActivity(activity, path = "scheduledActivity")
     validateScheduledActivityInto(activity, path, into);
     return into.violations;
 }
-function validateScheduledActivityInto(activity, path, into) {
+function validateScheduledActivityInto(activity, path, into, levels) {
     if (!isPlainObject(activity)) {
         into.add("activity.shape", path, "a scheduled activity must be an object");
         return;
@@ -213,7 +232,7 @@ function validateScheduledActivityInto(activity, path, into) {
         }
     }
     if (activity.party !== undefined)
-        validateContactInto(activity.party, `${path}.party`, into);
+        validateContactInto(activity.party, `${path}.party`, into, levels);
     validateAttributes(activity.attributes, `${path}.attributes`, into);
 }
 // ---------------------------------------------------------------------------
@@ -672,7 +691,7 @@ function validateBrowsers(value, path, into) {
         }
     });
 }
-function validateTaskAttributes(value, path, into) {
+function validateTaskAttributes(value, path, into, levels) {
     if (value === undefined)
         return;
     if (!Array.isArray(value)) {
@@ -699,7 +718,7 @@ function validateTaskAttributes(value, path, into) {
                 into.require(typeof attribute.value === "string", "task.attribute.text", `${at}.value`, "a text attribute needs a string value");
                 break;
             case "contact":
-                validateContactInto(attribute.contact, `${at}.contact`, into);
+                validateContactInto(attribute.party, `${at}.party`, into, levels);
                 break;
             case "timestamp":
                 into.timestamp(attribute.at, "task.attribute.timestamp", `${at}.at`);
@@ -791,13 +810,18 @@ 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, path, into) {
+function validateTaskMedia(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`))
         return;
-    into.oneOf(value, TASK_MEDIA_STATES, "task.media", path);
+    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`);
+    }
 }
+const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
 /**
  * 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
@@ -845,9 +869,23 @@ function validateOnCall(value, channel, path, into) {
             if (entry.label !== undefined)
                 into.filled(entry.label, "task.onCall.label", `${at}.label`, "a label must not be empty when present");
         }
+        else if (role === "party" && (entry.dialId !== undefined || entry.stage !== undefined)) {
+            // The party is dialled again on the same task -- a connect-back the host placed, a callback the
+            // platform placed -- and then carries the stage the dial has reached; a dial with no stage is
+            // half a claim, and the host's dialId is present where a host placed it, as on any dialled entry.
+            into.require(entry.stage !== undefined, "task.onCall.party.dial", at, "a party being dialled again carries the stage the dial has reached; the host's dialId beside it where a host placed the dial");
+            if (entry.dialId !== undefined)
+                into.filled(entry.dialId, "task.onCall.dialId", `${at}.dialId`, "dialId must not be empty when present");
+            if (entry.stage !== undefined && into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
+                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");
+            }
+            for (const field of ["destinationId", "label"]) {
+                into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on consulted or conferenced`);
+            }
+        }
         else {
             for (const field of ["destinationId", "dialId", "label", "stage"]) {
-                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(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 consulted or conferenced`);
             }
         }
     });
@@ -904,6 +942,7 @@ function validateMonitoring(value, channel, path, into) {
     }
     into.require(isUserId(value.memberId), "task.monitoring.memberId", `${path}.memberId`, "a monitored call names the member on it");
     into.require(isTaskId(value.taskId), "task.monitoring.taskId", `${path}.taskId`, "a monitored call names the member's task");
+    into.require(isAllocationId(value.allocationId), "task.monitoring.allocationId", `${path}.allocationId`, "a monitored call names the member's task by its allocation too");
     into.oneOf(value.mode, MONITOR_MODES, "task.monitoring.mode", `${path}.mode`);
     into.timestamp(value.since, "task.monitoring.since", `${path}.since`);
 }
@@ -918,6 +957,7 @@ function validateTaskInto(task, context, path, into) {
         return;
     }
     into.require(isTaskId(task.id), "task.id", `${path}.id`, "a task needs a non-empty id");
+    into.require(isAllocationId(task.allocationId), "task.allocationId", `${path}.allocationId`, "a task names this life of itself: an allocation id minted once per offer, never reused for the life of the login");
     into.filled(task.title, "task.title", `${path}.title`, "a task needs a title");
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
     if (into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`) && task.phase === "preview") {
@@ -975,7 +1015,7 @@ function validateTaskInto(task, context, path, into) {
     if (task.party !== undefined)
         validateContactInto(task.party, `${path}.party`, into, context.levels);
     validateBrowsers(task.browsers, `${path}.browsers`, into);
-    validateTaskAttributes(task.attributes, `${path}.attributes`, into);
+    validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
     validateOnCall(task.onCall, context.channel, `${path}.onCall`, into);
     // The room is who is on the call now, and a task outlives its call by the whole of wrap-up: a
@@ -984,7 +1024,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, `${path}.media`, into);
+    validateTaskMedia(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);
@@ -1197,6 +1237,7 @@ function validateTeamRosterInto(roster, path, context, into) {
                     into.require(request.memberId !== context.self, "team.request.self", `${at}.memberId`, "the roster carries the reader's own ask: an agent's request for a lead goes to whoever leads them");
                 }
                 into.require(isTaskId(request.taskId), "team.request.taskId", `${at}.taskId`, "a request names the task the lead would join");
+                into.require(isAllocationId(request.allocationId), "team.request.allocationId", `${at}.allocationId`, "a request names the task by its allocation too");
                 if (request.note !== undefined)
                     into.filled(request.note, "team.request.note", `${at}.note`, "a note must not be empty when present");
                 into.timestamp(request.since, "team.request.since", `${at}.since`);
@@ -1320,7 +1361,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     if (snapshot.contacts !== undefined) {
         into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
         if (Array.isArray(snapshot.contacts)) {
-            snapshot.contacts.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into));
+            snapshot.contacts.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into, levels));
         }
         else {
             into.add("snapshot.contacts.shape", `${path}.contacts`, "contacts must be an array when present");
@@ -1331,7 +1372,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         if (Array.isArray(snapshot.scheduledActivities)) {
             const seen = new Set();
             snapshot.scheduledActivities.forEach((activity, index) => {
-                validateScheduledActivityInto(activity, `${path}.scheduledActivities[${index}]`, into);
+                validateScheduledActivityInto(activity, `${path}.scheduledActivities[${index}]`, into, levels);
                 if (isPlainObject(activity) && isFilled(activity.id)) {
                     if (seen.has(activity.id)) {
                         into.add("activity.id.unique", `${path}.scheduledActivities[${index}].id`, `duplicate activity id: ${activity.id}`);
@@ -1485,12 +1526,15 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskMediaStarted.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
         case "task-media-ended":
             into.require(isTaskId(event.taskId), "event.taskMediaEnded.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskMediaEnded.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
         case "task-ended":
             into.require(isTaskId(event.taskId), "event.taskEnded.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskEnded.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             validateTaskOutcome(event.outcome, `${at}.outcome`, into);
             break;
         case "dial-outcome": {
@@ -1502,6 +1546,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.dialOutcome.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            allocationWithTask(event, "event.dialOutcome", at, into);
             if (event.destinationId !== undefined)
                 into.filled(event.destinationId, "event.dialOutcome.destinationId", `${at}.destinationId`, "a destinationId must not be empty when present");
             if (event.reason !== undefined)
@@ -1522,6 +1567,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             into.filled(event.observed, "event.diagnostic.observed", `${at}.observed`, "a diagnostic states what was observed instead");
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.diagnostic.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            allocationWithTask(event, "event.diagnostic", at, into);
             break;
         case "queue-summary":
             validateQueueSummary(event.summary, `${at}.summary`, into);
@@ -1535,7 +1581,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
             }
             else {
-                event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into));
+                event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
         case "calendar-updated":
@@ -1546,7 +1592,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             else {
                 const ids = new Set();
                 event.scheduledActivities.forEach((activity, index) => {
-                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into);
+                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into, levels);
                     if (isPlainObject(activity) && isFilled(activity.id)) {
                         if (ids.has(activity.id))
                             into.add("activity.id.unique", `${at}.scheduledActivities[${index}].id`, `duplicate activity id: ${activity.id}`);
@@ -1707,6 +1753,7 @@ export function validateHandlingReport(report, path = "handlingReport", manifest
         return into.violations;
     }
     into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
+    into.require(isAllocationId(report.allocationId), "handlingReport.allocationId", `${path}.allocationId`, "a report names the task's allocation, so a late one never lands on the next life of the id");
     into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
     into.timestamp(report.at, "handlingReport.at", `${path}.at`);
     // A muted leg says whose the silence was; no other leg has anyone to name for it.
@@ -1739,6 +1786,15 @@ function validateMutedBy(device, rule, path, into) {
         into.require(device.mutedBy === undefined, `${rule}.mutedBy.unexpected`, `${path}.mutedBy`, "mutedBy says who silenced a device that is not flowing; a flowing one names nobody");
     }
 }
+/** An event that may name a task names its allocation with it, and never an allocation alone. */
+function allocationWithTask(event, rule, at, into) {
+    if (event.taskId !== undefined) {
+        into.require(isAllocationId(event.allocationId), `${rule}.allocationId`, `${at}.allocationId`, "an event that names a task names its allocation too");
+    }
+    else {
+        into.require(event.allocationId === undefined, `${rule}.allocationId.unexpected`, `${at}.allocationId`, "an allocation is named with its task, never alone");
+    }
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {
@@ -1826,6 +1882,22 @@ export function validateTaskCommand(command, task, path = "command") {
         : [...new Set([...TASK_COMMAND_NAMES.voice, ...TASK_COMMAND_NAMES.chat, ...TASK_COMMAND_NAMES.email])];
     if (type === "custom") {
         into.filled(command.name, "command.custom.name", `${path}.name`, "a custom command names the control it presses");
+        if (task === undefined)
+            return into.violations;
+        // Held to the task: the control it presses is one the task published, and what the control asked for travels with it.
+        const custom = isPlainObject(task) && isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+        const control = Array.isArray(custom) ? custom.filter(isPlainObject).find(entry => entry.id === command.name) : undefined;
+        if (control === undefined) {
+            into.add("command.capability.custom", path, `custom ${String(command.name)} presses a control the task never published`);
+            return into.violations;
+        }
+        if (isPlainObject(control.prompt) && Array.isArray(control.prompt.fields)) {
+            for (const field of control.prompt.fields.filter(isPlainObject)) {
+                if (typeof field.name === "string") {
+                    into.require(typeof command[field.name] === "string" && command[field.name].length > 0, "command.custom.prompt", `${path}.${field.name}`, `the control asked for ${field.name} and the command does not carry it`);
+                }
+            }
+        }
         return into.violations;
     }
     if (!into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${String(type)}` : `a ${channel} task has no ${String(type)} command`)) {
@@ -1911,12 +1983,17 @@ export function validateTaskCommand(command, task, path = "command") {
     // to act on yet, and in completing the handling has ended: a call with nobody on it, a
     // conversation closed. What a capability offers, the phase decides whether there is anything to use it on.
     const handling = () => inPhase("command.phase.handling", "in-progress", "paused");
+    // A destination is one the directory offered: the id Omni sends is the id the provider published.
+    const listed = (name) => {
+        const declared = capabilities[name];
+        const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
+        into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${String(command.destinationId)} is not a destination the task's ${name} directory offered`);
+    };
     const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
     switch (type) {
         case "answer":
         case "accept":
         case "decline":
-        case "reject":
             inPhase("command.phase.pending", "pending");
             if (type === "decline")
                 offered("decline");
@@ -1944,10 +2021,14 @@ export function validateTaskCommand(command, task, path = "command") {
             break;
         case "transfer":
             handling();
-            if (command.action === "cold")
-                offered("coldTransfer");
-            else if (command.action === "warm")
-                offered("warmTransfer");
+            if (command.action === "cold") {
+                if (offered("coldTransfer"))
+                    listed("coldTransfer");
+            }
+            else if (command.action === "warm") {
+                if (offered("warmTransfer"))
+                    listed("warmTransfer");
+            }
             else if (command.action === "complete" || command.action === "cancel") {
                 into.require(onCall.some(entry => entry.role === "consulted"), "command.transfer.consulted", path, `${String(command.action)} needs a consulted entry on onCall: without one there is nothing to complete or cancel`);
             }
@@ -1964,9 +2045,12 @@ export function validateTaskCommand(command, task, path = "command") {
                 into.require(task.assisting !== undefined, "command.leadAssist.assisting", path, `${String(command.action)} is the lead's own act on a call they joined: the task carries assisting`);
             }
             break;
-        case "conference":
+        case "conference": {
             handling();
-            if (offered("conference") && command.action === "remove") {
+            const conferencing = offered("conference");
+            if (conferencing && command.action === "add")
+                listed("conference");
+            if (conferencing && command.action === "remove") {
                 const others = onCall.filter(entry => entry.role !== "agent");
                 if (command.party === true) {
                     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");
@@ -1977,9 +2061,32 @@ export function validateTaskCommand(command, task, path = "command") {
                 }
             }
             break;
-        case "complete":
+        }
+        case "complete": {
             into.require(task.completionMode === "agent-command", "command.complete.mode", path, "complete belongs to agent-command; a provider-automatic task completes itself");
+            // What travels with complete is what the dispositions capability published: a code from its
+            // list where it has one, a code at all where it requires one, notes as it said, nothing where it published nothing.
+            const dispositions = capabilities.dispositions;
+            if (dispositions === undefined) {
+                into.require(command.disposition === undefined, "command.complete.disposition.unexpected", `${path}.disposition`, "the task declares no dispositions; complete travels with no code");
+                into.require(command.notes === undefined, "command.complete.notes.unexpected", `${path}.notes`, "the task declares no dispositions; complete travels with no notes");
+            }
+            else if (isPlainObject(dispositions)) {
+                if (Array.isArray(dispositions.codes) && command.disposition !== undefined) {
+                    into.require(dispositions.codes.some(code => isPlainObject(code) && code.id === command.disposition), "command.complete.disposition.unknown", `${path}.disposition`, `${String(command.disposition)} is not a code the task published`);
+                }
+                if (dispositions.required === true) {
+                    into.require(command.disposition !== undefined, "command.complete.disposition.required", `${path}.disposition`, "the task requires a disposition and complete carries none");
+                }
+                if (dispositions.notes === "none") {
+                    into.require(command.notes === undefined, "command.complete.notes.unexpected", `${path}.notes`, "the task takes no notes");
+                }
+                else if (dispositions.notes === "required") {
+                    into.require(typeof command.notes === "string" && command.notes.length > 0, "command.complete.notes.required", `${path}.notes`, "the task requires notes and complete carries none");
+                }
+            }
             break;
+        }
         default:
             break;
     }
@@ -2076,6 +2183,26 @@ export function validateTimeZone(value, path = "context.timeZone") {
     into.require(isTimeZone(value), "context.timeZone", path, "a host states the agent's time zone at connect as an IANA name, such as Asia/Kolkata; an offset cannot survive a daylight-saving boundary");
     return into.violations;
 }
+/**
+ * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
+ * answers somebody nobody asked about.
+ */
+export function validateDescribedUsers(users, asked, path = "describeUsers") {
+    const into = new Collector();
+    if (!Array.isArray(users)) {
+        into.add("describeUsers.shape", path, "describeUsers answers an array of users, empty when it knows none of them");
+        return into.violations;
+    }
+    users.forEach((user, index) => {
+        const at = `${path}[${index}]`;
+        validateUser(user, "describeUsers.user", at, into);
+        if (isPlainObject(user) && typeof user.id === "string") {
+            into.require(asked.includes(user.id), "describeUsers.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
+        }
+    });
+    return into.violations;
+}
 function validateUser(value, rule, path, into) {
     if (!isPlainObject(value)) {
         into.add(rule, path, "an identity must be an object");