@webex/contact-center 3.12.0-next.8 → 3.12.0-next.81

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.