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

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
+    );
   }
 
   /**

package/src/utils/ai-docs/utils-spec.md

@@ -31,7 +31,7 @@ The utils scope currently provides shared pagination and cache behavior for cont
 
 - **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 search/filter/sort and enabled result/shape flags
 
 - **Spec-Driven Utility Workflow**: Utility-specific implementation and validation flow documented inline in this file
 
@@ -88,7 +88,7 @@ No claim is made that `src/types.ts`, AddressBook, EntryPoint, or Queue is imple
 ## Requirements
 | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
 |---|---|---|---|---|---|---|
-| UTILS-R-001 | Use cache only for simple pagination requests without search, filter, attributes, or sortBy. | Parameterized queries cannot safely reuse a page keyed only by scope/page/pageSize. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
+| UTILS-R-001 | Use cache only for simple pagination requests without search, filter, attributes, sortBy, or enabled desktop-profile/provisioning/single-object flags. Explicit `false` flags remain cache-compatible because they do not change the base result or response shape. | Parameterized or enabled variant queries cannot safely reuse a page keyed only by scope/page/pageSize, while a disabled boolean is semantically the same as omission. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` | None. | PRESENT |
 | UTILS-R-002 | Build cache keys from a caller-defined `scopeId` plus `page:pageSize`: `orgId` for EntryPoint/Queue and `bookId` for AddressBook. | Consumer scope and page boundaries prevent cross-scope or cross-page reuse. | `src/utils/PageCache.ts`, `src/services/AddressBook.ts`, `src/services/EntryPoint.ts`, `src/services/Queue.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/Queue.ts` | `PageCache.buildCacheKey` names its first implementation parameter `orgId`, but runtime callers establish the broader `scopeId` semantics. | PRESENT |
 | UTILS-R-003 | Expire entries after the configured five-minute TTL and delete them on stale lookup. | Bounded staleness prevents indefinite reuse of remote service data. | `src/utils/PageCache.ts` | None | Direct fake-clock expiration coverage is absent from current consumer tests. | PRESENT |
 | UTILS-R-004 | Cache data with total-page/record metadata and allow owning consumers to clear the cache. | Paginated services need consistent metadata without transferring ownership of remote records to the SDK. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts` | Cache hit/miss and metadata are exercised through consumers; `clearCache()` has no direct assertion. | PRESENT |
@@ -96,7 +96,7 @@ No claim is made that `src/types.ts`, AddressBook, EntryPoint, or Queue is imple
 | UTILS-R-006 | Keep PageCache free of rollout flags; consuming services decide whether to invoke it and query parameters determine cache eligibility. | Cache correctness must depend on request shape, not hidden deployment state. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` | None; rollout applicability is explicitly N/A. | PRESENT |
 
 ## Design Overview
-Utils separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Caching is intentionally limited to simple page browsing; search/filter/sort requests bypass cache to prevent incorrect reuse.
+Utils separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Caching is intentionally limited to simple page browsing; search/filter/sort requests and enabled result/shape flags bypass cache to prevent incorrect reuse.
 
 > **This is the authoritative documentation for the `src/utils` scope.** It covers shared pagination/cache contracts used by data services. For task routing and cross-service conventions, see the [root orchestrator AGENTS.md](../../../AGENTS.md).
 
@@ -117,7 +117,7 @@ Cross-scope mention:
 ```mermaid
 flowchart LR
   Service[AddressBook / EntryPoint / Queue] --> Eligible{canUseCache params?}
-  Eligible -->|search/filter/attributes/sort present| Backend[Fetch without cache]
+  Eligible -->|query variant or enabled result/shape flag| Backend[Fetch without cache]
   Eligible -->|simple pagination| Key[buildCacheKey scopeId:page:pageSize]
   Key --> Lookup[getCachedPage]
   Lookup -->|fresh| Hit[Return cached page]
@@ -201,7 +201,7 @@ classDiagram
 ```
 
 ## Use Cases
-- **UC-1 Cache eligibility:** AddressBook, EntryPoint, or Queue bypasses cache whenever search, filter, attributes, or sort is supplied. Evidence: `src/utils/PageCache.ts`, `test/unit/spec/services/AddressBook.ts`.
+- **UC-1 Cache eligibility:** AddressBook, EntryPoint, or Queue bypasses cache whenever search, filter, attributes, sort, or an enabled desktop-profile/provisioning/single-object flag is supplied; explicit `false` flags stay eligible. Evidence: `src/utils/PageCache.ts`, `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts`.
 - **UC-2 Cache-key construction:** a simple page lookup uses `<scopeId>:page:pageSize`; AddressBook supplies `bookId`, while EntryPoint and Queue supply `orgId`. Evidence: `src/utils/PageCache.ts`, `src/services/AddressBook.ts`, `src/services/EntryPoint.ts`, `src/services/Queue.ts`.
 - **UC-3 TTL lookup/expiry:** a fresh cached entry is returned; an expired entry is deleted and treated as a miss. Evidence: `src/utils/PageCache.ts`; no direct expiration test currently exists.
 - **UC-4 Page insertion and clearing:** successful page data and normalized totals are cached, while `clearCache()` removes all entries for that service instance. Evidence: `src/utils/PageCache.ts`; consumer tests cover insertion/hit behavior, but not direct clearing.
@@ -209,7 +209,7 @@ classDiagram
 ## State Model
 Utils retains only in-memory runtime state. Durable domain records remain owned by remote Webex services. State changes are driven by explicit calls, events, timers, or actor transitions documented below.
 
-`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/shape flags (`desktopProfileFilter`, `provisioningView`, `singleObjectResponse`).
 
 ```typescript
 import PageCache, {PAGINATION_DEFAULTS} from '../utils/PageCache';
@@ -222,8 +222,16 @@ const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
 const scopeId = bookIdOrOrgId;
 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 shape-changing input.
+const canUseCache = cache.canUseCache({
+  search,
+  filter,
+  attributes,
+  sortBy,
+  desktopProfileFilter,
+  provisioningView,
+  singleObjectResponse,
+});
 
 if (canUseCache) {
   const cachedEntry = cache.getCachedPage(cacheKey);
@@ -251,7 +259,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
@@ -277,7 +285,9 @@ Returns `true` only when all of these are absent:
 
 - `sortBy`
 
-`sortOrder` alone does not trigger cache bypass because `CacheValidationParams` currently keys bypass on fields that materially change the query result set in existing consumers.
+- `desktopProfileFilter`, `provisioningView`, or `singleObjectResponse` when `true`
+
+An explicit `false` boolean remains eligible because it is semantically identical to omitting that flag. Services must pass an effective `sortBy` whenever `sortOrder` changes the wire order; Queue normalizes a direction-only request to `sortBy=name` before cache validation.
 
 Builds deterministic cache key format:
 
@@ -320,7 +330,7 @@ Note: `clearCache()` and `getCacheSize()` are available for future use and are n
 
 ## Pitfalls
 - Do not describe the first cache-key field as universally `orgId`: AddressBook passes `bookId`, while EntryPoint and Queue pass `orgId`.
-- Do not cache queries containing `search`, `filter`, `attributes`, or `sortBy`; their result set is not represented in the key.
+- Do not cache queries containing `search`, `filter`, `attributes`, `sortBy`, or enabled desktop-profile/provisioning/single-object flags; their result set or shape is not represented in the key. Explicit `false` flags do not create a variant.
 - Do not treat an expired entry as usable data. `getCachedPage` deletes it and returns `null`.
 - Do not cache a rejected request or a response without data; only the consuming service owns the backend request and decides when to call `cachePage`.