@xema/omni-protocol 0.1.132 → 0.1.134

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CALL_FLOW.md 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.
@@ -83,7 +83,8 @@ hands only through routing or a lead's take-over.
83
83
  | --- | --- | --- |
84
84
  | **Capacity** | How many tasks the agent can take at once on this provider. Zero means none. | *Concurrency* (Amazon Connect routing profiles), *capacity* (Twilio, Salesforce), *utilization* (Genesys Cloud). |
85
85
  | **Break** | Time away: lunch, training, a personal break. The agent asks, the provider decides. | *Aux* or *auxiliary code* (Avaya and many floors), *presence* such as Break or Meal (Genesys Cloud), *agent status* (Amazon Connect), *unavailable code* (NICE). |
86
- | **Forced break** | A break a lead or the provider puts the agent on. | *Forced aux*, *supervisor-set status*. |
86
+ | **Forced break** | A break a lead or the provider puts the agent on. The agent cannot end it, and signing out does not clear it. | *Forced aux*, *supervisor-set status*. |
87
+ | **Team break** | A forced break on the whole team, to one end for everyone. Time signed out counts towards it. | *Scheduled break*, *team aux*. |
87
88
  | **Next call** | The agent says they are ready for another call before this one ends. | *Request next*, *ready for next*. |
88
89
  | **Lined up** | A call waiting in this agent's own queue, held for them. | *Agent queue* or *personal queue* (Amazon Connect), *direct routing*. |
89
90
  | **Shift** | The agent's day: when they signed in, their breaks, their totals. | *Schedule adherence* data, *agent state history*. |
package/README.md CHANGED
@@ -101,14 +101,14 @@ const task = {
101
101
  };
102
102
  ```
103
103
 
104
- **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
105
105
  the default does, silently; naming every arm means dropping one fails the build — indirectly, as a
106
106
  missing return — and keeps the narrowing that lets you read `dialId` without a cast.
107
107
 
108
108
  ```ts
109
- switch (command.action) {
110
- case "add": return addToCall(command.dialId, command.contactId ?? command.number);
111
- 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);
112
112
  }
113
113
  ```
114
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
  */
@@ -377,7 +380,9 @@ export declare const LEAD_COMMAND_CAPABILITY: {
377
380
  readonly "decide-break-request": "decideBreakRequest";
378
381
  readonly "set-break-policy": "setBreakPolicy";
379
382
  readonly "force-break": "forceBreak";
383
+ readonly "force-team-break": "forceBreak";
380
384
  readonly "end-forced-break": "endForcedBreak";
385
+ readonly "end-team-break": "endForcedBreak";
381
386
  readonly "set-policy": "setPolicy";
382
387
  };
383
388
  /**
@@ -398,21 +403,21 @@ export type AuthenticationState = {
398
403
  status: "authenticating";
399
404
  } | {
400
405
  status: "authenticated";
401
- identity: User;
406
+ identity: SignedInUser;
402
407
  capabilities: UserCapabilities;
403
408
  expiresAt?: IsoTimestamp;
404
409
  } | {
405
410
  status: "refreshing";
406
- identity: User;
411
+ identity: SignedInUser;
407
412
  capabilities: UserCapabilities;
408
413
  } | {
409
414
  status: "expired";
410
- identity?: User;
415
+ identity?: SignedInUser;
411
416
  failure?: AuthenticationFailure;
412
417
  } | {
413
418
  status: "terminated";
414
419
  by: UserId | "provider";
415
- identity?: User;
420
+ identity?: SignedInUser;
416
421
  failure: AuthenticationFailure & {
417
422
  retryable: false;
418
423
  };
@@ -464,7 +469,7 @@ export type CompleteAuthenticationRequest =
464
469
  };
465
470
  export type CompleteAuthenticationResult = {
466
471
  status: "authenticated";
467
- identity: User;
472
+ identity: SignedInUser;
468
473
  capabilities: UserCapabilities;
469
474
  expiresAt?: IsoTimestamp;
470
475
  } | {
@@ -493,12 +498,6 @@ export interface AuthenticationSession {
493
498
  signOut(): Promise<AuthenticationActionResult>;
494
499
  close(): Promise<void>;
495
500
  }
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
501
  /**
503
502
  * Who silenced a device that is present and permitted: the host, by its own Mute, or the station --
504
503
  * a slider on the headset, the operating system -- which the host observes and, on a browser,
@@ -556,11 +555,6 @@ export type HostAudioOutput =
556
555
  reason: HostOutputUnavailableReason;
557
556
  failure: ProtocolFailure;
558
557
  };
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
558
  /** What Omni's own chrome shows of a task browser's URL: nothing, the domain, or all of it. */
565
559
  export type UrlVisibility = "full" | "domain" | "hidden";
566
560
  /** Independent recorder owners. A command never targets both. */
@@ -657,17 +651,27 @@ export interface HostRecordingRequest {
657
651
  source: "host";
658
652
  };
659
653
  }
654
+ /**
655
+ * What only the host can see about the agent's station: the devices, the permissions, the
656
+ * network. Omni reports it; the adapter decides what any of it means for its platform and what
657
+ * to relay. `audio` is present on a voice connection.
658
+ */
660
659
  export interface HostReport {
661
660
  /** Full current host-owned recording view; never provider-owned state. */
662
661
  recordings?: HostRecordingReport[];
663
662
  /** 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
663
  online: boolean;
664
+ /**
665
+ * How the host's own audio stands: the microphone Omni captures for the agent, and whether it has
666
+ * it. Omni facilitates the microphone -- captures it, prompts, retries, tells the agent -- and
667
+ * does not decide for the adapter what a missing one means. The adapter does what its platform
668
+ * needs: go not-ready, refuse calls, or carry on because audio lands elsewhere.
669
+ */
665
670
  audio?: {
666
671
  input: HostAudioInput;
667
672
  output: HostAudioOutput;
668
673
  };
669
674
  }
670
- /** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
671
675
  /**
672
676
  * What the host promises the provider, declared once per connection. Presence is the guarantee:
673
677
  * an absent key is a host that makes no such promise, and a provider that needs one checks before
@@ -697,6 +701,7 @@ export interface ProviderTimeEstimate extends ProviderTimeScope {
697
701
  /** Estimated uncertainty only; not a guaranteed error bound. */
698
702
  uncertaintyMs?: number;
699
703
  }
704
+ /** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
700
705
  export interface Host {
701
706
  /** Optional current provider-clock estimate; undefined when no usable estimate exists. */
702
707
  estimateProviderTime?(scope: ProviderTimeScope): ProviderTimeEstimate | undefined;
@@ -715,9 +720,9 @@ export type ConnectContext = {
715
720
  /** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
716
721
  autoAcceptTasks: boolean;
717
722
  /**
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.
723
+ * The zone this session sees every day in, the same value passed as
724
+ * `AuthenticationContext.timeZone`. The provider carries it on the identity and cuts every
725
+ * day-scoped figure this session reads by it.
721
726
  */
722
727
  timeZone: TimeZone;
723
728
  /** The same value passed as `AuthenticationContext.languages`: what the agent reads, most preferred first. */
@@ -765,10 +770,10 @@ export type ConnectContext = {
765
770
  export type TransportStatus = "connecting" | "active" | "error";
766
771
  /**
767
772
  * 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.
773
+ * connection and call `connect()` again -- `reauthenticate` -- run the authentication flow
774
+ * first -- or `displaced` -- another client took the session, and nothing revives this one until
775
+ * the agent takes it back. The adapter knows which; the host acts on its word.
770
776
  */
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
777
  export type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
773
778
  /** Every field is optional: a provider sends what it knows and omits what it does not. */
774
779
  export interface Contact {
@@ -943,7 +948,7 @@ export type TaskAttribute = TaskAttributeBase & ({
943
948
  type: "timestamp";
944
949
  at: IsoTimestamp;
945
950
  });
946
- export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "callback-requested";
951
+ export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "connected-back" | "callback-requested";
947
952
  /**
948
953
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
949
954
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -966,7 +971,7 @@ export interface TaskHistoryStep {
966
971
  step: HistoryStep;
967
972
  at: IsoTimestamp;
968
973
  /**
969
- * On a step that dialled -- `transferred`, `added`, `unanswered` -- the host's identity for
974
+ * On a step that dialled -- `transferred`, `added`, `unanswered`, `connected-back` -- the host's identity for
970
975
  * that dial when a host placed it, and the contact it went to, by the contacts entry's `id`. Neither
971
976
  * belongs on any other step.
972
977
  */
@@ -1393,21 +1398,31 @@ export interface BreakRequest {
1393
1398
  reasonId?: string;
1394
1399
  }
1395
1400
  /**
1396
- * A break forced on the agent; the agent must explicitly resume when ready. A lead's `force-break`
1397
- * is a command to the provider, which forces the break: `by` names the lead who asked it to, or
1398
- * `provider` where the platform itself did, on its own rule or a schedule. The agent sees who, a
1399
- * person is named only when there is one, and a break the platform imposed is the platform's to
1400
- * lift: a lead's `end-forced-break` on it fails with `omni.break-forced-by-provider`.
1401
+ * Whom a forced break covers. `team`: the whole team, to one end for everyone, its clock running
1402
+ * while a member is signed out. `agent`: one agent, its clock counting only while they are signed in.
1403
+ */
1404
+ export type ForcedBreakScope = "team" | "agent";
1405
+ export declare const FORCED_BREAK_SCOPES: readonly ["team", "agent"];
1406
+ /**
1407
+ * A break forced on the agent, which the agent cannot end. Signing out ends the session, not the
1408
+ * break: the next session's snapshot carries it again while it stands. It is lifted by a lead, by
1409
+ * the platform, or by its time running out; lifting clears `forced` and leaves an ordinary break
1410
+ * the agent ends when ready. A lead's `force-break` or `force-team-break` is a command to the
1411
+ * provider, which forces the break: `by` names the lead who asked it to, or `provider` where the
1412
+ * platform itself did, on its own rule or a schedule. The agent sees who, a person is named only
1413
+ * when there is one, and a break the platform imposed is the platform's to lift: a lead's
1414
+ * `end-forced-break` on it fails with `omni.break-forced-by-provider`.
1401
1415
  */
1402
1416
  export type ForcedBreak = {
1403
1417
  by: UserId | "provider";
1418
+ scope: ForcedBreakScope;
1404
1419
  /**
1405
- * How long the break is expected to run yet, in whole seconds from this publication, restated
1406
- * on every publication that carries it so every screen counts down the same number from
1407
- * receipt. Advisory only: nothing ends the break but the agent. Absent once it has run out, or
1408
- * where none was expected.
1420
+ * How long the break has left, in whole seconds from this publication, restated on every
1421
+ * publication that carries it so every screen counts down the same number from receipt. When it
1422
+ * runs out the provider lifts the break. Required on a `team` break; absent on an `agent` break
1423
+ * that stands until a lead lifts it.
1409
1424
  */
1410
- expectedEndsInSeconds?: DurationSeconds;
1425
+ endsInSeconds?: DurationSeconds;
1411
1426
  };
1412
1427
  export interface BreakState {
1413
1428
  status: BreakStatus;
@@ -1416,7 +1431,8 @@ export interface BreakState {
1416
1431
  /** Shown when `canRequestBreak` is false, such as "Busy hours". */
1417
1432
  requestUnavailableReason?: string;
1418
1433
  decisionReason?: string;
1419
- retryRequestAfterMs?: number;
1434
+ /** Whole seconds until the agent may ask again, as of this publication and restated on each, when the provider can say. */
1435
+ retryRequestInSeconds?: DurationSeconds;
1420
1436
  /** Not-ready codes this provider offers. Omitted when it defines none. */
1421
1437
  reasons?: BreakReason[];
1422
1438
  /** 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 +1529,7 @@ export interface TeamMember {
1513
1529
  tasks?: MemberTask[];
1514
1530
  /** Every lead on this member's call, listening, coaching or joined, published to every lead alike; absent while none is. */
1515
1531
  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. */
1532
+ /** 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
1533
  shift?: Shift;
1518
1534
  /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
1519
1535
  request?: MemberRequest;
@@ -1580,21 +1596,37 @@ export interface ShiftEvent {
1580
1596
  at: IsoTimestamp;
1581
1597
  kind: ShiftEventKind;
1582
1598
  }
1599
+ /** A day's total that can be running now: talk, hold, or break. */
1600
+ export type ShiftFigure = "talk" | "hold" | "break";
1601
+ export declare const SHIFT_FIGURES: readonly ["talk", "hold", "break"];
1583
1602
  /**
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.
1603
+ * A stretch still running, which its total leaves out: the agent computer counts it on from `since`,
1604
+ * on the provider's clock, and adds it to the total it shows.
1605
+ */
1606
+ export interface ShiftRunning {
1607
+ figure: ShiftFigure;
1608
+ since: IsoTimestamp;
1609
+ }
1610
+ /**
1611
+ * An agent's own history for the day, about the person rather than any one call: the day's first
1612
+ * sign-in, the sign-out while they are signed out, today's totals as the provider counts them,
1613
+ * each present only when the provider knows it, the stretches still running, and the day's
1614
+ * sign-in, sign-out and break events, oldest first. The day is the viewer's: published to the
1615
+ * agent on their snapshot and on `shift-updated`, cut in the agent's zone, and to their lead on
1616
+ * the team member list, cut in the lead's -- the same instants from the same count.
1589
1617
  */
1590
1618
  export interface Shift {
1619
+ /** The day's first sign-in. */
1591
1620
  signedInAt: IsoTimestamp;
1621
+ /** The latest sign-out, present only while the agent is signed out; an earlier session's is in `events`. */
1592
1622
  signedOutAt?: IsoTimestamp;
1593
1623
  talkSeconds?: DurationSeconds;
1594
1624
  holdSeconds?: DurationSeconds;
1595
1625
  /** 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
1626
  breakSeconds?: DurationSeconds;
1597
1627
  tasksHandled?: number;
1628
+ /** The totals still running, at most one per figure; each total above leaves its running stretch out. */
1629
+ running?: ShiftRunning[];
1598
1630
  events?: ShiftEvent[];
1599
1631
  }
1600
1632
  /**
@@ -1679,18 +1711,29 @@ export type TeamBreakCommand = {
1679
1711
  type: "set-break-policy";
1680
1712
  policy: "approval-required" | "automatically-approved" | "requests-suspended";
1681
1713
  }
1682
- /** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. */
1714
+ /** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. Without `durationSeconds` it stands until lifted. */
1683
1715
  | {
1684
1716
  type: "force-break";
1685
1717
  memberId: UserId;
1686
1718
  reasonId?: string;
1687
1719
  reason?: string;
1688
- expectedDurationMs?: number;
1720
+ durationSeconds?: DurationSeconds;
1721
+ }
1722
+ /** The whole team, members who sign in while it runs included, to one end `durationSeconds` from now. */
1723
+ | {
1724
+ type: "force-team-break";
1725
+ reasonId?: string;
1726
+ reason?: string;
1727
+ durationSeconds: DurationSeconds;
1689
1728
  }
1690
1729
  /** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
1691
1730
  | {
1692
1731
  type: "end-forced-break";
1693
1732
  memberId: UserId;
1733
+ }
1734
+ /** Lifts the team break for every member, as `end-forced-break` does for one. */
1735
+ | {
1736
+ type: "end-team-break";
1694
1737
  };
1695
1738
  /** Every lead act, as `execute` takes a `TaskCommand`: discriminated by `type`. */
1696
1739
  export type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
@@ -1726,7 +1769,6 @@ export type OpenAudioResult = {
1726
1769
  status: "unavailable";
1727
1770
  failure: ProtocolFailure;
1728
1771
  };
1729
- /** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
1730
1772
  /**
1731
1773
  * What the team may leave to the person: a capability by its own name -- `hold` -- or a
1732
1774
  * skill by its provider id. The same key as in `Task.capabilities`, because it is the same
@@ -1810,6 +1852,7 @@ export type PreferenceResult = {
1810
1852
  status: "failed";
1811
1853
  failure: ProtocolFailure;
1812
1854
  };
1855
+ /** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
1813
1856
  export interface Snapshot<C extends Channel = Channel> {
1814
1857
  transport: TransportStatus;
1815
1858
  sessionId: string;
@@ -1985,7 +2028,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
1985
2028
  occurredAt: IsoTimestamp;
1986
2029
  event: ProviderEvent<C>;
1987
2030
  }
1988
- export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.on-hold", "omni.break-forced-by-provider"];
2031
+ export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.on-hold", "omni.break-forced-by-provider", "omni.break-forced"];
1989
2032
  export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
1990
2033
  /**
1991
2034
  * What the host refused, told to the adapter that published it: a snapshot the host would not
@@ -2082,7 +2125,6 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
2082
2125
  readonly chat: {
2083
2126
  readonly pending: "Incoming Chat";
2084
2127
  readonly confirmed: "Accepted";
2085
- readonly preview: "Preview";
2086
2128
  readonly "in-progress": "In Chat";
2087
2129
  readonly paused: "Paused";
2088
2130
  readonly completing: "Wrap-up";
@@ -2090,7 +2132,6 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
2090
2132
  readonly email: {
2091
2133
  readonly pending: "Assigned";
2092
2134
  readonly confirmed: "Accepted";
2093
- readonly preview: "Preview";
2094
2135
  readonly "in-progress": "Working";
2095
2136
  readonly paused: "Paused";
2096
2137
  readonly completing: "Completing";
@@ -2124,6 +2165,7 @@ export declare const DEFAULT_HISTORY_STEP_LABELS: {
2124
2165
  readonly transferred: "Transferred";
2125
2166
  readonly added: "Added";
2126
2167
  readonly unanswered: "Unanswered";
2168
+ readonly "connected-back": "Reconnected";
2127
2169
  readonly "callback-requested": "Callback requested";
2128
2170
  };
2129
2171
  /**
@@ -2150,12 +2192,12 @@ export declare const assignmentKey: (providerId: string, assignmentId: Assignmen
2150
2192
  export declare const userKey: (providerId: string, userId: UserId) => string;
2151
2193
  /**
2152
2194
  * 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
2195
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's own choice in the queue, so none
2154
2196
  * of them is here.
2155
2197
  */
2156
- export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered"];
2198
+ export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered", "connected-back"];
2157
2199
  /** 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"];
2200
+ export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "added", "unanswered", "connected-back"];
2159
2201
  export declare const historyStepDials: (step: HistoryStep) => boolean;
2160
2202
  /**
2161
2203
  * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
package/dist/index.js CHANGED
@@ -40,7 +40,9 @@ export const LEAD_COMMAND_CAPABILITY = {
40
40
  "decide-break-request": "decideBreakRequest",
41
41
  "set-break-policy": "setBreakPolicy",
42
42
  "force-break": "forceBreak",
43
+ "force-team-break": "forceBreak",
43
44
  "end-forced-break": "endForcedBreak",
45
+ "end-team-break": "endForcedBreak",
44
46
  "set-policy": "setPolicy",
45
47
  };
46
48
  export const MUTED_BY = ["host", "station"];
@@ -99,7 +101,9 @@ export const BREAK_KINDS = [
99
101
  "short-break", "meal", "rest", "training", "coaching",
100
102
  "meeting", "administrative", "technical", "personal", "other",
101
103
  ];
104
+ export const FORCED_BREAK_SCOPES = ["team", "agent"];
102
105
  export const SHIFT_EVENT_KINDS = ["signed-in", "signed-out", "break-started", "break-ended"];
106
+ export const SHIFT_FIGURES = ["talk", "hold", "break"];
103
107
  export const OMNI_FAILURE_CODES = [
104
108
  "omni.not-authenticated",
105
109
  "omni.capability-not-enabled",
@@ -115,6 +119,8 @@ export const OMNI_FAILURE_CODES = [
115
119
  "omni.on-hold",
116
120
  /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
117
121
  "omni.break-forced-by-provider",
122
+ /** The agent asked to end a break that is still forced; only its lifting does. */
123
+ "omni.break-forced",
118
124
  ];
119
125
  /**
120
126
  * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.
@@ -132,11 +138,11 @@ export const DEFAULT_TASK_PHASE_LABELS = {
132
138
  "in-progress": "On Call", paused: "On Hold", completing: "After Call Work",
133
139
  },
134
140
  chat: {
135
- pending: "Incoming Chat", confirmed: "Accepted", preview: "Preview",
141
+ pending: "Incoming Chat", confirmed: "Accepted",
136
142
  "in-progress": "In Chat", paused: "Paused", completing: "Wrap-up",
137
143
  },
138
144
  email: {
139
- pending: "Assigned", confirmed: "Accepted", preview: "Preview",
145
+ pending: "Assigned", confirmed: "Accepted",
140
146
  "in-progress": "Working", paused: "Paused", completing: "Completing",
141
147
  },
142
148
  };
@@ -148,7 +154,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
148
154
  export const DEFAULT_HISTORY_STEP_LABELS = {
149
155
  arrived: "Incoming call", "self-service": "Self-service", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
150
156
  muted: "Muted", transferred: "Transferred", added: "Added", unanswered: "Unanswered",
151
- "callback-requested": "Callback requested",
157
+ "connected-back": "Reconnected", "callback-requested": "Callback requested",
152
158
  };
153
159
  /**
154
160
  * The provider's text for the first of `languages` it has, matched as BCP 47 lookup does: the tag
@@ -196,14 +202,14 @@ export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent
196
202
  export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
197
203
  /**
198
204
  * 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
205
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's own choice in the queue, so none
200
206
  * of them is here.
201
207
  */
202
208
  export const HISTORY_STEPS_WITH_A_PERSON = [
203
- "offered", "answered", "held", "muted", "transferred", "added", "unanswered",
209
+ "offered", "answered", "held", "muted", "transferred", "added", "unanswered", "connected-back",
204
210
  ];
205
211
  /** 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"];
212
+ export const HISTORY_STEPS_THAT_DIAL = ["transferred", "added", "unanswered", "connected-back"];
207
213
  export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step);
208
214
  // Pinned both ways: a step added to `HistoryStep` has to be placed here, and a step listed here
209
215
  // has to exist there. `satisfies` on the list covers the second; this statement covers the first.
package/dist/testing.d.ts CHANGED
@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
7
7
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
8
8
  * declared contribution, and each event type.
9
9
  */
10
- declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "labels", "contacts", "calendar", "team.policies"];
10
+ declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "break.forced.signIn", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "labels", "contacts", "calendar", "team.policies"];
11
11
  export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
12
12
  export interface AdapterContractResult {
13
13
  events: ProviderEventEnvelope[];
@@ -57,6 +57,14 @@ export interface TestAdapterOptions {
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
+ /**
61
+ * Builds the adapter again after the agent signed out, for a backend that signs the same agent
62
+ * in again, as a sign-in screen would. Given it, a run whose agent is on a forced break at the end
63
+ * signs out, signs in, and expects the new session's snapshot to carry the same break, its time
64
+ * left counted by its kind's clock. Without it, or with no forced break to carry, the run lists
65
+ * `break.forced.signIn` under `notTested`.
66
+ */
67
+ signInAgain?: () => Adapter<Channel>;
60
68
  /**
61
69
  * The values the queue locks on this session's tasks -- a party's number or email -- as the run's
62
70
  * author knows them. A task whose party stands locked may carry none of them anywhere else