@webex/contact-center 3.12.0-next.72 → 3.12.0-next.74

package/ai-docs/templates/new-service/04-test-generation.md

@@ -0,0 +1,205 @@
+# New Service - Test Generation
+
+> **Purpose**: Create unit tests for the new service.
+
+---
+
+## Test File Location
+
+Create: `test/unit/spec/services/ServiceName.ts`
+
+---
+
+## Test File Template
+
+```typescript
+import 'jsdom-global/register';
+import MockWebex from '@webex/test-helper-mock-webex';
+import ServiceName, {
+  ServiceListResponse,
+  ServiceSearchParams,
+} from '../../../../src/services/ServiceName';
+
+jest.mock('../../../../src/logger-proxy', () => ({
+  __esModule: true,
+  default: {
+    log: jest.fn(),
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    trace: jest.fn(),
+    initialize: jest.fn(),
+  },
+}));
+
+describe('ServiceName', () => {
+  let webex: any;
+  let service: ServiceName;
+  
+  // Mock data
+  const mockOrgId = 'mock-org-id';
+  const mockResponse: ServiceListResponse = {
+    data: [
+      { id: 'item-1', name: 'Item 1' },
+      { id: 'item-2', name: 'Item 2' },
+    ],
+    meta: {
+      page: 0,
+      pageSize: 50,
+      totalPages: 1,
+      totalRecords: 2,
+    },
+  };
+
+  beforeEach(() => {
+    webex = MockWebex({
+      logger: {
+        log: jest.fn(),
+        error: jest.fn(),
+        info: jest.fn(),
+      },
+      credentials: {
+        getOrgId: jest.fn(() => mockOrgId),
+      },
+      request: jest.fn(),
+    });
+
+    service = new ServiceName(webex);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getItems', () => {
+    it('should fetch items successfully', async () => {
+      // Arrange
+      webex.request.mockResolvedValue({ body: mockResponse });
+
+      // Act
+      const result = await service.getItems();
+
+      // Assert
+      expect(result).toEqual(mockResponse);
+      expect(webex.request).toHaveBeenCalledWith({
+        method: 'GET',
+        uri: expect.stringContaining(mockOrgId),
+      });
+    });
+
+    it('should apply pagination parameters', async () => {
+      // Arrange
+      webex.request.mockResolvedValue({ body: mockResponse });
+      const params: ServiceSearchParams = { page: 1, pageSize: 25 };
+
+      // Act
+      await service.getItems(params);
+
+      // Assert
+      expect(webex.request).toHaveBeenCalledWith({
+        method: 'GET',
+        uri: expect.stringContaining('page=1'),
+      });
+      expect(webex.request).toHaveBeenCalledWith({
+        method: 'GET',
+        uri: expect.stringContaining('pageSize=25'),
+      });
+    });
+
+    it('should apply search parameter', async () => {
+      // Arrange
+      webex.request.mockResolvedValue({ body: mockResponse });
+      const params: ServiceSearchParams = { search: 'test' };
+
+      // Act
+      await service.getItems(params);
+
+      // Assert
+      expect(webex.request).toHaveBeenCalledWith({
+        method: 'GET',
+        uri: expect.stringContaining('search=test'),
+      });
+    });
+
+    it('should throw error on API failure', async () => {
+      // Arrange
+      const mockError = new Error('API Error');
+      webex.request.mockRejectedValue(mockError);
+
+      // Act & Assert
+      await expect(service.getItems()).rejects.toThrow('API Error');
+    });
+  });
+
+  describe('getItemById', () => {
+    it('should fetch single item successfully', async () => {
+      // Arrange
+      const mockItem = { id: 'item-1', name: 'Item 1' };
+      webex.request.mockResolvedValue({ body: mockItem });
+
+      // Act
+      const result = await service.getItemById('item-1');
+
+      // Assert
+      expect(result).toEqual(mockItem);
+      expect(webex.request).toHaveBeenCalledWith({
+        method: 'GET',
+        uri: expect.stringContaining('item-1'),
+      });
+    });
+
+    it('should throw error if item not found', async () => {
+      // Arrange
+      const mockError = new Error('Not Found');
+      webex.request.mockRejectedValue(mockError);
+
+      // Act & Assert
+      await expect(service.getItemById('invalid-id')).rejects.toThrow('Not Found');
+    });
+  });
+});
+```
+
+---
+
+## Test Integration with cc.ts
+
+Add to `test/unit/spec/cc.ts`:
+
+```typescript
+describe('cc.serviceName', () => {
+  it('should initialize service on ready', () => {
+    expect(webex.cc.serviceName).toBeDefined();
+  });
+
+  it('should fetch items through service', async () => {
+    // Mock the service method
+    const mockResponse = { data: [], meta: {} };
+    jest.spyOn(webex.cc.serviceName, 'getItems').mockResolvedValue(mockResponse);
+
+    // Act
+    const result = await webex.cc.serviceName.getItems();
+
+    // Assert
+    expect(result).toEqual(mockResponse);
+  });
+});
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run specific test file
+yarn workspace @webex/contact-center test -- --testPathPattern=ServiceName
+
+# Run with coverage
+yarn workspace @webex/contact-center test -- --coverage --testPathPattern=ServiceName
+```
+
+---
+
+## Next Step
+
+Proceed to: [`05-validation.md`](05-validation.md)

package/ai-docs/templates/new-service/05-validation.md

@@ -0,0 +1,145 @@
+# New Service - Validation Checklist
+
+> **Purpose**: Final quality check before completing service creation.
+
+---
+
+## Code Quality Checklist
+
+### Service Class
+- [ ] File created at correct location (based on placement from pre-questions Q3)
+- [ ] Class has proper JSDoc with `@public` tag
+- [ ] Methods have JSDoc with `@param`, `@returns`, `@example`
+- [ ] Uses `LoggerProxy` for all logging (no `console.log`)
+- [ ] Error handling uses `getErrorDetails` pattern (logs and re-throws)
+- [ ] Module name constant defined (`SERVICE_FILE`)
+- [ ] Method name constants defined (`METHODS`)
+
+### Types & Constants
+- [ ] Types placed in the correct location:
+  - Folder-based service: service folder's `types.ts`
+  - Single-file service: root `src/types.ts`
+  - Sub-module: parent service's `types.ts`
+- [ ] Constants: no duplicates — every constant was searched across the hierarchy before adding:
+  - `src/constants.ts` (SDK-wide: file names, method names, global settings)
+  - `src/services/constants.ts` (shared: API gateways, auth, network)
+  - `src/metrics/constants.ts` (all metric event names)
+  - `src/services/config/constants.ts` (endpoint maps, pagination, agent states)
+  - `src/services/{ServiceName}/constants.ts` (service-specific only)
+- [ ] Constants placed at the correct level (not duplicated at a lower level when shared exists)
+- [ ] New `constants.ts` file created ONLY if service is folder-based AND no existing file AND constants are service-specific
+- [ ] All public types have JSDoc
+- [ ] Response types match actual API response
+- [ ] Parameter types define all optional/required fields
+
+### Metrics
+- [ ] `metricsManager.timeEvent` called at method entry with success + failure event names
+- [ ] `metricsManager.trackEvent` called on success path
+- [ ] `metricsManager.trackEvent` called on failure path (in catch block)
+- [ ] Metric event names added to `src/metrics/constants.ts` (`METRIC_EVENT_NAMES`)
+
+### Integration
+- [ ] Service initialized at the correct integration point:
+  - Folder-based / single-file: in `cc.ts` or `Services` singleton (depends on AQM vs non-AQM)
+  - Sub-module: instantiated by parent service
+- [ ] Types re-exported from `src/types.ts` (if public)
+
+### Tests
+- [ ] Test file created mirroring source path under `test/unit/spec/`
+- [ ] LoggerProxy mocked
+- [ ] Success cases tested
+- [ ] Error cases tested
+- [ ] Metrics tracking verified (timeEvent and trackEvent calls asserted)
+- [ ] Tests pass: `yarn workspace @webex/contact-center test:unit`
+
+---
+
+## Pattern Compliance
+
+### LoggerProxy Usage
+```typescript
+// ✅ Correct
+LoggerProxy.info('Starting operation', {
+  module: SERVICE_FILE,
+  method: METHODS.GET_ITEMS,
+});
+
+// ❌ Wrong
+console.log('Starting operation');
+```
+
+### Error Handling
+```typescript
+// ✅ Correct
+catch (error) {
+  LoggerProxy.error(`Failed: ${error}`, {
+    module: SERVICE_FILE,
+    method: METHODS.GET_ITEMS,
+    error,
+  });
+  throw error;
+}
+
+// ❌ Wrong - swallowing error
+catch (error) {
+  console.error(error);
+}
+```
+
+### Type Exports
+```typescript
+// ✅ Correct - in src/types.ts
+export type {
+  ServiceItem,
+  ServiceSearchParams,
+  ServiceListResponse,
+} from './services/ServiceName';
+```
+
+---
+
+## Build & Test Verification
+
+```bash
+# Lint
+yarn workspace @webex/contact-center test:styles
+
+# Test unit tests
+yarn workspace @webex/contact-center test:unit
+
+# Build
+yarn workspace @webex/contact-center build:src
+```
+
+All should pass without errors.
+
+---
+
+## Documentation
+
+### Update Root AGENTS.md?
+If this is a significant new service, update the root [`AGENTS.md`](../../../AGENTS.md):
+- [ ] Added new service to the [Service Routing Table](../../../AGENTS.md#service-routing-table)
+- [ ] Added to repository structure tree
+- [ ] Added usage example if applicable
+
+### Create Service ai-docs?
+For complex services, create service-level documentation (use [`create-agents-md.md`](../documentation/create-agents-md.md) and [`create-architecture-md.md`](../documentation/create-architecture-md.md) templates):
+- [ ] `src/services/ServiceName/ai-docs/AGENTS.md` — usage guide, API reference
+- [ ] `src/services/ServiceName/ai-docs/ARCHITECTURE.md` — technical deep-dive, data flow
+
+---
+
+## Final Review
+
+Ask yourself:
+1. Can another developer understand this service by reading the JSDoc?
+2. Are all error paths properly handled and logged?
+3. Do tests cover the main use cases?
+4. Is the API surface clean and consistent with other services?
+
+---
+
+## Complete!
+
+Service creation is complete when all checkboxes are checked.

package/dist/cc.js

@@ -318,7 +318,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
       this.metricsManager = _MetricsManager.default.getInstance({
         webex: this.$webex
       });
-      this.taskManager = _TaskManager.default.getTaskManager(this.apiAIAssistant, this.services.contact, this.webCallingService, this.services.webSocketManager);
+      this.taskManager = _TaskManager.default.getTaskManager(this.apiAIAssistant, this.services.contact, this.webCallingService, this.services.webSocketManager, this.services.rtdWebSocketManager);
       this.incomingTaskListener();
 
       // Initialize API instances
@@ -350,6 +350,16 @@ class ContactCenter extends _webexCore.WebexPlugin {
     this.trigger(_types4.TASK_EVENTS.TASK_HYDRATE, task);
   };
 
+  /**
+   * Handles multi-login hydrate events for SDK instances without Mobius registration
+   * @private
+   * @param {ITask} task The task object associated with the multi-login hydrate
+   */
+  handleTaskMultiLoginHydrate = task => {
+    // @ts-ignore
+    this.trigger(_types4.TASK_EVENTS.TASK_MULTI_LOGIN_HYDRATE, task);
+  };
+
   /**
    * Handles task merged events when tasks are combined eg: EPDN merge/transfer
    * @private
@@ -369,18 +379,8 @@ class ContactCenter extends _webexCore.WebexPlugin {
     // @ts-ignore
     this.trigger(_types4.TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, task);
   };
-
-  /**
-   * Handles multi-login hydrate events emitted when browser login accepts an incoming call.
-   * @private
-   * @param {ITask} task The task object associated with multi-login hydrate
-   */
-  handleTaskMultiLoginHydrate = task => {
-    // @ts-ignore
-    this.trigger(_types4.TASK_EVENTS.TASK_MULTI_LOGIN_HYDRATE, task);
-  };
-  handleRTDWebsocketMessage = payload => {
-    this.taskManager.handleRealtimeWebsocketEvent(payload);
+  handleRTDWebsocketMessage = event => {
+    this.taskManager.handleRealtimeWebsocketEvent(event);
   };
 
   /**
@@ -391,8 +391,8 @@ class ContactCenter extends _webexCore.WebexPlugin {
   incomingTaskListener() {
     this.taskManager.on(_types4.TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
     this.taskManager.on(_types4.TASK_EVENTS.TASK_HYDRATE, this.handleTaskHydrate);
-    this.taskManager.on(_types4.TASK_EVENTS.TASK_MERGED, this.handleTaskMerged);
     this.taskManager.on(_types4.TASK_EVENTS.TASK_MULTI_LOGIN_HYDRATE, this.handleTaskMultiLoginHydrate);
+    this.taskManager.on(_types4.TASK_EVENTS.TASK_MERGED, this.handleTaskMerged);
     this.taskManager.on(_types4.TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, this.handleCampaignPreviewReservation);
   }
 
@@ -525,6 +525,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
       if (!this.services.webSocketManager.isSocketClosed) {
         this.services.webSocketManager.close(false, 'Unregistering the SDK');
       }
+      if (this.services.rtdWebSocketManager && !this.services.rtdWebSocketManager.isSocketClosed) {
+        this.services.rtdWebSocketManager.close(false, 'Unregistering the SDK');
+      }
       if (this.services.rtdWebSocketManager && !this.services.rtdWebSocketManager.isSocketClosed) {
         this.services.rtdWebSocketManager.close(false, 'Unregistering the RTD websocket');
       }
@@ -622,25 +625,6 @@ class ContactCenter extends _webexCore.WebexPlugin {
     }
   }
 
-  /**
-   * Checks whether WebRTC registration should be skipped by config.
-   * @returns {boolean}
-   * @private
-   */
-  isWebRTCRegistrationDisabled() {
-    return this.$config?.disableWebRTCRegistration === true;
-  }
-
-  /**
-   * Validates contact-center plugin configuration before service initialization
-   * @private
-   */
-  validatePluginConfig() {
-    if (this.$config?.disableWebRTCRegistration === true && this.$config?.allowMultiLogin === false) {
-      throw new Error('Invalid Contact Center configuration: disableWebRTCRegistration cannot be true when allowMultiLogin is false. Enable allowMultiLogin or allow WebRTC registration so an SDK instance can receive Mobius/WebRTC task events.');
-    }
-  }
-
   /**
    * Connects to the websocket and fetches the agent profile
    * @returns {Promise<Profile>} Agent profile information
@@ -664,18 +648,30 @@ class ContactCenter extends _webexCore.WebexPlugin {
         module: _constants.CC_FILE,
         method: _constants.METHODS.CONNECT_WEBSOCKET
       });
-
+      const configFlags = {
+        isEndTaskEnabled: this.agentConfig.isEndTaskEnabled,
+        isEndConsultEnabled: this.agentConfig.isEndConsultEnabled,
+        webRtcEnabled: this.agentConfig.webRtcEnabled,
+        autoWrapup: this.agentConfig.wrapUpData?.wrapUpProps?.autoWrapup ?? false,
+        aiFeature: this.agentConfig.aiFeature
+      };
+      this.taskManager.setConfigFlags(configFlags);
       // TODO: Make profile a singleton to make it available throughout app/sdk so we dont need to inject info everywhere
       this.taskManager.setWrapupData(this.agentConfig.wrapUpData);
       this.taskManager.setAgentId(this.agentConfig.agentId);
       this.taskManager.setWebRtcEnabled(this.agentConfig.webRtcEnabled);
       this.apiAIAssistant.setAIFeatureFlags(this.agentConfig.aiFeature);
-      if (this.agentConfig.aiFeature?.realtimeTranscripts?.enable) {
-        _loggerProxy.default.log('Connecting to RTD websocket', {
+
+      /**
+       * RTD websocket currently supports realtime transcripts and suggested responses.
+       * Extend this condition when additional AI RTD features are introduced.
+       */
+      if (this.agentConfig.aiFeature?.realtimeTranscripts?.enable || this.agentConfig.aiFeature?.suggestedResponses?.enable) {
+        _loggerProxy.default.info('Connecting to RTD websocket', {
           module: _constants.CC_FILE,
           method: _constants.METHODS.CONNECT_WEBSOCKET
         });
-        await this.services.rtdWebSocketManager.initWebSocket({
+        this.services.rtdWebSocketManager.initWebSocket({
           body: this.getConnectionConfig(),
           resource: _constants3.RTD_SUBSCRIBE_API
         }).then(() => {
@@ -685,7 +681,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
           });
           this.services.rtdWebSocketManager.on('message', this.handleRTDWebsocketMessage);
         }).catch(error => {
-          _loggerProxy.default.error(`Error during RTD websocket setup: ${error}`, {
+          _loggerProxy.default.error(`Error connecting to RTD websocket ${error}`, {
             module: _constants.CC_FILE,
             method: _constants.METHODS.CONNECT_WEBSOCKET
           });
@@ -1123,6 +1119,25 @@ class ContactCenter extends _webexCore.WebexPlugin {
     }
   };
 
+  /**
+   * Checks whether Mobius/WebRTC registration should be skipped by config
+   * @returns {boolean} True when browser WebRTC registration is disabled
+   * @private
+   */
+  isWebRTCRegistrationDisabled() {
+    return this.$config?.disableWebRTCRegistration === true;
+  }
+
+  /**
+   * Validates contact-center plugin configuration before service initialization
+   * @private
+   */
+  validatePluginConfig() {
+    if (this.$config?.disableWebRTCRegistration === true && this.$config?.allowMultiLogin === false) {
+      throw new Error('Invalid Contact Center configuration: disableWebRTCRegistration cannot be true when allowMultiLogin is false. Enable allowMultiLogin or allow WebRTC registration so an SDK instance can receive Mobius/WebRTC task events.');
+    }
+  }
+
   /**
    * Initializes event listeners for the Contact Center service
    * Sets up handlers for connection state changes and other core events