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

package/ai-docs/patterns/typescript-patterns.md

@@ -0,0 +1,365 @@
+# TypeScript Patterns - Contact Center SDK
+
+> **Purpose**: TypeScript conventions and patterns specific to the Contact Center SDK.
+
+---
+
+## Type Definition Patterns
+
+### Const Object + Type Pattern (for Enums)
+
+The SDK uses const objects instead of TypeScript enums for better tree-shaking and runtime access:
+
+```typescript
+// Step 1: Define const object
+export const CC_EVENTS = {
+  AGENT_LOGIN: 'AgentLogin',
+  AGENT_LOGOUT: 'AgentLogout',
+  AGENT_STATE_CHANGE: 'AgentStateChange',
+} as const;
+
+// Step 2: Create union type from values
+type Enum<T extends Record<string, unknown>> = T[keyof T];
+export type CC_EVENTS = Enum<typeof CC_EVENTS>;
+
+// Usage:
+const event: CC_EVENTS = CC_EVENTS.AGENT_LOGIN; // ✅ Type-safe
+const event2: CC_EVENTS = 'InvalidEvent';        // ❌ Compile error
+```
+
+### Failure Type Pattern
+
+Error responses use the `Failure` type:
+
+```typescript
+// From services/core/GlobalTypes.ts
+
+// Base message type — all WebSocket messages extend this
+export type Msg<T = any> = {
+  type: string;
+  orgId: string;
+  trackingId: string;
+  data: T;
+};
+
+// Failure wraps error details inside Msg
+export type Failure = Msg<{
+  agentId: string;
+  trackingId: string;
+  reasonCode: number;
+  orgId: string;
+  reason: string;
+}>;
+
+// Usage in catch blocks:
+const failure = error.details as Failure;
+// Access: failure.trackingId, failure.data.reason, failure.data.reasonCode
+LoggerProxy.error(`Operation failed`, {
+  module: CC_FILE,
+  method: 'methodName',
+  trackingId: failure.trackingId,
+});
+```
+
+---
+
+## Naming Conventions
+
+### Files
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Class files | PascalCase | `TaskManager.ts`, `WebSocketManager.ts` |
+| Type files | lowercase | `types.ts` |
+| Constant files | lowercase | `constants.ts` |
+| Index files | lowercase | `index.ts` |
+| Utility files | PascalCase | `Utils.ts`, `Err.ts` |
+
+### Code Elements
+
+```typescript
+// Classes: PascalCase
+class ContactCenter { }
+class TaskManager { }
+
+// Interfaces: PascalCase with I prefix for contracts
+// (e.g., IContactCenter, ITask, IVoice, IDigital)
+// Types: PascalCase without prefix
+type AgentLogin = { };
+type Profile = { };
+
+// Constants: SCREAMING_SNAKE_CASE
+const CC_FILE = 'ContactCenter';
+const METRIC_EVENT_NAMES = { };
+
+// Methods: camelCase
+public async stationLogin() { }
+private handleWebsocketMessage() { }
+
+// Properties: camelCase
+private agentConfig: Profile;
+private eventEmitter: EventEmitter;
+
+// SDK references: $ prefix
+private $webex: WebexSDK;
+private $config: CCPluginConfig;
+```
+
+---
+
+## Import Patterns
+
+### Import Order
+
+```typescript
+// 1. External packages
+import {WebexPlugin} from '@webex/webex-core';
+import EventEmitter from 'events';
+import {v4 as uuidv4} from 'uuid';
+
+// 2. Package-level imports (types, constants)
+import {
+  WebexSDK,
+  CCPluginConfig,
+  AgentLogin,
+  StationLoginResponse,
+} from './types';
+import {READY, CC_FILE, METHODS} from './constants';
+
+// 3. Service imports
+import Services from './services';
+import LoggerProxy from './logger-proxy';
+
+// 4. Utility imports
+import {getErrorDetails} from './services/core/Utils';
+import {Failure} from './services/core/GlobalTypes';
+
+// 5. Type-only imports (when applicable)
+import type {Profile} from './services/config/types';
+```
+
+### Re-exports
+
+```typescript
+// types.ts - Central export file
+export {Profile, CC_EVENTS} from './services/config/types';
+export {AGENT_EVENTS, StationLoginSuccess} from './services/agent/types';
+export {TASK_EVENTS, ITask} from './services/task/types';
+```
+
+---
+
+## Type Derivation Patterns
+
+### Pick for Subset Types
+
+```typescript
+// Original type
+type FullProfile = {
+  agentId: string;
+  teamId: string;
+  state: string;
+  dialNumber: string;
+  permissions: string[];
+};
+
+// Derived subset
+type LoginInfo = Pick<FullProfile, 'agentId' | 'teamId' | 'dialNumber'>;
+```
+
+### Partial for Optional Updates
+
+```typescript
+type AgentUpdate = Partial<AgentProfile>;
+
+// Usage: all fields optional
+function updateAgent(update: AgentUpdate) {
+  // Only specified fields will be updated
+}
+```
+
+### Omit for Exclusion
+
+```typescript
+type PublicProfile = Omit<FullProfile, 'permissions' | 'internalId'>;
+```
+
+---
+
+## Generic Patterns
+
+### Type Parameter for Response Data
+
+```typescript
+// Generic request handler
+async function request<T>(config: RequestConfig): Promise<ApiResponse<T>> {
+  const response = await fetch(config.url);
+  return response.json() as ApiResponse<T>;
+}
+
+// Usage with specific type
+const result = await request<AgentData>(config);
+// result.data is typed as AgentData
+```
+
+### Conditional Types (Advanced)
+
+```typescript
+// Used in event handling
+type EventDataMap = {
+  [CC_EVENTS.AGENT_LOGIN]: LoginData;
+  [CC_EVENTS.AGENT_LOGOUT]: LogoutData;
+  [CC_EVENTS.AGENT_STATE_CHANGE]: StateChangeData;
+};
+
+type EventData<T extends CC_EVENTS> = EventDataMap[T];
+```
+
+---
+
+## JSDoc Patterns
+
+### Public API Documentation
+
+```typescript
+/**
+ * Logs the agent into their assigned station.
+ *
+ * @description
+ * This method authenticates the agent and establishes their connection
+ * to the Contact Center system. The agent must be registered before
+ * calling this method.
+ *
+ * @param {AgentLogin} data - Login configuration
+ * @param {string} data.teamId - Team to log into
+ * @param {LoginOption} data.loginOption - Device type (BROWSER, EXTENSION, AGENT_DN)
+ * @param {string} [data.dialNumber] - Required for EXTENSION/AGENT_DN
+ *
+ * @returns {Promise<StationLoginResponse>} Login result with session info
+ *
+ * @throws {Error} If login fails with reason in error.data.reason
+ *
+ * @fires agent:stationLoginSuccess When login succeeds
+ * @fires agent:stationLoginFailed When login fails
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // Browser-based login
+ * const result = await cc.stationLogin({
+ *   teamId: 'team-123',
+ *   loginOption: 'BROWSER',
+ * });
+ *
+ * // Extension-based login
+ * const result = await cc.stationLogin({
+ *   teamId: 'team-123',
+ *   loginOption: 'EXTENSION',
+ *   dialNumber: '1234',
+ * });
+ * ```
+ */
+public async stationLogin(data: AgentLogin): Promise<StationLoginResponse> {
+  // Implementation
+}
+```
+
+### Type Documentation
+
+```typescript
+/**
+ * Configuration for agent login operation.
+ *
+ * @public
+ */
+export type AgentLogin = {
+  /**
+   * The team ID to log into.
+   * Must be a valid team from the agent's profile.
+   */
+  teamId: string;
+
+  /**
+   * Device type for the login.
+   * - BROWSER: WebRTC-based softphone
+   * - EXTENSION: Desk phone extension
+   * - AGENT_DN: Direct dial number
+   */
+  loginOption: LoginOption;
+
+  /**
+   * Phone number or extension.
+   * Required when loginOption is EXTENSION or AGENT_DN.
+   */
+  dialNumber?: string;
+};
+```
+
+---
+
+## Async Patterns
+
+### Standard Async/Await
+
+```typescript
+// Preferred pattern
+public async fetchData(): Promise<Data> {
+  try {
+    const result = await this.service.getData();
+    return result;
+  } catch (error) {
+    // Handle error
+    throw error;
+  }
+}
+```
+
+### Promise Chaining (When Necessary)
+
+```typescript
+// Used in some initialization flows
+this.$webex.once(READY, () => {
+  this.services = Services.getInstance({...});
+  
+  this.services.webSocketManager
+    .initWebSocket({body: config})
+    .then((data) => {
+      // Handle success
+    })
+    .catch((error) => {
+      // Handle error
+    });
+});
+```
+
+---
+
+## Type Guards
+
+### Type Narrowing
+
+```typescript
+// Check for specific error type
+function isFailure(error: unknown): error is {details: Failure} {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'details' in error
+  );
+}
+
+// Usage
+if (isFailure(error)) {
+  const failure = error.details;
+  // TypeScript knows failure is Failure type
+}
+```
+
+### Event Type Guards
+
+```typescript
+function isAgentEvent(event: CC_EVENTS): event is keyof typeof CC_AGENT_EVENTS {
+  return Object.values(CC_AGENT_EVENTS).includes(event as any);
+}
+```

package/ai-docs/templates/README.md

@@ -0,0 +1,102 @@
+# Contact Center SDK - Templates
+
+> **Purpose**: Code generation templates for AI agents to create, modify, and document SDK components.
+
+---
+
+## Template Categories
+
+| Category | Purpose | Use When |
+|----------|---------|----------|
+| **new-service/** | Creating new services (like AddressBook, Queue) | Adding new data/API services |
+| **new-method/** | Adding methods to existing services | Extending service capabilities |
+| **existing-service/** | Bug fixes, feature enhancements, and modifications to existing methods | Modifying existing code |
+| **documentation/** | Generating AGENTS.md and ARCHITECTURE.md | Creating service-level docs |
+
+---
+
+## Template Directory Structure
+
+```
+templates/
+├── README.md                    # This file
+├── new-service/                 # New service creation
+│   ├── 00-master.md             # Orchestrator
+│   ├── 01-pre-questions.md      # Requirements gathering (STOP gate)
+│   ├── 02-code-generation.md    # Service class generation
+│   ├── 03-integration.md        # Registration and exports
+│   ├── 04-test-generation.md    # Test file generation
+│   └── 05-validation.md         # Quality checklist
+├── new-method/                  # New method addition
+│   ├── 00-master.md             # Orchestrator
+│   ├── 01-requirements.md       # Method requirements (STOP gate)
+│   ├── 02-implementation.md     # Code implementation
+│   ├── 03-tests.md              # Test generation
+│   └── 04-validation.md         # Quality checklist
+├── existing-service/            # Modifications
+│   ├── bug-fix.md               # Bug fix workflow (STOP gate in Section A)
+│   └── feature-enhancement.md   # Feature addition / modify existing method (STOP gate in Step 0)
+└── documentation/               # Doc generation
+    ├── create-agents-md.md      # AGENTS.md template
+    └── create-architecture-md.md # ARCHITECTURE.md template
+```
+
+---
+
+## Quick Reference
+
+### Creating a New Service (Task Type A)
+Start with: [`new-service/00-master.md`](new-service/00-master.md)
+
+### Adding a New Method (Task Type B)
+Start with: [`new-method/00-master.md`](new-method/00-master.md)
+
+### Fixing a Bug (Task Type C)
+Use: [`existing-service/bug-fix.md`](existing-service/bug-fix.md)
+
+### Adding a Feature (Task Type D)
+Start with: [`existing-service/feature-enhancement.md`](existing-service/feature-enhancement.md)
+
+**Important:** Feature template includes a mandatory placement triage:
+- if feature fits existing service -> continue feature-enhancement flow
+- if feature needs standalone ownership -> reroute to [`new-service/00-master.md`](new-service/00-master.md)
+
+### Modifying an Existing Method (Task Type F)
+Use: [`existing-service/feature-enhancement.md`](existing-service/feature-enhancement.md)
+
+**Important:** When modifying an existing method (changing signature, parameters, return type, or behavior), use the feature-enhancement template but **skip Step 0 (Placement Triage)** since the method already exists. Start directly at Step 0B (Pre-Enhancement Questions).
+
+### Creating Service Documentation (Task Type E)
+Use: [`documentation/create-agents-md.md`](documentation/create-agents-md.md)
+
+---
+
+## Template Usage Flow
+
+```
+1. Classify task using root AGENTS.md decision tree (../../AGENTS.md)
+       |
+       v
+2. Route to appropriate template
+       |
+       v
+3. STOP — Present pre-questions to developer, wait for answers
+       |
+       v
+4. Present Spec Summary to developer, wait for approval
+       |
+       v
+5. If task is "Add Feature", run placement triage (existing vs new service)
+       |
+       v
+6. Load relevant patterns as specified
+       |
+       v
+7. Generate/modify code
+       |
+       v
+8. Run validation checklist
+       |
+       v
+9. Update documentation if needed
+```

package/ai-docs/templates/documentation/create-agents-md.md

@@ -0,0 +1,240 @@
+# Create AGENTS.md Template
+
+> **Purpose**: Template for generating service-level AGENTS.md files optimized for LLM consumption.
+
+---
+
+## Pre-Generation Questions
+
+Answer before writing:
+
+1. **Package/Service Name**: What is this service called?
+2. **Purpose**: What problem does this service solve? (1-2 sentences)
+3. **Key Capabilities**: What are the main features? (3-5 bullets)
+4. **Usage Examples**: What are the most common use cases?
+5. **API Surface**: What methods/properties are exposed?
+6. **Dependencies**: What does this service depend on?
+
+---
+
+## AGENTS.md Structure
+
+```markdown
+# [Service Name] - AI Agent Guide
+
+> **Purpose**: [One sentence describing what this service does]
+
+---
+
+## Quick Start
+
+[3-5 line code example showing most basic usage]
+
+---
+
+## Key Capabilities
+
+- [Capability 1]: [Brief description]
+- [Capability 2]: [Brief description]
+- [Capability 3]: [Brief description]
+
+---
+
+## Usage Examples
+
+### [Use Case 1]
+```typescript
+// Example code
+```
+
+### [Use Case 2]
+```typescript
+// Example code
+```
+
+---
+
+## API Reference
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `propertyName` | `Type` | Description |
+
+### Methods
+
+#### `methodName(params)`
+
+Description of what this method does.
+
+**Parameters**:
+- `param1` (Type): Description
+- `param2` (Type, optional): Description
+
+**Returns**: `Promise<ReturnType>` - Description
+
+**Example**:
+```typescript
+const result = await service.methodName({
+  param1: 'value',
+});
+```
+
+---
+
+## Events (if applicable)
+
+| Event | Data | When Emitted |
+|-------|------|--------------|
+| `event:name` | `EventData` | Description |
+
+---
+
+## Common Patterns
+
+### [Pattern Name]
+```typescript
+// Pattern example
+```
+
+---
+
+## Error Handling
+
+Errors are thrown as `Error` with:
+- `message`: Error description
+- `data.reason`: Error reason code
+
+```typescript
+try {
+  await service.method();
+} catch (error) {
+  console.error(error.message);
+  console.error(error.data?.reason);
+}
+```
+
+---
+
+## Dependencies
+
+- Requires: [dependency description]
+- Used by: [what uses this service]
+
+---
+
+## Related Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive
+- [Pattern files](../../../ai-docs/patterns/) - Coding patterns
+```
+
+---
+
+## Content Guidelines
+
+### Purpose Section
+- One clear sentence
+- Focus on business value, not implementation
+
+### Quick Start
+- Show the happy path
+- Minimal code to demonstrate value
+- Include all required setup steps
+
+### Examples
+- Use realistic parameter values
+- Show common variations
+- Include error handling when relevant
+
+### API Reference
+- List all public methods
+- Include parameter types and descriptions
+- Show return types
+- Provide example for each method
+
+### Error Handling
+- Document common error scenarios
+- Show how to access error details
+
+---
+
+## Token Optimization Strategy
+
+For LLM efficiency:
+1. **AGENTS.md first**: Contains usage info (most commonly needed)
+2. **ARCHITECTURE.md linked at end**: For deep technical questions
+3. **Concise examples**: Just enough to demonstrate
+4. **Tables for reference**: Quick scanning
+
+---
+
+## Validation Checklist
+
+- [ ] Purpose is clear and concise
+- [ ] Quick start works as-is
+- [ ] All public methods documented
+- [ ] Examples are realistic and working
+- [ ] Error handling documented
+- [ ] Links to ARCHITECTURE.md included
+- [ ] No implementation details (save for ARCHITECTURE.md)
+
+---
+
+## Example: Services/Agent AGENTS.md
+
+```markdown
+# Agent Service - AI Agent Guide
+
+> **Purpose**: Manage agent lifecycle including login, logout, and state changes.
+
+---
+
+## Quick Start
+
+```typescript
+const cc = webex.cc;
+await cc.register();
+
+// Login
+await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'BROWSER',
+});
+
+// Set available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+```
+
+---
+
+## Key Capabilities
+
+- **Station Login**: Login with browser, extension, or dial number
+- **Station Logout**: Logout from current station
+- **State Management**: Change between Available/Idle states
+- **Buddy Agents**: Retrieve list of available agents
+
+---
+
+## API Reference
+
+### `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>`
+
+---
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for technical details.
+```