@xema/omni-protocol 0.1.129 → 0.1.131
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/GLOSSARY.md +2 -2
- package/README.md +6 -8
- package/dist/index.d.ts +145 -94
- package/dist/index.js +27 -12
- package/dist/testing.d.ts +18 -18
- package/dist/testing.js +89 -92
- package/dist/validation.d.ts +23 -23
- package/dist/validation.js +178 -125
- package/guide/agent.md +34 -34
- package/guide/breaks.md +1 -1
- package/guide/lead.md +34 -17
- package/guide/phone.md +22 -22
- package/guide/queue.md +7 -7
- package/guide/voice.md +64 -54
- package/guide.md +168 -148
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -29,6 +29,20 @@ export const IDLE_CAPABILITY_UI = {
|
|
|
29
29
|
contacts: "Contacts",
|
|
30
30
|
};
|
|
31
31
|
export const LISTENING_MODES = ["listen", "coach", "join-call"];
|
|
32
|
+
/** The lead capability each lead command needs; `lead-features` and `leave` need none. */
|
|
33
|
+
export const LEAD_COMMAND_CAPABILITY = {
|
|
34
|
+
join: "join",
|
|
35
|
+
decline: "decline",
|
|
36
|
+
listen: "listen",
|
|
37
|
+
coach: "coach",
|
|
38
|
+
"join-call": "joinCall",
|
|
39
|
+
"take-over-call": "takeOverCall",
|
|
40
|
+
"decide-break-request": "decideBreakRequest",
|
|
41
|
+
"set-break-policy": "setBreakPolicy",
|
|
42
|
+
"force-break": "forceBreak",
|
|
43
|
+
"end-forced-break": "endForcedBreak",
|
|
44
|
+
"set-policy": "setPolicy",
|
|
45
|
+
};
|
|
32
46
|
export const MUTED_BY = ["host", "station"];
|
|
33
47
|
export const HOST_MUTES = ["stream", "station"];
|
|
34
48
|
export const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"];
|
|
@@ -62,14 +76,14 @@ export function isAllowedBrowserUrl(url) {
|
|
|
62
76
|
return false;
|
|
63
77
|
}
|
|
64
78
|
}
|
|
65
|
-
export const ON_CALL_ROLES = ["party", "agent", "
|
|
79
|
+
export const ON_CALL_ROLES = ["party", "agent", "added"];
|
|
66
80
|
export const CAPABILITY_SOURCES = ["queue", "dialer", "nobody", "not-yet-read"];
|
|
67
81
|
// ---------------------------------------------------------------------------
|
|
68
82
|
// Task commands.
|
|
69
83
|
// ---------------------------------------------------------------------------
|
|
70
84
|
export const TASK_COMMAND_NAMES = {
|
|
71
85
|
voice: ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call",
|
|
72
|
-
"connect-back", "lead-assist", "
|
|
86
|
+
"connect-back", "lead-assist", "add-to-call", "remove-from-call", "recording", "schedule", "complete"],
|
|
73
87
|
chat: ["accept", "decline", "pause", "resume", "schedule", "complete"],
|
|
74
88
|
email: ["accept", "decline", "schedule", "complete"],
|
|
75
89
|
};
|
|
@@ -77,7 +91,7 @@ export const TASK_COMMAND_NAMES = {
|
|
|
77
91
|
export function commandDialId(command) {
|
|
78
92
|
if (command.type === "connect-back" || command.type === "dial")
|
|
79
93
|
return command.dialId;
|
|
80
|
-
if (command.type === "
|
|
94
|
+
if (command.type === "add-to-call")
|
|
81
95
|
return command.dialId;
|
|
82
96
|
return undefined;
|
|
83
97
|
}
|
|
@@ -133,7 +147,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
|
|
|
133
147
|
};
|
|
134
148
|
export const DEFAULT_HISTORY_STEP_LABELS = {
|
|
135
149
|
arrived: "Incoming call", "self-service": "Self-service", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
|
|
136
|
-
muted: "Muted", transferred: "Transferred",
|
|
150
|
+
muted: "Muted", transferred: "Transferred", added: "Added", unanswered: "Unanswered",
|
|
137
151
|
"callback-requested": "Callback requested",
|
|
138
152
|
};
|
|
139
153
|
/**
|
|
@@ -186,10 +200,10 @@ export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)
|
|
|
186
200
|
* of them is here.
|
|
187
201
|
*/
|
|
188
202
|
export const HISTORY_STEPS_WITH_A_PERSON = [
|
|
189
|
-
"offered", "answered", "held", "muted", "transferred", "
|
|
203
|
+
"offered", "answered", "held", "muted", "transferred", "added", "unanswered",
|
|
190
204
|
];
|
|
191
|
-
/** The steps a dial writes, and so the only ones that carry a `dialId` and a `
|
|
192
|
-
export const HISTORY_STEPS_THAT_DIAL = ["transferred", "
|
|
205
|
+
/** 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"];
|
|
193
207
|
export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step);
|
|
194
208
|
// Pinned both ways: a step added to `HistoryStep` has to be placed here, and a step listed here
|
|
195
209
|
// has to exist there. `satisfies` on the list covers the second; this statement covers the first.
|
|
@@ -216,7 +230,7 @@ export function historyStepExpectsAPerson(step) {
|
|
|
216
230
|
return HISTORY_STEPS_WITH_A_PERSON.includes(step);
|
|
217
231
|
}
|
|
218
232
|
/**
|
|
219
|
-
* Whether two
|
|
233
|
+
* Whether two sessions declare the same capabilities, field by field. The comparison an adapter
|
|
220
234
|
* makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
|
|
221
235
|
* guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
|
|
222
236
|
* not the thing being compared. Key order does not matter, and a withdrawn `lead` is a change.
|
|
@@ -226,23 +240,24 @@ export function sameCapabilities(a, b) {
|
|
|
226
240
|
// list to the type, and a new key is a compile error until it is compared.
|
|
227
241
|
void { breaks: true, preferences: true, lead: true, nextCall: true };
|
|
228
242
|
const preferences = (list) => list === undefined ? undefined : list.map(p => [p.id, p.label, p.enabled, p.setBy, p.lockedBy ?? "", p.reason ?? ""].join("\u0000")).sort().join("\u0001");
|
|
243
|
+
const lead = (granted) => granted === undefined ? undefined : Object.keys(granted).filter(key => granted[key] === true).sort().join(",");
|
|
229
244
|
return a.breaks === b.breaks &&
|
|
230
|
-
a.lead === b.lead &&
|
|
245
|
+
lead(a.lead) === lead(b.lead) &&
|
|
231
246
|
a.nextCall === b.nextCall &&
|
|
232
247
|
preferences(a.preferences) === preferences(b.preferences);
|
|
233
248
|
}
|
|
234
249
|
/**
|
|
235
250
|
* The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
|
|
236
251
|
*
|
|
237
|
-
* Fails closed. A browser with `
|
|
252
|
+
* Fails closed. A browser with `sharedProfile: false` has no key; nor does a reusing one whose scheme is
|
|
238
253
|
* missing or unknown -- the type forbids that, but an adapter compiled against another version can
|
|
239
254
|
* still send it, and the safe reading is "do not share", never "share with everyone named the
|
|
240
255
|
* same". Every part is encoded, separator included, before joining, so a tab called `a.b`
|
|
241
256
|
* cannot collide with a provider called `a` and a tab called `b`.
|
|
242
257
|
*/
|
|
243
|
-
export function
|
|
258
|
+
export function browserProfileKey(input) {
|
|
244
259
|
const { providerId, assignmentId, taskType, browser } = input;
|
|
245
|
-
if (browser.
|
|
260
|
+
if (browser.sharedProfile !== true)
|
|
246
261
|
return undefined;
|
|
247
262
|
// `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
|
|
248
263
|
// provider `Acme.Voice` with type `Support` forge the key of `Acme` with `Voice.Support`.
|
package/dist/testing.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type BreakStatus, type
|
|
1
|
+
import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type BreakStatus, type BrowserProfileKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type SessionStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
|
|
2
2
|
import { type ProtocolViolation } from "./validation.js";
|
|
3
3
|
export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
|
|
4
4
|
/**
|
|
@@ -14,10 +14,10 @@ export interface AdapterContractResult {
|
|
|
14
14
|
/** The state the session was restored with at sign-in. */
|
|
15
15
|
authenticationState: AuthenticationState;
|
|
16
16
|
/**
|
|
17
|
-
* The latest
|
|
17
|
+
* The latest signed-in state the authentication session published during the run. Equal to `authenticationState` unless
|
|
18
18
|
* the adapter republished `authenticated` -- capabilities are current, not fixed.
|
|
19
19
|
*/
|
|
20
|
-
|
|
20
|
+
signedIn: AuthenticationState;
|
|
21
21
|
/** True only when every unsubscribe, `disconnect()`, and `close()` settled without throwing. */
|
|
22
22
|
disconnectWasClean: boolean;
|
|
23
23
|
/**
|
|
@@ -51,14 +51,14 @@ export interface TestAdapterOptions {
|
|
|
51
51
|
timeoutMs?: number;
|
|
52
52
|
/**
|
|
53
53
|
* Builds the adapter again, as a host reload does: a new object with no memory, for the same
|
|
54
|
-
*
|
|
54
|
+
* session. Given it, the test -- once the host's muted leg is recorded -- connects a second adapter
|
|
55
55
|
* with the same context and the same store and expects its snapshot to carry the task with that
|
|
56
56
|
* leg. A platform that holds the record hands it back; an adapter that composed the record in
|
|
57
57
|
* memory has nothing, and is named. Without it the store is required and never read.
|
|
58
58
|
*/
|
|
59
59
|
rebuild?: () => Adapter<Channel>;
|
|
60
60
|
/**
|
|
61
|
-
* The values the queue locks on this
|
|
61
|
+
* The values the queue locks on this session's tasks -- a party's number or email -- as the run's
|
|
62
62
|
* author knows them. A task whose party stands locked may carry none of them anywhere else
|
|
63
63
|
* (`task.locked.leak`). Required once any task locks a party field: a run that cannot ask the
|
|
64
64
|
* question is not a pass, and says so by throwing rather than passing.
|
|
@@ -69,7 +69,7 @@ export interface TestAdapterOptions {
|
|
|
69
69
|
* Adapter conformance exercise: validates the manifest, opens an authenticated session,
|
|
70
70
|
* connects, checks that every method the declarations require is implemented, subscribes,
|
|
71
71
|
* validates the snapshot, every delivered event, and every authentication state the session
|
|
72
|
-
* publishes during the run -- against the latest
|
|
72
|
+
* publishes during the run -- against the latest session, since capabilities are current, not
|
|
73
73
|
* fixed -- states a capacity, then unsubscribes and disconnects.
|
|
74
74
|
*
|
|
75
75
|
* Violations are collected rather than thrown from inside the adapter's own
|
|
@@ -80,16 +80,16 @@ export interface TestAdapterOptions {
|
|
|
80
80
|
export declare function testAdapter<C extends Channel>(adapter: Adapter<C>, context: ConnectContext, options?: TestAdapterOptions): Promise<AdapterContractResult>;
|
|
81
81
|
/**
|
|
82
82
|
* Validates restored authentication followed by a refresh failure or expiry. Every state is
|
|
83
|
-
* validated against the manifest's levels, and a `refreshing` state must carry over the
|
|
83
|
+
* validated against the manifest's levels, and a `refreshing` state must carry over the session it refreshes.
|
|
84
84
|
*/
|
|
85
85
|
export declare function assertAuthenticationRestoreAndExpiry(states: readonly AuthenticationState[], manifest: Manifest): void;
|
|
86
86
|
/**
|
|
87
87
|
* Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
|
|
88
88
|
* with the new set, and the next snapshot agrees with it. `states` is what the authentication
|
|
89
89
|
* session published, first to last: beginning and ending `authenticated` for the same identity,
|
|
90
|
-
* passing only through usable states (`expired`, `terminated` or `signed-out` ends the
|
|
90
|
+
* passing only through usable states (`expired`, `terminated` or `signed-out` ends the session instead), with at
|
|
91
91
|
* least one capability gone by the end. `snapshot` is the first snapshot published after the last
|
|
92
|
-
* state, validated against that
|
|
92
|
+
* state, validated against that sign-in -- so a team member list still published to a session that no longer
|
|
93
93
|
* leads, or requests to one that may no longer join, is the failure.
|
|
94
94
|
*/
|
|
95
95
|
export declare function assertCapabilityWithdrawal(states: readonly AuthenticationState[], snapshot: Snapshot, manifest: Manifest): void;
|
|
@@ -222,7 +222,7 @@ export declare class BreakStream {
|
|
|
222
222
|
private recovery;
|
|
223
223
|
/** True until a validated authoritative snapshot establishes a usable baseline. */
|
|
224
224
|
get needsRecovery(): boolean;
|
|
225
|
-
/** Caller establishes snapshot freshness/
|
|
225
|
+
/** Caller establishes snapshot freshness/session scope separately; malformed state never replaces the baseline. */
|
|
226
226
|
seed(snapshot: unknown): ProtocolViolation[];
|
|
227
227
|
/** Rejected transitions keep accepted state and require snapshot recovery before further deltas. */
|
|
228
228
|
apply(envelope: unknown, path?: string): ProtocolViolation[];
|
|
@@ -240,8 +240,8 @@ export declare function assertBreakFollowsItsRequests(envelopes: readonly Provid
|
|
|
240
240
|
* follows the audio ending is `completing` or `task-ended`.
|
|
241
241
|
*/
|
|
242
242
|
export declare function assertAudioFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
|
|
243
|
-
/** A
|
|
244
|
-
export declare function memoryStore():
|
|
243
|
+
/** A session store that lives in memory for the test: what most adapter tests hand `testAdapter` as `context.store`. */
|
|
244
|
+
export declare function memoryStore(): SessionStore;
|
|
245
245
|
/**
|
|
246
246
|
* A host that reports one thing and never changes: what most adapter tests hand `testAdapter`.
|
|
247
247
|
* A softphone host states what its Mute does; a hardphone or conversation host has no microphone and states nothing.
|
|
@@ -273,12 +273,12 @@ export interface BreakCandidate {
|
|
|
273
273
|
* A break one provider forces stops the agent everywhere: the host states a capacity of zero on
|
|
274
274
|
* every other usable provider holding capacity -- taken, never refused, and nothing the agent can
|
|
275
275
|
* cancel -- and on the forcing provider states nothing, since the break itself holds the agent
|
|
276
|
-
* there. A provider whose
|
|
276
|
+
* there. A provider whose session is not usable is left alone, as a break attempt leaves it.
|
|
277
277
|
*/
|
|
278
278
|
export declare function assertForcedBreakStopsTheRest(forcedOn: string, candidates: readonly BreakCandidate[], stopped: readonly string[]): void;
|
|
279
279
|
/**
|
|
280
280
|
* A break attempt asks every connected provider from which the agent can currently receive work.
|
|
281
|
-
* A provider whose
|
|
281
|
+
* A provider whose session is not usable -- `expired` above all -- is not asked, whatever else is
|
|
282
282
|
* true of it: nothing can be asked of it, and a host that waits on it stalls the break for
|
|
283
283
|
* everyone. A usable provider holding capacity is asked, and cannot be left out. `refreshing` is
|
|
284
284
|
* usable: identity and capabilities remain available and work continues.
|
|
@@ -297,13 +297,13 @@ export interface BreakOnTaskStep {
|
|
|
297
297
|
*/
|
|
298
298
|
export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;
|
|
299
299
|
/** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
|
|
300
|
-
export type BrowserIsolationScenario =
|
|
301
|
-
/** Validates whether two task-browser definitions should share one browser
|
|
302
|
-
export declare function
|
|
300
|
+
export type BrowserIsolationScenario = BrowserProfileKeyInput;
|
|
301
|
+
/** Validates whether two task-browser definitions should share one browser profile. */
|
|
302
|
+
export declare function assertBrowserProfileIsolation(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
|
|
303
303
|
/**
|
|
304
304
|
* Asserts that no two distinct scenarios in `scenarios` derive the same session key.
|
|
305
305
|
* Feed it adversarial names — a provider called `A.B` against a task type called
|
|
306
306
|
* `B`, casing variants, separators — because a collision silently shares cookies,
|
|
307
307
|
* storage, and permissions between two backends.
|
|
308
308
|
*/
|
|
309
|
-
export declare function
|
|
309
|
+
export declare function assertNoBrowserProfileKeyCollisions(scenarios: readonly BrowserIsolationScenario[]): void;
|