@xema/omni-protocol 0.1.131 → 0.1.133
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 +3 -3
- package/README.md +5 -4
- package/dist/index.d.ts +65 -46
- package/dist/index.js +7 -6
- package/dist/validation.js +43 -17
- package/guide/agent.md +25 -19
- package/guide/breaks.md +296 -5
- package/guide/chat.md +1 -1
- package/guide/lead.md +16 -14
- package/guide/phone.md +8 -7
- package/guide/queue.md +2 -292
- package/guide/voice.md +6 -6
- package/guide.md +80 -65
- package/package.json +1 -1
package/CALL_FLOW.md
CHANGED
|
@@ -20,7 +20,7 @@ stateDiagram-v2
|
|
|
20
20
|
in_progress --> paused: hold
|
|
21
21
|
paused --> in_progress: resume
|
|
22
22
|
in_progress --> completing: end call, or the caller hangs up
|
|
23
|
-
completing --> in_progress:
|
|
23
|
+
completing --> in_progress: reconnect
|
|
24
24
|
completing --> [*]: complete (task-ended)
|
|
25
25
|
in_progress --> [*]: completed straight from the call (task-ended)
|
|
26
26
|
|
package/GLOSSARY.md
CHANGED
|
@@ -59,9 +59,9 @@ for orientation only: each platform's own documentation is the authority on its
|
|
|
59
59
|
| **End call** | End the agent's part. The caller carries on to wherever the provider sends them, such as a survey. | *Leave*, *drop*, *hang up* (agent leg only). |
|
|
60
60
|
| **Terminate call** | End the whole call for everyone. | *Disconnect all*, *end conversation*. |
|
|
61
61
|
| **Add to call** | Bring someone onto the call while the agent stays; they leave when the agent ends their part. | *Conference*, *add participant*, *three-way call*. |
|
|
62
|
-
| **
|
|
63
|
-
| **Schedule** |
|
|
64
|
-
| **Callback requested** |
|
|
62
|
+
| **Reconnect** | Dial a dropped customer back into the same call, during the wrap: `connect-back` on the wire. | *Callback from wrap*, *re-dial*. |
|
|
63
|
+
| **Schedule** | Book a scheduled call with this customer, on the calendar. | *Scheduled callback* (Amazon Connect, Genesys Cloud), *personal callback* (Five9). |
|
|
64
|
+
| **Callback requested** | A waiting customer asked to be called back when an agent is free. | *Queued callback* (Amazon Connect), *callback* (Genesys Cloud), *virtual hold*. |
|
|
65
65
|
|
|
66
66
|
There is deliberately no **transfer**. An agent who needs help asks a lead, and a call changes
|
|
67
67
|
hands only through routing or a lead's take-over.
|
package/README.md
CHANGED
|
@@ -11,6 +11,7 @@ system.
|
|
|
11
11
|
|
|
12
12
|
| Path | |
|
|
13
13
|
| --- | --- |
|
|
14
|
+
| `PURPOSE.md` | **Why.** What the protocol is trying to achieve, and how choices in it are made. |
|
|
14
15
|
| `guide.md` | **The protocol.** The terms, the shapes, the rules, and how an adapter is declared, connected and held to them. |
|
|
15
16
|
| `guide/` | One file per role and channel: `agent.md`, `lead.md`, `queue.md`, `breaks.md`, `phone.md`, `voice.md`, `chat.md`, `email.md`. Each points back into `guide.md` for what it relies on. |
|
|
16
17
|
| `src/index.ts` | The TypeScript declarations. |
|
|
@@ -100,14 +101,14 @@ const task = {
|
|
|
100
101
|
};
|
|
101
102
|
```
|
|
102
103
|
|
|
103
|
-
**Switch on `command.
|
|
104
|
+
**Switch on `command.type` with no `default`.** A `default` turns a future command into whatever
|
|
104
105
|
the default does, silently; naming every arm means dropping one fails the build — indirectly, as a
|
|
105
106
|
missing return — and keeps the narrowing that lets you read `dialId` without a cast.
|
|
106
107
|
|
|
107
108
|
```ts
|
|
108
|
-
switch (command.
|
|
109
|
-
case "add":
|
|
110
|
-
case "remove": return removeFromCall(command.party === true ? "party" : command.contactId);
|
|
109
|
+
switch (command.type) {
|
|
110
|
+
case "add-to-call": return addToCall(command.dialId, command.contactId ?? command.number);
|
|
111
|
+
case "remove-from-call": return removeFromCall(command.party === true ? "party" : command.contactId);
|
|
111
112
|
}
|
|
112
113
|
```
|
|
113
114
|
|
package/dist/index.d.ts
CHANGED
|
@@ -52,13 +52,17 @@ export interface User {
|
|
|
52
52
|
id: UserId;
|
|
53
53
|
displayName: string;
|
|
54
54
|
/**
|
|
55
|
-
*
|
|
56
|
-
* authentication,
|
|
57
|
-
*
|
|
58
|
-
*
|
|
55
|
+
* On the signed-in identity, the zone this session sees every day in: the one the host stated at
|
|
56
|
+
* authentication, required there (`SignedInUser`). On anyone else -- a colleague from
|
|
57
|
+
* `getUserDetails()` -- the zone they last signed in from, for information only, and absent
|
|
58
|
+
* where the provider does not know it. No figure is cut by a colleague's zone.
|
|
59
59
|
*/
|
|
60
|
-
timeZone
|
|
60
|
+
timeZone?: TimeZone;
|
|
61
61
|
}
|
|
62
|
+
/** The person this session is signed in as: a `User` whose `timeZone` is always stated. */
|
|
63
|
+
export type SignedInUser = User & {
|
|
64
|
+
timeZone: TimeZone;
|
|
65
|
+
};
|
|
62
66
|
/** Key/value detail on a `Contact` or a `ScheduledActivity`. A task's attributes are typed. */
|
|
63
67
|
export interface Attribute {
|
|
64
68
|
key: string;
|
|
@@ -212,7 +216,6 @@ export interface Manifest<C extends Channel = Channel> {
|
|
|
212
216
|
supportedProtocolVersions: number[];
|
|
213
217
|
authenticationMethods: AuthenticationMethod[];
|
|
214
218
|
idleCapabilities?: IdleCapabilities<C>;
|
|
215
|
-
/** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
|
|
216
219
|
/**
|
|
217
220
|
* Implements `checkTime`, and states `providerTime` on every snapshot. Required of a provider
|
|
218
221
|
* that publishes an instant the agent computer renders as a running duration -- a member's `since`, a
|
|
@@ -276,7 +279,7 @@ export interface AuthenticationContext {
|
|
|
276
279
|
/** Omni's identity for this session. The same value arrives later as `ConnectContext.sessionId`. */
|
|
277
280
|
sessionId: string;
|
|
278
281
|
/**
|
|
279
|
-
* The zone
|
|
282
|
+
* The zone this session sees every day in, as the host's clock has it, stated before any
|
|
280
283
|
* identity exists so the first `authenticated` state already carries it. The same value arrives
|
|
281
284
|
* later as `ConnectContext.timeZone`.
|
|
282
285
|
*/
|
|
@@ -398,21 +401,21 @@ export type AuthenticationState = {
|
|
|
398
401
|
status: "authenticating";
|
|
399
402
|
} | {
|
|
400
403
|
status: "authenticated";
|
|
401
|
-
identity:
|
|
404
|
+
identity: SignedInUser;
|
|
402
405
|
capabilities: UserCapabilities;
|
|
403
406
|
expiresAt?: IsoTimestamp;
|
|
404
407
|
} | {
|
|
405
408
|
status: "refreshing";
|
|
406
|
-
identity:
|
|
409
|
+
identity: SignedInUser;
|
|
407
410
|
capabilities: UserCapabilities;
|
|
408
411
|
} | {
|
|
409
412
|
status: "expired";
|
|
410
|
-
identity?:
|
|
413
|
+
identity?: SignedInUser;
|
|
411
414
|
failure?: AuthenticationFailure;
|
|
412
415
|
} | {
|
|
413
416
|
status: "terminated";
|
|
414
417
|
by: UserId | "provider";
|
|
415
|
-
identity?:
|
|
418
|
+
identity?: SignedInUser;
|
|
416
419
|
failure: AuthenticationFailure & {
|
|
417
420
|
retryable: false;
|
|
418
421
|
};
|
|
@@ -464,7 +467,7 @@ export type CompleteAuthenticationRequest =
|
|
|
464
467
|
};
|
|
465
468
|
export type CompleteAuthenticationResult = {
|
|
466
469
|
status: "authenticated";
|
|
467
|
-
identity:
|
|
470
|
+
identity: SignedInUser;
|
|
468
471
|
capabilities: UserCapabilities;
|
|
469
472
|
expiresAt?: IsoTimestamp;
|
|
470
473
|
} | {
|
|
@@ -493,12 +496,6 @@ export interface AuthenticationSession {
|
|
|
493
496
|
signOut(): Promise<AuthenticationActionResult>;
|
|
494
497
|
close(): Promise<void>;
|
|
495
498
|
}
|
|
496
|
-
/**
|
|
497
|
-
* How the host's own audio stands: the microphone Omni captures for the agent, and whether it has
|
|
498
|
-
* it. Omni facilitates the microphone -- captures it, prompts, retries, tells the agent -- and
|
|
499
|
-
* does not decide for the adapter what a missing one means. The adapter does what its platform
|
|
500
|
-
* needs: go not-ready, refuse calls, or carry on because audio lands elsewhere.
|
|
501
|
-
*/
|
|
502
499
|
/**
|
|
503
500
|
* Who silenced a device that is present and permitted: the host, by its own Mute, or the station --
|
|
504
501
|
* a slider on the headset, the operating system -- which the host observes and, on a browser,
|
|
@@ -556,11 +553,6 @@ export type HostAudioOutput =
|
|
|
556
553
|
reason: HostOutputUnavailableReason;
|
|
557
554
|
failure: ProtocolFailure;
|
|
558
555
|
};
|
|
559
|
-
/**
|
|
560
|
-
* What only the host can see about the agent's station: the devices, the permissions, the
|
|
561
|
-
* network. Omni reports it; the adapter decides what any of it means for its platform and what
|
|
562
|
-
* to relay. `audio` is present on a voice connection.
|
|
563
|
-
*/
|
|
564
556
|
/** What Omni's own chrome shows of a task browser's URL: nothing, the domain, or all of it. */
|
|
565
557
|
export type UrlVisibility = "full" | "domain" | "hidden";
|
|
566
558
|
/** Independent recorder owners. A command never targets both. */
|
|
@@ -657,17 +649,27 @@ export interface HostRecordingRequest {
|
|
|
657
649
|
source: "host";
|
|
658
650
|
};
|
|
659
651
|
}
|
|
652
|
+
/**
|
|
653
|
+
* What only the host can see about the agent's station: the devices, the permissions, the
|
|
654
|
+
* network. Omni reports it; the adapter decides what any of it means for its platform and what
|
|
655
|
+
* to relay. `audio` is present on a voice connection.
|
|
656
|
+
*/
|
|
660
657
|
export interface HostReport {
|
|
661
658
|
/** Full current host-owned recording view; never provider-owned state. */
|
|
662
659
|
recordings?: HostRecordingReport[];
|
|
663
660
|
/** Whether the host has a network interface up. Not a claim that anything is reachable: the adapter knows its own platform's reachability better than the host does. */
|
|
664
661
|
online: boolean;
|
|
662
|
+
/**
|
|
663
|
+
* How the host's own audio stands: the microphone Omni captures for the agent, and whether it has
|
|
664
|
+
* it. Omni facilitates the microphone -- captures it, prompts, retries, tells the agent -- and
|
|
665
|
+
* does not decide for the adapter what a missing one means. The adapter does what its platform
|
|
666
|
+
* needs: go not-ready, refuse calls, or carry on because audio lands elsewhere.
|
|
667
|
+
*/
|
|
665
668
|
audio?: {
|
|
666
669
|
input: HostAudioInput;
|
|
667
670
|
output: HostAudioOutput;
|
|
668
671
|
};
|
|
669
672
|
}
|
|
670
|
-
/** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
|
|
671
673
|
/**
|
|
672
674
|
* What the host promises the provider, declared once per connection. Presence is the guarantee:
|
|
673
675
|
* an absent key is a host that makes no such promise, and a provider that needs one checks before
|
|
@@ -697,6 +699,7 @@ export interface ProviderTimeEstimate extends ProviderTimeScope {
|
|
|
697
699
|
/** Estimated uncertainty only; not a guaranteed error bound. */
|
|
698
700
|
uncertaintyMs?: number;
|
|
699
701
|
}
|
|
702
|
+
/** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
|
|
700
703
|
export interface Host {
|
|
701
704
|
/** Optional current provider-clock estimate; undefined when no usable estimate exists. */
|
|
702
705
|
estimateProviderTime?(scope: ProviderTimeScope): ProviderTimeEstimate | undefined;
|
|
@@ -715,9 +718,9 @@ export type ConnectContext = {
|
|
|
715
718
|
/** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
|
|
716
719
|
autoAcceptTasks: boolean;
|
|
717
720
|
/**
|
|
718
|
-
* The zone
|
|
719
|
-
* `AuthenticationContext.timeZone`. The provider
|
|
720
|
-
*
|
|
721
|
+
* The zone this session sees every day in, the same value passed as
|
|
722
|
+
* `AuthenticationContext.timeZone`. The provider carries it on the identity and cuts every
|
|
723
|
+
* day-scoped figure this session reads by it.
|
|
721
724
|
*/
|
|
722
725
|
timeZone: TimeZone;
|
|
723
726
|
/** The same value passed as `AuthenticationContext.languages`: what the agent reads, most preferred first. */
|
|
@@ -765,10 +768,10 @@ export type ConnectContext = {
|
|
|
765
768
|
export type TransportStatus = "connecting" | "active" | "error";
|
|
766
769
|
/**
|
|
767
770
|
* What revives a connection that reported `error`: `reconnect` -- the session is good, dispose this
|
|
768
|
-
* connection and call `connect()` again --
|
|
769
|
-
* first
|
|
771
|
+
* connection and call `connect()` again -- `reauthenticate` -- run the authentication flow
|
|
772
|
+
* first -- or `displaced` -- another client took the session, and nothing revives this one until
|
|
773
|
+
* the agent takes it back. The adapter knows which; the host acts on its word.
|
|
770
774
|
*/
|
|
771
|
-
/** What revives an errored connection: `displaced` says another client took the session, and nothing revives this one until the agent takes it back. */
|
|
772
775
|
export type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
|
|
773
776
|
/** Every field is optional: a provider sends what it knows and omits what it does not. */
|
|
774
777
|
export interface Contact {
|
|
@@ -943,7 +946,7 @@ export type TaskAttribute = TaskAttributeBase & ({
|
|
|
943
946
|
type: "timestamp";
|
|
944
947
|
at: IsoTimestamp;
|
|
945
948
|
});
|
|
946
|
-
export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "callback-requested";
|
|
949
|
+
export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "connected-back" | "callback-requested";
|
|
947
950
|
/**
|
|
948
951
|
* The call record: the steps that brought the task here, one entry per occurrence and oldest
|
|
949
952
|
* first, and what they add up to before this agent -- stated by the provider from its own record,
|
|
@@ -966,7 +969,7 @@ export interface TaskHistoryStep {
|
|
|
966
969
|
step: HistoryStep;
|
|
967
970
|
at: IsoTimestamp;
|
|
968
971
|
/**
|
|
969
|
-
* On a step that dialled -- `transferred`, `added`, `unanswered` -- the host's identity for
|
|
972
|
+
* On a step that dialled -- `transferred`, `added`, `unanswered`, `connected-back` -- the host's identity for
|
|
970
973
|
* that dial when a host placed it, and the contact it went to, by the contacts entry's `id`. Neither
|
|
971
974
|
* belongs on any other step.
|
|
972
975
|
*/
|
|
@@ -1416,7 +1419,8 @@ export interface BreakState {
|
|
|
1416
1419
|
/** Shown when `canRequestBreak` is false, such as "Busy hours". */
|
|
1417
1420
|
requestUnavailableReason?: string;
|
|
1418
1421
|
decisionReason?: string;
|
|
1419
|
-
|
|
1422
|
+
/** Whole seconds until the agent may ask again, as of this publication and restated on each, when the provider can say. */
|
|
1423
|
+
retryRequestInSeconds?: DurationSeconds;
|
|
1420
1424
|
/** Not-ready codes this provider offers. Omitted when it defines none. */
|
|
1421
1425
|
reasons?: BreakReason[];
|
|
1422
1426
|
/** Which reason the current break is on, a published `BreakReason.id`. Omitted when there is no break; required on a break in effect or starting after the task where the provider publishes `reasons`, a forced one included. */
|
|
@@ -1513,7 +1517,7 @@ export interface TeamMember {
|
|
|
1513
1517
|
tasks?: MemberTask[];
|
|
1514
1518
|
/** Every lead on this member's call, listening, coaching or joined, published to every lead alike; absent while none is. */
|
|
1515
1519
|
listening?: MemberListening[];
|
|
1516
|
-
/** The member's own history for the day: sign-in, sign-out, breaks and productivity, the same
|
|
1520
|
+
/** The member's own history for the day: sign-in, sign-out, breaks and productivity, the same instants and count the member's own snapshot carries, cut by the lead's day. Omitted where the provider cannot say. */
|
|
1517
1521
|
shift?: Shift;
|
|
1518
1522
|
/** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
|
|
1519
1523
|
request?: MemberRequest;
|
|
@@ -1580,21 +1584,37 @@ export interface ShiftEvent {
|
|
|
1580
1584
|
at: IsoTimestamp;
|
|
1581
1585
|
kind: ShiftEventKind;
|
|
1582
1586
|
}
|
|
1587
|
+
/** A day's total that can be running now: talk, hold, or break. */
|
|
1588
|
+
export type ShiftFigure = "talk" | "hold" | "break";
|
|
1589
|
+
export declare const SHIFT_FIGURES: readonly ["talk", "hold", "break"];
|
|
1583
1590
|
/**
|
|
1584
|
-
*
|
|
1585
|
-
*
|
|
1586
|
-
|
|
1587
|
-
|
|
1588
|
-
|
|
1591
|
+
* A stretch still running, which its total leaves out: the agent computer counts it on from `since`,
|
|
1592
|
+
* on the provider's clock, and adds it to the total it shows.
|
|
1593
|
+
*/
|
|
1594
|
+
export interface ShiftRunning {
|
|
1595
|
+
figure: ShiftFigure;
|
|
1596
|
+
since: IsoTimestamp;
|
|
1597
|
+
}
|
|
1598
|
+
/**
|
|
1599
|
+
* An agent's own history for the day, about the person rather than any one call: the day's first
|
|
1600
|
+
* sign-in, the sign-out while they are signed out, today's totals as the provider counts them,
|
|
1601
|
+
* each present only when the provider knows it, the stretches still running, and the day's
|
|
1602
|
+
* sign-in, sign-out and break events, oldest first. The day is the viewer's: published to the
|
|
1603
|
+
* agent on their snapshot and on `shift-updated`, cut in the agent's zone, and to their lead on
|
|
1604
|
+
* the team member list, cut in the lead's -- the same instants from the same count.
|
|
1589
1605
|
*/
|
|
1590
1606
|
export interface Shift {
|
|
1607
|
+
/** The day's first sign-in. */
|
|
1591
1608
|
signedInAt: IsoTimestamp;
|
|
1609
|
+
/** The latest sign-out, present only while the agent is signed out; an earlier session's is in `events`. */
|
|
1592
1610
|
signedOutAt?: IsoTimestamp;
|
|
1593
1611
|
talkSeconds?: DurationSeconds;
|
|
1594
1612
|
holdSeconds?: DurationSeconds;
|
|
1595
1613
|
/** Every break the member was on today, including time held elsewhere for a break another provider forced: the provider counts it under a break kind of its own. */
|
|
1596
1614
|
breakSeconds?: DurationSeconds;
|
|
1597
1615
|
tasksHandled?: number;
|
|
1616
|
+
/** The totals still running, at most one per figure; each total above leaves its running stretch out. */
|
|
1617
|
+
running?: ShiftRunning[];
|
|
1598
1618
|
events?: ShiftEvent[];
|
|
1599
1619
|
}
|
|
1600
1620
|
/**
|
|
@@ -1685,7 +1705,7 @@ export type TeamBreakCommand = {
|
|
|
1685
1705
|
memberId: UserId;
|
|
1686
1706
|
reasonId?: string;
|
|
1687
1707
|
reason?: string;
|
|
1688
|
-
|
|
1708
|
+
expectedDurationSeconds?: DurationSeconds;
|
|
1689
1709
|
}
|
|
1690
1710
|
/** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
|
|
1691
1711
|
| {
|
|
@@ -1726,7 +1746,6 @@ export type OpenAudioResult = {
|
|
|
1726
1746
|
status: "unavailable";
|
|
1727
1747
|
failure: ProtocolFailure;
|
|
1728
1748
|
};
|
|
1729
|
-
/** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
|
|
1730
1749
|
/**
|
|
1731
1750
|
* What the team may leave to the person: a capability by its own name -- `hold` -- or a
|
|
1732
1751
|
* skill by its provider id. The same key as in `Task.capabilities`, because it is the same
|
|
@@ -1810,6 +1829,7 @@ export type PreferenceResult = {
|
|
|
1810
1829
|
status: "failed";
|
|
1811
1830
|
failure: ProtocolFailure;
|
|
1812
1831
|
};
|
|
1832
|
+
/** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
|
|
1813
1833
|
export interface Snapshot<C extends Channel = Channel> {
|
|
1814
1834
|
transport: TransportStatus;
|
|
1815
1835
|
sessionId: string;
|
|
@@ -2082,7 +2102,6 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
|
|
|
2082
2102
|
readonly chat: {
|
|
2083
2103
|
readonly pending: "Incoming Chat";
|
|
2084
2104
|
readonly confirmed: "Accepted";
|
|
2085
|
-
readonly preview: "Preview";
|
|
2086
2105
|
readonly "in-progress": "In Chat";
|
|
2087
2106
|
readonly paused: "Paused";
|
|
2088
2107
|
readonly completing: "Wrap-up";
|
|
@@ -2090,7 +2109,6 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
|
|
|
2090
2109
|
readonly email: {
|
|
2091
2110
|
readonly pending: "Assigned";
|
|
2092
2111
|
readonly confirmed: "Accepted";
|
|
2093
|
-
readonly preview: "Preview";
|
|
2094
2112
|
readonly "in-progress": "Working";
|
|
2095
2113
|
readonly paused: "Paused";
|
|
2096
2114
|
readonly completing: "Completing";
|
|
@@ -2124,6 +2142,7 @@ export declare const DEFAULT_HISTORY_STEP_LABELS: {
|
|
|
2124
2142
|
readonly transferred: "Transferred";
|
|
2125
2143
|
readonly added: "Added";
|
|
2126
2144
|
readonly unanswered: "Unanswered";
|
|
2145
|
+
readonly "connected-back": "Reconnected";
|
|
2127
2146
|
readonly "callback-requested": "Callback requested";
|
|
2128
2147
|
};
|
|
2129
2148
|
/**
|
|
@@ -2150,12 +2169,12 @@ export declare const assignmentKey: (providerId: string, assignmentId: Assignmen
|
|
|
2150
2169
|
export declare const userKey: (providerId: string, userId: UserId) => string;
|
|
2151
2170
|
/**
|
|
2152
2171
|
* Every history step somebody from the provider takes part in. `arrived`, `self-service` and
|
|
2153
|
-
* `queued` are the ones nobody does, and `callback-requested` is the caller's choice
|
|
2172
|
+
* `queued` are the ones nobody does, and `callback-requested` is the caller's own choice in the queue, so none
|
|
2154
2173
|
* of them is here.
|
|
2155
2174
|
*/
|
|
2156
|
-
export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered"];
|
|
2175
|
+
export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered", "connected-back"];
|
|
2157
2176
|
/** The steps a dial writes, and so the only ones that carry a `dialId` and a `contactId`. */
|
|
2158
|
-
export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "added", "unanswered"];
|
|
2177
|
+
export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "added", "unanswered", "connected-back"];
|
|
2159
2178
|
export declare const historyStepDials: (step: HistoryStep) => boolean;
|
|
2160
2179
|
/**
|
|
2161
2180
|
* Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
|
package/dist/index.js
CHANGED
|
@@ -100,6 +100,7 @@ export const BREAK_KINDS = [
|
|
|
100
100
|
"meeting", "administrative", "technical", "personal", "other",
|
|
101
101
|
];
|
|
102
102
|
export const SHIFT_EVENT_KINDS = ["signed-in", "signed-out", "break-started", "break-ended"];
|
|
103
|
+
export const SHIFT_FIGURES = ["talk", "hold", "break"];
|
|
103
104
|
export const OMNI_FAILURE_CODES = [
|
|
104
105
|
"omni.not-authenticated",
|
|
105
106
|
"omni.capability-not-enabled",
|
|
@@ -132,11 +133,11 @@ export const DEFAULT_TASK_PHASE_LABELS = {
|
|
|
132
133
|
"in-progress": "On Call", paused: "On Hold", completing: "After Call Work",
|
|
133
134
|
},
|
|
134
135
|
chat: {
|
|
135
|
-
pending: "Incoming Chat", confirmed: "Accepted",
|
|
136
|
+
pending: "Incoming Chat", confirmed: "Accepted",
|
|
136
137
|
"in-progress": "In Chat", paused: "Paused", completing: "Wrap-up",
|
|
137
138
|
},
|
|
138
139
|
email: {
|
|
139
|
-
pending: "Assigned", confirmed: "Accepted",
|
|
140
|
+
pending: "Assigned", confirmed: "Accepted",
|
|
140
141
|
"in-progress": "Working", paused: "Paused", completing: "Completing",
|
|
141
142
|
},
|
|
142
143
|
};
|
|
@@ -148,7 +149,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
|
|
|
148
149
|
export const DEFAULT_HISTORY_STEP_LABELS = {
|
|
149
150
|
arrived: "Incoming call", "self-service": "Self-service", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
|
|
150
151
|
muted: "Muted", transferred: "Transferred", added: "Added", unanswered: "Unanswered",
|
|
151
|
-
"callback-requested": "Callback requested",
|
|
152
|
+
"connected-back": "Reconnected", "callback-requested": "Callback requested",
|
|
152
153
|
};
|
|
153
154
|
/**
|
|
154
155
|
* The provider's text for the first of `languages` it has, matched as BCP 47 lookup does: the tag
|
|
@@ -196,14 +197,14 @@ export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent
|
|
|
196
197
|
export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
|
|
197
198
|
/**
|
|
198
199
|
* Every history step somebody from the provider takes part in. `arrived`, `self-service` and
|
|
199
|
-
* `queued` are the ones nobody does, and `callback-requested` is the caller's choice
|
|
200
|
+
* `queued` are the ones nobody does, and `callback-requested` is the caller's own choice in the queue, so none
|
|
200
201
|
* of them is here.
|
|
201
202
|
*/
|
|
202
203
|
export const HISTORY_STEPS_WITH_A_PERSON = [
|
|
203
|
-
"offered", "answered", "held", "muted", "transferred", "added", "unanswered",
|
|
204
|
+
"offered", "answered", "held", "muted", "transferred", "added", "unanswered", "connected-back",
|
|
204
205
|
];
|
|
205
206
|
/** The steps a dial writes, and so the only ones that carry a `dialId` and a `contactId`. */
|
|
206
|
-
export const HISTORY_STEPS_THAT_DIAL = ["transferred", "added", "unanswered"];
|
|
207
|
+
export const HISTORY_STEPS_THAT_DIAL = ["transferred", "added", "unanswered", "connected-back"];
|
|
207
208
|
export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step);
|
|
208
209
|
// Pinned both ways: a step added to `HistoryStep` has to be placed here, and a step listed here
|
|
209
210
|
// has to exist there. `satisfies` on the list covers the second; this statement covers the first.
|
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, 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);
|
|
@@ -1475,7 +1475,7 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1475
1475
|
const allowed = {
|
|
1476
1476
|
"lead-features": ["type", "enabled"],
|
|
1477
1477
|
"decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
|
|
1478
|
-
"force-break": ["type", "memberId", "reasonId", "reason", "
|
|
1478
|
+
"force-break": ["type", "memberId", "reasonId", "reason", "expectedDurationSeconds"], "end-forced-break": ["type", "memberId"],
|
|
1479
1479
|
join: member, decline: [...member, "reason"], listen: member, coach: member, "join-call": member, leave: member, "take-over-call": member,
|
|
1480
1480
|
"set-policy": ["type", "capability", "setting"],
|
|
1481
1481
|
};
|
|
@@ -1536,8 +1536,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1536
1536
|
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
1537
|
}
|
|
1538
1538
|
if (command.type === "force-break") {
|
|
1539
|
-
if (command.
|
|
1540
|
-
into.require(
|
|
1539
|
+
if (command.expectedDurationSeconds !== undefined)
|
|
1540
|
+
into.require(isDurationSeconds(command.expectedDurationSeconds) && command.expectedDurationSeconds > 0, "team.command.expectedDurationSeconds", `${path}.expectedDurationSeconds`, "expectedDurationSeconds must be a whole number of seconds, more than zero; it never resumes the agent");
|
|
1541
1541
|
if (command.reasonId !== undefined)
|
|
1542
1542
|
into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
|
|
1543
1543
|
const reasons = Array.isArray(state.reasons) ? state.reasons : [];
|
|
@@ -1656,9 +1656,11 @@ function validateBreakState(value, path, into) {
|
|
|
1656
1656
|
if (value.requestUnavailableReason !== undefined) {
|
|
1657
1657
|
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
1658
|
}
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1659
|
+
for (const old of ["retryAfterMs", "retryRequestAfterMs"]) {
|
|
1660
|
+
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`);
|
|
1661
|
+
}
|
|
1662
|
+
if (value.retryRequestInSeconds !== undefined) {
|
|
1663
|
+
into.require(isDurationSeconds(value.retryRequestInSeconds), "break.retryRequestInSeconds", `${path}.retryRequestInSeconds`, "retryRequestInSeconds must be a whole number of seconds, zero or more, when present");
|
|
1662
1664
|
}
|
|
1663
1665
|
if (value.activeReasonId !== undefined) {
|
|
1664
1666
|
into.filled(value.activeReasonId, "break.activeReasonId", `${path}.activeReasonId`, "activeReasonId must not be empty when present");
|
|
@@ -2428,10 +2430,29 @@ function validateShiftInto(value, path, into, rule) {
|
|
|
2428
2430
|
}
|
|
2429
2431
|
for (const field of ["talkSeconds", "holdSeconds", "breakSeconds"]) {
|
|
2430
2432
|
if (value[field] !== undefined)
|
|
2431
|
-
into.require(isDurationSeconds(value[field]),
|
|
2433
|
+
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
2434
|
}
|
|
2433
2435
|
if (value.tasksHandled !== undefined)
|
|
2434
2436
|
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");
|
|
2437
|
+
if (value.running !== undefined) {
|
|
2438
|
+
if (!Array.isArray(value.running)) {
|
|
2439
|
+
into.add(`${rule}.running.shape`, `${path}.running`, "running must be an array when present");
|
|
2440
|
+
}
|
|
2441
|
+
else {
|
|
2442
|
+
const seen = new Set();
|
|
2443
|
+
value.running.forEach((entry, index) => {
|
|
2444
|
+
const at = `${path}.running[${index}]`;
|
|
2445
|
+
if (!isPlainObject(entry)) {
|
|
2446
|
+
into.add(`${rule}.running.shape`, at, "each running stretch must be an object");
|
|
2447
|
+
return;
|
|
2448
|
+
}
|
|
2449
|
+
into.oneOf(entry.figure, SHIFT_FIGURES, `${rule}.running.figure`, `${at}.figure`);
|
|
2450
|
+
into.timestamp(entry.since, `${rule}.running.since`, `${at}.since`);
|
|
2451
|
+
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`);
|
|
2452
|
+
seen.add(entry.figure);
|
|
2453
|
+
});
|
|
2454
|
+
}
|
|
2455
|
+
}
|
|
2435
2456
|
if (value.events !== undefined) {
|
|
2436
2457
|
if (!Array.isArray(value.events)) {
|
|
2437
2458
|
into.add(`${rule}.events.shape`, `${path}.events`, "events must be an array when present");
|
|
@@ -3096,22 +3117,27 @@ export function validateUserDetails(users, asked, path = "getUserDetails") {
|
|
|
3096
3117
|
}
|
|
3097
3118
|
users.forEach((user, index) => {
|
|
3098
3119
|
const at = `${path}[${index}]`;
|
|
3099
|
-
validateUser(user, "getUserDetails.user", at, into);
|
|
3120
|
+
validateUser(user, "getUserDetails.user", at, into, false);
|
|
3100
3121
|
if (isPlainObject(user) && typeof user.id === "string") {
|
|
3101
3122
|
into.require(asked.includes(user.id), "getUserDetails.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
|
|
3102
3123
|
}
|
|
3103
3124
|
});
|
|
3104
3125
|
return into.violations;
|
|
3105
3126
|
}
|
|
3106
|
-
function validateUser(value, rule, path, into) {
|
|
3127
|
+
function validateUser(value, rule, path, into, signedIn) {
|
|
3107
3128
|
if (!isPlainObject(value)) {
|
|
3108
3129
|
into.add(rule, path, "an identity must be an object");
|
|
3109
3130
|
return;
|
|
3110
3131
|
}
|
|
3111
3132
|
into.require(isUserId(value.id), `${rule}.id`, `${path}.id`, "an identity needs a provider-issued user id");
|
|
3112
3133
|
into.filled(value.displayName, `${rule}.displayName`, `${path}.displayName`, "an identity needs a display name");
|
|
3113
|
-
|
|
3114
|
-
|
|
3134
|
+
if (signedIn) {
|
|
3135
|
+
// Never absent: the host stated the zone at authentication, before this identity existed.
|
|
3136
|
+
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");
|
|
3137
|
+
}
|
|
3138
|
+
else if (value.timeZone !== undefined) {
|
|
3139
|
+
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");
|
|
3140
|
+
}
|
|
3115
3141
|
}
|
|
3116
3142
|
function validateUserCapabilitiesInto(value, path, into, levels) {
|
|
3117
3143
|
if (!isPlainObject(value)) {
|
|
@@ -3285,12 +3311,12 @@ export function validateAuthenticationState(state, path, context) {
|
|
|
3285
3311
|
// Only `authenticated` may carry an expiry, and only the states that know who the agent is
|
|
3286
3312
|
// may carry an identity. Anything else is a state claiming knowledge it does not have.
|
|
3287
3313
|
if (state.status === "authenticated" || state.status === "refreshing") {
|
|
3288
|
-
validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
|
|
3314
|
+
validateUser(state.identity, "authentication.identity", `${path}.identity`, into, true);
|
|
3289
3315
|
validateUserCapabilitiesInto(state.capabilities, `${path}.capabilities`, into, context.levels);
|
|
3290
3316
|
}
|
|
3291
3317
|
else if (state.status === "expired" || state.status === "terminated") {
|
|
3292
3318
|
if (state.identity !== undefined)
|
|
3293
|
-
validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
|
|
3319
|
+
validateUser(state.identity, "authentication.identity", `${path}.identity`, into, true);
|
|
3294
3320
|
if (state.failure !== undefined) {
|
|
3295
3321
|
validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
|
|
3296
3322
|
}
|