@webex/contact-center 3.12.0-next.9 → 3.12.0-task-refactor.2

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

@@ -85,7 +85,6 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  *   - `task:established` - Task/call has been connected
  *   - `task:ended` - Task/call has ended
  *   - `task:error` - An error occurred during task handling
- *   - `task:campaignPreviewReservation` - Campaign preview contact offered to agent
  *
  * @public
  *
@@ -318,7 +317,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
@@ -360,19 +359,6 @@ class ContactCenter extends _webexCore.WebexPlugin {
     this.trigger(_types4.TASK_EVENTS.TASK_MERGED, task);
   };
 
-  /**
-   * Handles campaign preview reservation events when a contact is offered to the agent
-   * @private
-   * @param {ITask} task The campaign reservation task
-   */
-  handleCampaignPreviewReservation = task => {
-    // @ts-ignore
-    this.trigger(_types4.TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, task);
-  };
-  handleRTDWebsocketMessage = payload => {
-    this.taskManager.handleRealtimeWebsocketEvent(payload);
-  };
-
   /**
    * Sets up event listeners for incoming tasks and task hydration
    * Subscribes to task events from the task manager
@@ -382,7 +368,6 @@ class ContactCenter extends _webexCore.WebexPlugin {
     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_CAMPAIGN_PREVIEW_RESERVATION, this.handleCampaignPreviewReservation);
   }
 
   /**
@@ -491,7 +476,6 @@ class ContactCenter extends _webexCore.WebexPlugin {
       this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.WEBSOCKET_DEREGISTER_SUCCESS, _constants4.METRIC_EVENT_NAMES.WEBSOCKET_DEREGISTER_FAIL]);
       this.taskManager.off(_types4.TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
       this.taskManager.off(_types4.TASK_EVENTS.TASK_HYDRATE, this.handleTaskHydrate);
-      this.taskManager.off(_types4.TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, this.handleCampaignPreviewReservation);
       this.taskManager.unregisterIncomingCallEvent();
       this.services.webSocketManager.off('message', this.handleWebsocketMessage);
       this.services.rtdWebSocketManager.off('message', this.handleRTDWebsocketMessage);
@@ -513,7 +497,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
         this.services.webSocketManager.close(false, 'Unregistering the SDK');
       }
       if (this.services.rtdWebSocketManager && !this.services.rtdWebSocketManager.isSocketClosed) {
-        this.services.rtdWebSocketManager.close(false, 'Unregistering the RTD websocket');
+        this.services.rtdWebSocketManager.close(false, 'Unregistering the SDK');
       }
 
       // Clear any cached agent configuration
@@ -621,62 +605,76 @@ class ContactCenter extends _webexCore.WebexPlugin {
       method: _constants.METHODS.CONNECT_WEBSOCKET
     });
     try {
-      const data = await this.services.webSocketManager.initWebSocket({
+      return this.services.webSocketManager.initWebSocket({
         body: this.getConnectionConfig(),
         resource: _constants3.SUBSCRIBE_API
-      });
-      const agentId = data.agentId;
-      const orgId = this.$webex.credentials.getOrgId();
-      this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
-      _loggerProxy.default.log(`Agent config is fetched successfully`, {
-        module: _constants.CC_FILE,
-        method: _constants.METHODS.CONNECT_WEBSOCKET
-      });
-
-      // 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.info('Connecting to RTD websocket', {
+      }).then(async data => {
+        const agentId = data.agentId;
+        const orgId = this.$webex.credentials.getOrgId();
+        this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
+        _loggerProxy.default.log(`Agent config is fetched successfully`, {
           module: _constants.CC_FILE,
           method: _constants.METHODS.CONNECT_WEBSOCKET
         });
-        await this.services.rtdWebSocketManager.initWebSocket({
-          body: this.getConnectionConfig(),
-          resource: _constants3.RTD_SUBSCRIBE_API
-        }).then(() => {
-          _loggerProxy.default.log('RTD websocket connected successfully', {
-            module: _constants.CC_FILE,
-            method: _constants.METHODS.CONNECT_WEBSOCKET
-          });
-          this.services.rtdWebSocketManager.on('message', this.handleRTDWebsocketMessage);
-        }).catch(error => {
-          _loggerProxy.default.error(`Error during RTD websocket setup: ${error}`, {
+        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);
+        /**
+         * TODO: We need to re-check this condition if this websocket is only for realtime transcripts
+         * or other AI Assistant features will also use the same.
+         * If the latter is true, we need to update this condition.
+         */
+        if (this.agentConfig.aiFeature?.realtimeTranscripts?.enable) {
+          _loggerProxy.default.info('Connecting to RTD websocket', {
             module: _constants.CC_FILE,
             method: _constants.METHODS.CONNECT_WEBSOCKET
           });
-        });
-      }
-      if (this.agentConfig.webRtcEnabled && this.agentConfig.loginVoiceOptions.includes(_types.LoginOption.BROWSER)) {
-        try {
-          await this.$webex.internal.mercury.connect();
-          _loggerProxy.default.log('Authentication: webex.internal.mercury.connect successful', {
-            module: _constants.CC_FILE,
-            method: _constants.METHODS.CONNECT_WEBSOCKET
+          this.services.rtdWebSocketManager.initWebSocket({
+            body: this.getConnectionConfig(),
+            resource: _constants3.RTD_SUBSCRIBE_API
+          }).then(() => {
+            _loggerProxy.default.log('RTD websocket connected successfully', {
+              module: _constants.CC_FILE,
+              method: _constants.METHODS.CONNECT_WEBSOCKET
+            });
+            this.services.rtdWebSocketManager.on('message', this.handleRTDWebsocketMessage);
+          }).catch(error => {
+            _loggerProxy.default.error(`Error connecting to RTD websocket ${error}`, {
+              module: _constants.CC_FILE,
+              method: _constants.METHODS.CONNECT_WEBSOCKET
+            });
           });
-        } catch (error) {
-          _loggerProxy.default.error(`Error occurred during mercury.connect() ${error}`, {
-            module: _constants.CC_FILE,
-            method: _constants.METHODS.CONNECT_WEBSOCKET
+        }
+        if (this.agentConfig.webRtcEnabled && this.agentConfig.loginVoiceOptions.includes(_types.LoginOption.BROWSER)) {
+          this.$webex.internal.mercury.connect().then(() => {
+            _loggerProxy.default.log('Authentication: webex.internal.mercury.connect successful', {
+              module: _constants.CC_FILE,
+              method: _constants.METHODS.CONNECT_WEBSOCKET
+            });
+          }).catch(error => {
+            _loggerProxy.default.error(`Error occurred during mercury.connect() ${error}`, {
+              module: _constants.CC_FILE,
+              method: _constants.METHODS.CONNECT_WEBSOCKET
+            });
           });
         }
-      }
-      if (this.$config && this.$config.allowAutomatedRelogin) {
-        await this.silentRelogin();
-      }
-      return this.agentConfig;
+        if (this.$config && this.$config.allowAutomatedRelogin) {
+          await this.silentRelogin();
+        }
+        return this.agentConfig;
+      }).catch(error => {
+        throw error;
+      });
     } catch (error) {
       _loggerProxy.default.error(`Error during register: ${error}`, {
         module: _constants.CC_FILE,
@@ -721,8 +719,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
     });
     try {
       this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, _constants4.METRIC_EVENT_NAMES.STATION_LOGIN_FAILED]);
-      const dialPlanEntries = this.agentConfig?.dialPlan?.dialPlanEntity ?? [];
-      if (data.loginOption === _types.LoginOption.AGENT_DN && !(0, _Utils.isValidDialNumber)(data.dialNumber, dialPlanEntries)) {
+      if (data.loginOption === _types.LoginOption.AGENT_DN && !(0, _Utils.isValidDialNumber)(data.dialNumber)) {
         const error = new Error('INVALID_DIAL_NUMBER');
         // @ts-ignore - adding custom key to the error object
         error.details = {
@@ -1070,6 +1067,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
         break;
     }
   };
+  handleRTDWebsocketMessage = event => {
+    this.taskManager.handleRealtimeWebsocketEvent(event);
+  };
 
   /**
    * Initializes event listeners for the Contact Center service
@@ -1386,64 +1386,6 @@ class ContactCenter extends _webexCore.WebexPlugin {
     }
   }
 
-  /**
-   * Accepts a campaign preview contact, initiating the outbound call.
-   *
-   * When a campaign manager reserves a contact for an agent, the agent receives an
-   * `AgentOfferCampaignReservation` event. The agent can then accept the preview contact
-   * to initiate the outbound call.
-   *
-   * @param {PreviewContactPayload} payload - The preview contact payload containing interactionId and campaignId (campaign name, not UUID).
-   * @returns {Promise<TaskResponse>} Promise resolving with agent contact on success.
-   * @throws {Error} If the operation fails (network error, customer unavailable, etc.)
-   *
-   * @example
-   * ```typescript
-   * webex.cc.on('task:campaignPreviewReservation', async (task) => {
-   *   const { interactionId } = task.data;
-   *   // campaignId is the campaign name (e.g. "MyCampaign"), not a UUID
-   *   const campaignId = task.data.interaction.callProcessingDetails.campaignId;
-   *
-   *   const result = await webex.cc.acceptPreviewContact({ interactionId, campaignId });
-   * });
-   * ```
-   */
-  async acceptPreviewContact(payload) {
-    _loggerProxy.default.info('Accepting campaign preview contact', {
-      module: _constants.CC_FILE,
-      method: _constants.METHODS.ACCEPT_PREVIEW_CONTACT
-    });
-    try {
-      this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.CAMPAIGN_PREVIEW_ACCEPT_SUCCESS, _constants4.METRIC_EVENT_NAMES.CAMPAIGN_PREVIEW_ACCEPT_FAILED]);
-      const result = await this.services.dialer.acceptPreviewContact({
-        data: payload
-      });
-      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.CAMPAIGN_PREVIEW_ACCEPT_SUCCESS, {
-        ..._MetricsManager.default.getCommonTrackingFieldForAQMResponse(result),
-        interactionId: payload.interactionId,
-        campaignId: payload.campaignId
-      }, ['behavioral', 'business', 'operational']);
-      _loggerProxy.default.log('Campaign preview contact accepted successfully', {
-        module: _constants.CC_FILE,
-        method: _constants.METHODS.ACCEPT_PREVIEW_CONTACT,
-        trackingId: result.trackingId,
-        interactionId: payload.interactionId
-      });
-      return result;
-    } catch (error) {
-      const failure = error.details;
-      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.CAMPAIGN_PREVIEW_ACCEPT_FAILED, {
-        ..._MetricsManager.default.getCommonTrackingFieldForAQMResponseFailed(failure),
-        interactionId: payload.interactionId,
-        campaignId: payload.campaignId
-      }, ['behavioral', 'business', 'operational']);
-      const {
-        error: detailedError
-      } = (0, _Utils.getErrorDetails)(error, _constants.METHODS.ACCEPT_PREVIEW_CONTACT, _constants.CC_FILE);
-      throw detailedError;
-    }
-  }
-
   /**
    * Fetches outdial ANI (Automatic Number Identification) entries for an outdial ANI ID.
    *