@webex/contact-center 3.12.0-next.16 → 3.12.0-next.161

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

@@ -0,0 +1,241 @@
+import routingContact from '../contact';
+import { ConsultPayload, ConsultEndPayload, ResumeRecordingPayload, TaskData, TaskResponse, DropConferenceParticipantPayload, IVoice, VoiceUIControlOptions, TaskToggleMuteOptions, TaskTransmitDtmfOptions, TransferPayLoad } from '../types';
+import Task from '../Task';
+import { TaskActionArgs } from '../state-machine';
+import type { WrapupData } from '../../config/types';
+import type ApiAIAssistant from '../../ApiAiAssistant';
+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;
+    /** Lazy — `super()` may call `updateUiControls` before field initializers run. */
+    private wxAppOfferObservability;
+    private getUsersubPublished?;
+    constructor(contact: ReturnType<typeof routingContact>, data: TaskData, callOptions?: VoiceUIControlOptions, wrapupData?: WrapupData, agentId?: string, agentName?: string, apiAIAssistant?: ApiAIAssistant);
+    private getWxAppVoiceDependencies;
+    /** @deprecated Use {@link Voice.getWxAppVoiceDependencies} */
+    private getWxAppVoiceDeps;
+    isWebexAppCallingOffer(): boolean;
+    isWebexAppInboundCallingOffer(): boolean;
+    private setWxAppAnswerPending;
+    private setWxAppAcceptInFlight;
+    setEnableWxBetterTogether(enabled: boolean): void;
+    private getOrCreateWxAppOfferObservability;
+    protected updateUiControls(forceEmit?: boolean): void;
+    /**
+     * Re-run OFFERED wxApp diagnostics without emitting UI controls.
+     * Used after usersub publish so a pre-publish offer can schedule mismatch grace.
+     */
+    refreshWxAppOfferObservability(): void;
+    /**
+     * Cancel pending participant-mismatch grace timer. Observability only.
+     */
+    disposeWxAppOfferObservability(): void;
+    private getWxAppOfferObservabilityContext;
+    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;
+    private getWxAppAcceptReasonForMetrics;
+    /**
+     * Accepts the task. Routes to wxApp telephony answer when `enableWxBetterTogether` and wxApp offer.
+     */
+    accept(): Promise<TaskResponse>;
+    /**
+     * 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>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.hold().then(()=>{}).catch(()=>{})
+     * ```
+     * */
+    hold(): Promise<TaskResponse>;
+    /**
+     * This is used to resume the task.
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.resume().then(()=>{}).catch(()=>{})
+     * ```
+     * */
+    resume(): Promise<TaskResponse>;
+    /**
+     * This is used to hold or resume the task.
+     * @param isHeld: boolean - true to hold the task, false to resume it
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.holdResume(isHeld: true).then(()=>{}).catch(()=>{})
+     * ```
+     * */
+    holdResume(): Promise<TaskResponse>;
+    /**
+     * This is used to pause the call recording
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.pauseRecording().then(()=>{}).catch(()=>{});
+     * ```
+     */
+    pauseRecording(): Promise<TaskResponse>;
+    /**
+     * This is used to pause the call recording
+     * @param resumeRecordingPayload
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.resumeRecording(resumeRecordingPayload).then(()=>{}).catch(()=>{});
+     * ```
+     */
+    resumeRecording(resumeRecordingPayload?: ResumeRecordingPayload): Promise<TaskResponse>;
+    /**
+     * This is used to consult the task
+     * @param consultPayload
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * const consultPayload = {
+     *   destination: 'myBuddyAgentId',
+     *   destinationType: DESTINATION_TYPE.AGENT,
+     * }
+     * task.consult(consultPayload).then(()=>{}).catch(()=>{});
+     * ```
+     * */
+    consult(consultPayload?: ConsultPayload): Promise<TaskResponse>;
+    /**
+     * This is used to end the consult session on the task.
+     * @param consultEndPayload - Payload indicating consult end flags and identifiers
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.endConsult({
+     *   isConsult: true,
+     *   queueId: 'myQueueId',
+     *   taskId: 'taskId',
+     * });
+     * ```
+     */
+    endConsult(consultEndPayload?: ConsultEndPayload): Promise<TaskResponse>;
+    /**
+     * This is used to transfer the task.
+     * @param payload - Transfer payload
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.transfer({
+     *   to: 'destinationId',
+     *   destinationType: DESTINATION_TYPE.AGENT,
+     *   consult: true, // Optional, if true will perform a consult transfer else blind transfer
+     * });
+     * ```
+     */
+    transfer(payload: TransferPayLoad): Promise<TaskResponse>;
+    /**
+     * 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:
+     * - Primary agent exits to wrapup
+     * - Non-primary agent exits to available/connected
+     * - Other participants continue the call
+     *
+     * @returns Promise<TaskResponse>
+     * @throws Error if not in conference or exit fails
+     * @example
+     * ```typescript
+     * task.exitConference().then(() => {}).catch(() => {});
+     * ```
+     */
+    exitConference(): Promise<TaskResponse>;
+    /**
+     * Transfer the conference to another participant.
+     * Per conference-spec.md: Only primary agent can transfer conference.
+     * After transfer, the transferring agent exits to wrapup.
+     *
+     * @returns Promise<TaskResponse>
+     * @throws Error if not in conference or transfer fails
+     * @example
+     * ```typescript
+     * task.transferConference().then(() => {}).catch(() => {});
+     * ```
+     */
+    transferConference(): Promise<TaskResponse>;
+    /**
+     * Toggle between consult call and main call during consulting.
+     * If on consult leg (consultCallHeld = false), switches to main call by holding consult.
+     * If on main call (consultCallHeld = true), switches to consult by resuming consult.
+     *
+     * @returns Promise<TaskResponse>
+     * @throws Error if not in CONSULTING state or no consult media resource
+     * @example
+     * ```typescript
+     * await task.switchCall();
+     * ```
+     */
+    switchCall(): Promise<TaskResponse>;
+    protected getChannelSpecificActionOverrides(): {
+        emitTaskHold: ({ event }: TaskActionArgs) => void;
+        emitTaskResume: ({ event }: TaskActionArgs) => void;
+        emitTaskRecordingStarted: ({ event }: TaskActionArgs) => void;
+        emitTaskRecordingPaused: ({ event }: TaskActionArgs) => void;
+        emitTaskRecordingPauseFailed: ({ event }: TaskActionArgs) => void;
+        emitTaskRecordingResumed: ({ event }: TaskActionArgs) => void;
+        emitTaskRecordingResumeFailed: ({ event }: TaskActionArgs) => void;
+        emitTaskParticipantJoined: ({ event }: TaskActionArgs) => void;
+        emitTaskParticipantLeft: ({ event }: TaskActionArgs) => void;
+        emitTaskConferenceStarted: ({ event }: TaskActionArgs) => void;
+        emitTaskConferenceEnded: ({ event }: TaskActionArgs) => void;
+        emitTaskConferenceFailed: ({ event }: TaskActionArgs) => void;
+        emitTaskExitConference: ({ event }: TaskActionArgs) => void;
+        emitTaskTransferConference: ({ event }: TaskActionArgs) => void;
+        emitTaskSwitchCall: ({ event }: TaskActionArgs) => void;
+        emitTaskTransferConferenceFailed: ({ event }: TaskActionArgs) => void;
+        emitTaskOutdialFailed: ({ event }: TaskActionArgs) => void;
+    };
+}

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

@@ -0,0 +1,54 @@
+import routingContact from '../contact';
+import { TaskData, TaskResponse, IWebRTC, VoiceUIControlOptions, TaskToggleMuteOptions } from '../types';
+import Voice from './Voice';
+import WebCallingService from '../../WebCallingService';
+import type { WrapupData } from '../../config/types';
+import type ApiAIAssistant from '../../ApiAiAssistant';
+export default class WebRTC extends Voice implements IWebRTC {
+    private localAudioStream;
+    private webCallingService;
+    constructor(contact: ReturnType<typeof routingContact>, webCallingService: WebCallingService, data: TaskData, callOptions?: VoiceUIControlOptions, wrapupData?: WrapupData, agentId?: string, agentName?: string, apiAIAssistant?: ApiAIAssistant);
+    private registerWebCallListeners;
+    private handleRemoteMedia;
+    /**
+     * This method is used to unregister the web call listeners.
+     * @returns void
+     * @example
+     * ```typescript
+     * task.unregisterWebCallListeners();
+     * ```
+     */
+    unregisterWebCallListeners(): void;
+    /**
+     * This is used for incoming task accept by agent.
+     *
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.accept().then(()=>{}).catch(()=>{})
+     * ```
+     */
+    accept(): Promise<TaskResponse>;
+    /**
+     * This is used for the incoming task decline by agent.
+     *
+     * @returns Promise<TaskResponse>
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.decline().then(()=>{}).catch(()=>{})
+     * ```
+     */
+    decline(): Promise<TaskResponse>;
+    /**
+     * This is used for the placing the call in mute or unmute by the agent.
+     *
+     * @throws Error
+     * @example
+     * ```typescript
+     * task.toggleMute().then(()=>{}).catch(()=>{})
+     * ```
+     */
+    toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
+}

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

@@ -0,0 +1,39 @@
+import MetricsManager from '../../../metrics/MetricsManager';
+import { TaskState } from '../state-machine';
+import { VoiceVariant } from '../types';
+import { WxAppVoiceDependencies } from './wxAppVoiceMethods';
+/** Defer mismatch WARN/metric so transient WS ordering gaps (~200–300 ms) do not false-alarm. */
+export declare const WXAPP_PARTICIPANT_MISMATCH_GRACE_MS = 500;
+export type WxAppOfferObservabilityContext = {
+    getInteractionId: () => string;
+    getTaskState: () => TaskState | undefined;
+    getAcceptControl: () => {
+        isVisible: boolean;
+        isEnabled: boolean;
+    } | undefined;
+    getVoiceVariant: () => VoiceVariant;
+    isOutdial: () => boolean;
+    isWxAppInboundOffer: () => boolean;
+    isWxAppCallingOffer: () => boolean;
+    getWxAppAcceptInFlight: () => boolean;
+    getWxAppAnswerPending: () => boolean;
+    getEnableWxBetterTogether: () => boolean;
+    getUsersubPublished: () => boolean;
+    getWxAppVoiceDependencies: () => WxAppVoiceDependencies;
+    getMetricsManager: () => MetricsManager;
+};
+/**
+ * OFFERED-state wxApp offer diagnostics: acceptReason logging and deferred participant mismatch.
+ * Invoked from Voice.updateUiControls — observability only.
+ */
+export declare class WxAppOfferObservability {
+    private lastLoggedWxAppAcceptReason?;
+    private lastLoggedWxAppParticipantMismatch;
+    private wxAppParticipantMismatchGraceTimer?;
+    private disposed;
+    handleUiControlsUpdate(ctx: WxAppOfferObservabilityContext): void;
+    dispose(): void;
+    private cancelGraceTimer;
+    private scheduleGraceTimer;
+    private emitParticipantMismatchIfStillNeeded;
+}

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

@@ -0,0 +1,68 @@
+import AnswerCallOnWebexService from '../../AnswerCallOnWebexService';
+import { TaskData, TaskToggleMuteOptions, TaskTransmitDtmfOptions } from '../types';
+import { TaskState } from '../state-machine';
+import MetricsManager from '../../../metrics/MetricsManager';
+import { WebexCallingDeviceDetails } from '../WebexCallingUtils';
+import { type WxAppAcceptReason } from '../../wxAppDiagnosticLogging';
+export type WxAppVoiceDependencies = {
+    enableWxBetterTogether: boolean;
+    answerCallOnWebexService?: AnswerCallOnWebexService;
+    agentId?: string;
+    metricsManager: MetricsManager;
+    getTaskData: () => TaskData;
+    getTaskState: () => TaskState | undefined;
+    getWxAppMuted: () => boolean;
+    setWxAppMuted: (muted: boolean) => void;
+    /** Read-only observability: whether usersub answer-calls-on-wxcc is active this session. */
+    getUsersubPublished?: () => boolean;
+};
+export type WxAppParticipantDiagnostics = {
+    participantDeviceType?: string;
+    hasDeviceCallId: boolean;
+    hasDeviceId: boolean;
+    hasValidWxAppParticipant: boolean;
+};
+/** @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 getWxAppParticipantDiagnostics(deps: WxAppVoiceDependencies): WxAppParticipantDiagnostics;
+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 type WxAppAcceptRejectOptions = {
+    lineOwnerId?: string;
+    acceptReason?: WxAppAcceptReason;
+};
+export declare function runWxAppAccept(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options?: WxAppAcceptRejectOptions): Promise<void>;
+export declare function runWxAppReject(deps: WxAppVoiceDependencies, lifecycle: WxAppVoiceLifecycle, options?: WxAppAcceptRejectOptions): Promise<void>;
+export type WxAppOutdialDeclineOptions = {
+    acceptReason?: WxAppAcceptReason;
+};
+export declare function runWxAppOutdialDecline<T>(deps: WxAppVoiceDependencies, executeCancel: () => Promise<T>, options?: WxAppOutdialDeclineOptions): 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,63 @@
+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;
+    hasDeviceId?: boolean;
+    usersubPublished?: boolean;
+}): void;
+export declare function logWxAppOfferParticipantMismatch(params: {
+    interactionId: string;
+    usersubPublished: boolean;
+    hasDeviceCallId: boolean;
+    hasDeviceId: boolean;
+    participantDeviceType?: string;
+    acceptVisible: boolean;
+    acceptEnabled: boolean;
+    acceptReason: WxAppAcceptReason;
+}): 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;