@xema/omni-protocol 0.1.132 → 0.1.134
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CALL_FLOW.md +1 -1
- package/GLOSSARY.md +5 -4
- package/README.md +4 -4
- package/dist/index.d.ts +100 -58
- package/dist/index.js +12 -6
- package/dist/testing.d.ts +9 -1
- package/dist/testing.js +133 -2
- package/dist/validation.js +63 -24
- package/guide/agent.md +28 -19
- package/guide/breaks.md +362 -25
- package/guide/chat.md +1 -1
- package/guide/lead.md +19 -15
- package/guide/phone.md +8 -7
- package/guide/queue.md +2 -292
- package/guide/voice.md +6 -6
- package/guide.md +90 -69
- package/package.json +1 -1
package/dist/testing.js
CHANGED
|
@@ -23,6 +23,7 @@ const STATE_SUBJECTS = [
|
|
|
23
23
|
"task.locked",
|
|
24
24
|
"break.reasons",
|
|
25
25
|
"break.forced",
|
|
26
|
+
"break.forced.signIn",
|
|
26
27
|
"team.members",
|
|
27
28
|
"team.request",
|
|
28
29
|
"team.tasks",
|
|
@@ -729,6 +730,100 @@ export async function testAdapter(adapter, context, options = {}) {
|
|
|
729
730
|
const restated = await connection.setCapacity({ count });
|
|
730
731
|
violations.push(...validateResult(restated, "setCapacity", "connection.setCapacity"));
|
|
731
732
|
}
|
|
733
|
+
// A forced break outlives the session: the agent signs out and in again and finds it waiting,
|
|
734
|
+
// or signing out would undo any forced break. Its time left runs on while a team break's
|
|
735
|
+
// members are away, and stands still for an agent's own.
|
|
736
|
+
if (options.signInAgain !== undefined && clientLive) {
|
|
737
|
+
const refuse = (rule, path, message) => violations.push({ rule, path, message });
|
|
738
|
+
const fresh = await connection.snapshot();
|
|
739
|
+
const readAt = Date.now();
|
|
740
|
+
const before = isRecord(fresh) && isRecord(fresh.break) ? fresh.break : undefined;
|
|
741
|
+
const forced = before !== undefined && isRecord(before.forced) ? before.forced : undefined;
|
|
742
|
+
if (before !== undefined && forced !== undefined) {
|
|
743
|
+
seen.add("break.forced.signIn");
|
|
744
|
+
ruleTested("test.signIn.rejected");
|
|
745
|
+
let clean = true;
|
|
746
|
+
try {
|
|
747
|
+
unsubscribe?.();
|
|
748
|
+
}
|
|
749
|
+
catch {
|
|
750
|
+
clean = false;
|
|
751
|
+
}
|
|
752
|
+
unsubscribe = undefined;
|
|
753
|
+
try {
|
|
754
|
+
await connection.disconnect();
|
|
755
|
+
}
|
|
756
|
+
catch {
|
|
757
|
+
clean = false;
|
|
758
|
+
}
|
|
759
|
+
try {
|
|
760
|
+
const out = await authentication.signOut();
|
|
761
|
+
ruleTested("test.signIn.signOut");
|
|
762
|
+
if (!isRecord(out) || out.status !== "applied")
|
|
763
|
+
refuse("test.signIn.signOut", "test.signIn.signOut", `the agent's Sign out on a forced break answered ${JSON.stringify(out)}: the run cannot sign in again from a session that would not end`);
|
|
764
|
+
}
|
|
765
|
+
catch {
|
|
766
|
+
clean = false;
|
|
767
|
+
}
|
|
768
|
+
try {
|
|
769
|
+
await authentication.close();
|
|
770
|
+
}
|
|
771
|
+
catch {
|
|
772
|
+
clean = false;
|
|
773
|
+
}
|
|
774
|
+
clientLive = false;
|
|
775
|
+
if (!clean)
|
|
776
|
+
refuse("test.signIn.rejected", "test.signIn", "signing out on a forced break threw: an unsubscribe, disconnect(), signOut() or close() failed");
|
|
777
|
+
const outAt = Date.now();
|
|
778
|
+
try {
|
|
779
|
+
const again = options.signInAgain();
|
|
780
|
+
const session = await again.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
|
|
781
|
+
try {
|
|
782
|
+
const state = await session.state();
|
|
783
|
+
ruleTested("test.signIn.session");
|
|
784
|
+
if (!(isRecord(state) && state.status === "authenticated" && isRecord(state.identity) && state.identity.id === current().identity.id)) {
|
|
785
|
+
refuse("test.signIn.session", "test.signIn.session", `signed in again, the session says ${String(isRecord(state) ? state.status : state)}; the run needs ${String(current().identity.id)} authenticated to see the break`);
|
|
786
|
+
}
|
|
787
|
+
else {
|
|
788
|
+
const inAt = Date.now();
|
|
789
|
+
const reconnecting = connectingReports(connected, violations);
|
|
790
|
+
let second;
|
|
791
|
+
try {
|
|
792
|
+
second = await again.connect(reconnecting.context);
|
|
793
|
+
}
|
|
794
|
+
finally {
|
|
795
|
+
reconnecting.settled();
|
|
796
|
+
}
|
|
797
|
+
try {
|
|
798
|
+
const after = await second.snapshot();
|
|
799
|
+
const gotAt = Date.now();
|
|
800
|
+
await snapshotRead(second, after, "test.signIn.snapshot");
|
|
801
|
+
violations.push(...forcedBreakCarried(before, forced, after, { readAt, outAt, inAt, gotAt }));
|
|
802
|
+
}
|
|
803
|
+
finally {
|
|
804
|
+
try {
|
|
805
|
+
await second.disconnect();
|
|
806
|
+
}
|
|
807
|
+
catch {
|
|
808
|
+
refuse("test.signIn.rejected", "test.signIn", "disconnecting the signed-in-again client threw");
|
|
809
|
+
}
|
|
810
|
+
}
|
|
811
|
+
}
|
|
812
|
+
}
|
|
813
|
+
finally {
|
|
814
|
+
try {
|
|
815
|
+
await session.close();
|
|
816
|
+
}
|
|
817
|
+
catch {
|
|
818
|
+
refuse("test.signIn.rejected", "test.signIn", "closing the signed-in-again session threw");
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
}
|
|
822
|
+
catch (error) {
|
|
823
|
+
refuse("test.signIn.rejected", "test.signIn", `signing in again rejected rather than answered: ${String(error)}`);
|
|
824
|
+
}
|
|
825
|
+
}
|
|
826
|
+
}
|
|
732
827
|
}
|
|
733
828
|
finally {
|
|
734
829
|
let clean = true;
|
|
@@ -2293,8 +2388,8 @@ async function testOneCall(call) {
|
|
|
2293
2388
|
// A request goes not-requested -> awaiting-approval | granted; a commit goes granted ->
|
|
2294
2389
|
// starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
|
|
2295
2390
|
// a cancel or an explicit agent end goes back to not-requested; a lead lifting forced status
|
|
2296
|
-
// preserves the committed break. A forced break arrives on-break
|
|
2297
|
-
//
|
|
2391
|
+
// preserves the committed break. A forced break arrives on-break with `forced`, and never goes
|
|
2392
|
+
// back to not-requested while it is forced. Nothing else is a move the guide describes.
|
|
2298
2393
|
/** What a stream has said about the agent's break, and the moves it may not make. */
|
|
2299
2394
|
/**
|
|
2300
2395
|
* The team as the events left it: whole on `team-updated` and on any snapshot carrying one, then
|
|
@@ -2417,6 +2512,42 @@ export function assertAudioFollowsTheTask(envelopes, snapshot) {
|
|
|
2417
2512
|
envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
|
|
2418
2513
|
assertNoViolations(found, "The audio follows the task");
|
|
2419
2514
|
}
|
|
2515
|
+
/**
|
|
2516
|
+
* The break the agent signed out on, held to the one the next session carries: the same forced
|
|
2517
|
+
* break, from the same person, on the same reason, with what is left of its time by its kind's
|
|
2518
|
+
* clock -- a team break's ran on while the agent was away, an agent's own stood still. Each bound
|
|
2519
|
+
* allows a second of rounding at either end.
|
|
2520
|
+
*/
|
|
2521
|
+
function forcedBreakCarried(before, forced, after, at) {
|
|
2522
|
+
const found = [];
|
|
2523
|
+
const left = typeof forced.endsInSeconds === "number" ? forced.endsInSeconds : undefined;
|
|
2524
|
+
const whole = Math.floor((at.gotAt - at.readAt) / 1000);
|
|
2525
|
+
// A team break that could have run out while the agent was away may rightly be gone.
|
|
2526
|
+
if (forced.scope === "team" && left !== undefined && left - whole <= 1)
|
|
2527
|
+
return found;
|
|
2528
|
+
ruleTested("test.signIn.forcedBreak");
|
|
2529
|
+
const now = isRecord(after) && isRecord(after.break) ? after.break : undefined;
|
|
2530
|
+
const carried = now !== undefined && isRecord(now.forced) ? now.forced : undefined;
|
|
2531
|
+
if (carried === undefined || !(now.status === "on-break" || now.status === "starting-after-task")
|
|
2532
|
+
|| carried.by !== forced.by || carried.scope !== forced.scope || now.activeReasonId !== before.activeReasonId) {
|
|
2533
|
+
found.push({ rule: "test.signIn.forcedBreak", path: "test.signIn.snapshot.break",
|
|
2534
|
+
message: `the agent signed out on a ${String(forced.scope)} break forced by ${String(forced.by)}, and the next session's snapshot carries ${carried === undefined ? "no forced break" : `a break forced by ${String(carried.by)}, ${String(carried.scope)}, on ${String(now.activeReasonId)}`}: signing out ends the session, not the break` });
|
|
2535
|
+
return found;
|
|
2536
|
+
}
|
|
2537
|
+
ruleTested("test.signIn.endsInSeconds");
|
|
2538
|
+
const leftNow = typeof carried.endsInSeconds === "number" ? carried.endsInSeconds : undefined;
|
|
2539
|
+
const signedIn = Math.ceil(((at.outAt - at.readAt) + (at.gotAt - at.inAt)) / 1000);
|
|
2540
|
+
const fault = left === undefined
|
|
2541
|
+
? (leftNow === undefined ? undefined : `it had no end and now ends in ${leftNow}s`)
|
|
2542
|
+
: leftNow === undefined ? `it had ${left}s left and now states none`
|
|
2543
|
+
: leftNow > left ? `it had ${left}s left and now has ${leftNow}s: time left never grows`
|
|
2544
|
+
: forced.scope === "team" && leftNow > left - whole + 1 ? `it had ${left}s left, ${whole}s passed, and it has ${leftNow}s: a team break's time runs on while the agent is away`
|
|
2545
|
+
: forced.scope === "agent" && leftNow < left - signedIn - 1 ? `it had ${left}s left, the agent was signed in for ${signedIn}s of it, and it has ${leftNow}s: an agent's own break counts only while they are signed in`
|
|
2546
|
+
: undefined;
|
|
2547
|
+
if (fault !== undefined)
|
|
2548
|
+
found.push({ rule: "test.signIn.endsInSeconds", path: "test.signIn.snapshot.break.forced.endsInSeconds", message: fault });
|
|
2549
|
+
return found;
|
|
2550
|
+
}
|
|
2420
2551
|
/** The store as handed to the adapter, and the keys it holds at any moment, seen rather than reported. */
|
|
2421
2552
|
function watchStore(store) {
|
|
2422
2553
|
const held = new Set();
|
package/dist/validation.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
// Each list is pinned to its type both ways -- a member the type lacks, or a member the list
|
|
10
10
|
// lacks, fails to compile -- so what the validators accept cannot drift from what the
|
|
11
11
|
// declarations say.
|
|
12
|
-
import { RECORDING_ACTIONS, 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";
|
|
12
|
+
import { RECORDING_ACTIONS, LEAD_COMMAND_CAPABILITY, SHIFT_EVENT_KINDS, SHIFT_FIGURES, FORCED_BREAK_SCOPES, 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") {
|
|
@@ -59,7 +59,7 @@ const TEAM_AVAILABILITIES = membersOf({
|
|
|
59
59
|
});
|
|
60
60
|
const HISTORY_STEPS = membersOf({
|
|
61
61
|
arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, added: true, unanswered: true,
|
|
62
|
-
"callback-requested": true,
|
|
62
|
+
"connected-back": true, "callback-requested": true,
|
|
63
63
|
});
|
|
64
64
|
const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
|
|
65
65
|
const CUSTOM_UI_PLACEMENTS = membersOf({ primary: true, secondary: true, overflow: true });
|
|
@@ -1040,8 +1040,8 @@ function validateHistory(value, path, into, task = {}) {
|
|
|
1040
1040
|
}
|
|
1041
1041
|
if (entry.by !== undefined) {
|
|
1042
1042
|
into.require(isUserId(entry.by), "task.history.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
|
|
1043
|
-
// On `arrived`, `self-service` and `queued` nobody takes part,
|
|
1044
|
-
into.require(entry.step !== "arrived" && entry.step !== "self-service" && entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
|
|
1043
|
+
// On `arrived`, `self-service` and `queued` nobody takes part, and a queue callback is the caller's own choice.
|
|
1044
|
+
into.require(entry.step !== "arrived" && entry.step !== "self-service" && entry.step !== "queued" && entry.step !== "callback-requested", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
|
|
1045
1045
|
}
|
|
1046
1046
|
// A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
|
|
1047
1047
|
const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);
|
|
@@ -1417,11 +1417,14 @@ function validateForcedBreak(value, path, into) {
|
|
|
1417
1417
|
}
|
|
1418
1418
|
into.require(isUserId(value.by) || value.by === "provider", "break.forced.by", `${path}.by`, "a forced break says who forced it: the lead by user id, or provider where the platform did");
|
|
1419
1419
|
for (const field of ["endsAutomatically", "endsAt"]) {
|
|
1420
|
-
into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "
|
|
1420
|
+
into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "the end is endsInSeconds, counted from each publication; after it the agent resumes by their own choice");
|
|
1421
1421
|
}
|
|
1422
|
-
into.
|
|
1423
|
-
|
|
1424
|
-
|
|
1422
|
+
into.oneOf(value.scope, FORCED_BREAK_SCOPES, "break.forced.scope", `${path}.scope`);
|
|
1423
|
+
into.require(value.scope !== "team" || value.endsInSeconds !== undefined, "break.forced.team.endsInSeconds", `${path}.endsInSeconds`, "a team break always has an end: state endsInSeconds on every publication, and lift the break when it runs out");
|
|
1424
|
+
into.require(!Object.hasOwn(value, "expectedEndsInSeconds"), "break.forced.expectedEndsInSeconds.renamed", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is now endsInSeconds: the break is lifted when it runs out");
|
|
1425
|
+
into.require(!Object.hasOwn(value, "expectedDurationMs"), "break.forced.expectedDurationMs.renamed", `${path}.expectedDurationMs`, "the state says how long is left, as endsInSeconds; the duration asked for travels on the lead's command alone");
|
|
1426
|
+
if (value.endsInSeconds !== undefined)
|
|
1427
|
+
into.require(isDurationSeconds(value.endsInSeconds), "break.forced.endsInSeconds", `${path}.endsInSeconds`, "endsInSeconds is how long the break has left: a whole number of seconds, zero or more, counted from this publication");
|
|
1425
1428
|
}
|
|
1426
1429
|
/** Checks break status against the full currently retained task set, after a transaction. */
|
|
1427
1430
|
export function validateBreakStatus(state, tasks, path = "snapshot") {
|
|
@@ -1475,7 +1478,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1475
1478
|
const allowed = {
|
|
1476
1479
|
"lead-features": ["type", "enabled"],
|
|
1477
1480
|
"decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
|
|
1478
|
-
"force-break": ["type", "memberId", "reasonId", "reason", "
|
|
1481
|
+
"force-break": ["type", "memberId", "reasonId", "reason", "durationSeconds"], "end-forced-break": ["type", "memberId"],
|
|
1482
|
+
"force-team-break": ["type", "reasonId", "reason", "durationSeconds"], "end-team-break": ["type"],
|
|
1479
1483
|
join: member, decline: [...member, "reason"], listen: member, coach: member, "join-call": member, leave: member, "take-over-call": member,
|
|
1480
1484
|
"set-policy": ["type", "capability", "setting"],
|
|
1481
1485
|
};
|
|
@@ -1494,6 +1498,16 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1494
1498
|
into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
|
|
1495
1499
|
for (const key of Object.keys(command))
|
|
1496
1500
|
into.require(fields.includes(key), "team.command.field", `${path}.${key}`, "field is not supported for this command");
|
|
1501
|
+
if (command.type === "force-break" || command.type === "force-team-break") {
|
|
1502
|
+
into.require(!Object.hasOwn(command, "expectedDurationSeconds"), "team.command.expectedDurationSeconds.renamed", `${path}.expectedDurationSeconds`, "expectedDurationSeconds is now durationSeconds: the break is lifted when it runs out");
|
|
1503
|
+
if (command.durationSeconds !== undefined || command.type === "force-team-break")
|
|
1504
|
+
into.require(isDurationSeconds(command.durationSeconds) && command.durationSeconds > 0, "team.command.durationSeconds", `${path}.durationSeconds`, "durationSeconds must be a whole number of seconds, more than zero; a team break always states one");
|
|
1505
|
+
if (command.reasonId !== undefined)
|
|
1506
|
+
into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
|
|
1507
|
+
}
|
|
1508
|
+
// A team break names no member: the provider rechecks its reason codes and whether one is running.
|
|
1509
|
+
if (command.type === "force-team-break" || command.type === "end-team-break")
|
|
1510
|
+
return into.violations;
|
|
1497
1511
|
if (command.reason !== undefined)
|
|
1498
1512
|
into.filled(command.reason, "team.command.reason", path, "reason must not be empty");
|
|
1499
1513
|
if (command.type === "lead-features") {
|
|
@@ -1536,10 +1550,6 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1536
1550
|
into.require(!(isPlainObject(state.forced) && state.forced.by === "provider"), "team.command.endForcedBreak.provider", path, "the platform put this member on the break, and it lifts it: a lead ends a break a lead forced");
|
|
1537
1551
|
}
|
|
1538
1552
|
if (command.type === "force-break") {
|
|
1539
|
-
if (command.expectedDurationMs !== undefined)
|
|
1540
|
-
into.require(typeof command.expectedDurationMs === "number" && Number.isFinite(command.expectedDurationMs) && command.expectedDurationMs > 0, "team.command.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be positive finite milliseconds; it never resumes the agent");
|
|
1541
|
-
if (command.reasonId !== undefined)
|
|
1542
|
-
into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
|
|
1543
1553
|
const reasons = Array.isArray(state.reasons) ? state.reasons : [];
|
|
1544
1554
|
into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.command.reasonId", path, "force-break uses the target's currently published reason codes");
|
|
1545
1555
|
}
|
|
@@ -1605,7 +1615,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1605
1615
|
into.require(status === "awaiting-approval" || status === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
|
|
1606
1616
|
if (method === "endBreak") {
|
|
1607
1617
|
into.require(status === "starting-after-task" || status === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
|
|
1608
|
-
|
|
1618
|
+
into.require(state.forced === undefined, "break.command.end.forced", path, "a forced break is not the agent's to end: it ends only when it is lifted");
|
|
1609
1619
|
}
|
|
1610
1620
|
}
|
|
1611
1621
|
return into.violations;
|
|
@@ -1629,6 +1639,9 @@ export function validateBreakTransition(before, after, path = "break") {
|
|
|
1629
1639
|
if (committed && (from === "not-requested" || from === "awaiting-approval") && after.forced === undefined) {
|
|
1630
1640
|
into.add("stream.breakState.commitBeforeGrant", `${path}.after.status`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
|
|
1631
1641
|
}
|
|
1642
|
+
if (before.forced !== undefined && from !== "not-requested" && to === "not-requested") {
|
|
1643
|
+
into.add("stream.breakState.forcedEnded", `${path}.after.status`, "a forced break is lifted first, clearing forced, before the break can end");
|
|
1644
|
+
}
|
|
1632
1645
|
const backwards = (from === "on-break" && (to === "awaiting-approval" || to === "granted" || to === "starting-after-task")) ||
|
|
1633
1646
|
(from === "starting-after-task" && (to === "awaiting-approval" || to === "granted")) ||
|
|
1634
1647
|
(from === "granted" && to === "awaiting-approval");
|
|
@@ -1656,9 +1669,11 @@ function validateBreakState(value, path, into) {
|
|
|
1656
1669
|
if (value.requestUnavailableReason !== undefined) {
|
|
1657
1670
|
into.require(value.canRequestBreak !== true, "break.requestUnavailableReason.canRequestBreak", `${path}.requestUnavailableReason`, "requestUnavailableReason is shown when canRequestBreak is false; omit it while the agent may ask");
|
|
1658
1671
|
}
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1672
|
+
for (const old of ["retryAfterMs", "retryRequestAfterMs"]) {
|
|
1673
|
+
into.require(!Object.hasOwn(value, old), "break.retryRequestInSeconds.renamed", `${path}.${old}`, `${old} is now retryRequestInSeconds on BreakState: whole seconds, as every countdown on this wire`);
|
|
1674
|
+
}
|
|
1675
|
+
if (value.retryRequestInSeconds !== undefined) {
|
|
1676
|
+
into.require(isDurationSeconds(value.retryRequestInSeconds), "break.retryRequestInSeconds", `${path}.retryRequestInSeconds`, "retryRequestInSeconds must be a whole number of seconds, zero or more, when present");
|
|
1662
1677
|
}
|
|
1663
1678
|
if (value.activeReasonId !== undefined) {
|
|
1664
1679
|
into.filled(value.activeReasonId, "break.activeReasonId", `${path}.activeReasonId`, "activeReasonId must not be empty when present");
|
|
@@ -2428,10 +2443,29 @@ function validateShiftInto(value, path, into, rule) {
|
|
|
2428
2443
|
}
|
|
2429
2444
|
for (const field of ["talkSeconds", "holdSeconds", "breakSeconds"]) {
|
|
2430
2445
|
if (value[field] !== undefined)
|
|
2431
|
-
into.require(isDurationSeconds(value[field]),
|
|
2446
|
+
into.require(isDurationSeconds(value[field]), `${rule}.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
|
|
2432
2447
|
}
|
|
2433
2448
|
if (value.tasksHandled !== undefined)
|
|
2434
2449
|
into.require(Number.isInteger(value.tasksHandled) && value.tasksHandled >= 0, `${rule}.tasksHandled`, `${path}.tasksHandled`, "tasksHandled must be a whole number, zero or more, or omitted when unknown");
|
|
2450
|
+
if (value.running !== undefined) {
|
|
2451
|
+
if (!Array.isArray(value.running)) {
|
|
2452
|
+
into.add(`${rule}.running.shape`, `${path}.running`, "running must be an array when present");
|
|
2453
|
+
}
|
|
2454
|
+
else {
|
|
2455
|
+
const seen = new Set();
|
|
2456
|
+
value.running.forEach((entry, index) => {
|
|
2457
|
+
const at = `${path}.running[${index}]`;
|
|
2458
|
+
if (!isPlainObject(entry)) {
|
|
2459
|
+
into.add(`${rule}.running.shape`, at, "each running stretch must be an object");
|
|
2460
|
+
return;
|
|
2461
|
+
}
|
|
2462
|
+
into.oneOf(entry.figure, SHIFT_FIGURES, `${rule}.running.figure`, `${at}.figure`);
|
|
2463
|
+
into.timestamp(entry.since, `${rule}.running.since`, `${at}.since`);
|
|
2464
|
+
into.require(!seen.has(entry.figure), `${rule}.running.duplicate`, `${at}.figure`, `${String(entry.figure)} is already running: a figure has one running stretch at a time`);
|
|
2465
|
+
seen.add(entry.figure);
|
|
2466
|
+
});
|
|
2467
|
+
}
|
|
2468
|
+
}
|
|
2435
2469
|
if (value.events !== undefined) {
|
|
2436
2470
|
if (!Array.isArray(value.events)) {
|
|
2437
2471
|
into.add(`${rule}.events.shape`, `${path}.events`, "events must be an array when present");
|
|
@@ -3096,22 +3130,27 @@ export function validateUserDetails(users, asked, path = "getUserDetails") {
|
|
|
3096
3130
|
}
|
|
3097
3131
|
users.forEach((user, index) => {
|
|
3098
3132
|
const at = `${path}[${index}]`;
|
|
3099
|
-
validateUser(user, "getUserDetails.user", at, into);
|
|
3133
|
+
validateUser(user, "getUserDetails.user", at, into, false);
|
|
3100
3134
|
if (isPlainObject(user) && typeof user.id === "string") {
|
|
3101
3135
|
into.require(asked.includes(user.id), "getUserDetails.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
|
|
3102
3136
|
}
|
|
3103
3137
|
});
|
|
3104
3138
|
return into.violations;
|
|
3105
3139
|
}
|
|
3106
|
-
function validateUser(value, rule, path, into) {
|
|
3140
|
+
function validateUser(value, rule, path, into, signedIn) {
|
|
3107
3141
|
if (!isPlainObject(value)) {
|
|
3108
3142
|
into.add(rule, path, "an identity must be an object");
|
|
3109
3143
|
return;
|
|
3110
3144
|
}
|
|
3111
3145
|
into.require(isUserId(value.id), `${rule}.id`, `${path}.id`, "an identity needs a provider-issued user id");
|
|
3112
3146
|
into.filled(value.displayName, `${rule}.displayName`, `${path}.displayName`, "an identity needs a display name");
|
|
3113
|
-
|
|
3114
|
-
|
|
3147
|
+
if (signedIn) {
|
|
3148
|
+
// Never absent: the host stated the zone at authentication, before this identity existed.
|
|
3149
|
+
into.require(isTimeZone(value.timeZone), `${rule}.timeZone`, `${path}.timeZone`, "the signed-in identity carries the session's time zone as an IANA name, such as Asia/Kolkata; the host stated it at authentication");
|
|
3150
|
+
}
|
|
3151
|
+
else if (value.timeZone !== undefined) {
|
|
3152
|
+
into.require(isTimeZone(value.timeZone), `${rule}.timeZone`, `${path}.timeZone`, "a described user's time zone, where the provider knows it, is an IANA name, such as Asia/Kolkata");
|
|
3153
|
+
}
|
|
3115
3154
|
}
|
|
3116
3155
|
function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
3117
3156
|
if (!isPlainObject(value)) {
|
|
@@ -3285,12 +3324,12 @@ export function validateAuthenticationState(state, path, context) {
|
|
|
3285
3324
|
// Only `authenticated` may carry an expiry, and only the states that know who the agent is
|
|
3286
3325
|
// may carry an identity. Anything else is a state claiming knowledge it does not have.
|
|
3287
3326
|
if (state.status === "authenticated" || state.status === "refreshing") {
|
|
3288
|
-
validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
|
|
3327
|
+
validateUser(state.identity, "authentication.identity", `${path}.identity`, into, true);
|
|
3289
3328
|
validateUserCapabilitiesInto(state.capabilities, `${path}.capabilities`, into, context.levels);
|
|
3290
3329
|
}
|
|
3291
3330
|
else if (state.status === "expired" || state.status === "terminated") {
|
|
3292
3331
|
if (state.identity !== undefined)
|
|
3293
|
-
validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
|
|
3332
|
+
validateUser(state.identity, "authentication.identity", `${path}.identity`, into, true);
|
|
3294
3333
|
if (state.failure !== undefined) {
|
|
3295
3334
|
validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
|
|
3296
3335
|
}
|
package/guide/agent.md
CHANGED
|
@@ -122,7 +122,7 @@ A preview's deadline is not on the offer. It travels on the task, as `previewEnd
|
|
|
122
122
|
A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome, `by:
|
|
123
123
|
"provider"`. **`cancelled` says who called the work off**, as `completed` says who completed it:
|
|
124
124
|
`agent` for a decline, `provider` for a withdrawal or a re-route, `party` for a caller who abandoned
|
|
125
|
-
the ring. One word for the three left a
|
|
125
|
+
the ring. One word for the three left a lead's record unable to tell them apart, so `by` is
|
|
126
126
|
required and closed (`event.taskEnded.outcome.cancelled.by`). An offer nobody acted on while
|
|
127
127
|
`expiresInSeconds` ran is not cancelled by anyone: it lapses, and ends `expired` naming `pending`.
|
|
128
128
|
|
|
@@ -372,7 +372,9 @@ Migration from the earlier spellings:
|
|
|
372
372
|
| schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`test.schedule.unsettled`) |
|
|
373
373
|
| a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
|
|
374
374
|
| end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
|
|
375
|
-
|
|
|
375
|
+
| endBreak on a forced break, Resume offered on one | refused: `break.command.end.forced`, `omni.break-forced`; no Resume while `forced` stands; a sign-out keeps it, and the next session's snapshot carries it again |
|
|
376
|
+
| ForcedBreak.expectedDurationMs, then expectedEndsInSeconds | `endsInSeconds`: seconds left, restated, and the break is lifted when it runs out (`break.forced.endsInSeconds`, `.expectedDurationMs.renamed`, `.expectedEndsInSeconds.renamed`); the command's is `durationSeconds` (`team.command.expectedDurationSeconds.renamed`) |
|
|
377
|
+
| a forced break with no scope | `scope`: `team` to one end for all, or `agent`, counted while signed in (`break.forced.scope`, `break.forced.team.endsInSeconds`); `force-team-break` and `end-team-break` for the team |
|
|
376
378
|
| MemberShift; the day on the lead's list alone | `Shift`, on `Snapshot.shift` and `shift-updated` for the agent, on `TeamMember.shift` for the lead |
|
|
377
379
|
| TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
|
|
378
380
|
| a member's history trimmed on the lead's list | the record whole, as the member's computer holds it |
|
|
@@ -384,7 +386,7 @@ Migration from the earlier spellings:
|
|
|
384
386
|
| the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
|
|
385
387
|
| the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
|
|
386
388
|
| a harness that exercised an adapter, drove a call and evaluated rules | the harness reads as a test: `testAdapter`, `withCall`, `timeoutMs`, `notTested`, `rulesTested`, rules `test.*` (`test.timeout`, `test.offer.expired`, `test.preview.deadline`, ...) |
|
|
387
|
-
| a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step (`by`
|
|
389
|
+
| a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step, never with `by` (`task.history.by.unexpected`); a callback's task carries the earlier call's steps, oldest first |
|
|
388
390
|
| a recording state with an observation id, an observation instant and a validity window, and the helpers that aged it | `recordings` on the task and on `HostRecordingReport`: a list, each recording with `id`, `follows` (`party` or `agent`), `status` (`starting`, `recording`, `paused`, `not-recording`, `unknown`) and a `reason` where paused or unknown; nothing expires; commands name `follows` for a start and `recordingId` otherwise; `validateRecordings` (`recording.task.renamed` refuses the former field) |
|
|
389
391
|
| a refusal on hold under `omni.command-not-permitted` | `omni.on-hold` |
|
|
390
392
|
| outbound work's terms reported as `queue` | `dialer`: the dialer that declared the task chose its capabilities |
|
|
@@ -432,7 +434,7 @@ something else, which will arrive under its own name and must not be folded in h
|
|
|
432
434
|
It rides in the snapshot and is replaced whole like everything else there.
|
|
433
435
|
|
|
434
436
|
Steps are `arrived`, `self-service`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `added`,
|
|
435
|
-
`unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
|
|
437
|
+
`unanswered`, `connected-back`, `callback-requested`, and each is defined on `TaskHistoryStep`.
|
|
436
438
|
|
|
437
439
|
**The record starts where the call started.** `arrived` is the instant the call reached the
|
|
438
440
|
provider, before any menu or queue, and its `seconds`, when the provider measured them, are how
|
|
@@ -454,13 +456,20 @@ part, so it has no `by`. `at` is when it began and `seconds`, once it ended, how
|
|
|
454
456
|
customer routed again after a transfer has a second entry, one per visit, as a second queue is a
|
|
455
457
|
second `queued`. A customer that words it *IVR* for its agents does so in `labels.historySteps`.
|
|
456
458
|
|
|
457
|
-
**A
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
459
|
+
**A reconnect is a dial on the same call.** When the agent dials a dropped caller back into the same
|
|
460
|
+
interaction -- the `connect-back` command, shown as *Reconnect* -- the provider writes a
|
|
461
|
+
`connected-back` step: `by` is the agent, `dialId` the command's, and `contactId` the contact dialled
|
|
462
|
+
where the provider has one. A reconnect that rings out reads as any dial does: its outcome, and an
|
|
463
|
+
`unanswered` step.
|
|
464
|
+
|
|
465
|
+
**A queue callback carries the call it comes back to.** When a waiting caller asks to be called back
|
|
466
|
+
once an agent is free, the provider writes a `callback-requested` step. It is the caller's own choice,
|
|
467
|
+
so it never names anyone (`task.history.by.unexpected`). The callback reaches an agent as a new task,
|
|
468
|
+
and that task's history carries the earlier call's steps, oldest first, the `callback-requested` step
|
|
469
|
+
among them, then the callback's own -- as a hand-over carries the steps before it. The agent opening a
|
|
470
|
+
callback sees that the caller waited and asked, and a second try reads as one, the way contact-centre
|
|
471
|
+
platforms keep a callback with its original contact. A call booked for later is a scheduled call: the
|
|
472
|
+
`schedule` command, on the calendar, and never a `callback-requested` step.
|
|
464
473
|
|
|
465
474
|
**One call has one history.** Every task the call reaches restates the earlier steps exactly as they
|
|
466
475
|
stood: the same step, instant, person, dial and destination, and a duration once stated never
|
|
@@ -982,8 +991,8 @@ Every task may publish additional provider-specific controls in `capabilities.cu
|
|
|
982
991
|
capabilities: {
|
|
983
992
|
hold: true,
|
|
984
993
|
custom: [
|
|
985
|
-
{ id: "
|
|
986
|
-
{ id: "mark-vip", ui: { control: "toggle", label: "Mark as VIP", placement: "overflow" } },
|
|
994
|
+
{ id: "send-survey", ui: { control: "button", label: "Send survey", placement: "secondary", render: "inline" } },
|
|
995
|
+
{ id: "mark-vip", ui: { control: "toggle", label: "Mark as VIP", placement: "overflow", render: "inline" } },
|
|
987
996
|
],
|
|
988
997
|
}
|
|
989
998
|
```
|
|
@@ -1002,7 +1011,7 @@ control and invokes it with the shared custom task command:
|
|
|
1002
1011
|
```ts
|
|
1003
1012
|
{
|
|
1004
1013
|
type: "custom",
|
|
1005
|
-
name: "
|
|
1014
|
+
name: "send-survey",
|
|
1006
1015
|
}
|
|
1007
1016
|
```
|
|
1008
1017
|
|
|
@@ -1048,23 +1057,22 @@ The one thing the agent application performs physically is the microphone, and t
|
|
|
1048
1057
|
|
|
1049
1058
|
### Which commands need a capability
|
|
1050
1059
|
|
|
1051
|
-
**Presence is the permission** gates the controls a provider chooses to offer.
|
|
1052
|
-
|
|
1053
|
-
declared:
|
|
1060
|
+
**Presence is the permission** gates the controls a provider chooses to offer. Each command below
|
|
1061
|
+
is authorized by what the provider declared, or by the phase it is issued in:
|
|
1054
1062
|
|
|
1055
1063
|
| Command | What makes it available |
|
|
1056
1064
|
| --- | --- |
|
|
1057
1065
|
| `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
|
|
1058
1066
|
| `end-call` | The `endCall` capability: ends my part, the caller continues. Never from hold: a `paused` task is resumed first (`command.endCall.held`), or the caller is left in the hold. |
|
|
1059
1067
|
| `terminate-call` | The `terminateCall` capability: ends the whole call, every channel on it. |
|
|
1060
|
-
| `
|
|
1068
|
+
| `remove-from-call` | The `addToCall` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
|
|
1061
1069
|
| `decline` | The `decline` capability on any channel, **and** Omni local policy permitting it. One word for refusing an offer, whatever the channel. |
|
|
1062
1070
|
| `dial` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
|
|
1063
1071
|
| `complete` | A wrap to cut short: any task but a `provider-automatic` one with `wrapAllowance: 0`, under either completion mode (`command.complete.wrapAllowance`). The `outcomes` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.outcome.unknown`), a code at all where it requires one (`.outcome.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no outcomes (`.outcome.unexpected`). |
|
|
1064
1072
|
| `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
|
|
1065
1073
|
| `schedule` | The `schedule` capability, on any channel, in `in-progress`, `paused` or `completing`: a follow-up is promised on the call and written up in wrap alike. The manifest declares `calendar` for it to land on. |
|
|
1066
1074
|
| `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with `stage: "requested"`. |
|
|
1067
|
-
| `
|
|
1075
|
+
| `add-to-call` | The `addToCall` capability, and a `contactId` from the provider's contacts, or a typed `number` where the capability says `any-number` (`command.addToCall.number.contactsOnly`), never both (`command.addToCall.number.both`). |
|
|
1068
1076
|
| `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying a non-empty string for each `required` prompt field and strings for any optional fields supplied (`command.custom.prompt`). A toggle carries its target `on` boolean (`command.custom.on`). |
|
|
1069
1077
|
| Everything else | Its own named capability. |
|
|
1070
1078
|
|
|
@@ -1146,5 +1154,6 @@ react rather than only display the message:
|
|
|
1146
1154
|
| `omni.recording-unsettled` | A recording command the provider could not settle either way: a settled `failed`, never a promise left unresolved. See **Independent task recording** in `guide/voice.md`. |
|
|
1147
1155
|
| `omni.on-hold` | Refused because the caller is on hold: the agent application's own Mute begun on a `paused` task, or `end-call` there. The agent application says resume first. The test expects this code on both (`test.recordStep.held`, `test.command.held`). |
|
|
1148
1156
|
| `omni.break-forced-by-provider` | A lead asked to lift a break the platform imposed; the platform lifts its own. See **Forced breaks** in `guide/breaks.md`. |
|
|
1157
|
+
| `omni.break-forced` | The agent asked to end a break that is still forced. Only lifting it ends it, and signing out does not. See **Forced breaks** in `guide/breaks.md`. |
|
|
1149
1158
|
|
|
1150
1159
|
They are published as `OMNI_FAILURE_CODES`.
|