@webex/contact-center 3.12.0-next.13 → 3.12.0-next.130

package/src/services/wxAppDiagnosticLogging.ts

@@ -0,0 +1,174 @@
+import LoggerProxy from '../logger-proxy';
+
+export const WXAPP_LOG_FEATURE = 'wxApp';
+export 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';
+
+type WxAppLogData = Record<string, string | boolean | number | undefined>;
+
+/** Last 8 chars of callId for correlation without logging full id. */
+export function callIdSuffix(callId: string | null | undefined): string | undefined {
+  if (!callId) {
+    return undefined;
+  }
+
+  return callId.length <= 8 ? callId : callId.slice(-8);
+}
+
+function logWxApp(message: string, method: string, data: WxAppLogData): void {
+  LoggerProxy.info(`${WXAPP_LOG_PREFIX} ${message}`, {
+    module: 'wxAppDiagnosticLogging',
+    method,
+    data: {feature: WXAPP_LOG_FEATURE, ...data},
+  });
+}
+
+function logWxAppError(message: string, method: string, data: WxAppLogData): void {
+  LoggerProxy.error(`${WXAPP_LOG_PREFIX} ${message}`, {
+    module: 'wxAppDiagnosticLogging',
+    method,
+    data: {feature: WXAPP_LOG_FEATURE, ...data},
+  });
+}
+
+export function logWxAppSessionReadiness(params: {
+  enableWxBetterTogether: boolean;
+  loginOption: string | undefined;
+  wxAppHooksApplied: boolean;
+  usersubPublished: boolean;
+  mercurySubscribed: boolean;
+  telephonyTaskType: 'Voice' | 'WebRTC' | 'unknown';
+  skipReason?: WxAppSessionSkipReason;
+}): void {
+  logWxApp('session readiness', 'logWxAppSessionReadiness', {
+    event: 'session_readiness',
+    enableWxBetterTogether: params.enableWxBetterTogether,
+    loginOption: params.loginOption,
+    wxAppHooksApplied: params.wxAppHooksApplied,
+    usersubPublished: params.usersubPublished,
+    mercurySubscribed: params.mercurySubscribed,
+    telephonyTaskType: params.telephonyTaskType,
+    skipReason: params.skipReason,
+  });
+}
+
+export function deriveWxAppAcceptReason(params: {
+  isWxAppInboundOffer: boolean;
+  isWxAppOutdialOffer: boolean;
+  isWebrtc: boolean;
+  isOutdial: boolean;
+  wxAppAcceptInFlight: boolean;
+  wxAppAnswerPending: boolean;
+  enableWxBetterTogether: boolean;
+  hasDeviceCallId: boolean;
+}): WxAppAcceptReason {
+  if (params.isWxAppInboundOffer || params.isWxAppOutdialOffer) {
+    if (params.wxAppAcceptInFlight) {
+      return 'wxApp_accept_in_flight';
+    }
+    if (params.wxAppAnswerPending) {
+      return 'wxApp_answer_pending';
+    }
+
+    return 'wxApp_offer_ready';
+  }
+
+  if (params.isWebrtc && !params.isOutdial) {
+    return 'browser_webrtc_offer';
+  }
+
+  if (params.isOutdial) {
+    return 'outdial_auto_answer';
+  }
+
+  if (params.enableWxBetterTogether && !params.hasDeviceCallId) {
+    return 'extension_non_wxApp_offer';
+  }
+
+  return 'extension_non_wxApp_offer';
+}
+
+export function logWxAppOfferDecision(params: {
+  interactionId: string;
+  acceptVisible: boolean;
+  acceptEnabled: boolean;
+  acceptReason: WxAppAcceptReason;
+  wxAppParticipantDeviceType?: string;
+  hasDeviceCallId: boolean;
+}): void {
+  logWxApp('offer decision', 'logWxAppOfferDecision', {
+    event: 'offer_decision',
+    interactionId: params.interactionId,
+    acceptVisible: params.acceptVisible,
+    acceptEnabled: params.acceptEnabled,
+    acceptReason: params.acceptReason,
+    wxAppParticipantDeviceType: params.wxAppParticipantDeviceType,
+    hasDeviceCallId: params.hasDeviceCallId,
+  });
+}
+
+export function logWxAppTelephonyAction(params: {
+  action: WxAppTelephonyAction;
+  phase: WxAppTelephonyPhase;
+  interactionId?: string;
+  trackingId?: string;
+  httpStatus?: number | string;
+  failureReason?: string;
+}): void {
+  const payload: WxAppLogData = {
+    event: 'telephony_action',
+    action: params.action,
+    phase: params.phase,
+    interactionId: params.interactionId,
+    trackingId: params.trackingId,
+    httpStatus: params.httpStatus,
+    failureReason: params.failureReason,
+  };
+
+  if (params.phase === 'failed') {
+    logWxAppError(`telephony ${params.action} ${params.phase}`, 'logWxAppTelephonyAction', payload);
+  } else {
+    logWxApp(`telephony ${params.action} ${params.phase}`, 'logWxAppTelephonyAction', payload);
+  }
+}
+
+export function logWxAppValidationFailure(reason: string, interactionId?: string): void {
+  logWxAppError('validation failed', 'logWxAppValidationFailure', {
+    event: 'validation_failed',
+    reason,
+    interactionId,
+  });
+}
+
+export function logWxAppMercuryMuteSync(params: {
+  phase: 'received' | 'applied' | 'dropped';
+  muted?: boolean;
+  callIdSuffix?: string;
+  interactionId?: string;
+  dropReason?: string;
+}): void {
+  logWxApp(`mercury mute sync ${params.phase}`, 'logWxAppMercuryMuteSync', {
+    event: 'mercury_mute_sync',
+    phase: params.phase,
+    muted: params.muted,
+    callIdSuffix: params.callIdSuffix,
+    interactionId: params.interactionId,
+    dropReason: params.dropReason,
+  });
+}

package/src/services/wxAppTelephonyUtils.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 function isWxAppCallNotFoundError(error: unknown): boolean {
+  const err = error as {status?: number | string; message?: string};
+  if (err?.status === 400 || err?.status === '400') {
+    return true;
+  }
+
+  const message = String(err?.message ?? error ?? '');
+
+  return message.includes('Call not found') || message.includes('101002');
+}

package/src/types.ts

@@ -6,7 +6,13 @@ import {
 } from '@webex/internal-plugin-metrics/src/metrics.types';
 import * as Agent from './services/agent/types';
 import * as Contact from './services/task/types';
-import {Profile} from './services/config/types';
+import {
+  AIFeatureFlags,
+  Entity,
+  Profile,
+  CreateUserPreferenceRequest,
+  UpdateUserPreferenceRequest,
+} from './services/config/types';
 import {PaginatedResponse, BaseSearchParams} from './utils/PageCache';
 
 /**
@@ -88,12 +94,19 @@ export type WebexRequestPayload = {
  */
 type Listener = (e: string, data?: unknown) => void;
 
+/**
+ * Mercury event handler callback.
+ * @internal
+ * @ignore
+ */
+type MercuryEventHandler = (data?: unknown) => void;
+
 /**
  * Event listener removal function type.
  * @internal
  * @ignore
  */
-type ListenerOff = (e: string) => void;
+type ListenerOff = (e: string, handler?: MercuryEventHandler) => void;
 
 /**
  * Service host configuration.
@@ -156,6 +169,10 @@ export interface CCPluginConfig {
   };
   /** Configuration for the calling client */
   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;
 }
 
 /**
@@ -286,6 +303,12 @@ interface IWebexInternal {
     version: string;
     /** Calling behavior configuration */
     callingBehavior: string;
+    /** Whether the device is registered with WDM */
+    registered?: boolean;
+    /** Register the device with WDM */
+    register?: () => Promise<void>;
+    /** Unregister the device from WDM */
+    unregister?: () => Promise<void>;
   };
   /** Presence service */
   presence: unknown;
@@ -397,6 +420,9 @@ export interface IContactCenter {
    * cc.register().then(profile => { ... });
    */
   register(): Promise<Profile>;
+
+  /** Returns the system-managed WellbeingBreak idle code for the registered session. */
+  getWellbeingBreakIdleCode(): Promise<Entity>;
 }
 
 /**
@@ -542,22 +568,22 @@ export type RequestBody =
   | Contact.cancelCtq
   | Contact.WrapupPayLoad
   | Contact.DialerPayload
-  | Contact.PreviewContactPayload;
+  | Contact.PreviewContactPayload
+  | CreateUserPreferenceRequest
+  | UpdateUserPreferenceRequest;
 
 /**
  * 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.
@@ -565,9 +591,37 @@ export type BuddyAgents = {
    * 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';
 };
 
 /**
+ * Holds the configuration flags for the Agent.
+ * These flags determine the availability of certain features in the Agent UI.
+ * @internal
+ */
+export type ConfigFlags = {
+  isEndTaskEnabled: boolean;
+  isEndConsultEnabled: boolean;
+  webRtcEnabled: boolean;
+  autoWrapup: boolean;
+  aiFeature?: AIFeatureFlags;
+  /** Agent-profile policy used to derive task consult/transfer destination controls. */
+  consultTransfer?: Contact.ConsultTransferDestinationConfig;
+  /**
+   * Optional toggle to globally enable/disable recording controls.
+   * Falls back to backend hints when omitted.
+   */
+  isRecordingEnabled?: boolean;
+  /** Whether wxApp thick-client answer controls/APIs are enabled (WXCC-6026) */
+  enableWxBetterTogether?: boolean;
+};
+
+/**
+
  * Generic error structure for Contact Center SDK errors.
  * Contains detailed information about the error context.
  * @public
@@ -653,10 +707,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>;
@@ -821,38 +877,233 @@ export type BuddyAgentsResponse = Agent.BuddyAgentsSuccess | Error;
  */
 export type UpdateDeviceTypeResponse = Agent.DeviceTypeUpdateSuccess | Error;
 
+/**
+ * Supported transcript control actions for AI Assistant events.
+ * @public
+ * @example
+ * const action: TranscriptAction = 'START';
+ * @ignore
+ */
 export type TranscriptAction = 'START' | 'STOP';
 
+/**
+ * Parameters used to request AI Assistant real-time assistance.
+ * @public
+ * @example
+ * const params: RealTimeAssistanceParams = {
+ *   interactionId: 'interaction-123',
+ *   context: 'Need help with credit card payment due date',
+ * };
+ */
+export type RealTimeAssistanceParams = {
+  /** Agent identifier */
+  agentId: string;
+  /** Interaction identifier for which assistance should be generated */
+  interactionId: string;
+  /** Optional additional context that should refine the assistance */
+  context?: string;
+  /** Optional language code for assistance (for example, 'en'). Defaults to 'en'. */
+  languageCode?: string;
+};
+
+/**
+ * Supported user actions on an AI Assistant real-time assistance adaptive card.
+ * @public
+ */
+export const RealTimeAssistanceUserActionId = {
+  /** User liked the real-time assistance response */
+  LIKE: 'likeButton',
+  /** User disliked the real-time assistance response */
+  DISLIKE: 'dislikeButton',
+  /** User copied the real-time assistance response */
+  COPY: 'copyButton',
+} as const;
+
+/**
+ * Union type of supported real-time assistance user actions.
+ * @public
+ */
+export type RealTimeAssistanceUserActionId = Enum<typeof RealTimeAssistanceUserActionId>;
+
+/**
+ * Parameters used to send user action feedback for a real-time assistance adaptive card.
+ * @public
+ * @example
+ * const params: RealTimeAssistanceUserActionParams = {
+ *   agentId: 'agent-123',
+ *   interactionId: 'interaction-123',
+ *   adaptiveCardId: 'adaptive-card-123',
+ *   actionId: RealTimeAssistanceUserActionId.LIKE,
+ * };
+ */
+export type RealTimeAssistanceUserActionParams = {
+  /** Agent identifier */
+  agentId: string;
+  /** Interaction identifier associated with the real-time assistance response */
+  interactionId: string;
+  /** Adaptive card identifier from the real-time assistance payload */
+  adaptiveCardId: string;
+  /** User action performed on the adaptive card */
+  actionId: RealTimeAssistanceUserActionId;
+  /** Optional language code. Defaults to 'en'. */
+  languageCode?: string;
+};
+
+/**
+ * Wellness notification actions delivered by the Contact Center notification service.
+ * @public
+ */
+export const WELLNESS_BREAK_NOTIFICATION_ACTIONS = {
+  PROVIDE_WELLNESS_BREAK: 'PROVIDE_WELLNESS_BREAK',
+  SUGGEST_WELLNESS_BREAK: 'SUGGEST_WELLNESS_BREAK',
+  WELLNESS_BREAK_NOT_ALLOWED: 'WELLNESS_BREAK_NOT_ALLOWED',
+} as const;
+
+/** Union of supported wellness notification actions. @public */
+export type WellnessBreakNotificationAction = Enum<typeof WELLNESS_BREAK_NOTIFICATION_ACTIONS>;
+
+/**
+ * Agent actions accepted by the wellness action API.
+ * @public
+ */
+export const WELLNESS_BREAK_USER_ACTIONS = {
+  REQUESTED: 'REQUESTED',
+  ACCEPTED: 'ACCEPTED',
+  REJECTED: 'REJECTED',
+  NO_RESPONSE: 'NO_RESPONSE',
+} as const;
+
+/** Union of supported wellness action API values. @public */
+export type WellnessBreakUserAction = Enum<typeof WELLNESS_BREAK_USER_ACTIONS>;
+
+/**
+ * Validated, agent-scoped wellness notification emitted by Contact Center.
+ * @public
+ */
+export interface WellnessBreakEvent {
+  /** Agent identifier */
+  agentId: string;
+  /** Organization identifier */
+  orgId: string;
+  /** Session identifier supplied by the notification; it may differ from the consumer's active session */
+  agentSessionId: string;
+  /** Backend wellness action */
+  actionEvent: WellnessBreakNotificationAction;
+  /** Optional untrusted plain-text message supplied by the backend */
+  actionText?: string;
+  /** Optional normalized interaction diagnostic */
+  interactionId?: string;
+  /** Notification diagnostic only; never an action-request correlation identifier */
+  trackingId?: string;
+}
+
+/**
+ * Parameters for responding to a backend-provided wellness offer.
+ * @public
+ */
+export interface RespondToWellnessBreakParams {
+  /** Agent response; REQUESTED is available only through requestWellnessBreak */
+  action: Exclude<WellnessBreakUserAction, typeof WELLNESS_BREAK_USER_ACTIONS.REQUESTED>;
+}
+
+/**
+ * Supported AI Assistant event categories.
+ * @public
+ * @example
+ * const eventType: AIAssistantEventType = AIAssistantEventType.CUSTOM_EVENT;
+ * @ignore
+ */
 export const AIAssistantEventType = {
+  /** Custom AI Assistant event */
   CUSTOM_EVENT: 'CUSTOM_EVENT',
+  /** CTI-backed AI Assistant event */
   CTI_EVENT: 'CTI_EVENT',
 } as const;
 
+/**
+ * Union type of AI Assistant event categories.
+ * @public
+ * @example
+ * function send(type: AIAssistantEventType) { ... }
+ * @ignore
+ */
 export type AIAssistantEventType = Enum<typeof AIAssistantEventType>;
 
+/**
+ * Supported AI Assistant event names.
+ * @public
+ * @example
+ * const name: AIAssistantEventName = AIAssistantEventName.GET_TRANSCRIPTS;
+ * @ignore
+ */
 export const AIAssistantEventName = {
+  /** Request transcript streaming for an interaction */
   GET_TRANSCRIPTS: 'GET_TRANSCRIPTS',
+  /** Request a suggested response for an interaction */
+  GET_SUGGESTIONS: 'GET_SUGGESTIONS',
+  /** Add extra context to refine a suggested response */
+  ADD_SUGGESTIONS_EXTRA_CONTEXT: 'ADD_SUGGESTIONS_EXTRA_CONTEXT',
+  /** Request mid-call summary generation */
   GET_MID_CALL_SUMMARY: 'GET_MID_CALL_SUMMARY',
+  /** Request post-call summary generation */
   GET_POST_CALL_SUMMARY: 'GET_POST_CALL_SUMMARY',
+  /** Mid-call summary response event */
   MID_CALL_SUMMARY_RESPONSE: 'MID_CALL_SUMMARY_RESPONSE',
+  /** Post-call summary response event */
   POST_CALL_SUMMARY_RESPONSE: 'POST_CALL_SUMMARY_RESPONSE',
+  /** Suggested digital response event */
   SUGGESTED_RESPONSES_DIGITAL: 'SUGGESTED_RESPONSES_DIGITAL',
+  /** User action on a suggested response adaptive card */
+  SUGGESTED_RESPONSES_USER_ACTION: 'SUGGESTED_RESPONSES_USER_ACTION',
+  /** Agent Wellness Break request/response action */
+  WELLNESS_BREAK_ACTION: 'WellnessBreakAction',
 } as const;
 
+/**
+ * Union type of AI Assistant event names.
+ * @public
+ * @example
+ * function handle(name: AIAssistantEventName) { ... }
+ * @ignore
+ */
 export type AIAssistantEventName = Enum<typeof AIAssistantEventName>;
 
+/**
+ * A single transcript message entry returned by AI Assistant APIs.
+ * @public
+ * @example
+ * const message: TranscriptMessage = { role: 'AGENT', content: 'Hello', messageId: '1', publishTimestamp: Date.now() };
+ *
+ */
 export type TranscriptMessage = {
+  /** Speaker role for this message */
   role: string;
+  /** Transcript chunk content */
   content: string;
+  /** Unique message identifier */
   messageId: string;
+  /** Message publish timestamp (epoch milliseconds) */
   publishTimestamp: number;
 };
 
+/**
+ * Response payload for historic transcripts API.
+ * @public
+ * @example
+ * const resp: HistoricTranscriptsResponse = { orgId: 'org', agentId: 'agent', conversationId: null, interactionId: 'int', source: 'AI', data: [] };
+ *
+ */
 export type HistoricTranscriptsResponse = {
+  /** Organization identifier */
   orgId: string;
+  /** Agent identifier */
   agentId: string;
+  /** Conversation identifier when available */
   conversationId: string | null;
+  /** Interaction identifier */
   interactionId: string;
+  /** Data source identifier */
   source: string;
+  /** Transcript messages */
   data: TranscriptMessage[];
 };