@xema/omni-protocol 0.1.32 → 0.1.33

package/dist/index.d.ts

@@ -26,6 +26,12 @@ export type IsoTimestamp = string;
 export type UserId = string;
 /** A non-empty, opaque task identifier unique within one provider. Scope it with `taskKey()`. */
 export type TaskId = string;
+/**
+ * The host's identity for one dial, minted before the command leaves and unique across the
+ * installation. A dial is the one command whose outcome arrives later and apart, so the provider
+ * names this on the outcome and the host has already placed it. Never shown to the agent.
+ */
+export type DialId = string;
 /** A non-negative whole number of seconds. */
 export type DurationSeconds = number;
 /** New channels require a later protocol version. */
@@ -68,6 +74,13 @@ export type DialDestinations = "contacts-only" | "any-number";
 export interface DialCapability {
     destinations: DialDestinations;
 }
+/**
+ * How a dial ended, as the switch distinguishes it. `answered` is the one success; the rest are
+ * the ways a destination was not reached. A manifest declares which of these its platform can
+ * tell apart (`dialOutcomes`), and a `dial-outcome` carries only a declared one.
+ */
+export type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected";
+export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "unreachable", "rejected"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
 export type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
@@ -113,6 +126,12 @@ export interface Manifest<C extends Channel = Channel> {
     taskTypePresentation?: Record<string, TaskTypePresentation>;
     /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_LEVELS`. */
     orgLevels?: LevelDeclaration[];
+    /**
+     * 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.
+     */
+    dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
     /**
      * The provider takes running reports of a host-performed step -- `recordStep` with `seconds`
      * so far and no `ended`. Absent, the host sends exactly two reports per leg, when it began and
@@ -520,6 +539,12 @@ export interface TaskHandlingHistory {
 export interface TaskHandlingStep {
     step: HandlingStep;
     at: IsoTimestamp;
+    /**
+     * On a step that dialled -- `transferred`, `conferenced`, `unanswered` -- the host's identity for
+     * that dial when a host placed it, and the address it went to. Neither belongs on any other step.
+     */
+    dialId?: DialId;
+    destination?: string;
     /**
      * Reported, never derived. An entry may be written while its leg is still running, so there is
      * no end to subtract from -- and omitted is the honest report of that, where nought would
@@ -547,16 +572,29 @@ export type TaskCompletion = {
     completionMode: "provider-automatic";
     wrapAllowance: DurationSeconds;
 };
+export type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
+export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "conferenced"];
 /**
- * A consultation in progress on a task: who is being consulted, and since when where the provider
- * records it. Present between `transfer` `consult` and whichever of `complete` or `cancel`
- * follows; its presence is what makes those two issuable.
+ * Somebody on the call right now, 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 brought in, carrying the dial when a host placed it and the address
+ * either way. `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.
  */
-export interface TaskConsultation {
+export type OnCall = {
+    since: IsoTimestamp;
+    held?: true;
+} & ({
+    role: "party";
+} | {
+    role: "agent";
+    userId: UserId;
+} | {
+    role: "consulted" | "conferenced";
     destination: string;
+    dialId?: DialId;
     label?: string;
-    since?: IsoTimestamp;
-}
+});
 /**
  * The agent's request for a lead, from asking until the lead leaves or the request ends.
  * `requested` while nobody has joined; `joined`, with `leadId`, once somebody has.
@@ -643,12 +681,12 @@ export type Task<C extends Channel = Channel> = {
     attributes?: TaskAttribute[];
     handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (C extends "voice" ? {
-    consultation?: TaskConsultation;
+    onCall?: OnCall[];
     lead?: TaskLead;
     assisting?: TaskAssisting;
     media?: TaskMediaState;
 } : {
-    consultation?: never;
+    onCall?: never;
     lead?: never;
     assisting?: never;
     media?: never;
@@ -708,13 +746,15 @@ export type VoiceTaskCommand = {
 } | {
     type: "disconnect";
 }
-/** Issuable only in `completing`, under the `callback` capability. Carries no destination. */
+/** Issuable only in `completing`, under the `callback` capability. Dials the party's own number, so it names none. */
  | {
     type: "callback";
+    dialId: DialId;
 }
 /** Blind: hand the customer to `destination` with nobody consulted. Gated by `blindTransfer`. */
  | {
     type: "transfer";
+    dialId: DialId;
     destination: string;
     action?: never;
 }
@@ -722,14 +762,15 @@ export type VoiceTaskCommand = {
  | {
     type: "transfer";
     action: "consult";
+    dialId: DialId;
     destination: string;
 }
-/** Hand the customer to the consulted destination and leave. Needs `Task.consultation`. */
+/** 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 `Task.consultation`. */
+/** Drop the consulted destination and return to the customer. Needs a `consulted` entry on `Task.onCall`. */
  | {
     type: "transfer";
     action: "cancel";
@@ -754,10 +795,19 @@ export type VoiceTaskCommand = {
  | {
     type: "lead";
     action: "leave";
-} | {
+}
+/** Dial `destination` into the call. Gated by `conference`. */
+ | {
+    type: "conference";
+    action: "add";
+    dialId: DialId;
+    destination: string;
+}
+/** Drop the `conferenced` entry on `Task.onCall` with this destination. */
+ | {
     type: "conference";
-    participant: string;
-    action: "add" | "remove";
+    action: "remove";
+    destination: string;
 } | {
     type: "recording";
     action: "start" | "pause" | "resume" | "stop";
@@ -795,22 +845,33 @@ export interface TaskCommandRequest<C extends Channel = Channel> {
 /**
  * `applied` rather than a verb per command: the command travels in the request, so
  * `execute({ command: { type: "hold" } })` returning `applied` already says the hold applied.
+ * A command that dials answers `dialling` instead, restating the host's `dialId`: accepted, the
+ * call being placed, and the outcome still to come on `dial-outcome`.
  *
  * A promise that rejects with no result means *unknown*, not `failed`. Omni does not retry --
  * no adapter on the agent's PC can make a repeat safe -- and the next snapshot shows what the
- * provider did. A command therefore carries no key of Omni's making.
+ * provider did. A command therefore carries no retry key of Omni's making; a `dialId` is not
+ * one, it is how an outcome arriving later is placed.
  */
 export type TaskCommandResult = {
     status: "applied";
+} | {
+    status: "dialling";
+    dialId: DialId;
 } | {
     status: "failed";
     failure: ProtocolFailure;
 };
+/** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
+export declare function commandDialId(command: TaskCommand): DialId | undefined;
 export interface DialRequest {
+    dialId: DialId;
     destination: string;
 }
+/** `dialling` says accepted and being placed, nothing more; the outcome arrives on `dial-outcome`. */
 export type DialResult = {
-    status: "dialled";
+    status: "dialling";
+    dialId: DialId;
 } | {
     status: "failed";
     failure: ProtocolFailure;
@@ -1148,6 +1209,20 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "task-ended";
     taskId: TaskId;
     outcome: TaskOutcome;
+}
+/**
+ * How a dial the host placed ended, once, either way -- `answered` is stated, never read off
+ * somebody appearing on the call. `taskId` where the dial was on a task, and that task may
+ * already have ended: a dial placed late routinely outlives its call. `reason` is the switch's
+ * own words, shown to the agent as such.
+ */
+ | {
+    type: "dial-outcome";
+    dialId: DialId;
+    outcome: DialOutcome;
+    taskId?: TaskId;
+    destination?: string;
+    reason?: string;
 } | {
     type: "announcement";
     text: string;
@@ -1291,6 +1366,9 @@ export declare const taskKey: (providerId: string, taskId: TaskId) => string;
 export declare const userKey: (providerId: string, userId: UserId) => string;
 /** Every handling step somebody takes part in. `queued` is the one nobody does. */
 export declare const HANDLING_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
+/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destination`. */
+export declare const HANDLING_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
+export declare const handlingStepDials: (step: HandlingStep) => boolean;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export declare function handlingStepExpectsAPerson(step: HandlingStep): boolean;
 export interface BrowserSessionKeyInput {

package/dist/index.js

@@ -15,6 +15,7 @@ export function negotiateProtocolVersion(adapterVersions, hostVersions = OMNI_SU
     const shared = adapterVersions.filter(version => host.has(version));
     return shared.length === 0 ? undefined : Math.max(...shared);
 }
+export const DIAL_OUTCOMES = ["answered", "busy", "no-answer", "unreachable", "rejected"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"];
 /** What Omni calls each idle capability. */
@@ -50,6 +51,7 @@ export function isAllowedBrowserUrl(url) {
         return false;
     }
 }
+export const ON_CALL_ROLES = ["party", "agent", "consulted", "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.
@@ -73,6 +75,16 @@ export const TASK_COMMAND_NAMES = {
     chat: ["accept", "reject", "pause", "resume", "complete"],
     email: ["accept", "reject", "complete"],
 };
+/** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
+export function commandDialId(command) {
+    if (command.type === "callback")
+        return command.dialId;
+    if (command.type === "transfer" && (command.action === undefined || command.action === "consult"))
+        return command.dialId;
+    if (command.type === "conference" && command.action === "add")
+        return command.dialId;
+    return undefined;
+}
 export const BREAK_KINDS = [
     "short-break", "meal", "rest", "training", "coaching",
     "meeting", "administrative", "technical", "personal", "other",
@@ -138,6 +150,12 @@ export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)
 export const HANDLING_STEPS_WITH_A_PERSON = [
     "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",
 ];
+/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destination`. */
+export const HANDLING_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
+export const handlingStepDials = (step) => HANDLING_STEPS_THAT_DIAL.includes(step);
+// Pinned both ways: a step added to `HandlingStep` has to be placed here, and a step listed here
+// has to exist there. `satisfies` on the list covers the second; this statement covers the first.
+true;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export function handlingStepExpectsAPerson(step) {
     return HANDLING_STEPS_WITH_A_PERSON.includes(step);

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 roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.onCall", "task.lead", "task.assisting", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -98,6 +98,10 @@ export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApp
 /** What a stream has said about the tasks it carries, and the rules across events. */
 export declare class TaskStream {
     private readonly tasks;
+    private readonly dials;
+    /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
+    dialled(dialId: string): void;
+    private noteDials;
     private static stated;
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot: unknown): void;
@@ -127,7 +131,7 @@ export declare function assertBreakFollowsItsRequests(envelopes: readonly Provid
 export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
 export declare function stillHost(report?: HostReport, guarantees?: HostGuarantees): Host;
-/** One provider as the host sees it when freezing a break attempt's participant set. */
+/** One provider as the host sees it when freezing the providers a break attempt asks. */
 export interface BreakCandidate {
     id: string;
     authentication: AuthenticationState["status"];
@@ -135,13 +139,13 @@ export interface BreakCandidate {
     holdsCapacity: boolean;
 }
 /**
- * The participant set of a break attempt is every connected provider from which the agent can
- * currently receive work. A provider whose login is not usable -- `expired` above all -- is not
- * one, whatever else is true of it: nothing can be asked of it, and a host that waits on it
- * stalls the break for everyone. A usable provider holding capacity is one, and cannot be left
- * out. `refreshing` is usable: identity and capabilities remain available and work continues.
+ * A break attempt asks every connected provider from which the agent can currently receive work.
+ * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is
+ * true of it: nothing can be asked of it, and a host that waits on it stalls the break for
+ * everyone. A usable provider holding capacity is asked, and cannot be left out. `refreshing` is
+ * usable: identity and capabilities remain available and work continues.
  */
-export declare function assertBreakParticipants(candidates: readonly BreakCandidate[], participants: readonly string[]): void;
+export declare function assertBreakAttemptProviders(candidates: readonly BreakCandidate[], asked: readonly string[]): void;
 /** One published moment of a break asked for on a task: the approval, and how many tasks were outstanding. */
 export interface BreakOnTaskStep {
     approval: BreakApproval;

package/dist/testing.js

@@ -12,7 +12,7 @@ const STATE_SUBJECTS = [
     "task.browsers",
     "task.attributes",
     "task.handlingHistory",
-    "task.consultation",
+    "task.onCall",
     "task.lead",
     "task.assisting",
     "task.media",
@@ -33,7 +33,7 @@ const STATE_SUBJECTS = [
 // `ProviderEvent` without a row here, or a row it lacks, is a compile error.
 const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
-    "task-media-started": true, "task-media-ended": true, "task-ended": true, announcement: true, "queue-summary": true, diagnostic: true,
+    "task-media-started": true, "task-media-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "contacts-updated": true, "calendar-updated": true,
 };
 const CONTRACT_SUBJECTS = [
@@ -54,8 +54,8 @@ function observeTask(value, seen) {
         seen.add("task.attributes");
     if (isRecord(value.handlingHistory) && some(value.handlingHistory.steps))
         seen.add("task.handlingHistory");
-    if (value.consultation !== undefined)
-        seen.add("task.consultation");
+    if (some(value.onCall))
+        seen.add("task.onCall");
     if (value.lead !== undefined)
         seen.add("task.lead");
     if (value.assisting !== undefined)
@@ -617,6 +617,27 @@ const WORK_BEGUN = new Set(["in-progress", "paused", "completing"]);
 /** What a stream has said about the tasks it carries, and the rules across events. */
 export class TaskStream {
     tasks = new Map();
+    // Every dial the stream can place an outcome against: one the host said it placed, or one a
+    // task carried on `onCall` or in its record -- which is how a dial made before a transfer is known
+    // to whoever holds the task now. `ended` once its outcome arrived, since an outcome comes once.
+    dials = new Map();
+    /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
+    dialled(dialId) {
+        if (!this.dials.has(dialId))
+            this.dials.set(dialId, "placed");
+    }
+    noteDials(task) {
+        if (!isRecord(task))
+            return;
+        const entries = [
+            ...(Array.isArray(task.onCall) ? task.onCall : []),
+            ...(isRecord(task.handlingHistory) && Array.isArray(task.handlingHistory.steps) ? task.handlingHistory.steps : []),
+        ];
+        for (const entry of entries) {
+            if (isRecord(entry) && typeof entry.dialId === "string")
+                this.dialled(entry.dialId);
+        }
+    }
     static stated(task) {
         const media = isRecord(task) && (task.media === "started" || task.media === "ended") ? task.media : "none";
         return { phase: String(isRecord(task) ? task.phase : undefined), media };
@@ -629,6 +650,7 @@ export class TaskStream {
         for (const task of snapshot.tasks) {
             if (isRecord(task) && typeof task.id === "string")
                 this.tasks.set(task.id, TaskStream.stated(task));
+            this.noteDials(task);
         }
     }
     /** Applies one envelope and returns what it may not say given what came before. */
@@ -651,6 +673,7 @@ export class TaskStream {
                 if (known !== undefined)
                     refuse("stream.taskOffered.duplicate", `${at}.task.id`, `${id} is already on the stream; an offer introduces a task once`);
                 this.tasks.set(id, TaskStream.stated(event.task));
+                this.noteDials(event.task);
                 break;
             case "task-updated":
                 if (id === undefined)
@@ -675,6 +698,7 @@ export class TaskStream {
                     }
                     this.tasks.set(id, next);
                 }
+                this.noteDials(event.task);
                 break;
             case "task-media-started":
                 if (id === undefined)
@@ -713,6 +737,21 @@ export class TaskStream {
                     refuse("stream.taskEnded.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
                 this.tasks.delete(id);
                 break;
+            case "dial-outcome": {
+                // An outcome ends a dial somebody placed, once. The task it names may already have ended;
+                // a dial placed late routinely outlives its call, which is why the dial has its own identity.
+                if (typeof event.dialId !== "string")
+                    break;
+                const dial = this.dials.get(event.dialId);
+                if (dial === undefined) {
+                    refuse("stream.dialOutcome.unknown", `${at}.dialId`, `${event.dialId} is not a dial the host placed or a task carried: an outcome ends a dial somebody made`);
+                }
+                else if (dial === "ended") {
+                    refuse("stream.dialOutcome.duplicate", `${at}.dialId`, `${event.dialId} already has its outcome; a dial ends once`);
+                }
+                this.dials.set(event.dialId, "ended");
+                break;
+            }
             default:
                 break;
         }
@@ -802,26 +841,26 @@ export function stillHost(report = { online: true }, guarantees = {}) {
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
 /**
- * The participant set of a break attempt is every connected provider from which the agent can
- * currently receive work. A provider whose login is not usable -- `expired` above all -- is not
- * one, whatever else is true of it: nothing can be asked of it, and a host that waits on it
- * stalls the break for everyone. A usable provider holding capacity is one, and cannot be left
- * out. `refreshing` is usable: identity and capabilities remain available and work continues.
+ * A break attempt asks every connected provider from which the agent can currently receive work.
+ * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is
+ * true of it: nothing can be asked of it, and a host that waits on it stalls the break for
+ * everyone. A usable provider holding capacity is asked, and cannot be left out. `refreshing` is
+ * usable: identity and capabilities remain available and work continues.
  */
-export function assertBreakParticipants(candidates, participants) {
-    const chosen = new Set(participants);
-    for (const id of participants) {
+export function assertBreakAttemptProviders(candidates, asked) {
+    const chosen = new Set(asked);
+    for (const id of asked) {
         if (!candidates.some(candidate => candidate.id === id))
             throw new Error(`${id} is not a provider the host knows`);
     }
     for (const candidate of candidates) {
         const expected = usableLogin(candidate.authentication) && candidate.holdsCapacity;
         if (expected && !chosen.has(candidate.id)) {
-            throw new Error(`${candidate.id} can give the agent work and must be a participant`);
+            throw new Error(`${candidate.id} can give the agent work and must be asked`);
         }
         if (!expected && chosen.has(candidate.id)) {
             const why = usableLogin(candidate.authentication) ? "holds no capacity" : `is ${candidate.authentication}`;
-            throw new Error(`${candidate.id} ${why} and is not a participant: nothing can be asked of it`);
+            throw new Error(`${candidate.id} ${why} and is not asked: nothing can be asked of it`);
         }
     }
 }

package/dist/validation.d.ts

@@ -17,6 +17,8 @@ export interface TaskValidationContext {
     levels?: readonly string[];
     /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
     autoAcceptTasks?: boolean;
+    /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
+    dialOutcomesDeclared?: boolean;
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -64,7 +66,7 @@ export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" |
  * shows the agent what it says. A status the method does not answer, a failure status without a
  * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
  */
-export declare function validateResult(result: unknown, method: ResultMethod, path?: string): ProtocolViolation[];
+export declare function validateResult(result: unknown, method: ResultMethod, path?: string, dialId?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */
 export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */