@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 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: connect back
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
- | **Connect back** | Call the customer again after the call has ended, during the wrap. | *Callback from wrap*, *re-dial*. |
63
- | **Schedule** | Put a follow-up with this customer on the calendar. | *Scheduled callback* (Amazon Connect, Genesys Cloud), *personal callback* (Five9). |
64
- | **Callback requested** | The customer asked to be called back, or an agent arranged it. | *Queued callback* (Amazon Connect), *callback* (Genesys Cloud), *virtual hold*. |
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.action` with no `default`.** A `default` turns a future action into whatever
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.action) {
109
- case "add": return addToCall(command.dialId, command.contactId ?? command.number);
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
- * The zone this person's day is reckoned in, as the provider keeps it: stated by the host at
56
- * authentication, stored on the agent, and carried on every identity and every described user
57
- * so a day-scoped figure -- theirs or a colleague's a lead is reading -- is bucketed by the
58
- * right day. Never absent: a person whose day nobody can name is not on this wire.
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: 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 the agent's day is reckoned in, as the host's clock has it, stated before any
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: User;
404
+ identity: SignedInUser;
402
405
  capabilities: UserCapabilities;
403
406
  expiresAt?: IsoTimestamp;
404
407
  } | {
405
408
  status: "refreshing";
406
- identity: User;
409
+ identity: SignedInUser;
407
410
  capabilities: UserCapabilities;
408
411
  } | {
409
412
  status: "expired";
410
- identity?: User;
413
+ identity?: SignedInUser;
411
414
  failure?: AuthenticationFailure;
412
415
  } | {
413
416
  status: "terminated";
414
417
  by: UserId | "provider";
415
- identity?: User;
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: User;
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 the agent's day is reckoned in, the same value passed as
719
- * `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the
720
- * identity; a roaming agent corrects it by signing in.
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 -- or `reauthenticate` -- run the authentication flow
769
- * first. The adapter knows which; the host acts on its word.
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
- retryRequestAfterMs?: number;
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 numbers the member's own snapshot carries. Omitted where the provider cannot say. */
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
- * An agent's own history for the day, about the person rather than any one call: when they
1585
- * signed in and out, today's totals as the provider counts them, each present only when the
1586
- * provider knows it, and the day's sign-in, sign-out and break events, oldest first. Published
1587
- * to the agent on their snapshot and on `shift-updated`, and to their lead on the team member
1588
- * list: the same numbers from the same count.
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
- expectedDurationMs?: number;
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 unless an agent arranged it, so none
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", preview: "Preview",
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", preview: "Preview",
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 unless an agent arranged it, so none
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.
@@ -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, so there is nothing to name.
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", "expectedDurationMs"], "end-forced-break": ["type", "memberId"],
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.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");
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
- into.require(!Object.hasOwn(value, "retryAfterMs"), "break.retryRequestAfterMs.renamed", `${path}.retryAfterMs`, "retryAfterMs was renamed to retryRequestAfterMs on BreakState");
1660
- if (value.retryRequestAfterMs !== undefined) {
1661
- into.require(typeof value.retryRequestAfterMs === "number" && Number.isFinite(value.retryRequestAfterMs) && value.retryRequestAfterMs >= 0, "break.retryRequestAfterMs", `${path}.retryRequestAfterMs`, "retryRequestAfterMs must be a non-negative number when present");
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]), `team.member.shift.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
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
- // Never absent: the host stated the zone at authentication, before this identity existed.
3114
- into.require(isTimeZone(value.timeZone), `${rule}.timeZone`, `${path}.timeZone`, "every identity carries the agent's time zone as an IANA name, such as Asia/Kolkata; the host stated it at authentication");
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
  }