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

package/.sdd/manifest.json

@@ -52,7 +52,8 @@
       "contracts": {
         "provides": [
           "Published @webex/contact-center package; ContactCenter WebexPlugin; public SDK methods, events, types, Task with ordered action-specific consult/transfer destination controls, AddressBook, ApiAIAssistant, UserPreference, cc.userPreference, existing getQueues/getEntryPoints methods with consult/transfer defaults, full Queue records, and mapped EntryPoint records with optional numbers, exported user-preference request/response types, and preview-campaign methods acceptPreviewContact/skipPreviewContact/removePreviewContact",
-          "WXCC-6026 wxApp Better Together: enableWxBetterTogether init config, isWxBetterTogetherEnabled read API, unified task telephony (task.accept/decline/toggleMute/transmitDtmf), TASK_WXAPP_MUTE_STATE_UPDATED event, optional main.keypad uiControl, multi-login supported; runtime toggle deferred to Phase 2 (private)"
+          "WXCC-6026 wxApp Better Together: enableWxBetterTogether init config, isWxBetterTogetherEnabled read API, unified task telephony (task.accept/decline/toggleMute/transmitDtmf), TASK_WXAPP_MUTE_STATE_UPDATED event, optional main.keypad uiControl, multi-login supported; runtime toggle deferred to Phase 2 (private)",
+          "BROWSER stationLogin payload: dialNumber and deviceId are webrtc-{agentId} (contact-center.station-login-browser-dn / AGENT-R-006); public stationLogin({loginOption: 'BROWSER'}) input unchanged"
         ],
         "requires": [
           "Webex SDK host/plugin runtime; Contact Center REST and WebSocket services; internal Webex calling, metrics, support, authorization, logger, and mercury packages"
@@ -180,7 +181,7 @@
       "canonical_spec": "src/services/agent/ai-docs/agent-spec.md",
       "contracts": {
         "provides": [
-          "Agent request factory; station login/logout, state changes, buddy-agent and relogin operations; AGENT_EVENTS and agent types"
+          "Agent request factory; station login/logout, state changes, buddy-agent and relogin operations; AGENT_EVENTS and agent types; BROWSER station login sends dialNumber and deviceId as webrtc-{agentId} (contact-center.station-login-browser-dn / AGENT-R-006)"
         ],
         "requires": [
           "AqmReqs; WCC API gateway; correlated WebSocket notifications; ContactCenter registration/profile state"
@@ -309,7 +310,7 @@
       "canonical_spec": "src/services/task/ai-docs/task-spec.md",
       "contracts": {
         "provides": [
-          "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager lifecycle correlation, narrowly scoped backend-authoritative ContactOwnerChanged recovery, and task-event publication, including routing owner-changing ContactUpdated through the existing task:hydrate event; task events/types; ordered action-specific consult/transfer destination controls; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact"
+          "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager lifecycle correlation, narrowly scoped backend-authoritative ContactOwnerChanged recovery, and task-event publication, including routing owner-changing ContactUpdated through the existing task:hydrate event; TaskManager/Voice stamp wrapUpRequired on wrap-up ingress so task:wrapup and profile-gated auto wrap-up can start; task events/types; ordered action-specific consult/transfer destination controls; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact"
         ],
         "requires": [
           "Contact/dialer AqmReqs; WebSocket managers; @webex/calling; MetricsManager; XState task-state module"

package/ai-docs/CONTRACTS.md

@@ -6,7 +6,8 @@
 | Contract ID | Owner module/package | Symbol | Signature / shape | Stability / deprecation | Schema / detail link | Defined at |
 |---|---|---|---|---|---|---|
 | `contact-center.plugin` | Contact Center | `ContactCenter` / default plugin | WebexPlugin implementing `IContactCenter` | semver public | `ai-docs/contact-center-spec.md` | `src/index.ts` |
-| `contact-center.routing-agent` | Agent/Core | `routingAgent` | `(routing: AqmReqs) => {stationLogin, logout, stateChange, buddyAgents, reload}` | semver public export; returned methods follow backend contracts | `src/services/agent/ai-docs/agent-spec.md` | `src/index.ts`, `src/services/agent/index.ts` |
+| `contact-center.routing-agent` | Agent/Core | `routingAgent` | `(routing: AqmReqs) => {stationLogin, logout, stateChange, buddyAgents, reload}`; BROWSER login payload follows `contact-center.station-login-browser-dn` | semver public export; returned methods follow backend contracts | `src/services/agent/ai-docs/agent-spec.md` | `src/index.ts`, `src/services/agent/index.ts` |
+| `contact-center.station-login-browser-dn` | Contact Center / Agent | `cc.stationLogin` BROWSER payload on `POST /v1/agents/login` | BROWSER sends `dialNumber` and `deviceId` as `webrtc-{agentId}`; EXTENSION and AGENT_DN continue to send the caller-supplied dial number for both fields | backend contract alignment; public `stationLogin({loginOption: 'BROWSER'})` input unchanged | `src/services/agent/ai-docs/agent-spec.md` AGENT-R-006 | `src/cc.ts` |
 | `contact-center.task` | Task | `Task`, `ITask`, task payload/control types | task instance and compatibility interface | semver public | `src/services/task/ai-docs/task-spec.md` | `src/index.ts` |
 | `contact-center.events` | Agent/Task/Config | `AGENT_EVENTS`, `TASK_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `CC_EVENTS` | typed string event contracts | additive; removals or semantic changes are breaking | owning module specs | `src/index.ts` |
 | `contact-center.data` | Services/Utils | `AddressBook`, `ApiAIAssistant`, SDK data response/search types | SDK data and AI-assistant access | semver public | Services/Utils specs | `src/index.ts` |
@@ -14,7 +15,7 @@
 | `contact-center.user-preference` | Services/Config | `UserPreference`, `cc.userPreference`, `UserPreferenceData`, request/response types | `getUserPreference(params?)`, `createUserPreference(data)`, `updateUserPreference(userId, data)`, `deleteUserPreference(userId)` | semver public | `src/services/ai-docs/services-spec.md` | `src/index.ts`, `src/cc.ts`, `src/services/UserPreference.ts`, `src/services/config/types.ts` |
 | `contact-center.preview-campaign` | Contact Center/Task | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact` | `(payload: PreviewContactPayload) => Promise<TaskResponse>` | semver public | `ai-docs/contact-center-spec.md`, `src/services/task/ai-docs/task-spec.md` | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` |
 | `contact-center.state-controls` | Task state machine | `getDefaultUIControls`, `TaskUIControls` with ordered `consultTransferDestinations` arrays | Task controls include per-leg action state plus ordered `consult`/`transfer` destination categories derived from profile and interaction policy | additive semver public field; destination arrays are SDK-owned and first item is the consumer default | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts` |
-| `contact-center.conference-participant-drop` | Task | `DropConferenceParticipantPayload`, `ITask.dropConferenceParticipant` | `(payload: {participantId: string}) => Promise<TaskResponse>`; Voice resolves from correlated `ParticipantLeftConference`, while non-voice base Task rejects as unsupported. Existing participant/consult lifecycle events may resolve one unique child-keyed task by `mainInteractionId`; no new public event is introduced. | semver public | `src/services/task/ai-docs/task-spec.md` | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/contact.ts`, `src/services/task/TaskManager.ts` |
+| `contact-center.conference-participant-drop` | Task | `DropConferenceParticipantPayload`, `ITask.dropConferenceParticipant` | `(payload: {participantId: string}) => Promise<TaskResponse>`; Voice resolves from correlated `ParticipantLeftConference`, while non-voice base Task rejects as unsupported. Existing participant/consult lifecycle events may resolve one unique child-keyed task by `mainInteractionId`; no new public event is introduced. | semver public | `src/services/task/ai-docs/task-spec.md`, `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/contact.ts`, `src/services/task/TaskManager.ts` |
 | `contact-center.wxapp-answer` | Contact Center / Task | `enableWxBetterTogether`, `isWxBetterTogetherEnabled()`, `getWxAppMuted`, `syncWxAppMuteFromCallDetails`, unified task telephony (`ITask.accept`, `decline`, `toggleMute({ muted?, lineOwnerId? })`, `transmitDtmf({ dtmf, lineOwnerId? })`) | init flag ON → usersub `true` + Mercury on supported station login **and silent relogin**; init flag OFF → force usersub `false` on supported station login **and silent relogin** (clears stale suppression after refresh); **Phase 1 init-only** — change flag via re-init; multi-login supported; mute backfill via GET call details + `getWxAppMuted()` on hydrate/refresh; shared-line `lineOwnerId` defaults from participant; SDK `Voice` routes wxApp telephony when flag active | semver public | `src/services/task/ai-docs/task-spec.md`, `ai-docs/contact-center-spec.md`, `src/services/ai-docs/services-spec.md` | `src/cc.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/voice/wxAppVoiceMethods.ts` |
 
 ### Events
@@ -22,7 +23,7 @@
 | Contract ID | Owner module | Event / topic | Direction | Payload schema link | Delivery guarantees | Compatibility / deprecation | Defined at |
 |---|---|---|---|---|---|---|---|
 | `agent.events` | Agent | `agent:*` | publish to application | agent spec/types | realtime; backend ordering/correlation | additive constants | `src/services/agent/types.ts` |
-| `task.events` | Task | `task:*`, including existing `task:hydrate` | consume/map backend task lifecycle events, then publish to application/task | task spec `TASK-R-010` / types | `ContactOwnerChanged` and owner-changing `ContactUpdated` route through `CONTACT_OWNER_CHANGED`; a complete promoted-current-Agent owner change may narrowly recover a missing task; consumers receive one `task:hydrate` and no synthetic `task:incoming` | compatible semantic extension of an existing event; no new event constant; backend `interaction.owner` remains authoritative | `src/services/task/TaskManager.ts`, `src/services/task/Task.ts`, `src/services/task/types.ts` |
+| `task.events` | Task | `task:*`, including existing `task:hydrate` and `task:wrapup` | consume/map backend task lifecycle events, then publish to application/task | task spec `TASK-R-010` / `TASK-R-011` / types | `ContactOwnerChanged` and owner-changing `ContactUpdated` route through `CONTACT_OWNER_CHANGED`; a complete promoted-current-Agent owner change may narrowly recover a missing task; consumers receive one `task:hydrate` and no synthetic `task:incoming`. TaskManager stamps `wrapUpRequired` once at ingress (`AGENT_WRAPUP`, conference-end/leave/transfer when this agent should wrap; HTTP `exitConference` on Voice uses the same empty-pending self-exit fallback as leave — true unless this agent is a consulted non-owner — and pending-list precedence uses the correlated response only) so consumers may receive `task:wrapup` and `task.autoWrapup` on those events. `PARTICIPANT_LEAVE` into `WRAPPING_UP` does not transition-emit; the `WRAPPING_UP` entry still emits `task:wrapup`. A nonempty `agentsPendingWrapUp` wins over transfer initiator signals (`consultingAgentId` / `transferConferenceRequested`); a named other `participantId` is never self-leave; leave wrap-up is not stamped when the actor ignores `PARTICIPANT_LEAVE` (`CONNECTED`, `HOLD_INITIATING`, `CONF_INITIATING`); leave-self with empty/absent pending stamps true unless this agent is a consulted non-owner; remaining conference agents stay unstamped. Profile-gated auto wrap-up still requires `autoWrapup !== false`, interval, and a default reason | compatible semantic extension of existing events; no new event constant; backend `interaction.owner` remains authoritative | `src/services/task/TaskManager.ts`, `src/services/task/Task.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/types.ts` |
 | `task.wxapp-mute.events` | Task | `task:wxapp-mute-state-updated` | publish to application/task | task spec/types | event-driven | additive | `src/services/task/types.ts`, `src/services/task/voice/Voice.ts` |
 | `cc.events` | Config/Core | backend CC_EVENTS | consume/map | config/core specs | remote WebSocket delivery; AQM correlation where configured | backend contract | `src/services/config/types.ts` |
 | `rtd.events` | Task | realtime transcription/suggestion | consume then publish per task | task spec | websocket best-effort according to remote service | additive payloads | `src/services/task/TaskManager.ts` |

package/dist/cc.js

@@ -22,6 +22,7 @@ var _WebCallingService = _interopRequireDefault(require("./services/WebCallingSe
 var _AnswerCallOnWebexService = _interopRequireDefault(require("./services/AnswerCallOnWebexService"));
 var _WebexCrossClientService = _interopRequireDefault(require("./services/WebexCrossClientService"));
 var _WxAppTelephonyMercurySync = _interopRequireDefault(require("./services/WxAppTelephonyMercurySync"));
+var _wxAppDiagnosticLogging = require("./services/wxAppDiagnosticLogging");
 var _types4 = require("./services/task/types");
 var _MetricsManager = _interopRequireDefault(require("./metrics/MetricsManager"));
 var _constants4 = require("./metrics/constants");
@@ -861,13 +862,15 @@ class ContactCenter extends _webexCore.WebexPlugin {
           throw error;
         }
       }
+      const deviceId = this.getDeviceId(data.loginOption, data.dialNumber);
       const loginResponse = await this.services.agent.stationLogin({
         data: {
-          dialNumber: data.loginOption === _types.LoginOption.BROWSER ? this.agentConfig.agentId : data.dialNumber,
+          // BROWSER DN must be webrtc-{agentId} so VPOP/RTMS do not treat a bare UUID as PSTN.
+          dialNumber: data.loginOption === _types.LoginOption.BROWSER ? deviceId : data.dialNumber,
           teamId: data.teamId,
           deviceType: data.loginOption,
           isExtension: data.loginOption === _types.LoginOption.EXTENSION,
-          deviceId: this.getDeviceId(data.loginOption, data.dialNumber),
+          deviceId,
           roles: [_constants3.AGENT],
           teamName: _constants.EMPTY_STRING,
           siteId: _constants.EMPTY_STRING,
@@ -1337,17 +1340,72 @@ class ContactCenter extends _webexCore.WebexPlugin {
       throw error;
     }
   }
+  getWxAppTelephonyTaskType() {
+    const loginOption = this.getCurrentStationLoginOption();
+    if (loginOption === _types.LoginOption.BROWSER) {
+      return 'WebRTC';
+    }
+    if (loginOption === _types.LoginOption.EXTENSION || loginOption === _types.LoginOption.AGENT_DN) {
+      return 'Voice';
+    }
+    return 'unknown';
+  }
   async ensureWxAppPostStationLogin() {
-    if (this.getCurrentStationLoginOption() === _types.LoginOption.BROWSER) {
+    const loginOption = this.getCurrentStationLoginOption();
+    const flagEnabled = this.isWxBetterTogetherEnabled();
+    const telephonyTaskType = this.getWxAppTelephonyTaskType();
+    if (loginOption === _types.LoginOption.BROWSER) {
+      if (flagEnabled) {
+        (0, _wxAppDiagnosticLogging.logWxAppSessionReadiness)({
+          enableWxBetterTogether: true,
+          loginOption,
+          wxAppHooksApplied: false,
+          usersubPublished: false,
+          mercurySubscribed: false,
+          telephonyTaskType,
+          skipReason: 'unsupported_browser_login'
+        });
+        this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_SKIPPED, {
+          loginOption,
+          enableWxBetterTogether: true,
+          skipReason: 'unsupported_browser_login'
+        }, ['operational', 'behavioral']);
+      }
       return;
     }
     let publishedEnable = false;
+    let wxAppInitStage = 'mercury';
     try {
-      if (this.isWxBetterTogetherEnabled()) {
+      if (flagEnabled) {
+        this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_SUCCESS, _constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_FAILED]);
         await this.ensureWxAppMercuryAndSubscribe();
+        wxAppInitStage = 'publish';
         await this.publishAnswerOnWebexCrossClientState(true);
         publishedEnable = true;
         this.taskManager.syncWxAppMuteFromCallDetailsForAllTasks();
+        const mercurySubscribed = this.wxAppTelephonyMercurySync.isSubscribed();
+        const usersubPublished = this.webexCrossClientService.isAnswerCallsStateActive();
+        (0, _wxAppDiagnosticLogging.logWxAppSessionReadiness)({
+          enableWxBetterTogether: true,
+          loginOption,
+          wxAppHooksApplied: true,
+          usersubPublished,
+          mercurySubscribed,
+          telephonyTaskType
+        });
+        const sessionInitReady = mercurySubscribed && usersubPublished;
+        if (sessionInitReady) {
+          this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_SUCCESS, {
+            loginOption,
+            enableWxBetterTogether: true
+          }, ['operational', 'behavioral']);
+        } else {
+          this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_FAILED, {
+            loginOption,
+            enableWxBetterTogether: true,
+            skipReason: !usersubPublished ? 'usersub_not_published' : 'mercury_not_subscribed'
+          }, ['operational', 'behavioral']);
+        }
       } else {
         await this.ensureWxAppDeviceRegistered();
         await this.publishAnswerOnWebexCrossClientState(false, {
@@ -1356,13 +1414,43 @@ class ContactCenter extends _webexCore.WebexPlugin {
         this.webexCrossClientService.teardown();
         this.wxAppTelephonyMercurySync.unsubscribe();
         await this.releaseWxAppMercuryResources();
+        (0, _wxAppDiagnosticLogging.logWxAppSessionReadiness)({
+          enableWxBetterTogether: false,
+          loginOption,
+          wxAppHooksApplied: true,
+          usersubPublished: false,
+          mercurySubscribed: false,
+          telephonyTaskType,
+          skipReason: 'flag_disabled'
+        });
+        this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_SKIPPED, {
+          loginOption,
+          enableWxBetterTogether: false,
+          skipReason: 'flag_disabled'
+        }, ['operational', 'behavioral']);
       }
     } catch (error) {
       _loggerProxy.default.error(`Failed to initialize wxApp post-station-login: ${error}`, {
         module: _constants.CC_FILE,
         method: _constants.METHODS.STATION_LOGIN
       });
-      if (this.isWxBetterTogetherEnabled()) {
+      if (flagEnabled) {
+        const sessionInitFailureReason = wxAppInitStage === 'mercury' ? 'mercury_subscribe_failed' : 'publish_failed';
+        this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_FAILED, {
+          loginOption,
+          enableWxBetterTogether: true,
+          skipReason: sessionInitFailureReason,
+          error: error instanceof Error ? error.toString() : String(error)
+        }, ['operational', 'behavioral']);
+        (0, _wxAppDiagnosticLogging.logWxAppSessionReadiness)({
+          enableWxBetterTogether: true,
+          loginOption,
+          wxAppHooksApplied: false,
+          usersubPublished: publishedEnable && this.webexCrossClientService.isAnswerCallsStateActive(),
+          mercurySubscribed: this.wxAppTelephonyMercurySync.isSubscribed(),
+          telephonyTaskType,
+          skipReason: sessionInitFailureReason
+        });
         if (publishedEnable) {
           await this.revertWxAppCrossClientPublish();
         } else {
@@ -1563,6 +1651,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
         module: _constants.CC_FILE,
         method: _constants.METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY
       });
+      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED, {
+        error: 'agentId unavailable'
+      }, ['operational', 'behavioral']);
       return;
     }
     try {
@@ -1575,6 +1666,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
         module: _constants.CC_FILE,
         method: _constants.METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY
       });
+      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED, {
+        error: error instanceof Error ? error.toString() : String(error)
+      }, ['operational', 'behavioral']);
       this.wxAppTelephonyMercurySync.unsubscribe();
       await this.releaseWxAppMercuryResources();
       throw error;
@@ -1589,10 +1683,18 @@ class ContactCenter extends _webexCore.WebexPlugin {
     }
     const userId = this.$webex.internal.device?.userId;
     if (!userId) {
+      if (enable && this.isWxBetterTogetherEnabled()) {
+        this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED, {
+          enableWxBetterTogether: true,
+          skipReason: 'user_id_unavailable',
+          error: 'User ID is unavailable for cross-client publish'
+        }, ['operational', 'behavioral']);
+      }
       return;
     }
     await this.webexCrossClientService.setManageWebexCallingInWxcc(enable, {
-      userId
+      userId,
+      trackPublishMetrics: true
     });
     if (enable) {
       this.clearWxAppFalsePublishRetryTimer();