@webex/contact-center 3.12.0-llmrefactor.2 → 3.12.0-llmrefactor.3

package/src/services/task/voice/wxAppVoiceMethods.ts

@@ -0,0 +1,307 @@
+import AnswerCallOnWebexService from '../../AnswerCallOnWebexService';
+import LoggerProxy from '../../../logger-proxy';
+import {METHODS} from '../../../constants';
+import {getErrorDetails} from '../../core/Utils';
+import {TaskData, TaskToggleMuteOptions, TaskTransmitDtmfOptions} from '../types';
+import {TaskState} from '../state-machine';
+import {
+  decodedLineOwnerId,
+  getWebexCallingDeviceDetailsForAgent,
+  WebexCallingDeviceDetails,
+} from '../WebexCallingUtils';
+
+type WxAppParticipant = {
+  deviceType?: string;
+  deviceCallId?: string;
+  deviceId?: string;
+};
+
+export type WxAppVoiceDependencies = {
+  enableWxBetterTogether: boolean;
+  answerCallOnWebexService?: AnswerCallOnWebexService;
+  agentId?: string;
+  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;
+};
+
+const isWxAppParticipant = (participant: unknown): participant is WxAppParticipant =>
+  (participant as WxAppParticipant)?.deviceType === 'wxApp' &&
+  typeof (participant as WxAppParticipant)?.deviceCallId === 'string' &&
+  (participant as WxAppParticipant).deviceCallId.trim() !== '' &&
+  typeof (participant as WxAppParticipant)?.deviceId === 'string' &&
+  (participant as WxAppParticipant).deviceId.trim() !== '';
+
+const isOutdialTask = (deps: WxAppVoiceDependencies): boolean =>
+  deps.getTaskData()?.interaction?.outboundType === 'OUTDIAL';
+
+function getWxAppAgentParticipant(deps: WxAppVoiceDependencies): unknown {
+  const taskData = deps.getTaskData();
+  const participants = taskData.interaction?.participants;
+  const agentId = deps.agentId ?? taskData.agentId;
+
+  if (!participants || !agentId) {
+    return undefined;
+  }
+
+  if (participants[agentId]) {
+    return participants[agentId];
+  }
+
+  return Object.values(participants).find(
+    (participant) => (participant as {id?: string})?.id === agentId
+  );
+}
+
+export function getCallingDeviceDetails(
+  deps: WxAppVoiceDependencies
+): WebexCallingDeviceDetails | undefined {
+  const taskData = deps.getTaskData();
+  const participant = getWxAppAgentParticipant(deps);
+
+  if (!isWxAppParticipant(participant)) {
+    return undefined;
+  }
+
+  return getWebexCallingDeviceDetailsForAgent(
+    deps.agentId ?? taskData.agentId,
+    taskData.interaction?.participants
+  );
+}
+
+export function isWebexAppCallingOffer(deps: WxAppVoiceDependencies): boolean {
+  if (!deps.enableWxBetterTogether) {
+    return false;
+  }
+
+  const state = deps.getTaskState();
+  if (state !== TaskState.OFFERED) {
+    return false;
+  }
+
+  const details = getCallingDeviceDetails(deps);
+
+  return Boolean(details);
+}
+
+/** Inbound wxApp offer only — outdial decline uses CC routing, not telephony reject. */
+export function isWebexAppInboundCallingOffer(deps: WxAppVoiceDependencies): boolean {
+  return isWebexAppCallingOffer(deps) && !isOutdialTask(deps);
+}
+
+export function getWebexCallingCallId(deps: WxAppVoiceDependencies): string | null {
+  const state = deps.getTaskState();
+  if (
+    !state ||
+    state === TaskState.OFFERED ||
+    state === TaskState.IDLE ||
+    state === TaskState.WRAPPING_UP ||
+    state === TaskState.TERMINATED ||
+    state === TaskState.COMPLETED
+  ) {
+    return null;
+  }
+
+  return getCallingDeviceDetails(deps)?.deviceCallId ?? null;
+}
+
+export function getWxAppLineOwnerId(deps: WxAppVoiceDependencies): string | undefined {
+  const participant = getWxAppAgentParticipant(deps) as {lineOwnerId?: string} | undefined;
+  const lineOwnerId = participant?.lineOwnerId;
+
+  return typeof lineOwnerId === 'string' && lineOwnerId.trim() !== '' ? lineOwnerId : undefined;
+}
+
+export function resolveWxAppLineOwnerId(
+  deps: WxAppVoiceDependencies,
+  override?: string
+): string | undefined {
+  if (typeof override === 'string' && override.trim() !== '') {
+    return override;
+  }
+
+  return decodedLineOwnerId(getWxAppLineOwnerId(deps));
+}
+
+function assertWxAppEnabled(deps: WxAppVoiceDependencies): void {
+  if (!deps.enableWxBetterTogether) {
+    throw new Error('enableWxBetterTogether is disabled');
+  }
+
+  if (!deps.answerCallOnWebexService) {
+    throw new Error('AnswerCallOnWebexService is unavailable');
+  }
+}
+
+export async function acceptOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  if (!isWebexAppCallingOffer(deps)) {
+    throw new Error('Task is not a wxApp calling offer');
+  }
+
+  const details = getCallingDeviceDetails(deps);
+  if (!details) {
+    throw new Error('WxApp calling device details are unavailable');
+  }
+
+  await deps.answerCallOnWebexService.answerCall({
+    callId: details.deviceCallId,
+    endpointId: details.deviceId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+}
+
+export async function rejectOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  if (!isWebexAppInboundCallingOffer(deps)) {
+    throw new Error('Task is not a wxApp inbound calling offer');
+  }
+
+  const details = getCallingDeviceDetails(deps);
+  if (!details) {
+    throw new Error('WxApp calling device details are unavailable');
+  }
+
+  await deps.answerCallOnWebexService.rejectCall({
+    callId: details.deviceCallId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+}
+
+export async function toggleMuteOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string; muted?: boolean}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  const callId = getWebexCallingCallId(deps);
+  if (!callId) {
+    throw new Error('WxApp call ID is unavailable');
+  }
+
+  const targetMuted = options?.muted ?? !deps.getWxAppMuted();
+  const request = targetMuted
+    ? deps.answerCallOnWebexService.muteCall.bind(deps.answerCallOnWebexService)
+    : deps.answerCallOnWebexService.unmuteCall.bind(deps.answerCallOnWebexService);
+
+  await request({
+    callId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+  deps.setWxAppMuted(targetMuted);
+}
+
+export async function transmitDtmfOnWebex(
+  deps: WxAppVoiceDependencies,
+  options: {dtmf: string; lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  const callId = getWebexCallingCallId(deps);
+  if (!callId) {
+    throw new Error('WxApp call ID is unavailable');
+  }
+
+  LoggerProxy.info('transmitDtmf', {
+    module: 'wxAppVoiceMethods',
+    method: METHODS.TRANSMIT_DTMF,
+    data: {
+      callId,
+      dtmfLength: options.dtmf.length,
+      hasLineOwnerId: Boolean(options.lineOwnerId),
+    },
+  });
+
+  await deps.answerCallOnWebexService.transmitDtmf({
+    callId,
+    dtmf: options.dtmf,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options.lineOwnerId),
+  });
+}
+
+export async function runWxAppAccept(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  try {
+    lifecycle.setWxAppAcceptInFlight(true);
+    lifecycle.setWxAppAnswerPending(true);
+    await acceptOnWebex(deps, options);
+    lifecycle.resetWxAppMuted();
+    await lifecycle.syncWxAppMuteFromCallDetails();
+  } catch (error) {
+    lifecycle.setWxAppAnswerPending(false);
+    lifecycle.mapWxAppVoiceError(error, METHODS.ACCEPT);
+  } finally {
+    lifecycle.setWxAppAcceptInFlight(false);
+  }
+}
+
+export async function runWxAppReject(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  try {
+    await rejectOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.REJECT);
+  }
+}
+
+export async function runWxAppToggleMute(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: TaskToggleMuteOptions
+): Promise<void> {
+  try {
+    await toggleMuteOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.TOGGLE_MUTE);
+  }
+}
+
+export async function runWxAppTransmitDtmf(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options: TaskTransmitDtmfOptions
+): Promise<void> {
+  try {
+    await transmitDtmfOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.TRANSMIT_DTMF);
+  }
+}
+
+export function mapWxAppVoiceError(error: unknown, method: string, module: string): never {
+  if (
+    error instanceof Error &&
+    (error as Error & {isWxAppTelephonyError?: boolean}).isWxAppTelephonyError
+  ) {
+    throw error;
+  }
+
+  const {error: detailedError} = getErrorDetails(error, method, module);
+  throw detailedError;
+}

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

@@ -93,12 +93,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.
@@ -163,6 +170,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;
 }
 
 /**
@@ -293,6 +302,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;
@@ -555,18 +570,16 @@ export type RequestBody =
 
 /**
  * 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.
@@ -574,6 +587,11 @@ 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';
 };
 
 /**
@@ -587,11 +605,15 @@ export type ConfigFlags = {
   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;
 };
 
 /**
@@ -681,10 +703,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/src/utils/AGENTS.md

@@ -12,7 +12,7 @@ The utils scope currently provides shared pagination and cache behavior for cont
 
 - **Typed Pagination Contracts**: Reusable interfaces for response metadata and query params
 - **Generic In-Memory Page Caching**: `PageCache<T>` utility for simple pagination reuse
-- **Cache Safety Rules**: Explicit bypass behavior for search/filter/sort scenarios
+- **Cache Safety Rules**: Explicit bypass behavior for query variants and enabled result/response-shape flags
 - **Spec-Driven Utility Workflow**: Utility-specific implementation and validation flow documented inline in this file
 
 | Component             | File                             | Description                                                                                                                                     |
@@ -36,7 +36,7 @@ src/utils/
 
 ## PageCache Utility
 
-`PageCache<T>` provides a consistent caching model for paginated list APIs. It is optimized for simple page browsing and intentionally bypasses cache for parameterized query cases (`search`, `filter`, `attributes`, `sortBy`).
+`PageCache<T>` provides a consistent caching model for paginated list APIs. It is optimized for simple page browsing and intentionally bypasses cache for parameterized query cases (`search`, `filter`, `attributes`, `sortBy`) and enabled result/response-shape flags (`desktopProfileFilter`, `provisioningView`, `singleObjectResponse`).
 
 ### Reference Usage
 
@@ -49,8 +49,16 @@ const page = PAGINATION_DEFAULTS.PAGE;
 const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
 const cacheKey = cache.buildCacheKey(scopeId, page, pageSize);
 
-// Include sortBy only for services that support sorting.
-const canUseCache = cache.canUseCache({search, filter, attributes, sortBy});
+// Include every supported result- or response-shape-changing input.
+const canUseCache = cache.canUseCache({
+  search,
+  filter,
+  attributes,
+  sortBy,
+  desktopProfileFilter,
+  provisioningView,
+  singleObjectResponse,
+});
 
 if (canUseCache) {
   const cachedEntry = cache.getCachedPage(cacheKey);
@@ -80,7 +88,7 @@ return response;
 ```mermaid
 graph TD
   A[Request arrives with scopeId/page/pageSize] --> B{canUseCache?}
-  B -->|No: search/filter/attributes/sortBy provided| C[Bypass cache and call API]
+  B -->|No: query variant or enabled result/shape flag| C[Bypass cache and call API]
   B -->|Yes| D[buildCacheKey scopeId:page:pageSize]
   D --> E["getCachedPage(cacheKey)"]
   E -->|Miss| C
@@ -138,11 +146,14 @@ Contract passed to `canUseCache()`:
 - `filter?: string`
 - `attributes?: string`
 - `sortBy?: string`
+- `desktopProfileFilter?: boolean`
+- `provisioningView?: boolean`
+- `singleObjectResponse?: boolean`
 
 Behavior note:
 
-- Cache bypass is triggered by `sortBy`, not by `sortOrder` alone.
-- If a new service treats `sortOrder` as meaningful without `sortBy`, extend `CacheValidationParams` and `canUseCache()` together.
+- Cache bypass is triggered by a truthy query variant or enabled result/response-shape flag; an explicit `false` boolean remains cache-compatible because it is semantically equivalent to omission.
+- `sortOrder` is not a `CacheValidationParams` field. A service where it changes the wire order without `sortBy` must pass an effective `sortBy`; Queue normalizes a direction-only request to `sortBy: 'name'` before cache validation.
 
 ### `BaseSearchParams`
 
@@ -175,8 +186,9 @@ Returns `true` only when all of these are absent:
 - `filter`
 - `attributes`
 - `sortBy`
+- `desktopProfileFilter`, `provisioningView`, or `singleObjectResponse` when `true`
 
-`sortOrder` alone does not trigger cache bypass because `CacheValidationParams` currently keys bypass on fields that materially change the query result set in existing consumers.
+An explicit `false` boolean remains eligible. `sortOrder` is normalized by the consuming service when it changes the effective wire order; Queue passes `sortBy: 'name'` for a direction-only request.
 
 ### `buildCacheKey(scopeId: string, page: number, pageSize: number): string`
 
@@ -223,7 +235,6 @@ Current consumers of `PageCache` and defaults:
 | Consumer                | File                                                       | Usage                                                        |
 | ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
 | `AddressBook`           | [`../services/AddressBook.ts`](../services/AddressBook.ts) | Caches paged address-book responses                          |
-| `EntryPoint`            | [`../services/EntryPoint.ts`](../services/EntryPoint.ts)   | Caches paged entry-point responses                           |
 | `Queue`                 | [`../services/Queue.ts`](../services/Queue.ts)             | Caches paged queue responses                                 |
 | `Public type contracts` | [`../types.ts`](../types.ts)                               | Re-exports pagination/search contracts into SDK-facing types |
 
@@ -268,7 +279,7 @@ flowchart TD
 - [ ] `canUseCache()` bypass conditions are unchanged or intentionally updated
 - [ ] `totalRecords`/`totalItems` mapping behavior is preserved
 - [ ] Logging still uses `LoggerProxy` with `module` and `method`
-- [ ] AddressBook/EntryPoint/Queue integration behavior remains correct
+- [ ] AddressBook/Queue cache integration remains correct; EntryPoint remains explicitly uncached
 
 ---
 

package/src/utils/PageCache.ts

@@ -97,6 +97,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;
 }
 
 /**
@@ -116,8 +122,18 @@ const DEFAULT_CACHE_TTL_MINUTES = 5;
  * // 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);
  *
@@ -145,15 +161,32 @@ export class PageCache<T> {
 
   /**
    * 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
    */
   public canUseCache(params: CacheValidationParams): boolean {
-    const {search, filter, attributes, sortBy} = params;
+    const {
+      search,
+      filter,
+      attributes,
+      sortBy,
+      desktopProfileFilter,
+      provisioningView,
+      singleObjectResponse,
+    } = params;
 
-    return !search && !filter && !attributes && !sortBy;
+    return (
+      !search &&
+      !filter &&
+      !attributes &&
+      !sortBy &&
+      !desktopProfileFilter &&
+      !provisioningView &&
+      !singleObjectResponse
+    );
   }
 
   /**