@xema/omni-protocol 0.1.96 → 0.1.98

package/dist/index.d.ts

@@ -24,16 +24,15 @@ export type IsoTimestamp = string;
  * provider id through `userKey()` before storing or comparing.
  */
 export type UserId = string;
-/** A non-empty, opaque task identifier unique within one provider. Scope it with `taskKey()`. */
-export type TaskId = string;
 /**
- * One life of a task on the wire. A platform retires a task id minutes after closing it and a
- * requeue takes seconds, so the same `TaskId` comes back for another customer while a late dial
- * outcome or a late interaction report for the first is still in flight. The allocation id is minted
- * once per offer and never reused for the life of the login, and every event, command and report
- * that names a task names its allocation too, so nothing lands on the next life of the id.
+ * The provider's name for one assignment: the call routed to this agent, from the offer until the
+ * task ends. Non-empty, opaque, unique within the provider and never reused while the provider is
+ * still speaking about it -- a lead names a member's assignment from another login, so the scope is
+ * the provider, not the login. What the platform calls its own record, and whether it reuses that
+ * name, is the adapter's business: a platform that reoffers a closed call under the same handle
+ * seconds later is why the adapter, not the desk, is held to this. Scope it with `assignmentKey()`.
  */
-export type AllocationId = string;
+export type AssignmentId = 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
@@ -483,8 +482,7 @@ export type RecordingCommand = {
     recordingId: string;
 });
 export interface HostRecordingReport {
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     state: RecordingState;
 }
 /** Host declaration in ConnectContext, not the provider-owned Manifest. */
@@ -501,8 +499,7 @@ export type RecordingCommandResult = Exclude<TaskCommandResult, {
     status: "dialling";
 }>;
 export interface HostRecordingRequest {
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     command: RecordingCommand & {
         source: "host";
     };
@@ -693,7 +690,7 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
  * mistype and unreadable as an argument.
  */
 export declare const BROWSER_ISOLATION_SCHEMES: {
-    readonly PROVIDER_NAME__TASK_ID__TAB_NAME: "ProviderName.TaskId.TabName";
+    readonly PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME: "ProviderName.AssignmentId.TabName";
     readonly TAB_NAME: "TabName";
     readonly PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME: "ProviderName.TaskTypeName.TabName";
     readonly PROVIDER_NAME__TAB_NAME: "ProviderName.TabName";
@@ -730,7 +727,7 @@ export type PersonalBrowser = Browser;
 export declare const ALLOWED_BROWSER_URL_SCHEMES: readonly ["http:", "https:"];
 export declare function isAllowedBrowserUrl(url: string): boolean;
 export type TaskPhase = 
-/** Allocated to this agent and not yet accepted. */
+/** Assigned to this agent and not yet accepted. */
 "pending"
 /** Accepted, and not yet started. */
  | "confirmed"
@@ -765,7 +762,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type InteractionStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered";
+export type HistoryStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered";
 /**
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -773,8 +770,8 @@ export type InteractionStep = "queued" | "offered" | "answered" | "held" | "mute
  * absent when it does not; a plausible nought is the fallback the no-fallbacks rule forbids. The
  * record rides on the task and is replaced with it, so a late entry corrects the sums.
  */
-export interface TaskInteractionHistory {
-    steps: TaskInteractionStep[];
+export interface TaskHistory {
+    steps: TaskHistoryStep[];
     /** Seconds others spent working on it before this agent. */
     interactionSeconds?: DurationSeconds;
     /** Seconds the caller spent on hold at others' hands. */
@@ -784,8 +781,8 @@ export interface TaskInteractionHistory {
     /** How many times the task changed hands. */
     transfers?: number;
 }
-export interface TaskInteractionStep {
-    step: InteractionStep;
+export interface TaskHistoryStep {
+    step: HistoryStep;
     at: IsoTimestamp;
     /**
      * On a step that dialled -- `transferred`, `conferenced`, `unanswered` -- the host's identity for
@@ -883,6 +880,8 @@ export type TaskLeadAssist = {
  */
 export interface TaskAssisting {
     memberId: UserId;
+    /** The member's assignment the lead joined: the lead's task has an assignment of its own. */
+    assignmentId: AssignmentId;
     note?: string;
     since: IsoTimestamp;
 }
@@ -895,8 +894,7 @@ export interface TaskAssisting {
  */
 export interface TaskListening {
     memberId: UserId;
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
 }
@@ -952,9 +950,8 @@ export type Lockable<T> = T | Locked;
 export type CapabilitySource = "queue" | "ungoverned" | "undetermined";
 export declare const CAPABILITY_SOURCES: readonly ["queue", "ungoverned", "undetermined"];
 export type Task<C extends Channel = Channel> = {
-    id: TaskId;
-    /** This life of the task: minted once per offer, never reused for the life of the login. See `AllocationId`. */
-    allocationId: AllocationId;
+    /** The assignment this task is the record of, and its one identity. See `AssignmentId`. */
+    assignmentId: AssignmentId;
     title: string;
     channel: C;
     /** The provider's own name for a category of work. Finer-grained than a channel. */
@@ -991,7 +988,7 @@ export type Task<C extends Channel = Channel> = {
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
-    interactionHistory?: TaskInteractionHistory;
+    history?: TaskHistory;
 } & TaskCompletion & (C extends "voice" ? {
     recording?: {
         provider?: RecordingState;
@@ -1036,7 +1033,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 `allocationExpiresAt` names `pending`. */
+/** Only the phases in which somebody is still being waited on can expire; an offer that lapses at `assignmentExpiresAt` names `pending`. */
  | {
     type: "expired";
     phase: "pending" | "confirmed" | "preview";
@@ -1179,8 +1176,7 @@ export interface CustomTaskCommand {
 }
 export type TaskCommand<C extends Channel = Channel> = (C extends "voice" ? VoiceTaskCommand : C extends "chat" ? ChatTaskCommand : EmailTaskCommand) | CustomTaskCommand;
 export interface TaskCommandRequest<C extends Channel = Channel> {
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     command: TaskCommand<C>;
 }
 /**
@@ -1274,7 +1270,7 @@ export interface BreakState {
     activeReasonId?: string;
     forced?: ForcedBreak;
 }
-/** Capacity is a statement, not a request: it is taken, never refused. A provider that cannot carry the count allocates within what it can and says so on a `diagnostic`. */
+/** Capacity is a statement, not a request: it is taken, never refused. A provider that cannot carry the count assigns within what it can and says so on a `diagnostic`. */
 export type CapacityResult = {
     status: "applied";
 };
@@ -1318,8 +1314,7 @@ export interface TeamMember {
 export interface LeadRequest {
     id: string;
     memberId: UserId;
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     note?: string;
     since: IsoTimestamp;
 }
@@ -1423,8 +1418,7 @@ export interface VoiceMediaSession {
     close(): void;
 }
 export interface OpenMediaRequest {
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
     localAudio?: MediaStream;
 }
@@ -1482,9 +1476,8 @@ export type SetPreferenceRequest = {
  * legs it performs, so `seconds` may say how long so far at any time; the end is stated, never
  * inferred from a number's presence. What the adapter forwards upstream, and how often, is its own.
  */
-export type InteractionReport = {
-    taskId: TaskId;
-    allocationId: AllocationId;
+export type HistoryReport = {
+    assignmentId: AssignmentId;
     at: IsoTimestamp;
 } & (
 /** A muted leg says whose the silence was: the host's own Mute, or the station's slider or system. */
@@ -1492,7 +1485,7 @@ export type InteractionReport = {
     step: "muted";
     mutedBy: MutedBy;
 } | {
-    step: Exclude<InteractionStep, "muted">;
+    step: Exclude<HistoryStep, "muted">;
     mutedBy?: never;
 }) & ({
     ended: true;
@@ -1501,7 +1494,7 @@ export type InteractionReport = {
     ended?: never;
     seconds?: DurationSeconds;
 });
-export type InteractionReportResult = {
+export type HistoryReportResult = {
     status: "recorded";
     at: IsoTimestamp;
 } | {
@@ -1527,12 +1520,12 @@ export interface Snapshot<C extends Channel = Channel> {
     team?: TeamMembers;
 }
 /**
- * How many tasks this provider may have allocated to the agent at once.
+ * How many tasks this provider may have assigned to the agent at once.
  *
  * An absolute ceiling standing until Omni restates it. The provider counts its own outstanding
  * tasks against it and needs no new signal when one ends. The agent is one person on several
  * providers, and the host divides their capacity among them: `0` is host-stopped -- the agent's
- * capacity is elsewhere for now, this provider allocates nothing and shows the member as
+ * capacity is elsewhere for now, this provider assigns nothing and shows the member as
  * `reserved` -- and is not a break, which is the agent not working at all. The host restates a
  * count of one or more when this provider has the agent's capacity again.
  */
@@ -1571,28 +1564,25 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    allocationExpiresAt?: IsoTimestamp;
+    assignmentExpiresAt?: IsoTimestamp;
 } | {
     type: "task-updated";
     task: Task<C>;
 } | {
     type: "task-media-started";
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
 } | {
     type: "task-media-ended";
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
 } | {
     type: "task-ended";
-    taskId: TaskId;
-    allocationId: AllocationId;
+    assignmentId: AssignmentId;
     outcome: TaskOutcome;
 }
 /**
  * How a dial the host placed ended, once, either way -- `answered` is stated, never read off
  * somebody appearing on the call, and says what happened to the dial; who is on the call is
- * `Task.onCall`. `taskId` is the task the dial was placed on, resolved from the dial and never
+ * `Task.onCall`. `assignmentId` is the task the dial was placed on, resolved from the dial and never
  * from what the agent is looking at, 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.
  */
@@ -1600,8 +1590,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "dial-outcome";
     dialId: DialId;
     outcome: DialOutcome;
-    taskId?: TaskId;
-    allocationId?: AllocationId;
+    assignmentId?: AssignmentId;
     destinationId?: string;
     reason?: string;
 } | {
@@ -1617,8 +1606,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "diagnostic";
     expected: string;
     observed: string;
-    taskId?: TaskId;
-    allocationId?: AllocationId;
+    assignmentId?: AssignmentId;
 } | {
     type: "team-updated";
     team: TeamMembers;
@@ -1641,7 +1629,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.task-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"];
 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
@@ -1682,7 +1670,7 @@ export interface Connection<C extends Channel = Channel> {
     subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;
     /** Told what the host refused, snapshot or event, with every rule broken. Always; a refusal is visible on both sides. */
     refused(report: Refusal): void;
-    /** Nothing may be allocated until a capacity is stated, so every connection receives it. */
+    /** Nothing may be assigned until a capacity is stated, so every connection receives it. */
     setCapacity(capacity: AgentCapacity): Promise<CapacityResult>;
     execute(request: TaskCommandRequest<C>): Promise<TaskCommandResult>;
     disconnect(): Promise<void>;
@@ -1712,7 +1700,7 @@ export interface Connection<C extends Channel = Channel> {
     /** Required when the login declares `capabilities.preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
     setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
     /** Records an interaction leg the host performed. Required of a softphone login's connection: the host mutes its microphone on any call, and the record is the provider's. */
-    recordStep?(report: InteractionReport): Promise<InteractionReportResult>;
+    recordStep?(report: HistoryReport): Promise<HistoryReportResult>;
 }
 export interface Adapter<C extends Channel = Channel> {
     manifest: Manifest<C>;
@@ -1774,7 +1762,7 @@ export declare const DEFAULT_TASK_TYPE_PRESENTATION: {
  * string. Encoding before joining is what stops a provider id containing a separator from
  * forging another provider's key.
  */
-export declare const taskKey: (providerId: string, taskId: TaskId) => string;
+export declare const assignmentKey: (providerId: string, assignmentId: AssignmentId) => string;
 /**
  * The same treatment for a `UserId`, and needed for the same reason.
  *
@@ -1783,19 +1771,18 @@ export declare const taskKey: (providerId: string, taskId: TaskId) => string;
  * same provider; anything wider goes through this.
  */
 export declare const userKey: (providerId: string, userId: UserId) => string;
-/** Every interaction step somebody takes part in. `queued` is the one nobody does. */
-export declare const INTERACTION_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
+/** Every history step somebody takes part in. `queued` is the one nobody does. */
+export declare const HISTORY_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 `destinationId`. */
-export declare const INTERACTION_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
-export declare const interactionStepDials: (step: InteractionStep) => boolean;
+export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
+export declare const historyStepDials: (step: HistoryStep) => boolean;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
-export declare function interactionStepExpectsAPerson(step: InteractionStep): boolean;
+export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
 export interface BrowserSessionKeyInput {
     /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
     providerId: string;
-    taskId: TaskId;
-    /** The task's allocation: a task-scoped session lives one life of the task, never the next customer's under a reused id. */
-    allocationId: AllocationId;
+    /** The task's assignment: a task-scoped session lives one assignment, never the next customer's. */
+    assignmentId: AssignmentId;
     /** `Task.taskType`. */
     taskType: string;
     browser: TaskBrowser;

package/dist/index.js

@@ -40,7 +40,7 @@ export const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"];
  * mistype and unreadable as an argument.
  */
 export const BROWSER_ISOLATION_SCHEMES = {
-    PROVIDER_NAME__TASK_ID__TAB_NAME: "ProviderName.TaskId.TabName",
+    PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME: "ProviderName.AssignmentId.TabName",
     TAB_NAME: "TabName",
     PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME: "ProviderName.TaskTypeName.TabName",
     PROVIDER_NAME__TAB_NAME: "ProviderName.TabName",
@@ -104,7 +104,7 @@ export const breakKindAllowsListening = (kind) => kind !== undefined && LISTENIN
 export const OMNI_FAILURE_CODES = [
     "omni.not-authenticated",
     "omni.capability-not-enabled",
-    "omni.task-not-found",
+    "omni.assignment-not-found",
     "omni.destination-not-permitted",
     "omni.phone-not-permitted",
     "omni.rate-limited",
@@ -150,7 +150,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
  * string. Encoding before joining is what stops a provider id containing a separator from
  * forging another provider's key.
  */
-export const taskKey = (providerId, taskId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(taskId)}`;
+export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(assignmentId)}`;
 /**
  * The same treatment for a `UserId`, and needed for the same reason.
  *
@@ -159,19 +159,19 @@ export const taskKey = (providerId, taskId) => `${encodeURIComponent(providerId)
  * same provider; anything wider goes through this.
  */
 export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
-/** Every interaction step somebody takes part in. `queued` is the one nobody does. */
-export const INTERACTION_STEPS_WITH_A_PERSON = [
+/** Every history step somebody takes part in. `queued` is the one nobody does. */
+export const HISTORY_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 `destinationId`. */
-export const INTERACTION_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
-export const interactionStepDials = (step) => INTERACTION_STEPS_THAT_DIAL.includes(step);
-// Pinned both ways: a step added to `InteractionStep` has to be placed here, and a step listed here
+export const HISTORY_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
+export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step);
+// Pinned both ways: a step added to `HistoryStep` 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 interactionStepExpectsAPerson(step) {
-    return INTERACTION_STEPS_WITH_A_PERSON.includes(step);
+export function historyStepExpectsAPerson(step) {
+    return HISTORY_STEPS_WITH_A_PERSON.includes(step);
 }
 /**
  * Whether two logins declare the same capabilities, field by field. The comparison an adapter
@@ -202,15 +202,15 @@ export function sameCapabilities(a, b) {
  * cannot collide with a provider called `a` and a tab called `b`.
  */
 export function browserSessionKey(input) {
-    const { providerId, allocationId, taskType, browser } = input;
+    const { providerId, assignmentId, taskType, browser } = input;
     if (browser.sharedSession !== true)
         return undefined;
     // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
     // provider `Acme.Voice` with type `Support` forge the key of `Acme` with `Voice.Support`.
     const part = (value) => encodeURIComponent(value).replaceAll(".", "%2E");
     switch (browser.isolationScheme) {
-        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_ID__TAB_NAME:
-            return `${part(providerId)}.${part(allocationId)}.${part(browser.name)}`;
+        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME:
+            return `${part(providerId)}.${part(assignmentId)}.${part(browser.name)}`;
         case BROWSER_ISOLATION_SCHEMES.TAB_NAME:
             return part(browser.name);
         case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME:

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.interactionHistory", "task.onCall", "task.leadAssist", "task.assisting", "task.listening", "task.media", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.assisting", "task.listening", "task.media", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -147,18 +147,17 @@ export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakSta
 export declare const SUPERSEDED_BY_A_SNAPSHOT: ReadonlySet<string>;
 export declare class TaskStream {
     private readonly tasks;
-    private readonly allocations;
-    private readonly endedAllocations;
+    private readonly assignments;
+    private readonly endedAssignments;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
     private noteDials;
     /**
-     * Whether an event about a task names the life that is open under its id. One naming a life that
-     * has ended is the late event the allocation exists to catch; one naming a life nobody has seen is
-     * a different fault. Either way it is not applied to the open task.
+     * Why an event names no open task: the assignment ended, so this is the late event that must not
+     * land on anything, or nobody has seen it. Either way it is not applied.
      */
-    private namesTheOpenLife;
+    private notOpen;
     /** How many tasks the stream currently holds open. */
     openCount(): number;
     /** 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. */