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

package/ai-docs/templates/new-method/03-tests.md

@@ -0,0 +1,201 @@
+# New Method - Tests
+
+> **Purpose**: Create unit tests for the new method.
+
+---
+
+## Test Location
+
+Add tests to the existing test file that corresponds to the source file:
+- For `cc.ts` methods: `test/unit/spec/cc.ts`
+- For service methods: `test/unit/spec/services/[service]/index.ts`
+- For non-service files: `test/unit/spec/[filename].ts`
+
+> **Convention**: The test file path mirrors the source file path under `test/unit/spec/`. For example:
+> - `src/cc.ts` → `test/unit/spec/cc.ts`
+> - `src/logger-proxy.ts` → `test/unit/spec/logger-proxy.ts`
+> - `src/metrics/MetricsManager.ts` → `test/unit/spec/metrics/MetricsManager.ts`
+> - `src/services/agent/index.ts` → `test/unit/spec/services/agent/index.ts`
+> - `src/services/task/Task.ts` → `test/unit/spec/services/task/Task.ts`
+> - `src/services/WebCallingService.ts` → `test/unit/spec/services/WebCallingService.ts`
+
+---
+
+## Test Template
+
+```typescript
+describe('cc.methodName', () => {
+  // Mock data
+  const mockParams = {
+    requiredField: 'test-value',
+  };
+  
+  const mockSuccessResponse = {
+    data: {
+      field: 'value',
+    },
+    trackingId: 'track-123',
+  };
+  
+  const mockError = new Error('Operation failed');
+  mockError.details = {
+    type: 'OperationFailed',
+    data: { reason: 'INVALID_INPUT' },
+    trackingId: 'track-456',
+  };
+
+  beforeEach(() => {
+    // Reset mocks
+    jest.clearAllMocks();
+    
+    // Setup default mock behavior
+    mockServicesInstance.someService.method.mockResolvedValue(mockSuccessResponse);
+  });
+
+  describe('success scenarios', () => {
+    it('should complete operation successfully', async () => {
+      // Act
+      const result = await webex.cc.methodName(mockParams);
+
+      // Assert
+      expect(result).toEqual(mockSuccessResponse);
+      expect(mockServicesInstance.someService.method).toHaveBeenCalledWith({
+        data: {
+          requiredField: 'test-value',
+          agentId: 'mock-agent-id',
+        },
+      });
+    });
+
+    it('should track success metrics', async () => {
+      // Act
+      await webex.cc.methodName(mockParams);
+
+      // Assert
+      expect(mockMetricsManager.timeEvent).toHaveBeenCalledWith([
+        METRIC_EVENT_NAMES.OPERATION_SUCCESS,
+        METRIC_EVENT_NAMES.OPERATION_FAILED,
+      ]);
+      expect(mockMetricsManager.trackEvent).toHaveBeenCalledWith(
+        METRIC_EVENT_NAMES.OPERATION_SUCCESS,
+        {
+          ...mockCommonTrackingFields,
+          customField: 'test-value',
+        },
+        ['behavioral', 'operational']
+      );
+    });
+
+    it('should log operation start and completion', async () => {
+      // Act
+      await webex.cc.methodName(mockParams);
+
+      // Assert
+      expect(LoggerProxy.info).toHaveBeenCalledWith(
+        'Starting operation',
+        {
+          module: CC_FILE,
+          method: METHODS.METHOD_NAME,
+        }
+      );
+      expect(LoggerProxy.log).toHaveBeenCalledWith(
+        'Operation completed successfully',
+        {
+          module: CC_FILE,
+          method: METHODS.METHOD_NAME,
+          trackingId: 'track-123',
+        }
+      );
+    });
+  });
+
+  describe('error scenarios', () => {
+    it('should throw error on service failure', async () => {
+      // Arrange
+      mockServicesInstance.someService.method.mockRejectedValue(mockError);
+
+      // Act & Assert
+      await expect(webex.cc.methodName(mockParams)).rejects.toThrow();
+    });
+
+    it('should track failure metrics on error', async () => {
+      // Arrange
+      mockServicesInstance.someService.method.mockRejectedValue(mockError);
+
+      // Act
+      await expect(webex.cc.methodName(mockParams)).rejects.toThrow();
+
+      // Assert
+      expect(mockMetricsManager.trackEvent).toHaveBeenCalledWith(
+        METRIC_EVENT_NAMES.OPERATION_FAILED,
+        {
+          ...mockCommonFailedTrackingFields,
+          customField: 'test-value',
+        },
+        ['behavioral', 'operational']
+      );
+    });
+
+    it('should call getErrorDetails on failure', async () => {
+      // Arrange
+      mockServicesInstance.someService.method.mockRejectedValue(mockError);
+
+      // Act
+      await expect(webex.cc.methodName(mockParams)).rejects.toThrow();
+
+      // Assert
+      expect(getErrorDetailsSpy).toHaveBeenCalledWith(
+        mockError,
+        METHODS.METHOD_NAME,
+        CC_FILE
+      );
+    });
+  });
+
+  describe('input validation', () => {
+    it('should handle optional parameters', async () => {
+      // Arrange
+      const paramsWithOptional = {
+        ...mockParams,
+        optionalField: 42,
+      };
+
+      // Act
+      await webex.cc.methodName(paramsWithOptional);
+
+      // Assert
+      expect(mockServicesInstance.someService.method).toHaveBeenCalledWith({
+        data: {
+          requiredField: 'test-value',
+          optionalField: 42,
+          agentId: 'mock-agent-id',
+        },
+      });
+    });
+  });
+});
+```
+
+---
+
+## Test Assertion Guidelines
+
+> **Team standard: Use exact matches, not partial matchers.** Always use `expect(result).toEqual(expectedValue)` with the full expected object. Avoid `expect.objectContaining()` or `expect.arrayContaining()` unless there is a specific reason (e.g., dynamic fields like timestamps). Exact assertions catch unintended payload changes early.
+
+---
+
+## Running Tests
+
+```bash
+# Run specific test file
+yarn workspace @webex/contact-center test:unit -- <path_to_specific_file>
+
+# Run with coverage
+yarn workspace @webex/contact-center test:unit --coverage
+```
+
+---
+
+## Next Step
+
+Proceed to: [`04-validation.md`](04-validation.md)

package/ai-docs/templates/new-method/04-validation.md

@@ -0,0 +1,141 @@
+# New Method - Validation Checklist
+
+> **Purpose**: Final quality check before completing method addition.
+
+---
+
+## Code Quality Checklist
+
+### Method Implementation
+- [ ] Method added with correct signature
+- [ ] JSDoc with `@param`, `@returns`, `@throws`, `@example`
+- [ ] `@public` tag for public API methods
+- [ ] LoggerProxy.info at method start
+- [ ] LoggerProxy.log on success
+- [ ] LoggerProxy.error on failure (via getErrorDetails)
+- [ ] MetricsManager.timeEvent at start
+- [ ] MetricsManager.trackEvent on success
+- [ ] MetricsManager.trackEvent on failure
+- [ ] Error handling uses `getErrorDetails` pattern
+- [ ] Failure cast: `const failure = error.details as Failure`
+
+### Constants
+- [ ] Method name added to `METHODS` constant
+- [ ] Metric events added to `METRIC_EVENT_NAMES`
+
+### Types
+- [ ] Parameter type defined with JSDoc
+- [ ] Return type defined with JSDoc
+- [ ] Types exported from `src/types.ts`
+
+### Tests
+- [ ] Success case tested
+- [ ] Error case tested
+- [ ] Metrics tracking verified
+- [ ] Logging verified
+- [ ] Optional parameters tested
+
+---
+
+## Pattern Verification
+
+### Correct Logging Pattern
+```typescript
+// ✅ At start
+LoggerProxy.info('Starting operation', {
+  module: CC_FILE,
+  method: METHODS.METHOD_NAME,
+});
+
+// ✅ On success
+LoggerProxy.log('Operation completed successfully', {
+  module: CC_FILE,
+  method: METHODS.METHOD_NAME,
+  trackingId: result.trackingId,
+});
+```
+
+### Error Logging — `error` vs `warn`
+
+| Level | When to Use | Stack Trace Included? |
+|---|---|---|
+| `LoggerProxy.error()` | Operation failures, API errors, exceptions in catch blocks | **Yes** — full stack trace is appended automatically |
+| `LoggerProxy.warn()` | Non-critical issues that don't break flow (e.g., deprecation notices, fallback behavior) | **No** — only the message is logged |
+
+> **Current codebase convention**: `LoggerProxy.error()` is used extensively across the SDK. `LoggerProxy.warn()` is not currently used in any source file. Default to `error` for catch blocks and failure paths.
+
+```typescript
+// ✅ Error — in catch blocks and failure paths (includes stack trace)
+LoggerProxy.error(`${methodName} failed with reason: ${reason}`, {
+  module: moduleName,
+  method: methodName,
+  trackingId: failure?.trackingId,
+});
+
+// ✅ Error — via getErrorDetails (logs error + uploads logs automatically)
+// Most methods use this pattern instead of calling LoggerProxy.error() directly
+const {error: detailedError} = getErrorDetails(error, METHODS.METHOD_NAME, CC_FILE);
+
+// ⚠️ Warn — for non-critical issues only (no stack trace)
+LoggerProxy.warn('Falling back to default configuration', {
+  module: CC_FILE,
+  method: METHODS.METHOD_NAME,
+});
+```
+
+> **Note**: `getErrorDetails()` (in `src/services/core/Utils.ts`) already calls `LoggerProxy.error()` internally and uploads logs via `WebexRequest.uploadLogs()`. Do not double-log errors when using `getErrorDetails`.
+
+### Correct Metrics Pattern
+```typescript
+// ✅ Start timing
+this.metricsManager.timeEvent([
+  METRIC_EVENT_NAMES.SUCCESS,
+  METRIC_EVENT_NAMES.FAILED,
+]);
+
+// ✅ Track success
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.SUCCESS,
+  {...MetricsManager.getCommonTrackingFieldForAQMResponse(result)},
+  ['behavioral', 'operational']
+);
+
+// ✅ Track failure
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.FAILED,
+  {...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure)},
+  ['behavioral', 'operational']
+);
+```
+
+### Correct Error Pattern
+```typescript
+// ✅ 
+const failure = error.details as Failure;
+this.metricsManager.trackEvent(FAILED_EVENT, {...}, [...]);
+const {error: detailedError} = getErrorDetails(error, METHOD, MODULE);
+throw detailedError;
+```
+
+---
+
+## 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.
+
+---
+
+## Complete!
+
+Method addition is complete when all checkboxes are checked.

package/ai-docs/templates/new-service/00-master.md

@@ -0,0 +1,109 @@
+# New Service Creation - Master Template
+
+> **Purpose**: Orchestrator for creating new services or modules within the Contact Center SDK — whether top-level (e.g., AddressBook, EntryPoint, Queue), a sub-module under an existing service (e.g., a new module under `task/`), or an internal-only utility service.
+
+---
+
+## Entry Paths
+
+You can land on this template from:
+- direct "create new service" requests
+- "add feature" requests after feature triage determines the feature should be a standalone service/module
+
+If coming from feature triage, include:
+- feature placement rationale
+- desired service/module name
+- expected public API surface
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Clear understanding of what the service will do
+- Complete API signature details (payload, response, HTTP method, endpoint)
+- Event contract details when feature uses events (listener object, payload shape, emission source)
+- Understanding of data structures involved
+
+---
+
+## Workflow Overview
+
+```
+Step 1: Requirements → Step 2: Code Generation → Step 3: Integration → Step 4: Tests → Step 5: Validation
+```
+
+---
+
+## Step-by-Step Process
+
+### Step 1: Gather Requirements
+**Template**: [`01-pre-questions.md`](01-pre-questions.md)
+
+Answer these questions:
+- What is the service name?
+- What API endpoints will it call?
+- What data will it manage?
+- Will it be exposed on `cc.serviceName`?
+
+### Step 2: Generate Code
+**Template**: [`02-code-generation.md`](02-code-generation.md)
+
+Create:
+- Service class file (placement determined by pre-questions — see Step 1)
+- Type definitions (location depends on placement — service folder's `types.ts` or root `src/types.ts`)
+- Constants if needed (service folder's `constants.ts` or shared `src/services/constants.ts`)
+
+### Step 3: Integration
+**Template**: [`03-integration.md`](03-integration.md)
+
+Integrate:
+- Initialize the service (location depends on placement — `cc.ts` for top-level, parent service for sub-modules)
+- Expose via `cc.serviceName` if developer confirmed public in pre-questions Q7
+- Export types from `src/types.ts` (for public services only)
+
+### Step 4: Generate Tests
+**Template**: [`04-test-generation.md`](04-test-generation.md)
+
+Create:
+- Unit test file
+- Mock service methods
+- Test success and error cases
+
+### Step 5: Validation
+**Template**: [`05-validation.md`](05-validation.md)
+
+Verify:
+- All patterns followed
+- Tests pass
+- Types exported
+- Documentation updated
+
+---
+
+## Patterns to Load
+
+Before generating code, read:
+1. [`../../patterns/typescript-patterns.md`](../../patterns/typescript-patterns.md) - Type conventions
+2. [`../../patterns/event-driven-patterns.md`](../../patterns/event-driven-patterns.md) - Event and WebSocket patterns
+3. [`../../patterns/testing-patterns.md`](../../patterns/testing-patterns.md) - Test patterns
+
+---
+
+## Reference Implementation
+
+Study existing service: `src/services/AddressBook.ts` or `src/services/EntryPoint.ts`
+
+---
+
+## Quick Checklist
+
+- [ ] Service class created with WebexSDK injection
+- [ ] LoggerProxy used for all logging
+- [ ] Metrics tracked for all operations (success + failure)
+- [ ] Error handling follows `getErrorDetails` pattern
+- [ ] Types defined and placed correctly (folder `types.ts` or root `src/types.ts`)
+- [ ] Constants placed correctly (folder `constants.ts` or shared `src/services/constants.ts`)
+- [ ] Initialized and integrated (in `cc.ts` for top-level, or parent service for sub-modules)
+- [ ] Unit tests created
+- [ ] JSDoc added for public methods

package/ai-docs/templates/new-service/01-pre-questions.md

@@ -0,0 +1,159 @@
+# New Service - Pre-Questions
+
+> **Purpose**: Gather requirements from the developer before generating service code.
+
+---
+
+## STOP — Ask These Questions First
+
+**You MUST present the following questions to the developer and wait for their answers before proceeding.** Do not infer answers from the developer's initial request. Do not fill in fields yourself. Do not read code or load patterns yet.
+
+Present questions grouped by section. If the developer cannot answer a MANDATORY question, ask follow-up questions to help them clarify. Only proceed to code generation when all MANDATORY fields have explicit developer-provided answers.
+
+---
+
+## 1. Service Identity (MANDATORY)
+
+Ask the developer:
+
+1. **"What should the service be named?"**
+   - Must be PascalCase (e.g., "AddressBook", "Queue", "EntryPoint")
+
+2. **"What problem does this service solve? What data does it manage?"**
+   - Need a one-sentence purpose description.
+
+3. **"Where should this service live?"**
+   - **Folder-based service**: `src/services/ServiceName/` — complex service with its own folder, `index.ts`, `types.ts`, and optionally `constants.ts` (e.g., `agent/`, `config/`, `task/`)
+   - **Single-file service**: `src/services/ServiceName.ts` — lightweight service as a single file; types go in `src/types.ts`, constants go in `src/services/constants.ts` (e.g., `AddressBook.ts`, `EntryPoint.ts`, `Queue.ts`)
+   - **Sub-module under existing service**: a file within an existing service folder (e.g., `task/Voice.ts`, `task/Digital.ts`)
+
+   This determines the file structure and where types/constants are placed.
+
+---
+
+## 2. API Contract (MANDATORY)
+
+Ask the developer to provide the complete API signature for **each** API the service will use:
+
+4. **"What API endpoint(s) will this service call? For each, provide:"**
+
+   | Field | What to Ask |
+   |---|---|
+   | API Name | "What should the method be called?" (e.g., `getEntries`, `createItem`) |
+   | HTTP Method | "Is this a GET, POST, PUT, or DELETE?" |
+   | Endpoint | "What is the full endpoint path?" (e.g., `/v1/address-books/{id}/entries`) |
+   | Request Payload | "What fields does the request body contain? Which are required vs optional?" |
+   | Response Structure | "What does the response look like? What fields does `data` contain?" |
+   | Error Shape | "What error reason codes can this return?" |
+
+   **If any API field is unknown, STOP and ask the developer before proceeding. Do not guess endpoint structures or payload shapes.**
+
+---
+
+## 3. Event Contract (MANDATORY if the service uses events, otherwise skip)
+
+Ask the developer:
+
+5. **"Does this service listen to or emit any events?"**
+   - If YES, for each event ask:
+
+   | Field | What to Ask |
+   |---|---|
+   | Event Name | "What is the event name?" |
+   | Direction | "Is this incoming (received from WebSocket) or outgoing (emitted by SDK)?" |
+   | Source | "Is this a WebSocket event, or an internal EventEmitter event?" |
+   | Listen/Emit Object | "Where do consumers subscribe to this event?" (`cc`, `task`, `taskManager`, service) |
+   | Payload Type/Shape | "What data does the event carry? What are the field names and types?" |
+   | Emitted From | "Which class/file/method emits this event?" |
+   | Emission Trigger | "What causes this event to fire?" |
+
+   - If any events come from WebSocket: "How should these WebSocket events map to service behavior?"
+   - If NO events at all, skip to section 4.
+
+---
+
+## 4. Dependencies & Exposure (MANDATORY)
+
+Ask the developer:
+
+6. **"Does this service need any data from the agent profile?"**
+   - If YES: "Which specific fields?" (e.g., `addressBookId`, `teamIds`)
+   - If NO: note "No profile dependency"
+
+7. **"Should this service be accessible as `cc.serviceName` (public API), or is it internal only?"**
+   - If public: it will be exposed on the `cc` object and types will be re-exported from `src/types.ts`
+   - If internal: it will only be used by other services within the SDK
+
+8. **"What methods should be exposed? For each method, what is the expected behavior?"**
+   - e.g., `getEntries(params)` — Fetch paginated list
+   - e.g., `getEntryById(id)` — Fetch single item
+
+---
+
+## 6. Caching (OPTIONAL)
+
+Ask the developer:
+
+9. **"Should responses be cached in memory, or should every call fetch fresh data?"**
+   - If caching: "What is the cache invalidation strategy?"
+
+---
+
+## Completion Gate
+
+**Before proceeding, verify:**
+
+- [ ] Service name provided by developer
+- [ ] Service purpose described by developer
+- [ ] Service placement decided (top-level, sub-module, or single file)
+- [ ] At least one API endpoint fully specified (method, path, request, response, errors)
+- [ ] Event contract captured (or developer confirmed no events)
+- [ ] Dependencies identified (or developer confirmed none)
+- [ ] Exposure decision made (public vs internal)
+- [ ] Methods to expose listed
+
+**If any MANDATORY field above is missing an explicit developer answer, ask a targeted follow-up question. Do not proceed.**
+
+---
+
+## Spec Summary
+
+Once all questions are answered, present this summary to the developer for approval before proceeding to code generation:
+
+```
+## Spec Summary — New Service
+
+**Service Name**: [from Q1]
+**Purpose**: [from Q2]
+**Placement**: [from Q3 — folder-based / single-file / sub-module under {parent}]
+**Target location**: [derived from Q3, e.g., `src/services/ServiceName/` or `src/services/ServiceName.ts` or `src/services/{parent}/ServiceName.ts`]
+
+### API Contract:
+| Method | HTTP | Endpoint | Request | Response |
+|---|---|---|---|---|
+| [method] | [GET/POST/...] | [path] | [payload] | [response] |
+
+### Events:
+[event table or "None"]
+
+### Dependencies:
+- Profile fields: [list or "None"]
+
+### Exposure:
+- Public API: [Yes/No] — `cc.[serviceName]`
+- Methods: [list]
+
+### Caching: [Yes/No]
+
+---
+Does this match your intent? (Yes / No / Adjust)
+```
+
+**Wait for developer approval. Do not proceed to [`02-code-generation.md`](02-code-generation.md) until confirmed.**
+
+---
+
+## Next Step
+
+Once the developer approves the spec summary, proceed to:
+[`02-code-generation.md`](02-code-generation.md)