@xema/omni-protocol 0.1.100 → 0.1.102

package/dist/index.d.ts

@@ -164,7 +164,7 @@ export interface Manifest<C extends Channel = Channel> {
     /**
      * The outcomes this platform distinguishes when a dial ends, `answered` and at least one way of
      * not reaching the destination. Required of a provider that dials at all -- an idle dialpad, or
-     * a task that may transfer, conference, or call back -- and forbidden off voice, where nothing dials.
+     * a task that may conference or call back -- and forbidden off voice, where nothing dials.
      */
     dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
     /**
@@ -180,10 +180,9 @@ export interface Manifest<C extends Channel = Channel> {
     runningStepReports?: true;
     /**
      * How long after an applied completion -- `complete`, or a lead's `take-over-call` -- the provider's
-     * `task-ended` is owed, in milliseconds. A warm transfer's `complete` is not one: the agent's
-     * wrap runs after it as after any call. `applied` says the provider
-     * has completed the task; the ending follows within this, or the host resyncs and shows the
-     * task as unsettled. Stated per provider, since platforms settle at different speeds.
+     * `task-ended` is owed, in milliseconds. `applied` says the provider has completed the task;
+     * the ending follows within this, or the host resyncs and shows the task as unsettled. Stated
+     * per provider, since platforms settle at different speeds.
      */
     completionSettleMs: number;
 }
@@ -251,9 +250,10 @@ export interface UserCapabilities {
     /**
      * This login leads a team. The flag alone turns on the team feature in the agent application:
      * the lead sees their members with their tasks and stats, and acts on them through `executeTeam`
-     * with the authority the flag carries. No per-action permission rides beside it. While the lead
-     * has the feature on, a `TeamMembers` object is published to them on every snapshot, `members: []`
-     * included; to nobody else, ever.
+     * with the authority the flag carries. No per-action permission rides beside it. The provider
+     * assumes nothing of the switch: the application sends `lead-features` on every connect, and
+     * only while it is on does the team reach the lead -- `team-updated` whole after the switch and
+     * on any snapshot, then one member at a time as members change; to nobody else, ever.
      */
     lead?: true;
 }
@@ -458,7 +458,6 @@ export type RecordingState = {
 export type RecordingCommand = {
     type: "recording";
     source: RecordingSource;
-    requestId: string;
     /** Compare-and-set against current evidence; never act on a replacement recording. */
     observationId: string;
 } & ({
@@ -622,7 +621,7 @@ export interface Destination {
     id: string;
     label: string;
 }
-/** The items a transfer or conference control offers. Nothing is typed; the agent picks one. */
+/** The items a conference control offers. Nothing is typed; the agent picks one. */
 export interface DestinationDirectory {
     destinations: Destination[];
 }
@@ -653,14 +652,13 @@ export interface SharedTaskCapabilities {
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
-    /** The provider ends the caller connection and agent-added channels owned by this interaction, including inherited channels after transfer/takeover. Interaction completion remains separate. */
+    /** The provider ends the caller connection and agent-added channels owned by this interaction, including inherited channels after a take-over. Interaction completion remains separate. */
     endCall?: Lockable<true>;
     terminateCall?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
-    coldTransfer?: Lockable<DestinationDirectory>;
-    /** Park the customer and call a destination first; then `complete` or `cancel`. */
-    warmTransfer?: Lockable<DestinationDirectory>;
+    /** Put a time on the calendar for this party, from the call: a follow-up the agent promised. */
+    schedule?: Lockable<true>;
     /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
     leadAssist?: Lockable<true>;
     conference?: Lockable<DestinationDirectory>;
@@ -721,7 +719,7 @@ export type TaskPhase =
  | "confirmed"
 /**
  * Voice only: the customer's record is available for preparation, then dialing before answer. The agent
- * presses Call, or `previewEndsAt` arrives and `atDeadline` says what the system does instead.
+ * presses Call, or `previewEndsInSeconds` runs out and `atDeadline` says what the system does instead.
  */
  | "preview" | "in-progress" | "paused"
 /** The work is over and the agent is finishing up. */
@@ -807,19 +805,18 @@ export type TaskCompletion = {
     completionMode: "provider-automatic";
     wrapAllowance: DurationSeconds;
 };
-export type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
+export type OnCallRole = "party" | "agent" | "conferenced";
 /** Where a dialled entry stands: `ringing` until its dial is answered, `joined` after. */
 export type OnCallStage = "ringing" | "joined";
-export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "conferenced"];
+export declare const ON_CALL_ROLES: readonly ["party", "agent", "conferenced"];
 /**
  * Somebody on the call, or being brought onto it, as the provider states it: who, since when, and
- * whether they are held aside. `party` is the customer; `agent` a person, by user id; `consulted`
- * and `conferenced` someone a dial is bringing in -- listed from the moment the dial is placed, so
- * the agent can call it off while it rings -- carrying the dial when a host placed it, the address
- * either way, and the `stage` it has reached: `ringing` until the dial is answered, `joined` after,
- * stated so a snapshot says who is present without anyone having seen the outcome. Nobody ringing is
- * held. `label` names a destination -- a person, a queue -- not a phrase. At most one `party` and
- * one `consulted`: the consult commands name neither because there is exactly one. The `party`
+ * whether they are held aside. `party` is the customer; `agent` a person, by user id; `conferenced`
+ * someone a dial is bringing in -- listed from the moment the dial is placed, so the agent can call
+ * it off while it rings -- carrying the dial when a host placed it, the address either way, and the
+ * `stage` it has reached: `ringing` until the dial is answered, `joined` after, stated so a snapshot
+ * says who is present without anyone having seen the outcome. Nobody ringing is held. `label` names
+ * a destination -- a person, a queue -- not a phrase. At most one `party`. The `party`
  * carries a `stage` while being dialled -- by any host dial, a dialpad call, a preview Call or a
  * connect-back, carrying its `dialId`, or by a callback the platform places itself, carrying none --
  * `ringing` from the moment the dial is placed, `joined` on the publication that follows its
@@ -842,7 +839,7 @@ export type OnCall = {
     role: "agent";
     userId: UserId;
 } | {
-    role: "consulted" | "conferenced";
+    role: "conferenced";
     destinationId: string;
     stage: OnCallStage;
     dialId?: DialId;
@@ -866,7 +863,7 @@ export type TaskLeadAssist = {
  * On a task that reached this agent by a lead's take-over: which member the call was taken from,
  * and when. The provider moves the call from one agent to another, and the lead is the new agent,
  * so the task is an ordinary assignment with the call's history -- offered whatever break the lead
- * is on, counted against no capacity, provided their voice channel is free.
+ * is on, counted against their capacity like any other call, provided they are under it and their voice channel is free.
  */
 export interface TaskTakenOver {
     memberId: UserId;
@@ -952,12 +949,14 @@ export type Task<C extends Channel = Channel> = {
      */
     acceptance?: AcceptanceMode;
     /**
-     * In `preview` only, and together: the preparation target and behavior when it elapses,
-     * and who acts then -- `provider-dials` makes the provider initiate dialing, `host-dials` makes the
-     * host issue Call, and `waits` keeps waiting for the agent without dialing or ending the task.
-     * Absent, the agent has as long as they need, without a preparation countdown.
+     * In `preview` only, and together: how long the preparation has left, in whole seconds from
+     * this publication -- restated on every publication that carries it, so a resync starts the
+     * countdown afresh and no clock is compared -- and behavior when it runs out, and who acts then:
+     * `provider-dials` makes the provider initiate dialing, `host-dials` makes the host issue Call,
+     * and `waits` keeps waiting for the agent without dialing or ending the task. Absent, the agent
+     * has as long as they need, without a preparation countdown.
      */
-    previewEndsAt?: IsoTimestamp;
+    previewEndsInSeconds?: DurationSeconds;
     atDeadline?: PreviewDeadline;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
@@ -989,11 +988,6 @@ export type TaskOutcome = {
     type: "completed";
     by: "agent" | "provider";
 }
-/** A cold transfer to a destination the agent chose: a directory item's id. */
- | {
-    type: "transferred";
-    destinationId?: string;
-}
 /** A lead took the call over and the agent has wrapped it: the outcome at the agent's own completion. Named by the lead, since a lead is not a directory item. */
  | {
     type: "taken-over";
@@ -1005,7 +999,7 @@ export type TaskOutcome = {
     by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire; an offer that lapses at `assignmentExpiresAt` names `pending`. */
+/** Only the phases in which somebody is still being waited on can expire; an offer whose `expiresInSeconds` runs out names `pending`. */
  | {
     type: "expired";
     phase: "pending" | "confirmed" | "preview";
@@ -1014,7 +1008,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"];
     readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "decline", "complete"];
 };
@@ -1041,7 +1035,7 @@ export type VoiceTaskCommand = {
  | {
     type: "end-call";
 }
-/** End the caller channel. Gated by `terminateCall`. */
+/** End the whole call at the provider: every channel on it, the agent's, the caller's and anyone else's. Gated by `terminateCall`. */
  | {
     type: "terminate-call";
 }
@@ -1050,29 +1044,15 @@ export type VoiceTaskCommand = {
     type: "connect-back";
     dialId: DialId;
 }
-/** Cold: hand the customer to the directory item `destinationId` with nobody spoken to first. Gated by `coldTransfer`. */
- | {
-    type: "transfer";
-    action: "cold";
-    dialId: DialId;
-    destinationId: string;
-}
-/** Warm: park the customer and call the directory item `destinationId` first. Gated by `warmTransfer`. */
- | {
-    type: "transfer";
-    action: "warm";
-    dialId: DialId;
-    destinationId: string;
-}
-/** Hand the customer to the consulted destination and leave. Needs a `consulted` entry on `Task.onCall`. */
- | {
-    type: "transfer";
-    action: "complete";
-}
-/** Drop the consulted destination and return to the customer. Needs a `consulted` entry on `Task.onCall`. */
+/**
+ * Put a time on the calendar for this party: a follow-up promised on the call. Gated by
+ * `schedule`, issuable in `in-progress`, `paused` or `completing`; the activity arrives on
+ * `calendar-updated`, which is the provider's word that it stands.
+ */
  | {
-    type: "transfer";
-    action: "cancel";
+    type: "schedule";
+    at: IsoTimestamp;
+    note?: string;
 }
 /** Ask a lead to join, with a note. Gated by `leadAssist`. */
  | {
@@ -1206,9 +1186,13 @@ export interface BreakRequest {
     /** The chosen `BreakReason.id`, where the provider publishes codes. */
     reasonId?: string;
 }
-/** A break forced on the agent; the agent must explicitly resume when ready. */
+/**
+ * A break forced on the agent; the agent must explicitly resume when ready. `by` is the lead who
+ * forced it, or `provider` where the platform itself did, on its own rule or a schedule: the agent
+ * sees who, and a person is named only when there is one.
+ */
 export type ForcedBreak = {
-    by: UserId;
+    by: UserId | "provider";
     /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
     expectedDurationMs?: number;
 };
@@ -1269,10 +1253,13 @@ export interface TeamMember {
     tasks?: MemberTask[];
     /** Present while this lead is on the member's call, listening, coaching or joined; absent otherwise. */
     listening?: MemberListening;
+    /** The member's own history for the day: sign-in, sign-out, breaks and productivity. Omitted where the provider cannot say. */
+    shift?: MemberShift;
+    /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
+    request?: MemberRequest;
 }
-/** A member asking this lead to join their call, named by the member and the assignment. */
-export interface LeadRequest {
-    memberId: UserId;
+/** This member asking their lead to join a call: which assignment, the note they wrote, since when. */
+export interface MemberRequest {
     assignmentId: AssignmentId;
     note?: string;
     since: IsoTimestamp;
@@ -1309,20 +1296,45 @@ export type MemberTask<C extends Channel = Channel> = {
     takenOver?: never;
     audio?: never;
 });
-/** The lead on this member's call, in the mode they are heard, since when. */
+/**
+ * The lead on this member's call: which of the member's calls, in the mode they are heard, since
+ * when. Its appearance on the team member list is the provider's word that the lead's audio is up,
+ * and the application opens `openAudio` on the assignment named; its disappearance closes it.
+ */
 export interface MemberListening {
+    assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
 }
+export type ShiftEventKind = "signed-in" | "signed-out" | "break-started" | "break-ended";
+export declare const SHIFT_EVENT_KINDS: readonly ["signed-in", "signed-out", "break-started", "break-ended"];
+export interface ShiftEvent {
+    at: IsoTimestamp;
+    kind: ShiftEventKind;
+}
+/**
+ * The member's own history for the day, about the person rather than any one call: when they
+ * signed in and out, today's totals as the provider counts them, each present only when the
+ * provider knows it, and the day's sign-in, sign-out and break events, oldest first.
+ */
+export interface MemberShift {
+    signedInAt: IsoTimestamp;
+    signedOutAt?: IsoTimestamp;
+    talkSeconds?: DurationSeconds;
+    holdSeconds?: DurationSeconds;
+    breakSeconds?: DurationSeconds;
+    tasksHandled?: number;
+    events?: ShiftEvent[];
+}
 /**
  * The lead's view of their team: published to a login that declares `capabilities.lead` while the
- * lead has the team feature on, on every snapshot, and to nobody else. The provider keeps it
- * current: when a member holds, mutes or is transferred, the list is republished whole.
+ * lead has the team feature on, and to nobody else. Whole on `team-updated` -- after the switch,
+ * and on any snapshot -- and from then on one member at a time: `team-member-updated` carries the
+ * member whole, so applying it twice changes nothing, and `team-member-removed` takes one off.
+ * A team of two hundred is never resent because one of them held.
  */
 export interface TeamMembers {
     members: TeamMember[];
-    /** Members asking a lead to join their call; `[]` when nobody is asking. */
-    requests: LeadRequest[];
     /** The team's policy per capability, as it stands. Present where the provider offers policy control; absent where it does not. */
     policies?: TeamPolicies;
 }
@@ -1578,7 +1590,8 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    assignmentExpiresAt?: IsoTimestamp;
+    /** How long the agent has to answer, in whole seconds from this event; the offer expires when it runs out. Absent, it stands until the provider says otherwise. */
+    expiresInSeconds?: DurationSeconds;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1588,20 +1601,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-audio-ended";
     assignmentId: AssignmentId;
-}
-/**
- * The lead's channel is in a member's call -- listening, coaching or joined -- and its audio should
- * attach: on a softphone the application opens audio on the member's assignment as it does for a
- * task. Voice, to a login that declares `lead`, never to the member.
- */
- | {
-    type: "team-audio-started";
-    memberId: UserId;
-    assignmentId: AssignmentId;
-} | {
-    type: "team-audio-ended";
-    memberId: UserId;
-    assignmentId: AssignmentId;
 } | {
     type: "task-ended";
     assignmentId: AssignmentId;
@@ -1635,9 +1634,22 @@ export type ProviderEvent<C extends Channel = Channel> = {
     expected: string;
     observed: string;
     assignmentId?: AssignmentId;
-} | {
+}
+/** The whole team, once: after `lead-features` comes on, and on every snapshot while it is. */
+ | {
     type: "team-updated";
     team: TeamMembers;
+}
+/** One member, whole, as they now stand: replaces the member of that id, or adds them. */
+ | {
+    type: "team-member-updated";
+    member: TeamMember;
+} | {
+    type: "team-member-removed";
+    memberId: UserId;
+} | {
+    type: "team-policies-updated";
+    policies: TeamPolicies;
 } | {
     type: "contacts-updated";
     contacts: Contact[];
@@ -1657,7 +1669,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-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"];
+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"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 /**
  * What the host refused, told to the adapter that published it: a snapshot the host would not

package/dist/index.js

@@ -56,7 +56,7 @@ export function isAllowedBrowserUrl(url) {
         return false;
     }
 }
-export const ON_CALL_ROLES = ["party", "agent", "consulted", "conferenced"];
+export const ON_CALL_ROLES = ["party", "agent", "conferenced"];
 /**
  * The levels a typical organisation has: the ladder in force when a manifest declares no
  * `orgLevels`. A manifest that declares any states its whole ladder outright.
@@ -77,7 +77,7 @@ export const CAPABILITY_SOURCES = ["queue", "nobody", "not-yet-read"];
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
     voice: ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call",
-        "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"],
+        "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"],
     chat: ["accept", "decline", "pause", "resume", "complete"],
     email: ["accept", "decline", "complete"],
 };
@@ -85,8 +85,6 @@ export const TASK_COMMAND_NAMES = {
 export function commandDialId(command) {
     if (command.type === "connect-back" || command.type === "dial")
         return command.dialId;
-    if (command.type === "transfer" && (command.action === "cold" || command.action === "warm"))
-        return command.dialId;
     if (command.type === "conference" && command.action === "add")
         return command.dialId;
     return undefined;
@@ -95,6 +93,7 @@ export const BREAK_KINDS = [
     "short-break", "meal", "rest", "training", "coaching",
     "meeting", "administrative", "technical", "personal", "other",
 ];
+export const SHIFT_EVENT_KINDS = ["signed-in", "signed-out", "break-started", "break-ended"];
 export const OMNI_FAILURE_CODES = [
     "omni.not-authenticated",
     "omni.capability-not-enabled",
@@ -104,6 +103,8 @@ export const OMNI_FAILURE_CODES = [
     "omni.rate-limited",
     "omni.unavailable",
     "omni.break-already-committed",
+    /** A recording command the provider could not settle either way: no start, stop, pause or resume it can vouch for. */
+    "omni.recording-unsettled",
 ];
 /**
  * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
  * declared contribution, and each event type.
  */
-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.requests", "team.tasks", "team.listening", "contacts", "calendar", "team.policies"];
+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", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -149,6 +149,8 @@ export declare class TaskStream {
     private readonly tasks;
     private readonly assignments;
     private readonly endedAssignments;
+    /** Every assignment a `task-offered` introduced, as against one a snapshot carried: each is owed its ending. */
+    private readonly offered;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
@@ -160,6 +162,8 @@ export declare class TaskStream {
     private notOpen;
     /** How many tasks the stream currently holds open. */
     openCount(): number;
+    /** The assignments an offer introduced that are still open: each was owed a `task-ended` that has not come. */
+    unended(): string[];
     /** Whether an offered task is a dial arriving -- the host's own call, a connect-back -- which counts against no capacity: an entry on its call carrying a dial. */
     static carriesDial(task: unknown): boolean;
     /**
@@ -188,6 +192,20 @@ export declare class TaskStream {
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 /** What a stream has said about the agent's break, and the moves it may not make. */
+/**
+ * The team as the events left it: whole on `team-updated` and on any snapshot carrying one, then
+ * one member at a time. A member event before the whole team, or a removal of a member the team
+ * never carried, is a change to a team the lead was never given.
+ */
+export declare class TeamStream {
+    private members;
+    private static ids;
+    /** A snapshot carrying a team is the team whole; one carrying none leaves the lead with none. */
+    seed(snapshot: unknown): void;
+    /** Whether the team currently carries this member, as the events left it. */
+    has(id: string): boolean;
+    apply(envelope: unknown, path?: string): ProtocolViolation[];
+}
 export declare class BreakStream {
     private state;
     private recovery;