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

package/src/services/WebexCrossClientService.ts

@@ -0,0 +1,212 @@
+import LoggerProxy from '../logger-proxy';
+import {METHODS} from '../constants';
+import {WebexSDK} from '../types';
+
+const WEBEX_CROSS_CLIENT_FILE = 'WebexCrossClientService';
+const DEFAULT_CROSS_CLIENT_STATE_TTL = 900;
+const EXPIRATION_OFFSET_MS = 60_000;
+/** Must match Agent Desktop usersub publish — Webex App reads `wxcc` cross-client state. */
+const DEFAULT_APP_NAME = 'wxcc';
+const REFRESH_RETRY_DELAY_MS = 30_000;
+const MAX_REFRESH_RETRIES = 3;
+
+type RefreshTimer = ReturnType<typeof setTimeout>;
+
+/**
+ * Publishes usersub cross-client state so Webex App suppresses native calling toasts (WXCC-6026).
+ */
+export default class WebexCrossClientService {
+  private webex: WebexSDK;
+  private refreshTimer?: RefreshTimer;
+  private refreshRetryTimer?: RefreshTimer;
+  private answerCallsState = false;
+  private appName = DEFAULT_APP_NAME;
+  /** Incremented on teardown/disable to ignore stale refresh timer callbacks. */
+  private refreshGeneration = 0;
+
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+  }
+
+  private extractDeviceIdFromUrl(url: string): string {
+    const match = url.match(/\/devices\/([^/?]+)/);
+
+    return match ? match[1] : '';
+  }
+
+  private getDeviceUrl(): string | undefined {
+    return this.webex.internal.device?.url;
+  }
+
+  private clearRefreshTimer(): void {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = undefined;
+    }
+
+    if (this.refreshRetryTimer) {
+      clearTimeout(this.refreshRetryTimer);
+      this.refreshRetryTimer = undefined;
+    }
+  }
+
+  private scheduleRefreshRetry(
+    userId: string,
+    ttl: number,
+    scheduledGeneration: number,
+    retryAttempt: number
+  ): void {
+    if (
+      retryAttempt >= MAX_REFRESH_RETRIES ||
+      scheduledGeneration !== this.refreshGeneration ||
+      !this.answerCallsState
+    ) {
+      return;
+    }
+
+    this.refreshRetryTimer = setTimeout(async () => {
+      if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
+        return;
+      }
+
+      try {
+        await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
+      } catch (error) {
+        LoggerProxy.error(`WebexCrossClientService refresh retry failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+        this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, retryAttempt + 1);
+      }
+    }, REFRESH_RETRY_DELAY_MS);
+  }
+
+  private startRefreshTimer(userId: string, ttl: number): void {
+    this.clearRefreshTimer();
+
+    if (!this.answerCallsState) {
+      return;
+    }
+
+    const refreshTime = ttl * 1000 - EXPIRATION_OFFSET_MS;
+    const scheduledGeneration = this.refreshGeneration;
+    this.refreshTimer = setTimeout(async () => {
+      if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
+        return;
+      }
+
+      try {
+        await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
+      } catch (error) {
+        LoggerProxy.error(`WebexCrossClientService refresh failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+        this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, 0);
+      }
+    }, refreshTime);
+  }
+
+  private publishCrossClientState(
+    users: string[],
+    ttl: number,
+    composition: Record<string, unknown>,
+    logContext: string
+  ): Promise<unknown> {
+    const body = {
+      users,
+      compositions: [
+        {
+          type: 'cross-client-state',
+          ttl,
+          composition,
+        },
+      ],
+    };
+
+    return this.webex
+      .request({
+        method: 'POST',
+        service: 'usersub',
+        resource: 'publish',
+        body,
+      })
+      .then((response: {body?: unknown}) => response?.body)
+      .catch((error: unknown) => {
+        LoggerProxy.error(`WebexCrossClientService.${logContext} failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+
+        return Promise.reject(error);
+      });
+  }
+
+  public async setManageWebexCallingInWxcc(
+    enable: boolean,
+    options?: {userId?: string; ttl?: number; appName?: string}
+  ): Promise<void> {
+    const operationGeneration = this.refreshGeneration;
+    const userId = options?.userId ?? this.webex.internal.device?.userId;
+    const ttl = options?.ttl ?? DEFAULT_CROSS_CLIENT_STATE_TTL;
+    const appName = options?.appName ?? DEFAULT_APP_NAME;
+    this.appName = appName;
+
+    if (!userId) {
+      throw new Error('User ID is unavailable for cross-client publish');
+    }
+
+    const deviceUrl = this.getDeviceUrl();
+    if (!deviceUrl) {
+      throw new Error('Device URL is unavailable for cross-client publish');
+    }
+
+    const composition = {
+      devices: [
+        {
+          deviceId: this.extractDeviceIdFromUrl(deviceUrl),
+          appName,
+          state: {
+            'answer-calls-on-wxcc': enable,
+          },
+        },
+      ],
+    };
+
+    await this.publishCrossClientState([userId], ttl, composition, 'setManageWebexCallingInWxcc');
+
+    if (operationGeneration !== this.refreshGeneration) {
+      return;
+    }
+
+    this.answerCallsState = enable;
+
+    if (enable) {
+      this.startRefreshTimer(userId, ttl);
+    } else {
+      this.refreshGeneration += 1;
+      this.clearRefreshTimer();
+    }
+
+    LoggerProxy.info(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
+      module: WEBEX_CROSS_CLIENT_FILE,
+      method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+      data: {
+        appName,
+        deviceId: this.extractDeviceIdFromUrl(deviceUrl),
+        ttl,
+      },
+    });
+  }
+
+  public teardown(): void {
+    this.refreshGeneration += 1;
+    this.clearRefreshTimer();
+    this.answerCallsState = false;
+  }
+
+  /** Whether usersub `answer-calls-on-wxcc: true` was successfully published this session. */
+  public isAnswerCallsStateActive(): boolean {
+    return this.answerCallsState;
+  }
+}

package/src/services/WxAppTelephonyMercurySync.ts

@@ -0,0 +1,115 @@
+import LoggerProxy from '../logger-proxy';
+import {METHODS} from '../constants';
+import {WebexSDK} from '../types';
+
+const WXAPP_TELEPHONY_MERCURY_SYNC_FILE = 'WxAppTelephonyMercurySync';
+
+export const TELEPHONY_CALL_MUTED = 'event:telephony_calls.muted';
+export const TELEPHONY_CALL_UNMUTED = 'event:telephony_calls.unmuted';
+
+export type UpdatedCallMuteStateEvent = {
+  data: {
+    actorId: string;
+    callId: string;
+    muted: boolean;
+  };
+};
+
+type MuteChangeHandler = (callId: string, muted: boolean) => void;
+
+/**
+ * Subscribes to Mercury telephony mute/unmute events for wxApp thick-client sync (AD parity).
+ */
+export default class WxAppTelephonyMercurySync {
+  private webex: WebexSDK;
+  private subscribedAgentId?: string;
+  private muteChangeHandler?: MuteChangeHandler;
+  private boundMuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
+  private boundUnmuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
+
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+  }
+
+  private decodeBase64(value: string): string {
+    try {
+      return atob(value);
+    } catch {
+      return value;
+    }
+  }
+
+  private handleMuteStateEvent = (agentId: string, event: UpdatedCallMuteStateEvent): void => {
+    const {actorId, callId, muted} = event?.data ?? {};
+    if (!actorId || !callId || muted === undefined) {
+      return;
+    }
+
+    const decodedActorId = this.decodeBase64(actorId);
+    const decodedCallId = this.decodeBase64(callId);
+
+    if (!decodedActorId.endsWith(agentId)) {
+      return;
+    }
+
+    LoggerProxy.info('WxApp telephony mute state sync received', {
+      module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+      method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+      data: {muted},
+    });
+
+    this.muteChangeHandler?.(decodedCallId, muted);
+  };
+
+  public subscribe(agentId: string, onMuteChange: MuteChangeHandler): void {
+    this.unsubscribe();
+
+    const mercury = this.webex.internal.mercury;
+    if (!mercury) {
+      LoggerProxy.error('Mercury is unavailable for wxApp mute sync', {
+        module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+        method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+      });
+
+      return;
+    }
+
+    this.subscribedAgentId = agentId;
+    this.muteChangeHandler = onMuteChange;
+
+    this.boundMuteHandler = (event: UpdatedCallMuteStateEvent) => {
+      this.handleMuteStateEvent(agentId, event);
+    };
+    this.boundUnmuteHandler = (event: UpdatedCallMuteStateEvent) => {
+      this.handleMuteStateEvent(agentId, event);
+    };
+
+    mercury.on(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
+    mercury.on(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
+
+    LoggerProxy.info('Subscribed to wxApp telephony Mercury mute sync', {
+      module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+      method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+    });
+  }
+
+  public unsubscribe(): void {
+    const mercury = this.webex.internal.mercury;
+
+    if (mercury && this.boundMuteHandler) {
+      mercury.off(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
+    }
+    if (mercury && this.boundUnmuteHandler) {
+      mercury.off(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
+    }
+
+    this.subscribedAgentId = undefined;
+    this.muteChangeHandler = undefined;
+    this.boundMuteHandler = undefined;
+    this.boundUnmuteHandler = undefined;
+  }
+
+  public isSubscribed(): boolean {
+    return Boolean(this.subscribedAgentId && this.muteChangeHandler);
+  }
+}

package/src/services/agent/ai-docs/AGENTS.md

@@ -0,0 +1,240 @@
+# Agent Service - AI Agent Guide
+
+> **Legacy/reference-only.** Canonical SDD: [`agent-spec.md`](agent-spec.md). Use the package [manifest](../../../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
+
+> **Purpose**: Manage agent lifecycle including login, logout, state changes, and buddy agent queries.
+
+---
+
+## Quick Start
+
+```typescript
+const cc = webex.cc;
+
+// Register and login
+const profile = await cc.register();
+await cc.stationLogin({
+  teamId: profile.teams[0].teamId,
+  loginOption: 'BROWSER',
+});
+
+// Set state to Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Get available agents for transfer
+const buddies = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+```
+
+---
+
+## Key Capabilities
+
+- **Station Login**: Login with browser (WebRTC), extension, or dial number
+- **Station Logout**: Logout from current station with reason
+- **State Management**: Toggle between Available/Idle states with aux codes
+- **Buddy Agents**: Query available agents for consult/transfer
+- **Silent Relogin**: Automatic re-authentication on reconnection
+
+---
+
+## API Reference
+
+### Login Options
+
+| Option | Description | Requires dialNumber |
+|--------|-------------|---------------------|
+| `BROWSER` | WebRTC softphone in browser | No |
+| `EXTENSION` | Desk phone extension | Yes |
+| `AGENT_DN` | Direct dial number | Yes |
+
+### Methods
+
+#### `cc.stationLogin(params)`
+
+Login agent to a station.
+
+**Parameters**:
+- `teamId` (string): Team to login to
+- `loginOption` ('BROWSER' | 'EXTENSION' | 'AGENT_DN'): Device type
+- `dialNumber` (string, optional): Required for EXTENSION/AGENT_DN
+
+**Returns**: `Promise<StationLoginResponse>`
+
+**Example**:
+```typescript
+// Browser login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'BROWSER',
+});
+
+// Extension login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'EXTENSION',
+  dialNumber: '1234',
+});
+```
+
+---
+
+#### `cc.stationLogout(params)`
+
+Logout agent from station.
+
+**Parameters**:
+- `logoutReason` (string, optional): 'User requested logout' | 'Inactivity Logout' | 'User requested agent profile update'
+
+**Returns**: `Promise<StationLogoutResponse>`
+
+**Example**:
+```typescript
+await cc.stationLogout({
+  logoutReason: 'User requested logout',
+});
+```
+
+---
+
+#### `cc.setAgentState(params)`
+
+Change agent state (Available/Idle).
+
+**Parameters**:
+- `state` ('Available' | 'Idle'): New state
+- `auxCodeId` (string): Auxiliary code ID
+- `lastStateChangeReason` (string, optional): Reason for change
+- `agentId` (string, optional): Agent ID (defaults to current agent)
+
+**Returns**: `Promise<SetStateResponse>`
+
+**Example**:
+```typescript
+// Go Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Go to Idle with specific code
+await cc.setAgentState({
+  state: 'Idle',
+  auxCodeId: 'break-code-123',
+  lastStateChangeReason: 'Coffee break',
+});
+```
+
+---
+
+#### `cc.getBuddyAgents(params)`
+
+Get list of agents for consult/transfer.
+
+**Parameters**:
+- `state` (string, optional): Filter by state ('Available', 'Idle')
+- `mediaType` (string): Media type filter ('telephony', 'chat', 'social', 'email')  
+**Returns**: `Promise<BuddyAgentsResponse>`
+
+**Example**:
+```typescript
+const response = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+
+response.data.agentList.forEach(agent => {
+  console.log(`${agent.agentName} (${agent.state})`);
+});
+```
+
+---
+
+## Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `agent:stationLoginSuccess` | `StationLoginSuccessResponse` | Login succeeded |
+| `agent:stationLoginFailed` | Error | Login failed |
+| `agent:logoutSuccess` | `LogoutSuccess` | Logout succeeded |
+| `agent:logoutFailed` | Error | Logout failed |
+| `agent:stateChange` | `StateChangeSuccess` | State changed (any source) |
+| `agent:stateChangeSuccess` | `StateChangeSuccess` | State change succeeded |
+| `agent:stateChangeFailed` | Error | State change failed |
+| `agent:multiLogin` | Object | Multi-login detected |
+| `agent:reloginSuccess` | `ReloginSuccess` | Silent relogin succeeded |
+| `agent:dnRegistered` | Object | DN registration complete |
+
+### Event Usage
+
+```typescript
+cc.on('agent:stateChange', (event) => {
+  console.log(`State: ${event.subStatus}, AuxCode: ${event.auxCodeId}`);
+});
+
+cc.on('agent:multiLogin', (event) => {
+  console.warn('Another session detected');
+});
+```
+
+---
+
+## Agent States
+
+The `AgentState` type (`'Available' | 'Idle' | 'RONA' | string`) is extensible -- the `string` union member allows backend-defined states beyond the known values listed below.
+
+| State | SubStatus | Description |
+|-------|-----------|-------------|
+| LoggedIn | Available | Ready to receive tasks |
+| LoggedIn | Idle | On break or not ready (uses aux code for sub-reason) |
+| RONA | - | Rang but no answer; agent failed to accept offered task |
+| LoggedOut | - | Not logged in |
+| LoggedIn | *(custom)* | Additional org-specific states defined via aux codes |
+
+> **Note**: `AgentState` is a union with `string`, so consumers should handle unknown state values gracefully rather than exhaustively matching only the known literals.
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  await cc.stationLogin(params);
+} catch (error) {
+  console.error('Login failed:', error.message);
+  // Access error details
+  if (error.data) {
+    console.error('Field:', error.data.fieldName);
+    console.error('Message:', error.data.message);
+  }
+}
+```
+
+### Common Error Reasons
+
+| Reason | Description |
+|--------|-------------|
+| `DUPLICATE_LOCATION` | Extension/DN already in use |
+| `INVALID_DIAL_NUMBER` | Invalid phone number format |
+| `AGENT_NOT_FOUND` | Agent doesn't exist (silent relogin) |
+
+---
+
+## Dependencies
+
+- Requires `cc.register()` to be called first
+- Agent profile must be fetched before login
+- WebRTC (BROWSER option) requires mercury connection
+
+---
+
+## Related
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive
+- [`cc.ts`](../../../cc.ts) - Main plugin implementation
+- [`types.ts`](../types.ts) - Type definitions