@webex/contact-center 3.12.0-llmrefactor.1 → 3.12.0-llmrefactor.10

package/dist/types/services/task/types.d.ts

@@ -22,7 +22,7 @@ export declare const DESTINATION_TYPE: {
     DIALNUMBER: string;
     /** Route task to a specific agent */
     AGENT: string;
-    /** Route task to an entry point (supported only for consult operations) */
+    /** Route task to an entry point */
     ENTRYPOINT: string;
 };
 /**
@@ -203,6 +203,10 @@ export declare enum TASK_EVENTS {
      * Triggered whenever task UI controls are recalculated
      */
     TASK_UI_CONTROLS_UPDATED = "task:ui-controls-updated",
+    /**
+     * Triggered when wxApp mute state changes from Webex App (Mercury sync or call details).
+     */
+    TASK_WXAPP_MUTE_STATE_UPDATED = "task:wxapp-mute-state-updated",
     /**
      * Triggered when a consultation request is accepted
      * @example
@@ -1051,6 +1055,8 @@ export type TaskData = {
     reservedAgentChannelId?: string;
     /** Indicates if wrap-up is required for this task */
     wrapUpRequired?: boolean;
+    /** SDK-internal: skip task:outdialFailed when non-wxApp agent-terminated outdial still needs wrapup */
+    suppressOutdialFailedPopup?: boolean;
     /**
      * Current consultation status derived from state machine
      * Values: CONSULT_INITIATED, CONSULT_ACCEPTED, BEING_CONSULTED,
@@ -1121,6 +1127,17 @@ export type InteractionUIControls = {
     mergeToConference: TaskUIControlState;
     wrapup: TaskUIControlState;
     switch: TaskUIControlState;
+    keypad?: TaskUIControlState;
+};
+/** Options for {@link ITask.toggleMute} — wxApp engaged calls use `muted` for target state. */
+export type TaskToggleMuteOptions = {
+    muted?: boolean;
+    lineOwnerId?: string;
+};
+/** Options for {@link ITask.transmitDtmf} — wxApp engaged in-call DTMF. */
+export type TaskTransmitDtmfOptions = {
+    dtmf: string;
+    lineOwnerId?: string;
 };
 export type TaskUILeg = 'main' | 'consult';
 /**
@@ -1132,6 +1149,14 @@ export type TaskUIControls = {
     main: InteractionUIControls;
     consult: InteractionUIControls;
     activeLeg: TaskUILeg;
+    /**
+     * Ordered destination categories available for each action.
+     * The first category is the default for consumers that render a destination picker.
+     */
+    consultTransferDestinations: {
+        consult: ConsultTransferDestinationType[];
+        transfer: ConsultTransferDestinationType[];
+    };
 };
 /**
  * Helper class for managing task action control state
@@ -1491,6 +1516,14 @@ export type ParticipantBooleanKey = 'autoAnswerEnabled' | 'hasJoined' | 'hasLeft
  * @public
  */
 export type TaskResponse = AgentContact | Error | void;
+/**
+ * Request payload for removing a supported participant from an active conference.
+ * @public
+ */
+export type DropConferenceParticipantPayload = {
+    /** Participant identifier supplied by the current task roster. */
+    participantId: string;
+};
 /**
  * Payload shape used by consult conference helper utilities.
  */
@@ -1539,6 +1572,14 @@ export interface ITask extends IEventEmitter {
      * Subscribe to {@link TASK_EVENTS.TASK_UI_CONTROLS_UPDATED} for change notifications.
      */
     readonly uiControls: TaskUIControls;
+    /**
+     * Current wxApp mute state for engaged telephony (Voice tasks only).
+     */
+    getWxAppMuted?(): boolean;
+    /**
+     * Re-seed wxApp mute from GET telephony/calls/{callId}. Resolves to muted state when known.
+     */
+    syncWxAppMuteFromCallDetails?(): Promise<boolean | undefined>;
     state?: any;
     /**
      * Cancels the auto-wrapup timer for the task.
@@ -1690,6 +1731,17 @@ export interface ITask extends IEventEmitter {
      * ```
      */
     consultConference(): Promise<TaskResponse>;
+    /**
+     * Removes a supported participant from the active conference.
+     * Resolves after the correlated ParticipantLeftConference routing event.
+     * @param payload - Participant identifier to remove
+     * @returns Promise<TaskResponse>
+     * @example
+     * ```typescript
+     * await task.dropConferenceParticipant({participantId: 'participant-id'});
+     * ```
+     */
+    dropConferenceParticipant(payload: DropConferenceParticipantPayload): Promise<TaskResponse>;
     /**
      * Exits from an ongoing conference.
      * @returns Promise<TaskResponse>
@@ -1721,14 +1773,28 @@ export interface ITask extends IEventEmitter {
      */
     switchCall(): Promise<TaskResponse>;
     /**
-     * Toggles mute/unmute for the local audio stream during a WebRTC task.
+     * Toggles mute/unmute for the active call.
+     * WebRTC tasks toggle the local stream; wxApp engaged tasks route to telephony mute REST when
+     * `enableWxBetterTogether` is active.
+     * @param options - Optional target mute state (`muted`) for wxApp; ignored for WebRTC toggle.
      * @returns Promise<void>
      * @example
      * ```typescript
      * await task.toggleMute();
+     * await task.toggleMute({ muted: true });
+     * ```
+     */
+    toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
+    /**
+     * Sends in-call DTMF tones for wxApp engaged telephony tasks when `enableWxBetterTogether` is active.
+     * @param options - DTMF digit(s) and optional shared-line owner id.
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * await task.transmitDtmf({ dtmf: '5' });
      * ```
      */
-    toggleMute(): Promise<void>;
+    transmitDtmf(options: TaskTransmitDtmfOptions): Promise<void>;
 }
 /**
  * Interface for managing digital channel task operations in the contact center
@@ -1762,6 +1828,12 @@ export interface IVoice extends ITask {
      * ```
      */
     holdResume(): Promise<TaskResponse>;
+    /** @see wxAppVoiceMethods — WXCC-6026 */
+    isWebexAppCallingOffer(): boolean;
+    /** @see wxAppVoiceMethods — WXCC-6026 */
+    getCallingDeviceDetails(): import('./WebexCallingUtils').WebexCallingDeviceDetails | undefined;
+    /** @see wxAppVoiceMethods — WXCC-6026 */
+    getWebexCallingCallId(): string | null;
 }
 /**
  * Configuration options for voice task UI controls
@@ -1771,6 +1843,9 @@ export type VoiceUIControlOptions = {
     isEndConsultEnabled?: boolean;
     voiceVariant?: VoiceVariant;
     isRecordingEnabled?: boolean;
+    enableWxBetterTogether?: boolean;
+    consultTransferConfig?: ConsultTransferDestinationConfig;
+    answerCallOnWebexService?: import('../AnswerCallOnWebexService').default;
 };
 /**
  * Participant information for UI display
@@ -1793,7 +1868,7 @@ export interface IWebRTC extends IVoice {
      * task.toggleMute();
      * ```
      */
-    toggleMute(): Promise<void>;
+    toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
     /**
      * Decline the incoming task for Browser Login
      *
@@ -1817,6 +1892,8 @@ export type WebSocketPayload = TaskData & {
     type: string;
     mediaResourceId?: string;
     reason?: string;
+    /** ContactEnded: party that ended the contact (e.g. 'Agent', 'Customer') */
+    terminatingParty?: string;
     /**
      * Optional real-time transcript chunk payload.
      * Present on REAL_TIME_TRANSCRIPTION notifications.

package/dist/types/services/task/voice/Voice.d.ts

@@ -1,25 +1,61 @@
 import routingContact from '../contact';
-import { ConsultPayload, ConsultEndPayload, ResumeRecordingPayload, TaskData, TaskResponse, IVoice, VoiceUIControlOptions, TransferPayLoad } from '../types';
+import { ConsultPayload, ConsultEndPayload, ResumeRecordingPayload, TaskData, TaskResponse, DropConferenceParticipantPayload, IVoice, VoiceUIControlOptions, TaskToggleMuteOptions, TaskTransmitDtmfOptions, TransferPayLoad } from '../types';
 import Task from '../Task';
 import { TaskActionArgs } from '../state-machine';
 import { WrapupData } from '../../config/types';
 export default class Voice extends Task implements IVoice {
+    private static readonly WXAPP_MUTE_SYNC_RETRY_DELAY_MS;
+    private static readonly WXAPP_MUTE_SYNC_MAX_RETRIES;
+    private answerCallOnWebexService?;
+    private enableWxBetterTogether;
+    private wxAppMuted;
+    private wxAppAnswerPending;
+    private wxAppAcceptInFlight;
+    private wxAppMuteSyncInFlight?;
+    private wxAppMuteToggleTail;
+    private wxAppDtmfTail;
+    private lastLoggedWxAppAcceptReason?;
     constructor(contact: ReturnType<typeof routingContact>, data: TaskData, callOptions?: VoiceUIControlOptions, wrapupData?: WrapupData, agentId?: string);
+    private getWxAppVoiceDependencies;
+    /** @deprecated Use {@link Voice.getWxAppVoiceDependencies} */
+    private getWxAppVoiceDeps;
+    isWebexAppCallingOffer(): boolean;
+    isWebexAppInboundCallingOffer(): boolean;
+    private setWxAppAnswerPending;
+    private setWxAppAcceptInFlight;
+    setEnableWxBetterTogether(enabled: boolean): void;
+    protected updateUiControls(forceEmit?: boolean): void;
+    private logWxAppOfferDecisionIfNeeded;
+    applyWxAppMuteStateFromSync(incomingCallId: string, muted: boolean): void;
+    getWxAppMuted(): boolean;
+    private static delay;
+    private canRetryWxAppMuteSync;
+    private shouldSkipWxAppMuteSync;
+    private applyWxAppMuteFromBackfill;
+    syncWxAppMuteFromCallDetails(retryAttempt?: number): Promise<boolean | undefined>;
+    private performWxAppMuteSync;
+    protected onTaskAssigned(): void;
+    protected onTaskHydrated(): void;
+    getCallingDeviceDetails(): import("../WebexCallingUtils").WebexCallingDeviceDetails;
+    getWebexCallingCallId(): string | null;
+    private createWxAppLifecycle;
     private getStateMachineSnapshot;
     /**
-     * This method is used to accept the task.
-     * It is expected to be overridden by child classes.
-     * @returns Promise<TaskResponse>
-     * @throws Error
+     * Accepts the task. Routes to wxApp telephony answer when `enableWxBetterTogether` and wxApp offer.
      */
     accept(): Promise<TaskResponse>;
     /**
-     * This method is used to decline the task.
-     * It is expected to be overridden by child classes.
-     * @returns Promise<TaskResponse>
-     * @throws Error
+     * Declines the task. Routes wxApp inbound to telephony reject; wxApp outdial offer to cancelTask.
      */
     decline(): Promise<TaskResponse>;
+    /**
+     * Toggles mute for wxApp engaged telephony when `enableWxBetterTogether` is active.
+     */
+    toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
+    /**
+     * Sends in-call DTMF for wxApp engaged telephony when `enableWxBetterTogether` is active.
+     */
+    transmitDtmf(options: TaskTransmitDtmfOptions): Promise<void>;
     /**
      * This is used to hold the task.
      * @returns Promise<TaskResponse>
@@ -121,6 +157,13 @@ export default class Voice extends Task implements IVoice {
      * Start a consult conference, merging main and consult calls.
      */
     consultConference(): Promise<TaskResponse>;
+    /**
+     * Removes another participant from an active conference.
+     * Completion is correlated with ParticipantLeftConference by the AQM request layer.
+     * @param payload - Participant identifier to remove
+     * @returns Promise<TaskResponse>
+     */
+    dropConferenceParticipant(payload: DropConferenceParticipantPayload): Promise<TaskResponse>;
     /**
      * Exit from a conference call.
      * Per conference-spec.md:

package/dist/types/services/task/voice/WebRTC.d.ts

@@ -1,5 +1,5 @@
 import routingContact from '../contact';
-import { TaskData, TaskResponse, IWebRTC, VoiceUIControlOptions } from '../types';
+import { TaskData, TaskResponse, IWebRTC, VoiceUIControlOptions, TaskToggleMuteOptions } from '../types';
 import Voice from './Voice';
 import WebCallingService from '../../WebCallingService';
 import { WrapupData } from '../../config/types';
@@ -49,5 +49,5 @@ export default class WebRTC extends Voice implements IWebRTC {
      * task.toggleMute().then(()=>{}).catch(()=>{})
      * ```
      */
-    toggleMute(): Promise<void>;
+    toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
 }

package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts

@@ -0,0 +1,55 @@
+import AnswerCallOnWebexService from '../../AnswerCallOnWebexService';
+import { TaskData, TaskToggleMuteOptions, TaskTransmitDtmfOptions } from '../types';
+import { TaskState } from '../state-machine';
+import MetricsManager from '../../../metrics/MetricsManager';
+import { WebexCallingDeviceDetails } from '../WebexCallingUtils';
+export type WxAppVoiceDependencies = {
+    enableWxBetterTogether: boolean;
+    answerCallOnWebexService?: AnswerCallOnWebexService;
+    agentId?: string;
+    metricsManager: MetricsManager;
+    getTaskData: () => TaskData;
+    getTaskState: () => TaskState | undefined;
+    getWxAppMuted: () => boolean;
+    setWxAppMuted: (muted: boolean) => void;
+};
+/** @deprecated Use {@link WxAppVoiceDependencies} */
+export type WxAppVoiceDeps = WxAppVoiceDependencies;
+export type WxAppVoiceLifecycle = {
+    setWxAppAcceptInFlight: (inFlight: boolean) => void;
+    setWxAppAnswerPending: (pending: boolean) => void;
+    resetWxAppMuted: () => void;
+    syncWxAppMuteFromCallDetails: () => Promise<boolean | undefined>;
+    mapWxAppVoiceError: (error: unknown, method: string) => never;
+};
+export declare function getCallingDeviceDetails(deps: WxAppVoiceDependencies): WebexCallingDeviceDetails | undefined;
+export declare function isWebexAppCallingOffer(deps: WxAppVoiceDependencies): boolean;
+/** Inbound wxApp offer only — outdial decline uses CC routing, not telephony reject. */
+export declare function isWebexAppInboundCallingOffer(deps: WxAppVoiceDependencies): boolean;
+export declare function getWebexCallingCallId(deps: WxAppVoiceDependencies): string | null;
+export declare function getWxAppLineOwnerId(deps: WxAppVoiceDependencies): string | undefined;
+export declare function resolveWxAppLineOwnerId(deps: WxAppVoiceDependencies, override?: string): string | undefined;
+export declare function acceptOnWebex(deps: WxAppVoiceDependencies, options?: {
+    lineOwnerId?: string;
+}): Promise<void>;
+export declare function rejectOnWebex(deps: WxAppVoiceDependencies, options?: {
+    lineOwnerId?: string;
+}): Promise<void>;
+export declare function toggleMuteOnWebex(deps: WxAppVoiceDependencies, options?: {
+    lineOwnerId?: string;
+    muted?: boolean;
+}): Promise<void>;
+export declare function transmitDtmfOnWebex(deps: WxAppVoiceDependencies, options: {
+    dtmf: string;
+    lineOwnerId?: string;
+}): Promise<void>;
+export declare function runWxAppAccept(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options?: {
+    lineOwnerId?: string;
+}): Promise<void>;
+export declare function runWxAppReject(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options?: {
+    lineOwnerId?: string;
+}): Promise<void>;
+export declare function runWxAppOutdialDecline<T>(deps: WxAppVoiceDependencies, executeCancel: () => Promise<T>): Promise<T>;
+export declare function runWxAppToggleMute(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options?: TaskToggleMuteOptions): Promise<void>;
+export declare function runWxAppTransmitDtmf(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options: TaskTransmitDtmfOptions): Promise<void>;
+export declare function mapWxAppVoiceError(error: unknown, method: string, module: string): never;

package/dist/types/services/wxAppDiagnosticLogging.d.ts

@@ -0,0 +1,51 @@
+export declare const WXAPP_LOG_FEATURE = "wxApp";
+export declare const WXAPP_LOG_PREFIX = "[CC wxApp]";
+export type WxAppAcceptReason = 'wxApp_offer_ready' | 'wxApp_answer_pending' | 'wxApp_accept_in_flight' | 'extension_non_wxApp_offer' | 'browser_webrtc_offer' | 'outdial_auto_answer';
+export type WxAppSessionSkipReason = 'unsupported_browser_login' | 'flag_disabled' | 'mercury_subscribe_failed' | 'publish_failed';
+export type WxAppTelephonyAction = 'accept' | 'decline' | 'mute' | 'dtmf';
+export type WxAppTelephonyPhase = 'started' | 'success' | 'failed';
+/** Last 8 chars of callId for correlation without logging full id. */
+export declare function callIdSuffix(callId: string | null | undefined): string | undefined;
+export declare function logWxAppSessionReadiness(params: {
+    enableWxBetterTogether: boolean;
+    loginOption: string | undefined;
+    wxAppHooksApplied: boolean;
+    usersubPublished: boolean;
+    mercurySubscribed: boolean;
+    telephonyTaskType: 'Voice' | 'WebRTC' | 'unknown';
+    skipReason?: WxAppSessionSkipReason;
+}): void;
+export declare function deriveWxAppAcceptReason(params: {
+    isWxAppInboundOffer: boolean;
+    isWxAppOutdialOffer: boolean;
+    isWebrtc: boolean;
+    isOutdial: boolean;
+    wxAppAcceptInFlight: boolean;
+    wxAppAnswerPending: boolean;
+    enableWxBetterTogether: boolean;
+    hasDeviceCallId: boolean;
+}): WxAppAcceptReason;
+export declare function logWxAppOfferDecision(params: {
+    interactionId: string;
+    acceptVisible: boolean;
+    acceptEnabled: boolean;
+    acceptReason: WxAppAcceptReason;
+    wxAppParticipantDeviceType?: string;
+    hasDeviceCallId: boolean;
+}): void;
+export declare function logWxAppTelephonyAction(params: {
+    action: WxAppTelephonyAction;
+    phase: WxAppTelephonyPhase;
+    interactionId?: string;
+    trackingId?: string;
+    httpStatus?: number | string;
+    failureReason?: string;
+}): void;
+export declare function logWxAppValidationFailure(reason: string, interactionId?: string): void;
+export declare function logWxAppMercuryMuteSync(params: {
+    phase: 'received' | 'applied' | 'dropped';
+    muted?: boolean;
+    callIdSuffix?: string;
+    interactionId?: string;
+    dropReason?: string;
+}): void;

package/dist/types/services/wxAppTelephonyUtils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Expected Hydra responses when mute backfill races call creation (WXCC-6026).
+ * These must not be logged as errors — see task-spec wxApp mute backfill guard.
+ */
+export declare function isWxAppCallNotFoundError(error: unknown): boolean;

package/dist/types/types.d.ts

@@ -108,6 +108,8 @@ export interface CCPluginConfig {
     callingClientConfig: CallingClientConfig;
     /** Whether to skip Mobius/WebRTC registration for browser login flows */
     disableWebRTCRegistration?: boolean;
+    /** Whether wxApp Better Together (telephony REST + usersub) is enabled at init (WXCC-6026) */
+    enableWxBetterTogether?: boolean;
 }
 /**
  * Logger interface for standardized logging throughout the plugin.
@@ -366,24 +368,26 @@ export type AgentLogin = {
 export type AgentProfileUpdate = Pick<AgentLogin, 'loginOption' | 'dialNumber' | 'teamId'>;
 /**
  * Represents the options to fetch buddy agents for the logged in agent.
- * Buddy agents are other agents who can be consulted or transfered to.
+ * Buddy agents are other agents who can be consulted or transferred to.
  * @public
  * @example
  * const opts: BuddyAgents = { mediaType: 'telephony', state: 'Available' };
- * @ignore
  */
 export type BuddyAgents = {
     /**
-     * The media type channel to filter buddy agents.
-     * Determines which channel capability the returned agents must have.
+     * The media type channel to filter buddy agents. Defaults to telephony when omitted.
      */
-    mediaType: 'telephony' | 'chat' | 'social' | 'email';
+    mediaType?: 'telephony' | 'chat' | 'social' | 'email';
     /**
      * Optional filter for agent state.
      * If specified, returns only agents in that state.
      * If omitted, returns both available and idle agents.
      */
     state?: 'Available' | 'Idle';
+    /**
+     * Applies the default state policy for the operation. An explicit state takes precedence.
+     */
+    action?: 'Consult' | 'Transfer';
 };
 /**
 
@@ -464,10 +468,12 @@ export interface AddressBookEntrySearchParams extends BaseSearchParams {
 export interface EntryPointRecord {
     id: string;
     name: string;
+    /** Dialled number mapped to this entry point when included in the list response. */
+    number?: string;
     description?: string;
-    type: string;
-    isActive: boolean;
-    orgId: string;
+    type?: string;
+    isActive?: boolean;
+    orgId?: string;
     createdAt?: string;
     updatedAt?: string;
     settings?: Record<string, any>;

package/dist/types/utils/PageCache.d.ts

@@ -90,6 +90,12 @@ export interface CacheValidationParams {
     attributes?: string;
     /** Sort by parameter */
     sortBy?: string;
+    /** Desktop-profile filtering changes the returned result set */
+    desktopProfileFilter?: boolean;
+    /** Provisioning-view filtering changes the returned result set */
+    provisioningView?: boolean;
+    /** Single-object response mode changes the response shape */
+    singleObjectResponse?: boolean;
 }
 /**
  * Page cache utility class for managing paginated API response caching.
@@ -103,8 +109,18 @@ export interface CacheValidationParams {
  * // Create a cache instance for a specific data type
  * const cache = new PageCache<AddressBookEntry>('AddressBook');
  *
- * // Check if we can use cache (no search/filter parameters)
- * if (cache.canUseCache({ search, filter })) {
+ * // Check if we can use cache for the complete result/response-shape input set
+ * if (
+ *   cache.canUseCache({
+ *     search,
+ *     filter,
+ *     attributes,
+ *     sortBy,
+ *     desktopProfileFilter,
+ *     provisioningView,
+ *     singleObjectResponse,
+ *   })
+ * ) {
  *   const cacheKey = cache.buildCacheKey(orgId, page, pageSize);
  *   const cachedPage = cache.getCachedPage(cacheKey);
  *
@@ -128,7 +144,8 @@ export declare class PageCache<T> {
     constructor(apiName: string);
     /**
      * Checks if cache can be used for the given parameters.
-     * Cache is only used for simple pagination without search/filter/attributes/sort.
+     * Cache is only used for simple pagination without query variants or enabled
+     * result/response-shape flags.
      * @param {CacheValidationParams} params - Parameters to validate
      * @returns {boolean} True if cache can be used
      * @public

package/dist/types.js

@@ -58,6 +58,12 @@ const HTTP_METHODS = exports.HTTP_METHODS = {
  * @ignore
  */
 
+/**
+ * Mercury event handler callback.
+ * @internal
+ * @ignore
+ */
+
 /**
  * Event listener removal function type.
  * @internal
@@ -228,11 +234,10 @@ const LoginOption = exports.LoginOption = {
 
 /**
  * Represents the options to fetch buddy agents for the logged in agent.
- * Buddy agents are other agents who can be consulted or transfered to.
+ * Buddy agents are other agents who can be consulted or transferred to.
  * @public
  * @example
  * const opts: BuddyAgents = { mediaType: 'telephony', state: 'Available' };
- * @ignore
  */
 
 /**